chore: Bump version to 2.9.0-beta

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
docs: Add player selector implementation plan
2026-01-20 10:16:35 +00:00 · 2026-01-20 10:04:58 +00:00 · 2026-01-20 08:11:53 +00:00 · 2026-01-20 07:44:13 +00:00 · 2026-01-20 07:21:29 +00:00 · 2026-01-20 07:17:53 +00:00
118 changed files with 30325 additions and 5536 deletions
@@ -35,6 +35,16 @@ jobs:
          channel: 'stable'
          cache: true
      - name: Cache Gradle dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            gradle-${{ runner.os }}-
      - name: Get dependencies
        run: flutter pub get
@@ -65,7 +75,12 @@ jobs:
          EOF
      - name: Build APK
-        run: flutter build apk --release
+        run: |
          # Use init.gradle to force Maven mirrors (workaround for Maven Central 403)
          mkdir -p ~/.gradle
          cp android/init.gradle ~/.gradle/init.gradle
          flutter build apk --release
      - name: Upload APK artifact
        uses: actions/upload-artifact@v4
@@ -0,0 +1,182 @@
 # Player System Animation & Polish Audit
 ## Context
 This is a Music Assistant client app (Ensemble) built with Flutter. The player system has undergone extensive development and now needs a comprehensive polish audit. The goal is buttery smooth 60fps animations and a premium user experience.
 ## Architecture Overview
 The player system consists of three interconnected components:
 1. **Mini Player** (collapsed state) - Floating card at bottom, shows current track
 2. **Expanded Player** - Full-screen player with album art, controls, progress
 3. **Queue Panel** - Slides in from right of expanded player, shows playback queue
 Additionally:
 - **Player Selector** - Horizontal swipe between multiple players (collapsed mode)
 - **Device Reveal** - Swipe down from mini player to show available players
 ## Key Files
 ```
 lib/widgets/
 ├── expandable_player.dart      # Main player widget (1800+ lines)
 ├── global_player_overlay.dart  # Overlay wrapper, static accessors
 ├── player/
 │   ├── queue_panel.dart        # Queue list with great_list_view
 │   ├── chapters_panel.dart     # Audiobook chapters
 │   └── mini_player_content.dart
 ```
 ## CRITICAL CONSTRAINTS
 1. **DO NOT MODIFY the queue list implementation** - It uses `great_list_view` package with `AutomaticAnimatedListView`. This was chosen specifically to avoid Flutter's grey screen overlay bug (#103804). The current implementation works correctly.
 2. **Preserve all existing functionality** - Focus on polish, not rewrites
 3. **Test changes incrementally** - This system is complex with many interdependencies
 ## Audit Areas
 ### 1. Animation Performance Audit
 Use sub-agents to analyze each animation system:
 **Agent 1: Expand/Collapse Animation**
 - Analyze `_controller` and `_expandAnimation`
 - Check for jank during morphing transition
 - Verify lerp functions are efficient
 - Look for unnecessary rebuilds during animation
 - Check `RepaintBoundary` placement
 **Agent 2: Queue Panel Animation**
 - Analyze `_queuePanelController` and `_queuePanelAnimation`
 - Verify slide-in/out is smooth
 - Check interaction with expanded player state
 - Verify the Listener-based swipe detection doesn't cause issues
 **Agent 3: Player Selector Animation**
 - Analyze horizontal swipe between players
 - Check `_slideOffset` and peek player animations
 - Verify finger-following feels natural
 - Look for edge cases with rapid swipes
 **Agent 4: Micro-interactions**
 - Play/pause button animations
 - Progress bar interactions
 - Volume swipe overlay
 - Favorite button feedback
 - Skip button responsiveness
 ### 2. State Management Audit
 **Check for:**
 - Unnecessary `setState` calls during animations
 - ValueNotifier usage efficiency
 - Animation listener cleanup
 - Memory leaks from subscriptions
 - State synchronization between components
 ### 3. Visual Polish Audit
 **Check for:**
 - Color transitions during expand/collapse
 - Text fade/scale animations
 - Image loading placeholders
 - Shadow/elevation consistency
 - Border radius morphing smoothness
 - Safe area handling
 ### 4. Gesture Conflict Resolution
 **Verify:**
 - Vertical drag (expand/collapse) vs horizontal drag (player switch)
 - Queue panel swipe-right-to-close vs Dismissible swipe-left-to-delete
 - Edge dead zones for Android back gesture
 - Tap vs drag disambiguation
 ### 5. Edge Cases
 **Test scenarios:**
 - Rapid expand/collapse
 - Swipe during animation
 - Back button during animations
 - Track change during queue scroll
 - Network image loading failures
 - Very long track/artist names
 ## Execution Strategy
 ```
 ultrathink: true
 ```
 ### Phase 1: Discovery (Read-Only)
 Launch parallel sub-agents to analyze each file:
 - Read and understand the animation architecture
 - Map all animation controllers and their relationships
 - Identify potential performance bottlenecks
 - Document current RepaintBoundary usage
 ### Phase 2: Analysis Report
 Compile findings into categories:
 - **Critical**: Causes visible jank or bugs
 - **Important**: Noticeable but not breaking
 - **Nice-to-have**: Minor polish improvements
 ### Phase 3: Implementation Plan
 For each finding:
 - Specific file and line numbers
 - Proposed change
 - Risk assessment
 - Testing approach
 ### Phase 4: Incremental Fixes
 - One fix at a time
 - Build and test after each change
 - Verify no regressions
 ## Output Format
 Provide a structured audit report:
 ```markdown
 ## Animation Audit Report
 ### Executive Summary
 [2-3 sentences on overall state]
 ### Critical Issues
 1. [Issue]: [File:Line] - [Description] - [Proposed Fix]
 ### Important Issues
 1. [Issue]: [File:Line] - [Description] - [Proposed Fix]
 ### Polish Opportunities
 1. [Issue]: [File:Line] - [Description] - [Proposed Fix]
 ### Architecture Observations
 [Notes on overall structure, patterns noticed]
 ### Recommended Priority Order
 1. [First fix]
 2. [Second fix]
 ...
 ```
 ## Success Criteria
 After this audit and fixes:
 - All animations run at consistent 60fps
 - No jank during any transition
 - Gestures feel responsive and natural
 - State transitions are seamless
 - No visual glitches or flickers
 - Memory usage is stable during interactions
 ## Notes
 - The app uses adaptive theming (colors extracted from album art)
 - There's an `AnimationDebugger` utility for profiling
 - Position tracking uses a shared `PositionTracker` singleton
 - The player supports both music and audiobooks (different UI modes)
@@ -1,136 +1,257 @@
-# Ensemble Flutter App - Code Audit Report
+# Ensemble Codebase Audit Report
-**Date:** January 4, 2026
+**Date**: 2026-01-14
-**Branch:** `audit/code-quality-review`
+**Scope**: Full codebase audit (104 Dart files, 18 screens)
-**Files Audited:** 93 Dart files
+**Focus Areas**: UI Continuity, Performance, Logic/Best Practices
 ---
 ## Executive Summary
-The codebase is generally well-maintained with good existing performance optimizations (RepaintBoundary, ListView.builder, cacheExtent settings). Key improvement areas identified:
+The Ensemble codebase is a **mature, feature-rich Flutter application** with many good patterns already in place. However, the audit identified **significant architectural debt** that should be addressed:
-| Category | Issues Found | Priority |
+| Severity | Count | Key Themes |
-|----------|-------------|----------|
+|----------|-------|------------|
-| Deprecated APIs | 20 instances | HIGH |
+| **Critical** | 6 | God classes (5,443 & 4,209 lines), design token adoption, startup blocking |
-| Missing const constructors | 100+ instances | MEDIUM |
+| **High** | 15 | Touch targets, batch DB operations, over-notification, code duplication |
-| Image cache parameters | 7 locations | MEDIUM |
+| **Medium** | 25+ | Inconsistencies, memory issues, missing error boundaries |
-| Code duplication | 8 view mode functions | LOW |
+| **Low** | 15+ | Minor polish items |
-| Color constants | 3 files with duplicates | LOW |
+
 **Top 3 Priorities:**
 1. **Split `MusicAssistantProvider` (5,443 lines)** - God object handling everything
 2. **Split `new_library_screen.dart` (4,209 lines)** - 10 scroll controllers, 15+ view modes
 3. **Fix startup performance** - Sequential blocking ops could save 1-8 seconds
 ---
-## 1. CRITICAL: Deprecated API Usage
+## Critical Issues
-### `colorScheme.background` (20 instances)
+### 1. God Object: MusicAssistantProvider (5,443 lines)
-Flutter Material 3 deprecates `ColorScheme.background`. Replace with `colorScheme.surface`.
+**File**: `lib/providers/music_assistant_provider.dart`
 - 54 `notifyListeners()` calls
 - 30+ state variables
 - 100+ public methods
 - Handles: connection, auth, players, library, search, caching, local playback, Sendspin
 - **Fix**: Split into ConnectionManager, PlayerStateManager, LibraryStateManager, SearchStateManager
-**Files affected:**
+### 2. God Object: NewLibraryScreen (4,209 lines)
- lib/main.dart:335, 336
+**File**: `lib/screens/new_library_screen.dart`
- lib/screens/library_artists_screen.dart:21
+- 10 scroll controllers
- lib/screens/new_home_screen.dart:121
+- 15+ view mode states
- lib/screens/artist_details_screen.dart:708, 720
+- 15+ sort order states
- lib/screens/library_playlists_screen.dart:53
+- Handles: Music, Books, Podcasts, Radio tabs
- lib/screens/library_tracks_screen.dart:19
+- **Fix**: Extract to ArtistsTab, AlbumsTab, TracksTab, PlaylistsTab, BooksTab, PodcastsTab, RadioTab
- lib/screens/login_screen.dart:489
+
- lib/screens/new_library_screen.dart:933, 957, 1020, 1021
+### 3. Sequential Blocking Startup (500-1500ms wasted)
- lib/screens/album_details_screen.dart:807, 819
+**File**: `lib/main.dart:33-66`
- lib/screens/library_albums_screen.dart:19
+```dart
- lib/screens/search_screen.dart:427, 738, 739
+await DatabaseService.instance.initialize();
- lib/screens/settings_screen.dart:245
+await ProfileService.instance.migrateFromOwnerName();
 await SettingsService.migrateToSecureStorage();
 await SyncService.instance.loadFromCache();
 audioHandler = await AudioService.init(...);
 ```
 - **Fix**: Parallelize with `Future.wait()`, defer AudioService to post-first-frame
 ### 4. Design Tokens Exist But Unused
 **File**: `lib/theme/design_tokens.dart`
 - `Spacing.*` used in only ~6 of 34+ widget files
 - `Radii.*` used in only ~5 files
 - `IconSizes.*` used in only ~4 files
 - **Fix**: Systematic replacement of hardcoded values
 ### 5. Touch Targets Too Small (32x32)
 **File**: `lib/screens/new_library_screen.dart:1805-1867`
 - Sort, favorites, view mode buttons are 32x32
 - Material Design minimum: 48x48
 - **Fix**: Increase to 48x48 or add padding for hit area
 ### 6. No Batch Database Inserts
 **File**: `lib/services/sync_service.dart:212-273`
 - 1000 albums = 1000 separate DB transactions
 - **Fix**: Wrap in single transaction or use Drift batch insert
 ---
-## 2. HIGH: Missing const Constructors
+## High Severity Issues
-### EdgeInsets.zero (64 instances)
+### Performance
-High-impact optimization - used extensively in button padding.
+| Issue | File | Impact |
 |-------|------|--------|
 | `context.watch()` in nested tabs | new_library_screen.dart:2960 | All tabs rebuild on any provider change |
 | Consumer wrapping 800-line player | expandable_player.dart:1234 | Full rebuild on every state change |
 | Inline sorting during build | new_library_screen.dart:3647 | 5-20ms for 1000+ albums |
 | Multiple setState for author images | new_library_screen.dart:1017 | 20+ rebuilds as images load |
 | SecureStorage migration every startup | secure_storage_service.dart:103 | 100-300ms wasted |
-**Key files:**
+### Architecture
- lib/screens/album_details_screen.dart (12 instances)
+| Issue | File | Impact |
- lib/screens/artist_details_screen.dart (8 instances)
+|-------|------|--------|
- lib/screens/audiobook_detail_screen.dart (3 instances)
+| State duplication across 4 providers | providers/*.dart | Maintenance burden, sync issues |
- lib/screens/audiobook_series_screen.dart (2 instances)
+| 8 duplicate `_cycle*ViewMode()` methods | new_library_screen.dart:251-402 | DRY violation |
- lib/screens/audiobook_author_screen.dart (2 instances)
+| 60+ duplicate getter/setter pairs | settings_service.dart:500-1000 | Code bloat |
 | Global singleton NavigationProvider | navigation_provider.dart:40 | Untestable |
 | CacheService duplicated in providers | Multiple | Memory waste, inconsistency |
-### BorderRadius.circular (40+ instances)
+### UI/UX
-Cannot use `const BorderRadius.circular()` directly. Alternative: `const BorderRadius.all(Radius.circular(X))`.
+| Issue | File | Impact |
 |-------|------|--------|
 | Hardcoded bottom spacing (140, 164, 100) | Multiple detail screens | Content obscured by player |
 | Inconsistent button sizes (44 vs 50) | Multiple screens | Visual disharmony |
 | No debounce on card taps | album_card.dart:118 | Double navigation possible |
 | Missing PopScope on AudiobookSeriesScreen | audiobook_series_screen.dart:276 | Adaptive colors not cleared |
 ### Error Handling
 | Issue | File | Impact |
 |-------|------|--------|
 | No Flutter error boundaries | main.dart | Red error screen on build failure |
 | API returns empty list on error | music_assistant_api.dart | Can't distinguish error from empty |
 ---
-## 3. MEDIUM: Scroll Performance - Missing Image Cache Parameters
+## Medium Severity Issues
-### CachedNetworkImage without memCacheWidth/Height
+### Performance
 - PaletteGenerator on main isolate (10-30ms blocking)
 - Multiple `SharedPreferences.getInstance()` calls (132 occurrences)
 - AppStartup polling loop with fixed 250ms delay
 - SystemThemeHelper FutureBuilder recreated on every build
-**lib/screens/new_library_screen.dart:**
+### UI Consistency
- Line 1395-1402: Author image (48x48) - missing cache params
+- Border radius varies: 8, 12, 20, 22, 25 for same element types
- Line 1480-1486: Author card image - missing cache params
+- `SizedBox(height: 8)` appears 40+ times instead of `Spacing.vGap8`
- Line 1572-1580: Audiobook cover (56x56) - missing cache params
+- Hardcoded colors for status (Colors.red, Colors.green)
- Line 1740-1745: Audiobook grid cover - missing cache params
+- Inconsistent icon sizes across screens
 - Line 1959-1969: Playlist cover (56x56) - missing cache params
 - Line 2143-2152: Playlist grid covers - missing cache params
 - Line 2973-2981: Album cover (56x56) - missing cache params
-**Note:** DecorationImage with CachedNetworkImageProvider cannot have cache size specified (structural Flutter limitation).
+### State Management
 - Over-notification (multiple notifyListeners in single methods)
 - Wide Consumer scope (watch instead of select)
 - Missing dispose() in some providers
 - Inconsistent async state handling (loading/error)
 ### Navigation
 - `isQueuePanelOpen` vs `isQueuePanelTargetOpen` inconsistency
 - `popToHome()` doesn't clear adaptive colors
 - Infinite navigation loop possible (Album → Artist → Album)
 - Orphaned Hero animations in podcast_card, radio_station_card
 ### Data/Caching
 - Unbounded `_podcastCoverCache`
 - SyncService listener not removed on error
 - Redundant API calls between providers
 - Fire-and-forget persistence race condition
 ### Error Handling
 - No zone error handler for async exceptions
 - `retryCritical()` retries all errors including non-recoverable
 - No user notification of offline queue status
 - DisconnectedState not used consistently
 ---
-## 4. LOW: Code Duplication
+## Quick Wins (High Impact, Low Effort)
-### View Mode Cycling Functions (8 nearly identical functions)
+| # | Task | File(s) | Effort |
-**File:** lib/screens/new_library_screen.dart
+|---|------|---------|--------|
-
+| 1 | Replace hardcoded bottom spacing with `BottomSpacing.withMiniPlayer` | Detail screens | 30 min |
-Functions that follow identical switch/case pattern:
+| 2 | Add navigation debounce to card widgets | album_card, artist_card, etc. | 1 hr |
- `_cycleArtistsViewMode()` (line 184)
+| 3 | Fix touch targets to 48x48 minimum | new_library_screen.dart | 15 min |
- `_cycleAlbumsViewMode()` (line 200)
+| 4 | Add migration skip flag for SecureStorage | secure_storage_service.dart | 30 min |
- `_cyclePlaylistsViewMode()` (line 216)
+| 5 | Add Flutter error boundary | main.dart | 30 min |
- `_cycleAuthorsViewMode()` (line 232)
+| 6 | Use `context.select()` instead of `context.watch()` | global_player_overlay, etc. | 2 hr |
- `_cycleAudiobooksViewMode()` (line 248)
+| 7 | Cache `SharedPreferences.getInstance()` | settings_service.dart | 30 min |
 - `_cycleSeriesViewMode()` (line 286)
 - `_cycleRadioViewMode()` (line 303)
 - `_cyclePodcastsViewMode()` (line 319)
 **Recommendation:** Create generic utility function.
 ### Duplicated Color Constants (3 files)
 Series fallback colors defined identically in:
 - lib/widgets/series_row.dart:246-253
 - lib/screens/audiobook_series_screen.dart:466-473
 - lib/screens/new_library_screen.dart:2112-2119
 **Recommendation:** Extract to lib/constants/colors.dart
 ---
-## 5. POSITIVE FINDINGS (Already Optimized)
+## Refactoring Roadmap
- **RepaintBoundary**: Properly implemented in all list item widgets
+### Phase 1: Quick Wins (1-2 days)
- **ListView.builder**: Used consistently with cacheExtent: 1000
+- Fix touch targets
- **ScrollController disposal**: All 8+ controllers properly disposed
+- Fix bottom spacing
- **Animation patterns**: Proper listener cleanup in expandable_player.dart
+- Add navigation debounce
- **Debounced operations**: Color extraction debounced to 300ms
+- Add error boundaries
 - Cache SharedPreferences singleton
 ### Phase 2: Performance (3-5 days)
 - Parallelize startup operations
 - Replace `context.watch()` with `context.select()`
 - Batch database inserts
 - Add SecureStorage migration skip flag
 - Fix over-notification in provider
 ### Phase 3: Design System (1 week)
 - Systematic design token adoption
 - Standardize button sizes (44 vs 50)
 - Standardize border radius values
 - Create StatusColors semantic tokens
 - Replace all magic numbers
 ### Phase 4: Architecture (2-3 weeks)
 - ~~Split MusicAssistantProvider into focused managers~~ **DEFERRED** - MusicAssistantProvider has evolved with Sendspin, Cast-Sendspin ID mapping, position tracker integration. Splitting would require ~1600 lines of sync work. Code is working and tested.
 - ~~Split new_library_screen into tab widgets~~ **DEFERRED** - Tabs have tight state coupling (15+ view modes, 15+ sort orders, 10 scroll controllers). Extraction would require InheritedWidget/callbacks for all shared state. Risk outweighs benefit.
 - ✅ Extract generic helpers for SettingsService - Reduced from 1,031 to 874 lines (~15%)
 - ✅ Remove/integrate unused providers - Deleted PlayerProvider (964 lines), LibraryProvider, ConnectionProvider (651 lines total)
 - ~~Split music_assistant_api.dart by domain~~ **DEFERRED** - All methods share WebSocket connection and auth state. Clean extraction would require connection manager abstraction.
 ---
-## Recommended Action Plan
+## Positive Findings
-### Phase 1: Quick Wins (Low Risk)
+The codebase already demonstrates many good practices:
 1. Replace `colorScheme.background` with `colorScheme.surface` (20 locations)
 2. Add `const` to EdgeInsets.zero instances
-### Phase 2: Image Optimization
+- **Performance awareness**: `// PERF:` comments, RepaintBoundary (55 occurrences), image caching (80 memCacheWidth/Height)
-1. Add memCacheWidth/memCacheHeight to CachedNetworkImage instances in new_library_screen.dart
+- **Caching**: Multi-tier caching with LRU eviction, proper TTLs, proper DB indexes
-
+- **Error handling**: DebugLogger, RetryHelper, OfflineActionQueue well-implemented
-### Phase 3: Code Cleanup (Optional)
+- **Theme system**: Material You support, adaptive colors from album art
-1. Extract view mode cycling to utility function
+- **Offline support**: Cache-first loading, graceful degradation
-2. Centralize color constants
+- **Navigation**: Consistent FadeSlidePageRoute, proper Hero animations (mostly)
 ---
-## Files by Complexity
+## Files by Priority
-| File | Lines | Status |
+| Priority | File | Lines | Key Issues |
-|------|-------|--------|
+|----------|------|-------|------------|
-| lib/screens/search_screen.dart | 3,489 | Good structure, minor fixes needed |
+| 1 | music_assistant_provider.dart | 5,443 | God object, over-notification |
-| lib/screens/new_library_screen.dart | 3,351 | Good performance, some duplication |
+| 2 | new_library_screen.dart | 4,209 | God class, performance, touch targets |
-| lib/widgets/expandable_player.dart | 2,577 | Well-optimized animations |
+| 3 | main.dart | 549 | Startup blocking, error boundaries |
 | 4 | music_assistant_api.dart | 3,434 | Silent failures, needs splitting |
 | 5 | settings_service.dart | 1,019 | Code duplication, no caching |
 | 6 | expandable_player.dart | ~800 | Wide Consumer scope |
 | 7 | global_player_overlay.dart | ~500 | BottomSpacing source, Consumer scope |
 | 8 | All detail screens | Various | Hardcoded bottom spacing |
 | 9 | All card widgets | Various | Navigation debounce, design tokens |
 ---
 ## Audit Methodology
 This audit was conducted using 9 parallel sub-agents analyzing:
 **UI Continuity (3 agents)**
 1. Navigation & Flow - back button, Hero animations, tab preservation
 2. Visual Consistency - design tokens, spacing, typography
 3. Component Placement - touch targets, bottom spacing, modals
 **Performance (3 agents)**
 4. Rendering Performance - ListView.builder, const, rebuilds
 5. Data & Caching - streams, invalidation, memory bounds
 6. Startup & Load Time - blocking operations, initialization order
 **Logic/Best Practices (3 agents)**
 7. State Management - Provider patterns, notification frequency
 8. Error Handling - try-catch, boundaries, resilience
 9. Code Quality - file size, duplication, SOLID principles
 ---
 ## Conclusion
 The Ensemble app is well-architected at the macro level but has accumulated technical debt in its largest files. The most impactful improvements would be:
 1. **Splitting the two 4,000+ line files** into focused components
 2. **Adopting design tokens systematically** for visual consistency
 3. **Optimizing startup sequence** for faster app launch
 4. **Using granular state management** (select vs watch) for better performance
 The quick wins section provides immediate value with minimal risk, while the roadmap offers a path to sustainable improvement.
@@ -20,44 +20,63 @@ This application was built with AI-assisted development using **Claude Code** an
 ## Features
 ### Local Playback
- **Stream to Your Phone** - Play music from your Music Assistant library directly on your mobile device
+- **Stream to Your Phone** - Play music from your Music Assistant library directly on your mobile device via Sendspin protocol
 - **Background Playback** - Music continues playing when the app is minimized
 - **Media Notifications** - Control playback from your notification shade with album art display
 - **Instant Response** - Pause/resume in ~300ms
 ### Remote Control
 - **Multi-Player Support** - Control any speaker or device connected to Music Assistant
- **Device Selector** - Quickly switch between your phone and other players
+- **Device Selector** - Swipe down on mini player to reveal all your devices
 - **Multi-Room Grouping** - Long-press any player to sync it with the current player
 - **Full Playback Controls** - Play, pause, skip, seek, and adjust volume
- **Queue Management** - View and manage the playback queue
+- **Volume Precision Mode** - Hold the volume slider for fine-grained control with haptic feedback
 - **Power Control** - Turn players on/off directly from the mini player
 ### Queue Management
 - **View & Manage Queue** - See upcoming tracks in the playback queue
 - **Drag to Reorder** - Instant drag handles for reordering tracks
 - **Swipe to Delete** - Remove tracks with a simple swipe gesture
 ### Home Screen
- **Customizable Rows** - Toggle Recently Played, Discover Artists, and Discover Albums
+- **Customizable Rows** - Toggle and reorder: Recently Played, Discover Artists, Discover Albums
- **Favorites Rows** - Optional rows for Favorite Albums, Artists, and Tracks
+- **Favorites Rows** - Optional rows for Favorite Albums, Artists, Tracks, Playlists, and Radio Stations
 - **Adaptive Layout** - Rows scale properly for different screen sizes and aspect ratios
 - **Pull to Refresh** - Refresh content with a simple pull gesture
-### Library Browsing
+### Library
- **Browse Your Collection** - Artists, albums, playlists, and tracks from all your music sources
+- **Music** - Browse artists, albums, playlists, and tracks from all your music sources
 - **Radio Stations** - Browse and play radio stations with list or grid view
 - **Podcasts** - Browse podcasts, view episodes with descriptions and publish dates
 - **Audiobooks** - Browse by title, series, or author with progress tracking
 - **Favorites Filter** - Toggle to show only your favorite items
- **Album Details** - View track listings with artwork
+- **Letter Scrollbar** - Fast navigation through long lists
- **Artist Details** - View artist albums and top tracks
+
- **Playlist Support** - Browse and play your playlists
+### Search
- **Search** - Find music across your entire library
+- **Universal Search** - Find music, podcasts, radio stations, playlists, and audiobooks
 - **Fuzzy Matching** - Typo-tolerant search (e.g., "beetles" finds "Beatles")
 - **Smart Scoring** - Results ranked by relevance with colored type indicators
 - **Search History** - Quickly access your recent searches
 - **Quick Actions** - Long-press any result to add to queue or play next
 ### Audiobooks
 - **Audiobooks Tab** - Browse your audiobook library with grid/list view options
 - **Series Support** - View audiobooks organized by series with collage cover art
 - **Author Browsing** - Browse audiobooks by author
 - **Chapter Navigation** - Jump between chapters with timestamp display
 - **Progress Tracking** - Track your listening progress across sessions
 - **Continue Listening** - Pick up where you left off
 - **Mark as Finished/Unplayed** - Manage your reading progress
 - **Series Support** - View audiobooks organized by series with collage cover art
 ### Podcasts
 - **Episode Browser** - View full episode list with artwork and descriptions
 - **Skip Controls** - Skip forward/backward during playback
 - **High-Resolution Artwork** - Fetched via iTunes for best quality
 ### Smart Features
 - **Instant App Restore** - App loads instantly with cached library data while syncing in background
 - **Auto-Reconnect** - Automatically reconnects when connection is lost
 - **Offline Browsing** - Browse your cached library even when disconnected
 - **Hero Animations** - Smooth transitions between screens
 - **Welcome Screen** - Guided onboarding for first-time users
 ### Theming
 - **Material You** - Dynamic theming based on your device's wallpaper
@@ -67,14 +86,16 @@ This application was built with AI-assisted development using **Claude Code** an
 ## Screenshots
 <div align="center">
-  <img src="assets/screenshots/1.png?v=2" alt="Connection Screen" width="150">
+  <img src="assets/screenshots/1.png?v=3" alt="Screenshot 1" width="150">
-  <img src="assets/screenshots/2.png?v=2" alt="Home Screen" width="150">
+  <img src="assets/screenshots/2.png?v=3" alt="Screenshot 2" width="150">
-  <img src="assets/screenshots/3.png?v=2" alt="Album Details" width="150">
+  <img src="assets/screenshots/3.png?v=3" alt="Screenshot 3" width="150">
-  <img src="assets/screenshots/4.png?v=2" alt="Now Playing" width="150">
+  <img src="assets/screenshots/4.png?v=3" alt="Screenshot 4" width="150">
-  <img src="assets/screenshots/5.png?v=2" alt="Queue" width="150">
+  <img src="assets/screenshots/5.png?v=3" alt="Screenshot 5" width="150">
-  <img src="assets/screenshots/6.png?v=2" alt="Settings" width="150">
+  <img src="assets/screenshots/6.png?v=3" alt="Screenshot 6" width="150">
-  <img src="assets/screenshots/7.png?v=2" alt="Audiobooks" width="150">
+  <img src="assets/screenshots/7.png?v=3" alt="Screenshot 7" width="150">
-  <img src="assets/screenshots/8.png?v=2" alt="Audiobook Player" width="150">
+  <img src="assets/screenshots/8.png?v=3" alt="Screenshot 8" width="150">
  <img src="assets/screenshots/9.png?v=3" alt="Screenshot 9" width="150">
  <img src="assets/screenshots/10.png?v=3" alt="Screenshot 10" width="150">
 </div>
 ## Download
@@ -84,9 +105,29 @@ Download the latest release from the [Releases page](https://github.com/CollotsS
 ## Setup
 1. Launch the app
-2. Enter your Music Assistant server URL (e.g., `music.example.com` or `192.168.1.100`)
+2. Enter your Music Assistant server URL
 3. Connect to your server
-4. Start playing! Music plays on your phone by default, or tap the device icon to choose a different player.
+4. Start playing! Music plays on your phone by default, or swipe down on the mini player to choose a different player.
 ### Finding Your Server URL
 **Important:** You need the **Music Assistant** URL, not your Home Assistant URL.
 To find the correct URL:
 1. Open Music Assistant web UI
 2. Go to **Settings** > **About**
 3. Look for **Base URL** (e.g., `http://192.168.1.100:8095`)
 ### Home Assistant Add-on Users
 If you run Music Assistant as a Home Assistant add-on:
 - Use the IP address of your Home Assistant server
 - Enter `8095` in the port field
 - Do **not** use your Home Assistant URL or ingress URL
 ### Remote Access
 For access outside your home network, you'll need to expose Music Assistant through a reverse proxy (e.g., Nginx Proxy Manager, Cloudflare Tunnel).
 ## Authentication
@@ -103,7 +144,7 @@ Ensemble supports multiple authentication methods:
 ## Requirements
- Music Assistant server (v2.7.0 beta 20 or later)
+- Music Assistant server (v2.7.0 beta 20 or later recommended)
 - Network connectivity to your Music Assistant server
 - Android device (Android 5.0+)
 - Audiobookshelf provider configured in Music Assistant (for audiobook features)
@@ -11,6 +11,7 @@
        android:label="Ensemble"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher"
        android:appCategory="audio"
        android:usesCleartextTraffic="true"
        android:networkSecurityConfig="@xml/network_security_config">
        <activity
@@ -0,0 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
  <background android:drawable="@color/ic_launcher_background"/>
  <foreground android:drawable="@drawable/ic_launcher_foreground"/>
 </adaptive-icon>
@@ -1,4 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
    <color name="launch_background_color">#1a1a1a</color>
-</resources>
+	<color name="ic_launcher_background">#1a1a1a</color>
 </resources>
@@ -2,6 +2,9 @@ buildscript {
    ext.kotlin_version = '1.9.10'
    repositories {
        google()
        // Use Maven Central mirrors as fallback for 403 errors
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        mavenCentral()
    }
@@ -14,6 +17,9 @@ buildscript {
 allprojects {
    repositories {
        google()
        // Use Maven Central mirrors as fallback for 403 errors
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        mavenCentral()
    }
 }
@@ -0,0 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
 distributionUrl=https\://services.gradle.org/distributions/gradle-8.0-all.zip
@@ -0,0 +1,37 @@
 // Force all repositories to use mirrors first
 allprojects {
    repositories {
        all { ArtifactRepository repo ->
            if (repo instanceof MavenArtifactRepository) {
                def url = repo.url.toString()
                if (url.contains('repo.maven.apache.org') || url.contains('repo1.maven.org')) {
                    remove repo
                }
            }
        }
        // Add mirrors before Maven Central
        maven { url 'https://maven.aliyun.com/repository/central' }
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        maven { url 'https://maven.aliyun.com/repository/public' }
    }
 }
 settingsEvaluated { settings ->
    settings.pluginManagement {
        repositories {
            all { ArtifactRepository repo ->
                if (repo instanceof MavenArtifactRepository) {
                    def url = repo.url.toString()
                    if (url.contains('repo.maven.apache.org') || url.contains('repo1.maven.org')) {
                        remove repo
                    }
                }
            }
            maven { url 'https://maven.aliyun.com/repository/central' }
            maven { url 'https://maven.aliyun.com/repository/google' }
            maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
            maven { url 'https://maven.aliyun.com/repository/public' }
        }
    }
 }
@@ -0,0 +1,336 @@
 # Per-Provider Sync Implementation
 ## Date: January 17, 2026
 ## Overview
 This document details the implementation of per-provider sync with source tracking, enabling instant client-side filtering that properly differentiates between multiple accounts of the same provider type (e.g., two different Spotify accounts).
 ## Problem Statement
 ### The Core Issue
 When a user has multiple accounts of the same provider type (e.g., two Spotify accounts: "Chris Laycock" and "Bababagoly"), the existing provider filter couldn't differentiate between them.
 **Why?** Music Assistant's `provider_mappings` field on media items shows which providers **CAN PLAY** an item, not which provider **ADDED** it. When both Spotify accounts can play the same artist, both appear in `provider_mappings`, making client-side filtering impossible.
 ### Previous Approach (Failed)
 The initial implementation tried to filter client-side using `provider_mappings`:
 ```dart
 bool isItemAllowedByProviderFilter(MediaItem item) {
  final mappings = item.providerMappings;
  for (final mapping in mappings) {
    if (_providerFilter.contains(mapping.providerInstance)) {
      return true;
    }
  }
  return false;
 }
 ```
 **Result:** Both Spotify accounts showed the same items because `provider_mappings` contained both account IDs for shared content.
 ### Race Condition Issue
 Additionally, when rapidly toggling providers, a race condition occurred:
 1. User toggles Provider A off
 2. Sync starts for remaining providers
 3. User toggles Provider B off before sync completes
 4. First sync completes with wrong filter state
 5. UI shows incorrect results
 ## Solution: Per-Provider Sync with Source Tracking
 ### Concept
 Instead of relying on `provider_mappings`, we:
 1. **Sync each provider separately** using the MA API's `provider` parameter
 2. **Tag each item** with which provider instance(s) returned it
 3. **Store source tracking** in the local database
 4. **Filter client-side** using the source tracking data (instant)
 5. **Background sync** keeps data fresh without blocking UI
 ### Why This Works
 When we call the MA API with `provider: ["spotify--RKnr3jKx"]`, the server returns **only items from that specific account's library**. By syncing each provider separately and remembering which provider returned each item, we can accurately filter.
 ## Implementation Details
 ### 1. Database Schema Update
 **File:** `lib/database/database.dart`
 Added `sourceProviders` column to `LibraryCache` table:
 ```dart
 class LibraryCache extends Table {
  // ... existing columns ...
  /// Provider instance IDs that provided this item (JSON array)
  /// Used for client-side filtering by source provider
  TextColumn get sourceProviders => text().withDefault(const Constant('[]'))();
 }
 ```
 **Schema version:** 5 → 6
 **Migration:**
 ```dart
 if (from < 6) {
  await customStatement(
    "ALTER TABLE library_cache ADD COLUMN source_providers TEXT NOT NULL DEFAULT '[]'"
  );
 }
 ```
 ### 2. Database Service Updates
 **File:** `lib/services/database_service.dart`
 Added `sourceProvider` parameter to `cacheItem()`:
 ```dart
 Future<void> cacheItem<T>({
  required String itemType,
  required String itemId,
  required Map<String, dynamic> data,
  String? sourceProvider,  // NEW: tracks which provider this item came from
 })
 ```
 Added new method to retrieve items with source tracking:
 ```dart
 Future<List<(Map<String, dynamic>, List<String>)>> getCachedItemsWithProviders(String itemType)
 ```
 Returns tuples of `(itemData, sourceProviderIds)`.
 ### 3. SyncService Rewrite
 **File:** `lib/services/sync_service.dart`
 #### New Fields
 ```dart
 // Source provider tracking for client-side filtering
 Map<String, List<String>> _albumSourceProviders = {};
 Map<String, List<String>> _artistSourceProviders = {};
 Map<String, List<String>> _audiobookSourceProviders = {};
 Map<String, List<String>> _playlistSourceProviders = {};
 ```
 #### Per-Provider Sync Logic
 ```dart
 Future<void> syncFromApi(MusicAssistantAPI api, {
  bool force = false,
  List<String>? providerInstanceIds,
 }) async {
  // If specific providers are requested, sync each separately
  if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
    for (final providerId in providerInstanceIds) {
      // Fetch from this specific provider
      final results = await Future.wait([
        api.getAlbums(limit: 1000, providerInstanceIds: [providerId]),
        api.getArtists(limit: 1000, providerInstanceIds: [providerId]),
        // ... etc
      ]);
      // Track source provider for each item
      for (final album in albums) {
        albumMap[album.itemId] = album;
        _albumSourceProviders.putIfAbsent(album.itemId, () => []);
        if (!_albumSourceProviders[album.itemId]!.contains(providerId)) {
          _albumSourceProviders[album.itemId]!.add(providerId);
        }
      }
    }
  }
 }
 ```
 #### Client-Side Filtering Methods
 ```dart
 /// Filter albums by source provider (instant, no network)
 List<Album> getAlbumsFilteredByProviders(Set<String> enabledProviderIds) {
  if (enabledProviderIds.isEmpty || _albumSourceProviders.isEmpty) {
    return _cachedAlbums;
  }
  return _cachedAlbums.where((album) {
    final sources = _albumSourceProviders[album.itemId];
    if (sources == null || sources.isEmpty) return true; // No tracking = show
    return sources.any((s) => enabledProviderIds.contains(s));
  }).toList();
 }
 // Similar methods for artists, audiobooks, playlists
 ```
 ### 4. Library Screen Updates
 **File:** `lib/screens/new_library_screen.dart`
 #### Hybrid Provider Toggle Handler
 ```dart
 void _handleProviderToggle(String providerId, bool enabled) {
  final maProvider = context.read<MusicAssistantProvider>();
  // Instant UI update via global provider toggle
  maProvider.toggleProviderEnabled(providerId, enabled);
  setState(() {}); // Rebuild with client-side filtering
  // Background sync after 1.5s debounce
  _providerFilterDebounce?.cancel();
  _providerFilterDebounce = Timer(const Duration(milliseconds: 1500), () async {
    if (mounted) {
      await maProvider.forceLibrarySync();
      if (mounted) setState(() {});
    }
  });
 }
 ```
 #### Updated Tab Builders
 Artists tab now uses source tracking:
 ```dart
 Widget _buildArtistsTab(BuildContext context, S l10n) {
  return Selector<MusicAssistantProvider, (List<Artist>, bool, Set<String>)>(
    selector: (_, provider) => (
      provider.artists,
      provider.isLoading,
      provider.enabledProviderIds.toSet()
    ),
    builder: (context, data, _) {
      final (allArtists, isLoading, enabledProviders) = data;
      // Client-side filtering using SyncService source tracking
      final syncService = SyncService.instance;
      final filteredArtists = syncService.hasSourceTracking && enabledProviders.isNotEmpty
          ? syncService.getArtistsFilteredByProviders(enabledProviders)
          : allArtists;
      // ... rest of build
    },
  );
 }
 ```
 Similar updates for albums, playlists, and audiobooks tabs.
 ### 5. Provider Instance Model
 **File:** `lib/models/provider_instance.dart` (new file)
 ```dart
 class ProviderInstance {
  final String instanceId;  // e.g., "spotify--abc123"
  final String domain;      // e.g., "spotify"
  final String name;        // e.g., "Spotify (John's Account)"
  final bool available;
  /// Known music provider domains
  static const Set<String> musicProviderDomains = {
    'spotify', 'tidal', 'qobuz', 'deezer', 'ytmusic', 'soundcloud',
    'apple_music', 'amazon_music', 'plex', 'subsonic', 'opensubsonic',
    'jellyfin', 'emby', 'navidrome', 'audiobookshelf', 'filesystem',
    'tunein', 'radiobrowser', 'snapcast', 'fully_kiosk',
  };
  bool get isMusicProvider => musicProviderDomains.contains(domain);
 }
 ```
 ## Data Flow
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                     User Toggles Provider                        │
 └─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  1. MusicAssistantProvider.toggleProviderEnabled()              │
 │     - Updates enabledProviderIds                                │
 │     - Triggers setState() for instant UI update                 │
 └─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  2. UI Rebuilds Immediately                                     │
 │     - Selector detects enabledProviderIds change                │
 │     - Calls SyncService.getArtistsFilteredByProviders()         │
 │     - Filters using source tracking (instant, no network)       │
 └─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │  3. Background Sync (after 1.5s debounce)                       │
 │     - forceLibrarySync() called                                 │
 │     - Syncs each enabled provider separately                    │
 │     - Updates source tracking in database                       │
 │     - UI refreshes with fresh data                              │
 └─────────────────────────────────────────────────────────────────┘
 ```
 ## Files Changed
 | File | Changes |
 |------|---------|
 | `lib/database/database.dart` | Added `sourceProviders` column, schema v6, migration |
 | `lib/database/database.g.dart` | Auto-generated from schema changes |
 | `lib/services/database_service.dart` | Added `sourceProvider` param, `getCachedItemsWithProviders()` |
 | `lib/services/sync_service.dart` | Per-provider sync, source tracking maps, filtering methods |
 | `lib/screens/new_library_screen.dart` | Hybrid toggle handler, updated tab builders |
 | `lib/models/provider_instance.dart` | New model for provider instances |
 ## Testing Checklist
 - [ ] Fresh install: First sync should populate source tracking
 - [ ] Toggle single provider: UI updates instantly
 - [ ] Toggle multiple providers rapidly: Debounce prevents race conditions
 - [ ] Two Spotify accounts: Toggling one only shows that account's items
 - [ ] Mixed providers: Toggling Spotify doesn't affect Audiobookshelf items
 - [ ] Legacy cache: Items without source tracking show regardless of filter
 - [ ] Pull to refresh: Refreshes source tracking data
 ## Known Limitations
 1. **First sync required:** Source tracking only works after at least one sync with providers enabled
 2. **Network cost:** Per-provider sync makes N API calls (one per provider) vs. 1 call for all providers
 3. **Items in multiple accounts:** If the same item exists in both Spotify accounts, it will show when either is enabled
 ## Future Improvements
 1. **Incremental sync:** Only sync changed items instead of full library
 2. **Provider-specific cache age:** Different sync intervals per provider
 3. **Offline source tracking:** Persist source tracking independently of full cache
 ## Branch
 All changes are on the `feature/per-provider-sync` branch.
 ```bash
 git checkout feature/per-provider-sync
 ```
 ## Commit
 ```
 feat: Add per-provider sync with source tracking for instant filtering
 - Add sourceProviders column to database schema (v6) for tracking which
  provider instance each item came from
 - Update SyncService to sync each enabled provider separately and tag
  items with their source provider
 - Add client-side filtering methods that use source tracking to properly
  differentiate between multiple accounts of the same provider type
 - Update library UI to use instant client-side filtering with background
  sync for data freshness
 ```
@@ -0,0 +1,217 @@
 # Provider Filter Implementation Notes
 ## Overview
 This document captures the context and learnings from an attempted implementation of provider filtering in the Ensemble app. The goal was to allow users to filter their library to show only items from a specific music provider (e.g., only one Spotify account when multiple are configured).
 ## The Problem
 Users with multiple music provider accounts (e.g., two Spotify accounts: one personal, one family) want to filter their library view to show only items from one specific account. The Music Assistant (MA) web UI successfully implements this feature.
 ## What Works vs What Failed
 ### Works: Different Provider Types
 Filtering between different provider types (e.g., Spotify vs Tidal vs Plex) works correctly. Each provider type has distinct `provider_mappings` entries.
 ### Failed: Multiple Accounts of Same Provider
 Filtering between multiple Spotify accounts (e.g., `spotify--abc123` vs `spotify--xyz789`) does NOT work correctly. The same library items appear regardless of which Spotify account is selected.
 ## Root Cause Analysis
 ### The provider_mappings Problem
 MA's `provider_mappings` field on media items does NOT indicate "which account ADDED this item to the library." Instead, it indicates "which providers CAN PLAY this item."
 Example: An artist "Ari Mason" that exists ONLY in User A's Spotify library will show provider_mappings containing BOTH Spotify accounts:
 ```json
 {
  "provider_mappings": [
    {"provider_instance": "spotify--userA_id", "item_id": "..."},
    {"provider_instance": "spotify--userB_id", "item_id": "..."}
  ]
 }
 ```
 This happens because:
 1. MA's internal database stores that the artist exists
 2. MA knows both Spotify accounts CAN play this artist (Spotify has the content)
 3. MA doesn't track WHICH account originally added the item to the library
 ### MA Web UI Behavior
 The MA web UI's provider filter works differently - it appears to use server-side filtering via the `provider` parameter on library_items API calls. When you select a single provider in MA settings, the API returns only items from that provider's library.
 ## API Investigation
 ### Server-Side Filtering Parameter
 The MA server's `library_items` method accepts a `provider` parameter:
 - Parameter name: `provider` (string or list of strings)
 - Endpoint: `music/{type}/library_items` (e.g., `music/artists/library_items`)
 - Expected behavior: Filter to only return items from the specified provider's library
 ### What We Tried
 1. **Client-side filtering based on provider_mappings**
   - Result: Failed - all Spotify accounts appear in mappings regardless of which added the item
 2. **Server-side filtering with `provider` parameter**
   - Result: Partially implemented but behavior was inconsistent
   - The API accepts the parameter but may not filter correctly for same-provider-type accounts
 3. **Using `provider_instance_id_or_domain` parameter**
   - Result: This parameter is for getting specific items by ID, not for filtering library_items
 ## Code Locations
 ### Files Modified (in stash)
 The implementation attempt is preserved in git stash:
 ```bash
 git stash list  # Look for "provider-filter-and-dropdown-work"
 git stash show -p stash@{0}  # View the changes
 ```
 Key files that were modified:
 1. **lib/providers/music_assistant_provider.dart**
   - `_disabledProviders`: List of disabled provider instance IDs (local app setting)
   - `selectedProviderForFilter`: Returns single enabled provider for server-side filtering
   - `toggleProviderEnabled()`: Toggle provider on/off and trigger re-sync
   - `loadDisabledProviders()`: Load from local settings
   - `filterByProvider()`: Client-side filtering (enhanced version)
   - `isItemAllowedByProviderFilter()`: Check if item should be visible
 2. **lib/services/music_assistant_api.dart**
   - Added `provider` parameter to: `getArtists`, `getAlbums`, `getTracks`, `getRandomArtists`, `getRandomAlbums`
   - Added `MusicProvider` model parsing from `/providers` endpoint
   - `musicProviders` getter: List of available music providers
 3. **lib/services/sync_service.dart**
   - Added `provider` parameter to `syncFromApi()` and `forceSync()`
   - Pass provider filter to API calls during sync
 4. **lib/services/settings_service.dart**
   - `getDisabledMusicProviders()`: Get list of disabled provider IDs
   - `setDisabledMusicProviders()`: Save disabled providers
   - `toggleProviderEnabled()`: Toggle and persist
 5. **lib/screens/settings_screen.dart**
   - UI for toggling individual providers on/off
   - Display provider name and instance ID
 6. **lib/screens/new_library_screen.dart**
   - Integration with provider filtering
 7. **lib/models/music_provider.dart** (new file)
   - Model for MA provider instances
   - Fields: `instanceId`, `domain`, `name`, `available`
 ## Race Condition Issue
 A race condition was identified where:
 1. Initial app sync starts WITHOUT provider filter
 2. User toggles provider filter
 3. `clearCache()` is called
 4. New sync with provider filter tries to start
 5. "Sync already in progress" - new sync is skipped
 6. Result: Old unfiltered data remains
 Fix attempted: Reset `_isSyncing = false` in `clearCache()` to allow fresh sync.
 ## Potential Solutions to Explore
 ### 1. Investigate MA Server-Side Filtering
 The MA server should support filtering by provider. Need to verify:
 - Does the `provider` parameter work for filtering between same-type providers?
 - Is there a different parameter or API endpoint?
 - Check MA source code: https://github.com/music-assistant/server
 ### 2. Library Sync Per Provider
 Instead of syncing all items and filtering, sync each provider's library separately:
 ```dart
 for (final provider in enabledProviders) {
  final items = await api.getAlbums(provider: provider.instanceId);
  // Store with provider association
 }
 ```
 ### 3. Track Item Origin
 Store which provider originally added each item:
 - Modify database schema to track `source_provider`
 - When syncing, record which provider the item came from
 - Filter based on source, not playability
 ### 4. Use MA's Internal Library State
 MA might have internal state about which items are in which provider's library. Investigate:
 - `/music/library/items` endpoint
 - Provider-specific library endpoints
 - MA's database schema for library associations
 ### 5. Check MA User Settings
 The MA web UI's provider filter might be stored in user settings:
 ```dart
 final userInfo = await api.getCurrentUserInfo();
 // Check for provider_filter or similar field
 ```
 ## Testing Notes
 ### Log Messages to Watch
 ```
 🔌 Selected provider for filter: spotify--xxxxx
 🔍 API getArtists args: {limit: 1000, provider: spotify--xxxxx}
 🔍 API getArtists returned XXX items
 🔌 filterByProvider: XXX → YYY (disabled=[...])
 ```
 ### Test Scenario
 1. Configure two Spotify accounts in MA
 2. Add different artists to each account's library
 3. In Ensemble, select only one Spotify account
 4. Verify library shows ONLY that account's items
 5. Switch to other account, verify different items
 ### Expected vs Actual
 - **Expected**: Artist "Ari Mason" (only in Account A) should NOT appear when Account B is selected
 - **Actual**: Artist appears regardless of which account is selected
 ## MA API Reference
 ### Get Providers
 ```
 Command: providers
 Returns: List of provider instances with type, domain, instanceId, name, available
 ```
 ### Library Items with Filter
 ```
 Command: music/artists/library_items
 Args: {
  limit: int,
  offset: int,
  provider: string | list<string>,  // Filter to specific provider(s)
  album_artists_only: bool,
  order_by: string
 }
 ```
 ### Relevant MA Source Files
 - `music_assistant/server/controllers/music.py` - Library item retrieval
 - `music_assistant/server/models/provider.py` - Provider model
 - `music_assistant/server/providers/` - Individual provider implementations
 ## Conclusion
 The core challenge is that MA's `provider_mappings` indicates playability, not ownership. Server-side filtering via the `provider` parameter should work but needs further investigation to understand why it doesn't differentiate between multiple accounts of the same provider type.
 The implementation is preserved in the git stash for future reference. The sorting/dropdown improvements were extracted and committed separately.
@@ -0,0 +1,271 @@
 # Audiobook Provider Filtering Fix
 ## Date: January 17, 2026 (Continuation)
 ## Overview
 This session focused on fixing provider filtering issues discovered after the initial provider filtering improvements:
 1. Audiobooks were not responding to provider filter changes (browse API ignoring `providerInstanceIds`)
 2. UI not updating instantly when toggling providers (missing `notifyListeners()` call)
 3. Audiobook tabs not rebuilding on provider changes (using `context.read` instead of `Selector`)
 ---
 ## Problem Statement
 After implementing capability-based provider filtering for the music library, two issues remained:
 ### Issue 1: Audiobooks Not Filtering During Sync
 The bug report showed:
 ```
 📊 Source tracking: 252 albums, 87 artists have provider info
 📚 Total audiobooks from browse: 186
 ```
 - Albums and artists had provider source tracking
 - Audiobooks had NO provider source tracking (not listed)
 - All 186 audiobooks were returned regardless of provider selection
 ### Issue 2: UI Not Updating Instantly
 When toggling providers in the library menu:
 - Music tabs weren't updating immediately
 - Audiobooks required manual pull-to-refresh
 - Changes only appeared after ~600ms (debounce timer)
 ---
 ## Root Cause Analysis
 ### Cause 1: Browse API Ignoring Provider Filter
 In `lib/services/music_assistant_api.dart`, when ABS library filtering is enabled, the `getAudiobooks()` function uses the browse API but was **ignoring** the `providerInstanceIds` parameter:
 ```dart
 // BEFORE: providerInstanceIds was ignored when using browse API
 if (enabledLibraries != null && enabledLibraries.isNotEmpty) {
  return await _getAudiobooksFromBrowse(enabledLibraries, favoriteOnly: favoriteOnly);
 }
 ```
 ### Cause 2: `notifyListeners()` Called Too Late
 In `lib/providers/music_assistant_provider.dart`, the `toggleProviderEnabled()` function only called `notifyListeners()` **inside** the 600ms debounce timer:
 ```dart
 // BEFORE: notifyListeners only called after 600ms debounce
 _providerFilterDebounceTimer = Timer(const Duration(milliseconds: 600), () {
  forceLibrarySync();
  notifyListeners();  // Too late! UI should update immediately
 });
 ```
 ### Cause 3: Audiobook Tabs Not Listening for Changes
 The audiobook tabs used `context.read<MusicAssistantProvider>()` which doesn't trigger rebuilds when the provider changes:
 ```dart
 // BEFORE: context.read doesn't listen for changes
 Widget _buildBooksAuthorsTab(BuildContext context, S l10n) {
  final maProvider = context.read<MusicAssistantProvider>();
  final enabledProviders = maProvider.enabledProviderIds.toSet();
  // ... widget doesn't rebuild when enabledProviders changes
 }
 ```
 ---
 ## Solutions
 ### Fix 1: Browse API Provider Filtering
 **File:** `lib/services/music_assistant_api.dart` (lines 760-785)
 Added logic to filter library paths by provider ID before browsing:
 ```dart
 if (enabledLibraries != null && enabledLibraries.isNotEmpty) {
  _logger.log('📚 getAudiobooks: enabledLibraries=$enabledLibraries, providerInstanceIds=$providerInstanceIds');
  // If specific providers are requested, filter libraries to only matching providers
  // Library paths start with provider ID (e.g., "audiobookshelf--abc123://lb...")
  var librariesToBrowse = enabledLibraries;
  if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
    librariesToBrowse = enabledLibraries.where((libPath) {
      // Extract provider ID from library path (everything before "://")
      final providerEnd = libPath.indexOf('://');
      if (providerEnd == -1) return false;
      final providerId = libPath.substring(0, providerEnd);
      return providerInstanceIds.contains(providerId);
    }).toList();
    // If no libraries match the requested providers, return empty
    if (librariesToBrowse.isEmpty) {
      return [];
    }
  }
  return await _getAudiobooksFromBrowse(librariesToBrowse, favoriteOnly: favoriteOnly);
 }
 ```
 ### Fix 2: Immediate `notifyListeners()` Call
 **File:** `lib/providers/music_assistant_provider.dart` (line 1149)
 Moved `notifyListeners()` to fire immediately after `_enabledProviderIds` changes:
 ```dart
 // Reload the enabled providers
 final savedEnabled = await SettingsService.getEnabledMusicProviders();
 _enabledProviderIds = savedEnabled ?? [];
 // Notify listeners IMMEDIATELY so UI rebuilds with client-side filtering
 // This enables instant UI updates using cached data with source tracking
 notifyListeners();
 // Cancel any pending debounce timer
 _providerFilterDebounceTimer?.cancel();
 // Start debounced sync - waits 600ms for user to finish toggling
 // This refreshes the cache with new data from enabled providers
 _providerFilterDebounceTimer = Timer(const Duration(milliseconds: 600), () {
  _logger.log('🔄 Debounce complete, starting library sync...');
  forceLibrarySync();
 });
 ```
 ### Fix 3: Audiobook Tabs Use Selector
 **File:** `lib/screens/new_library_screen.dart`
 Wrapped `_buildBooksAuthorsTab` and `_buildAllBooksTab` in `Selector` to rebuild when `enabledProviderIds` changes:
 ```dart
 Widget _buildBooksAuthorsTab(BuildContext context, S l10n) {
  // Use Selector to rebuild when enabledProviderIds changes
  return Selector<MusicAssistantProvider, Set<String>>(
    selector: (_, provider) => provider.enabledProviderIds.toSet(),
    builder: (context, enabledProviders, _) {
      final syncService = SyncService.instance;
      // Client-side filtering using SyncService source tracking for instant updates
      var audiobooks = syncService.hasSourceTracking && enabledProviders.isNotEmpty
          ? syncService.getAudiobooksFilteredByProviders(enabledProviders)
          : List<Audiobook>.from(_audiobooks);
      // ... rest of widget
    },
  );
 }
 ```
 ### Fix 4: Enhanced Sync Logging
 **File:** `lib/services/sync_service.dart`
 Added audiobook counts to logging:
 ```dart
 // Per-provider log (line 237)
 _logger.log('  📥 Got ${albums.length} albums, ${artists.length} artists, ${audiobooks.length} audiobooks from $providerId');
 // Source tracking summary (line 323)
 _logger.log('📊 Source tracking: ${_albumSourceProviders.length} albums, ${_artistSourceProviders.length} artists, ${_audiobookSourceProviders.length} audiobooks have provider info');
 ```
 ---
 ## Data Flow After Fixes
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                    User Toggles Provider                         │
 │                                                                  │
 │   1. toggleProviderEnabled() called                             │
 │   2. _enabledProviderIds updated                                │
 │   3. notifyListeners() called IMMEDIATELY                       │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                    Selectors Detect Change                       │
 │                                                                  │
 │   Music tabs: Selector<..., (List, bool, Set<String>)>         │
 │   Audiobook tabs: Selector<..., Set<String>>                    │
 │                                                                  │
 │   → All tabs rebuild immediately                                 │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                Client-Side Filtering (Instant)                   │
 │                                                                  │
 │   syncService.getAlbumsFilteredByProviders(enabledProviders)    │
 │   syncService.getArtistsFilteredByProviders(enabledProviders)   │
 │   syncService.getAudiobooksFilteredByProviders(enabledProviders)│
 │                                                                  │
 │   → Uses EXISTING cache with source tracking                    │
 │   → Instant UI update, no network required                      │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │              Background Sync (After 600ms Debounce)              │
 │                                                                  │
 │   - Refreshes cache with new data from enabled providers        │
 │   - Updates source tracking                                      │
 │   - Only needed when ENABLING providers (to fetch new data)     │
 └─────────────────────────────────────────────────────────────────┘
 ```
 ---
 ## Files Changed
 | File | Changes |
 |------|---------|
 | `lib/services/music_assistant_api.dart` | Added provider filtering to browse API path in `getAudiobooks()`, added debug logging |
 | `lib/services/sync_service.dart` | Added audiobook counts to per-provider and summary logs |
 | `lib/providers/music_assistant_provider.dart` | Moved `notifyListeners()` to fire immediately on provider toggle |
 | `lib/screens/new_library_screen.dart` | Wrapped audiobook tabs in `Selector` to rebuild on provider changes |
 ---
 ## Expected Behavior After Fixes
 1. **Instant UI Updates:** When you toggle a provider, the library immediately updates using client-side filtering
 2. **Audiobook Source Tracking:** Audiobooks now have provider source tracking (visible in logs)
 3. **Audiobook Tab Rebuilds:** Both audiobook tabs (Authors and All Books) rebuild instantly on provider toggle
 4. **Music Tab Consistency:** Music tabs continue to work as before, now with immediate rebuilds
 ---
 ## Testing Checklist
 - [ ] Toggle a music provider, verify instant UI update (no 600ms delay)
 - [ ] Toggle between different Spotify accounts, verify correct filtering
 - [ ] Sync with ABS library filtering enabled
 - [ ] Verify audiobooks appear in source tracking log
 - [ ] Toggle ABS provider off in library menu
 - [ ] Verify audiobooks list becomes empty immediately (no pull-to-refresh needed)
 - [ ] Toggle ABS provider back on
 - [ ] Verify audiobooks reappear after sync completes
 - [ ] Test with multiple providers (Spotify audiobooks + ABS)
 ---
 ## Related Documentation
 - `docs/SESSION_2026_01_17_PROVIDER_FILTERING.md` - Initial provider filtering implementation
 - `docs/PER_PROVIDER_SYNC_IMPLEMENTATION.md` - Per-provider sync architecture
 ---
 ## Known Limitations
 1. **Series Tab:** The Series tab still doesn't filter by provider. Series are fetched as `AudiobookSeries` objects without per-provider tracking.
 2. **Mixed Provider Scenario:** If user has both Spotify audiobooks and ABS audiobooks, and ABS library filtering is enabled, Spotify audiobooks may not be fetched because the browse API path is taken. This is a pre-existing architectural limitation.
 3. **Enabling Providers:** When ENABLING a previously disabled provider, the UI updates immediately but shows empty until the background sync completes (because the cache doesn't have that provider's data yet). This is expected behavior.
@@ -0,0 +1,217 @@
 # Session 2026-01-17: Optimistic Updates & Podcast Provider Filtering
 ## Overview
 This session focused on fixing provider filtering for podcasts, resolving iTunes podcast provider issues, and implementing optimistic updates for library buttons across detail screens.
 ## Issues Addressed
 ### 1. Podcast Provider Counts Showing Incorrectly
 **Problem**: All Spotify accounts showed the same podcast count instead of only counting podcasts owned by each account.
 **Root Cause**: The podcast counting logic wasn't checking the `inLibrary` field on provider mappings.
 **Solution**:
 - Added `inLibrary` field to `ProviderMapping` model
 - Updated `getProvidersWithPodcasts()` to only count mappings where `inLibrary == true`
 - Updated podcast filtering in library screen to check `inLibrary` field
 **Files Modified**:
 - `lib/models/media_item.dart` - Added `inLibrary` field
 - `lib/providers/music_assistant_provider.dart` - Updated counting logic
 - `lib/screens/new_library_screen.dart` - Updated filtering logic
 ### 2. iTunes Podcasts Not Appearing in Library
 **Problem**: Podcasts added from iTunes search weren't showing in library and iTunes provider filter showed 0 count.
 **Investigation**:
 - Added `itunes_podcasts` to provider capabilities and music provider domains
 - Added synthetic provider instance creation for search-only providers
 - Added debug logging to understand podcast loading
 **Resolution**: The issue was with Music Assistant's iTunes podcast provider itself - podcasts added via iTunes weren't being properly stored in the MA library. The user removed the iTunes provider from MA and re-added podcasts via Spotify search as a workaround.
 **Files Modified**:
 - `lib/models/provider_instance.dart` - Added `itunes_podcasts` to capabilities
 ### 3. Episode Loading Failing for Non-Library Podcasts
 **Problem**: When a podcast was removed from library, the old library ID became invalid and episodes wouldn't load.
 **Solution**: Added fallback logic to try loading episodes via provider mappings when the primary ID fails.
 **Files Modified**:
 - `lib/screens/podcast_detail_screen.dart` - Added fallback episode loading
 ### 4. Search Filtering Rework
 **Problem**: Server-side provider filtering was being applied to search results when it should only apply when the "in library" toggle is enabled.
 **Solution**:
 - Removed `filterSearchResults()` calls from search methods
 - Added client-side `_filterByEnabledProviders()` helper
 - Applied filtering only when `_libraryOnly` toggle is ON
 **Files Modified**:
 - `lib/providers/music_assistant_provider.dart` - Removed filterSearchResults calls
 - `lib/screens/search_screen.dart` - Added client-side filtering
 ### 5. Library Buttons Not Updating Immediately
 **Problem**: Add/remove library buttons on detail screens waited for API response before updating, causing perceived lag.
 **Solution**: Implemented optimistic updates - update UI immediately, revert on failure.
 **Files Modified**:
 - `lib/screens/podcast_detail_screen.dart`
 - `lib/screens/album_details_screen.dart`
 - `lib/screens/artist_details_screen.dart`
 ## Code Changes
 ### ProviderMapping.inLibrary Field
 ```dart
 // lib/models/media_item.dart
 class ProviderMapping {
  final String itemId;
  final String providerDomain;
  final String providerInstance;
  final bool available;
  final Map<String, dynamic>? audioFormat;
  final bool inLibrary;  // NEW: indicates ownership
  factory ProviderMapping.fromJson(Map<String, dynamic> json) {
    return ProviderMapping(
      // ... other fields ...
      inLibrary: json['in_library'] == true || json['in_library'] == 1,
    );
  }
 }
 ```
 ### Podcast Provider Counting
 ```dart
 // lib/providers/music_assistant_provider.dart
 Map<String, int> getProvidersWithPodcasts() {
  final counts = <String, int>{};
  for (final item in _podcasts) {
    final mappings = item.providerMappings;
    if (mappings != null) {
      for (final mapping in mappings) {
        // Only count if this provider "owns" the item
        if (mapping.inLibrary) {
          final instanceId = mapping.providerInstance;
          if (instanceId.isNotEmpty) {
            counts[instanceId] = (counts[instanceId] ?? 0) + 1;
          }
        }
      }
    }
  }
  return counts;
 }
 ```
 ### Optimistic Update Pattern
 ```dart
 // Example from podcast_detail_screen.dart
 Future<void> _toggleLibrary() async {
  final newState = !_isInLibrary;
  // OPTIMISTIC UPDATE: Update UI immediately
  setState(() {
    _isInLibrary = newState;
  });
  if (mounted) {
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(content: Text(S.of(context)!.addedToLibrary)),
    );
  }
  // Fire and forget - API call happens in background
  maProvider.addToLibrary(...).catchError((e) {
    // Revert on failure
    if (mounted) {
      setState(() {
        _isInLibrary = !newState;
      });
    }
  });
 }
 ```
 ### Client-Side Search Filtering
 ```dart
 // lib/screens/search_screen.dart
 Map<String, List<MediaItem>> _filterByEnabledProviders(
  Map<String, List<MediaItem>> results,
  Set<String> enabledProviders,
 ) {
  if (enabledProviders.isEmpty) return results;
  bool isItemAllowed(MediaItem item) {
    final mappings = item.providerMappings;
    if (mappings == null || mappings.isEmpty) return true;
    return mappings.any((m) => m.inLibrary && enabledProviders.contains(m.providerInstance));
  }
  return {
    for (final entry in results.entries)
      entry.key: entry.value.where(isItemAllowed).toList(),
  };
 }
 // Applied when setting results:
 if (_libraryOnly) {
  final enabledProviders = provider.enabledProviderIds.toSet();
  combinedResults = _filterByEnabledProviders(combinedResults, enabledProviders);
 }
 ```
 ## Provider Capabilities Update
 ```dart
 // lib/models/provider_instance.dart
 static const Map<String, Set<String>> providerCapabilities = {
  'spotify': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
  'ytmusic': {'artists', 'albums', 'tracks', 'playlists', 'podcasts'},
  'apple_music': {'artists', 'albums', 'tracks', 'playlists', 'podcasts'},
  'plex': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
  'jellyfin': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
  'emby': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
  'audiobookshelf': {'audiobooks', 'podcasts'},
  'itunes_podcasts': {'podcasts'},  // NEW
  'tunein': {'radio', 'podcasts'},
  // ... other providers
 };
 ```
 ## Summary of All Modified Files
 | File | Changes |
 |------|---------|
 | `lib/models/media_item.dart` | Added `inLibrary` field to ProviderMapping |
 | `lib/models/provider_instance.dart` | Added `itunes_podcasts`, podcasts to capabilities |
 | `lib/providers/music_assistant_provider.dart` | Updated podcast counting, removed filterSearchResults |
 | `lib/screens/new_library_screen.dart` | Updated podcast filtering with inLibrary check |
 | `lib/screens/search_screen.dart` | Added client-side filtering for in-library mode |
 | `lib/screens/podcast_detail_screen.dart` | Optimistic updates, fallback episode loading |
 | `lib/screens/album_details_screen.dart` | Optimistic updates for library button |
 | `lib/screens/artist_details_screen.dart` | Optimistic updates for library button |
 ## Key Learnings
 1. **inLibrary field**: Music Assistant's provider mappings include an `in_library` field that indicates whether the user added the item from that specific provider account. This is essential for accurate per-provider filtering.
 2. **iTunes podcast provider**: The MA iTunes podcast provider is for search only - it doesn't properly store items in the library. Users should add podcasts from streaming providers like Spotify instead.
 3. **Optimistic updates**: For better UX, library toggle buttons should update immediately and only revert if the API call fails, rather than waiting for API response.
 4. **Search vs Library filtering**: Server-side provider filtering should only apply to library views, not search results (unless the "in library" toggle is enabled).
@@ -0,0 +1,263 @@
 # Provider Filtering Improvements
 ## Date: January 17, 2026
 ## Overview
 This session focused on improving the provider filtering system across the app, building on the per-provider sync implementation. Key improvements include a cleaner capability-based architecture, fixing filter visibility bugs, and extending filtering to the audiobooks library.
 ---
 ## Changes Made
 ### 1. Provider Capability Mapping
 **File:** `lib/models/provider_instance.dart`
 Replaced the clunky item-count-based filtering with a static capability map that defines what content types each provider domain supports.
 ```dart
 static const Map<String, Set<String>> providerCapabilities = {
  // Music streaming services
  'spotify': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
  'tidal': {'artists', 'albums', 'tracks', 'playlists'},
  'qobuz': {'artists', 'albums', 'tracks', 'playlists'},
  'deezer': {'artists', 'albums', 'tracks', 'playlists'},
  'ytmusic': {'artists', 'albums', 'tracks', 'playlists'},
  'soundcloud': {'artists', 'albums', 'tracks', 'playlists'},
  'apple_music': {'artists', 'albums', 'tracks', 'playlists'},
  'amazon_music': {'artists', 'albums', 'tracks', 'playlists'},
  // Self-hosted media servers (can have music and audiobooks)
  'plex': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
  'jellyfin': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
  'emby': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks'},
  // Music-only servers
  'subsonic': {'artists', 'albums', 'tracks', 'playlists'},
  'opensubsonic': {'artists', 'albums', 'tracks', 'playlists'},
  'navidrome': {'artists', 'albums', 'tracks', 'playlists'},
  'filesystem': {'artists', 'albums', 'tracks', 'playlists'},
  // Audiobook-only providers
  'audiobookshelf': {'audiobooks'},
  // Radio providers
  'tunein': {'radio'},
  'radiobrowser': {'radio'},
  // Player/system providers (no library content)
  'snapcast': <String>{},
  'fully_kiosk': <String>{},
 };
 ```
 **Added helper methods:**
 ```dart
 Set<String> get supportedContentTypes => providerCapabilities[domain] ?? <String>{};
 bool supportsContentType(String category) => supportedContentTypes.contains(category);
 ```
 **Benefits:**
 - Radio providers never show in Artists tab (by design, not by count)
 - Works immediately, even with empty libraries
 - Disabled providers still show in menu (if they support the content type)
 - Clean separation of concerns
 ---
 ### 2. Updated Provider Filtering in MusicAssistantProvider
 **File:** `lib/providers/music_assistant_provider.dart`
 Updated `getRelevantProvidersForCategory()` to filter by capability:
 ```dart
 List<(ProviderInstance, int)> getRelevantProvidersForCategory(String category) {
  // ... get counts ...
  final result = <(ProviderInstance, int)>[];
  for (final provider in _availableMusicProviders) {
    // Only include providers that support this content type
    if (provider.supportsContentType(category)) {
      final count = counts[provider.instanceId] ?? 0;
      result.add((provider, count));
    }
  }
  // ...
 }
 ```
 ---
 ### 3. Simplified Library Menu Provider Filter
 **File:** `lib/screens/new_library_screen.dart`
 Simplified the options menu overlay to show all providers that support the current category:
 **Before (clunky):**
 ```dart
 if (widget.relevantProviders.where((p) {
  final hasItems = p.$2 > 0;
  final isDisabledByUser = widget.enabledProviderIds.isNotEmpty &&
      !widget.enabledProviderIds.contains(p.$1.instanceId);
  return hasItems || isDisabledByUser;
 }).length > 1) ...[
 ```
 **After (clean):**
 ```dart
 // relevantProviders is pre-filtered by capability
 if (widget.relevantProviders.length > 1) ...[
  // Show all providers that support this category
  ...widget.relevantProviders.map((providerData) {
 ```
 ---
 ### 4. Removed Provider Toggles from Settings Screen
 **File:** `lib/screens/settings_screen.dart`
 Removed the "Music Providers" section entirely since provider filtering is now handled in the library menu:
 - Removed `_providerEnabled` state variable
 - Removed provider loading code from `_loadSettings()`
 - Removed the entire Music Providers UI section (~100 lines)
 **Rationale:** Single source of truth - provider toggles now only appear in the library menu where they're contextually relevant.
 ---
 ### 5. Fixed Audiobooks Library Provider Filtering
 **File:** `lib/screens/new_library_screen.dart`
 The audiobooks tabs were not filtering by provider - they loaded data once and displayed it without responding to provider changes.
 **Fixed `_buildBooksAuthorsTab()`:**
 ```dart
 final syncService = SyncService.instance;
 final enabledProviders = maProvider.enabledProviderIds.toSet();
 // Client-side filtering using SyncService source tracking
 var audiobooks = syncService.hasSourceTracking && enabledProviders.isNotEmpty
    ? syncService.getAudiobooksFilteredByProviders(enabledProviders)
    : List<Audiobook>.from(_audiobooks);
 // Filter by favorites if enabled
 if (_showFavoritesOnly) {
  audiobooks = audiobooks.where((a) => a.favorite == true).toList();
 }
 // Group filtered audiobooks by author (dynamic, not cached)
 final groupedByAuthor = <String, List<Audiobook>>{};
 for (final book in audiobooks) {
  final authorName = book.authorsString;
  groupedByAuthor.putIfAbsent(authorName, () => []).add(book);
 }
 ```
 **Fixed `_buildAllBooksTab()`:**
 - Same provider filtering pattern
 - Dynamic sorting after filtering
 - Updated PageStorageKey to include provider count for proper rebuild
 ---
 ## Bug Fixes
 ### Provider Filter Menu Disappearing
 **Problem:** When providers were deselected, the background sync would clear the cache and only fetch data for enabled providers. Disabled providers then had 0 items, and the menu required `> 1 providers WITH items` to show. The entire Providers section would disappear.
 **Solution:** Changed to capability-based filtering. The menu now shows all providers that support the category, regardless of item count.
 ### Audiobooks Not Filtering by Provider
 **Problem:** Audiobooks tabs loaded data once into `_audiobooks` and displayed it without provider filtering. Toggling providers in the menu had no effect.
 **Solution:** Added inline provider filtering during build (same pattern as music tabs).
 ---
 ## Files Changed
 | File | Changes |
 |------|---------|
 | `lib/models/provider_instance.dart` | Added `providerCapabilities` map and helper methods |
 | `lib/providers/music_assistant_provider.dart` | Updated `getRelevantProvidersForCategory()` to filter by capability |
 | `lib/screens/new_library_screen.dart` | Simplified menu filter logic, added audiobook provider filtering |
 | `lib/screens/settings_screen.dart` | Removed Music Providers section |
 ---
 ## Architecture
 ```
 ┌─────────────────────────────────────────────────────────────────┐
 │                    Provider Capability Map                       │
 │         (ProviderInstance.providerCapabilities)                  │
 │                                                                  │
 │   spotify → {artists, albums, tracks, playlists, audiobooks}    │
 │   audiobookshelf → {audiobooks}                                 │
 │   tunein → {radio}                                              │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │            getRelevantProvidersForCategory(category)             │
 │                                                                  │
 │   - Filters _availableMusicProviders by capability              │
 │   - Returns only providers that support the category            │
 │   - Includes item counts for display                            │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                    Library Menu (Options)                        │
 │                                                                  │
 │   - Shows providers section if > 1 providers support category   │
 │   - All relevant providers shown (can toggle on/off)            │
 │   - Instant UI update via setState()                            │
 │   - Background sync after 1.5s debounce                         │
 └─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                   Tab Build Methods                              │
 │                                                                  │
 │   - Get enabledProviderIds from MusicAssistantProvider          │
 │   - Filter data using SyncService source tracking               │
 │   - Display filtered results                                    │
 └─────────────────────────────────────────────────────────────────┘
 ```
 ---
 ## Known Limitations
 1. **Series Tab:** The Series tab in audiobooks doesn't filter by provider yet. Series are fetched separately as `AudiobookSeries` objects and don't have the same source tracking as individual audiobooks.
 2. **First Sync Required:** Source tracking only works after at least one sync with providers enabled.
 ---
 ## Testing Checklist
 - [x] Music tabs filter by provider correctly
 - [x] Provider menu shows only relevant providers per category
 - [x] Radio providers don't appear in Artists/Albums tabs
 - [x] Spotify appears in Audiobooks tab (has audiobooks)
 - [x] Audiobooks Authors tab filters by provider
 - [x] Audiobooks All Books tab filters by provider
 - [ ] Audiobooks Series tab filters by provider (not implemented)
 - [x] Disabled providers can be re-enabled from menu
 - [x] Settings screen no longer has provider toggles
 ---
 ## Related Documentation
 - `docs/PER_PROVIDER_SYNC_IMPLEMENTATION.md` - Original per-provider sync implementation
@@ -0,0 +1,221 @@
 # Feature: Replace "Play On" Popups with Player Selector
 ## Overview
 Replace the `PlayerPickerSheet` popup modal with the existing Player Selector (reveal overlay) when users tap "Play on" buttons throughout the app. This provides a consistent, richer player selection experience.
 ## Current State
 ### PlayerPickerSheet Popup
 Used in 7+ places:
 - `album_details_screen.dart` - Play Album, Play From Here, Play Radio
 - `playlist_details_screen.dart` - Play Playlist, Play Radio
 - `search_screen.dart` - Play album/playlist/audiobook/radio from search
 - `podcast_detail_screen.dart` - Play Episode
 - `audiobook_detail_screen.dart` - Play Audiobook
 - `queue_screen.dart` - Transfer Queue (special case - keep popup)
 ### Player Selector (Reveal Overlay)
 - Location: `lib/widgets/player/player_reveal_overlay.dart`
 - Shows vertical list of all players with artwork, current track, sync status
 - Has hints above player list: "Long-press to sync" & "Swipe to adjust volume"
 - Triggered by pull-down gesture or device button tap
 ## Proposed Changes
 ### 1. Modify PlayerRevealOverlay
 **File:** `lib/widgets/player/player_reveal_overlay.dart`
 Add new optional parameters:
 ```dart
 class PlayerRevealOverlay extends StatefulWidget {
  final VoidCallback onDismiss;
  final double miniPlayerBottom;
  final double miniPlayerHeight;
  final bool showOnboardingHints;
  // NEW: Callback when player is selected for a pending action
  final void Function(Player player)? onPlayerSelected;
  // NEW: Context hint to display instead of default hints
  // e.g., "Select player to play album"
  final String? contextHint;
  // NEW: Icon for context hint (default: speaker icon)
  final IconData? contextHintIcon;
 ```
 ### 2. Modify Hint Display
 **File:** `lib/widgets/player/player_reveal_overlay.dart` (around line 386-394)
 ```dart
 // Current:
 : Column(
    mainAxisSize: MainAxisSize.min,
    children: [
      buildHintRow(Icons.lightbulb_outline, S.of(context)!.holdToSync),
      const SizedBox(height: 4),
      buildHintRow(Icons.lightbulb_outline, S.of(context)!.swipeToAdjustVolume),
    ],
  ),
 // New:
 : widget.contextHint != null
    ? buildHintRow(
        widget.contextHintIcon ?? Icons.play_circle_outline,
        widget.contextHint!,
      )
    : Column(
        mainAxisSize: MainAxisSize.min,
        children: [
          buildHintRow(Icons.lightbulb_outline, S.of(context)!.holdToSync),
          const SizedBox(height: 4),
          buildHintRow(Icons.lightbulb_outline, S.of(context)!.swipeToAdjustVolume),
        ],
      ),
 ```
 ### 3. Modify Player Card onTap
 **File:** `lib/widgets/player/player_reveal_overlay.dart` (around line 437-441 and 490-494)
 ```dart
 // Current:
 onTap: () {
  HapticFeedback.mediumImpact();
  maProvider.selectPlayer(data.player);
  dismiss();
 },
 // New:
 onTap: () {
  HapticFeedback.mediumImpact();
  if (widget.onPlayerSelected != null) {
    // Execute the pending action with selected player
    widget.onPlayerSelected!(data.player);
  } else {
    // Default behavior: just select the player
    maProvider.selectPlayer(data.player);
  }
  dismiss();
 },
 ```
 ### 4. Add Helper Method to GlobalPlayerOverlay
 **File:** `lib/widgets/global_player_overlay.dart`
 Add a static method to show player selector with pending action:
 ```dart
 /// Show player selector for a "Play on" action
 ///
 /// [contextHint] - Message shown instead of default hints
 /// [onPlayerSelected] - Called when user taps a player
 ///
 /// Example:
 /// ```dart
 /// GlobalPlayerOverlay.showPlayerSelectorForAction(
 ///   contextHint: "Select player to play album",
 ///   onPlayerSelected: (player) {
 ///     provider.playAlbum(albumId, playerId: player.playerId);
 ///   },
 /// );
 /// ```
 static void showPlayerSelectorForAction({
  required String contextHint,
  required void Function(Player player) onPlayerSelected,
  IconData? hintIcon,
 }) {
  // Implementation: trigger the player reveal overlay with these parameters
  // May need to store pending action in state and pass to overlay
 }
 ```
 ### 5. Update Calling Sites
 Replace `showPlayerPickerSheet()` calls with new method:
 **Example - album_details_screen.dart:**
 ```dart
 // Current (around line 1305-1316):
 showPlayerPickerSheet(
  context: context,
  title: 'Play Album',
  onPlayerSelected: (player) async {
    GlobalPlayerOverlay.hidePlayer();
    await maProvider.playAlbum(albumId, playerId: player.playerId);
    GlobalPlayerOverlay.showPlayer();
  },
 );
 // New:
 GlobalPlayerOverlay.showPlayerSelectorForAction(
  contextHint: S.of(context)!.selectPlayerToPlayAlbum, // Add localization
  onPlayerSelected: (player) async {
    await maProvider.playAlbum(albumId, playerId: player.playerId);
  },
 );
 ```
 ### 6. Add Localizations
 **File:** `lib/l10n/app_en.arb` (and other language files)
 ```json
 "selectPlayerToPlay": "Select player to play",
 "selectPlayerToPlayAlbum": "Select player to play album",
 "selectPlayerToPlayPlaylist": "Select player to play playlist",
 "selectPlayerToPlayRadio": "Select player to start radio",
 "selectPlayerToPlayEpisode": "Select player to play episode",
 "selectPlayerToPlayAudiobook": "Select player to play audiobook"
 ```
 ## Files to Modify
 1. `lib/widgets/player/player_reveal_overlay.dart` - Add parameters, modify hints & onTap
 2. `lib/widgets/global_player_overlay.dart` - Add helper method
 3. `lib/screens/album_details_screen.dart` - Replace 3 popup calls
 4. `lib/screens/playlist_details_screen.dart` - Replace 2 popup calls
 5. `lib/screens/search_screen.dart` - Replace ~5 popup calls
 6. `lib/screens/podcast_detail_screen.dart` - Replace 1 popup call
 7. `lib/screens/audiobook_detail_screen.dart` - Replace 1 popup call
 8. `lib/l10n/app_en.arb` - Add new strings
 9. `lib/l10n/app_de.arb`, `app_fr.arb`, `app_es.arb` - Translations
 ## Exception: Queue Transfer
 **Keep the popup for `queue_screen.dart`** because:
 - Needs to filter out current player (can't transfer to self)
 - Needs to filter out certain player types
 - Different UX intent (transfer vs play)
 ## Implementation Order
 1. Modify `PlayerRevealOverlay` to accept new parameters
 2. Add helper method to `GlobalPlayerOverlay`
 3. Test with one screen (album_details_screen.dart)
 4. Add localizations
 5. Migrate remaining screens
 6. Clean up unused code from PlayerPickerSheet if no longer needed elsewhere
 ## Testing Checklist
 - [ ] Album details: Play Album button
 - [ ] Album details: Play From Here (track context menu)
 - [ ] Album details: Play Radio (track context menu)
 - [ ] Playlist details: Play Playlist button
 - [ ] Playlist details: Play Radio (track context menu)
 - [ ] Search: Play album from results
 - [ ] Search: Play playlist from results
 - [ ] Search: Play radio from results
 - [ ] Podcast detail: Play episode
 - [ ] Audiobook detail: Play audiobook
 - [ ] Queue transfer still works with popup
 - [ ] Long-press to sync still works in player selector
 - [ ] Dismiss by tapping backdrop works
 - [ ] Dismiss by swiping down works
@@ -28,4 +28,19 @@ class HeroTags {
  /// Podcast cover hero tag prefix
  static const String podcastCover = 'podcast_cover_';
  /// Podcast title hero tag prefix
  static const String podcastTitle = 'podcast_title_';
  /// Playlist cover hero tag prefix
  static const String playlistCover = 'playlist_cover_';
  /// Playlist title hero tag prefix
  static const String playlistTitle = 'playlist_title_';
  /// Radio station cover hero tag prefix
  static const String radioCover = 'radio_cover_';
  /// Radio station title hero tag prefix
  static const String radioTitle = 'radio_title_';
 }
@@ -10,4 +10,7 @@ class NetworkConstants {
  /// Default HTTP port
  static const int defaultHttpPort = 80;
  /// Maximum number of pending WebSocket requests to prevent memory leaks
  static const int maxPendingRequests = 100;
 }
@@ -31,6 +31,9 @@ class Timings {
  /// Search debounce delay
  static const Duration searchDebounce = Duration(milliseconds: 500);
  /// Navigation debounce to prevent double-tap navigation
  static const Duration navigationDebounce = Duration(milliseconds: 500);
  /// Delay after track change before updating state
  static const Duration trackChangeDelay = Duration(milliseconds: 500);
 }
@@ -78,6 +78,10 @@ class LibraryCache extends Table {
  /// Whether this item was deleted on the server
  BoolColumn get isDeleted => boolean().withDefault(const Constant(false))();
  /// Provider instance IDs that provided this item (JSON array)
  /// Used for client-side filtering by source provider
  TextColumn get sourceProviders => text().withDefault(const Constant('[]'))();
  @override
  Set<Column> get primaryKey => {cacheKey};
 }
@@ -191,7 +195,7 @@ class AppDatabase extends _$AppDatabase {
  AppDatabase([QueryExecutor? executor]) : super(executor ?? _openConnection());
  @override
-  int get schemaVersion => 5;
+  int get schemaVersion => 6;
  @override
  MigrationStrategy get migration {
@@ -226,6 +230,10 @@ class AppDatabase extends _$AppDatabase {
          await customStatement('CREATE INDEX IF NOT EXISTS idx_cached_queue_player ON cached_queue (player_id)');
          await customStatement('CREATE INDEX IF NOT EXISTS idx_cached_queue_player_position ON cached_queue (player_id, position)');
        }
        // Migration from v5 to v6: Add source_providers column for client-side filtering
        if (from < 6) {
          await customStatement("ALTER TABLE library_cache ADD COLUMN source_providers TEXT NOT NULL DEFAULT '[]'");
        }
      },
    );
  }
@@ -368,20 +376,57 @@ class AppDatabase extends _$AppDatabase {
  // ============================================
  /// Cache a library item
  /// [sourceProvider] - the provider instance ID that provided this item (for filtering)
  Future<void> cacheItem({
    required String itemType,
    required String itemId,
    required String data,
    String? sourceProvider,
  }) async {
    final cacheKey = '${itemType}_$itemId';
-    await into(libraryCache).insertOnConflictUpdate(LibraryCacheCompanion.insert(
+    // If sourceProvider is specified, we need to merge with existing providers
-      cacheKey: cacheKey,
+    if (sourceProvider != null) {
-      itemType: itemType,
+      final existing = await getCachedItem(itemType, itemId);
-      itemId: itemId,
+      List<String> providers = [];
-      data: data,
+      if (existing != null) {
-      lastSynced: DateTime.now(),
+        try {
-    ));
+          final existingProviders = existing.sourceProviders;
          if (existingProviders.isNotEmpty && existingProviders != '[]') {
            providers = List<String>.from(
              (await Future.value(existingProviders))
                  .replaceAll('[', '')
                  .replaceAll(']', '')
                  .replaceAll('"', '')
                  .split(',')
                  .where((s) => s.trim().isNotEmpty)
                  .map((s) => s.trim()),
            );
          }
        } catch (_) {}
      }
      if (!providers.contains(sourceProvider)) {
        providers.add(sourceProvider);
      }
      final sourceProvidersJson = '[${providers.map((p) => '"$p"').join(',')}]';
      await into(libraryCache).insertOnConflictUpdate(LibraryCacheCompanion.insert(
        cacheKey: cacheKey,
        itemType: itemType,
        itemId: itemId,
        data: data,
        lastSynced: DateTime.now(),
        sourceProviders: Value(sourceProvidersJson),
      ));
    } else {
      await into(libraryCache).insertOnConflictUpdate(LibraryCacheCompanion.insert(
        cacheKey: cacheKey,
        itemType: itemType,
        itemId: itemId,
        data: data,
        lastSynced: DateTime.now(),
      ));
    }
  }
  /// Get cached items by type
@@ -650,4 +695,66 @@ class AppDatabase extends _$AppDatabase {
  Future<void> clearSearchHistory() async {
    await delete(searchHistory).go();
  }
  // ============================================
  // Batch Cache Operations
  // ============================================
  /// Batch size for chunked inserts to prevent SQLite limits
  static const int _batchChunkSize = 500;
  /// Batch cache multiple items efficiently using drift batch API
  /// This is much faster than individual inserts for large datasets.
  /// Items are chunked into batches of 500 to prevent SQLite variable limits.
  ///
  /// [items] - List of items to cache, each containing:
  ///   - itemType: 'album', 'artist', 'track', 'playlist', 'audiobook', etc.
  ///   - itemId: the item's ID
  ///   - data: JSON string of the item
  ///   - sourceProviders: list of provider instance IDs
  Future<void> batchCacheItems(List<BatchCacheItem> items) async {
    if (items.isEmpty) return;
    // Process in chunks to avoid SQLite variable limits
    for (var i = 0; i < items.length; i += _batchChunkSize) {
      final chunk = items.skip(i).take(_batchChunkSize).toList();
      await batch((b) {
        for (final item in chunk) {
          final cacheKey = '${item.itemType}_${item.itemId}';
          final sourceProvidersJson = item.sourceProviders.isEmpty
              ? '[]'
              : '[${item.sourceProviders.map((p) => '"$p"').join(',')}]';
          b.insert(
            libraryCache,
            LibraryCacheCompanion.insert(
              cacheKey: cacheKey,
              itemType: item.itemType,
              itemId: item.itemId,
              data: item.data,
              lastSynced: DateTime.now(),
              sourceProviders: Value(sourceProvidersJson),
            ),
            mode: InsertMode.insertOrReplace,
          );
        }
      });
    }
  }
 }
 /// Data class for batch cache operations
 class BatchCacheItem {
  final String itemType;
  final String itemId;
  final String data;
  final List<String> sourceProviders;
  const BatchCacheItem({
    required this.itemType,
    required this.itemId,
    required this.data,
    this.sourceProviders = const [],
  });
 }
@@ -203,6 +203,7 @@
  "english": "Englisch",
  "german": "Deutsch",
  "spanish": "Spanisch",
  "french": "Französisch",
  "noTracksInPlaylist": "Keine Songs in Wiedergabeliste",
  "sortAlphabetically": "Alphabetisch sortieren",
@@ -251,6 +251,21 @@
    "description": "Home screen section title"
  },
  "favoritePlaylists": "Favorite Playlists",
  "@favoritePlaylists": {
    "description": "Home screen section title"
  },
  "favoriteRadioStations": "Favorite Radio Stations",
  "@favoriteRadioStations": {
    "description": "Home screen section title"
  },
  "favoritePodcasts": "Favorite Podcasts",
  "@favoritePodcasts": {
    "description": "Home screen section title"
  },
  "searchMusic": "Search music...",
  "@searchMusic": {
    "description": "Search placeholder text"
@@ -1045,6 +1060,11 @@
    "description": "Spanish language"
  },
  "french": "French",
  "@french": {
    "description": "French language"
  },
  "noTracksInPlaylist": "No tracks in playlist",
  "sortAlphabetically": "Sort alphabetically",
  "sortByYear": "Sort by year",
@@ -1062,6 +1082,9 @@
  "showFavoriteAlbums": "Show a row of your favorite albums",
  "showFavoriteArtists": "Show a row of your favorite artists",
  "showFavoriteTracks": "Show a row of your favorite tracks",
  "showFavoritePlaylists": "Show a row of your favorite playlists",
  "showFavoriteRadioStations": "Show a row of your favorite radio stations",
  "showFavoritePodcasts": "Show a row of your favorite podcasts",
  "extractColorsFromArtwork": "Extract colors from album and artist artwork",
  "chooseHomeScreenRows": "Choose which rows to display on the home screen",
  "addedToFavorites": "Added to favorites",
@@ -1117,6 +1140,10 @@
  "audiobookLibraries": "Audiobook Libraries",
  "chooseAudiobookLibraries": "Choose which Audiobookshelf libraries to include",
  "unknownLibrary": "Unknown Library",
  "musicProviders": "Music Providers",
  "musicProvidersDescription": "Choose which accounts to show in your library",
  "libraryRefreshing": "Refreshing library...",
  "cannotDisableLastProvider": "Cannot disable the last provider",
  "noSeriesFound": "No Series Found",
  "ensembleBugReport": "Ensemble Bug Report",
  "byOwner": "By {owner}",
@@ -1378,5 +1405,228 @@
        "type": "String"
      }
    }
  },
  "noTracks": "No tracks",
  "@noTracks": {
    "description": "Empty state title when no tracks exist in library"
  },
  "addTracksHint": "Add some music to your library to see tracks here",
  "@addTracksHint": {
    "description": "Hint for adding tracks to library"
  },
  "noFavoriteRadioStations": "No favorite radio stations",
  "@noFavoriteRadioStations": {
    "description": "Empty state when no favorite radio stations"
  },
  "longPressRadioHint": "Long-press a station and tap the heart to add it to favorites",
  "@longPressRadioHint": {
    "description": "Hint for favoriting radio stations"
  },
  "noFavoritePodcasts": "No favorite podcasts",
  "@noFavoritePodcasts": {
    "description": "Empty state when no favorite podcasts"
  },
  "longPressPodcastHint": "Long-press a podcast and tap the heart to add it to favorites",
  "@longPressPodcastHint": {
    "description": "Hint for favoriting podcasts"
  },
  "failedToPlayRadioStation": "Failed to play radio station: {error}",
  "@failedToPlayRadioStation": {
    "description": "Error when playing radio station fails",
    "placeholders": {
      "error": {
        "type": "String"
      }
    }
  },
  "itemAlreadyInLibrary": "Item is already in library",
  "@itemAlreadyInLibrary": {
    "description": "Message when trying to add item already in library"
  },
  "failedToAddToLibrary": "Failed to add to library",
  "@failedToAddToLibrary": {
    "description": "Error when adding to library fails"
  },
  "cannotFindLibraryId": "Cannot find library ID for removal",
  "@cannotFindLibraryId": {
    "description": "Error when library ID not found for removal"
  },
  "failedToRemoveFromLibrary": "Failed to remove from library",
  "@failedToRemoveFromLibrary": {
    "description": "Error when removing from library fails"
  },
  "failedToPlayAlbum": "Failed to play album: {error}",
  "@failedToPlayAlbum": {
    "description": "Error when playing album fails",
    "placeholders": {
      "error": {
        "type": "String"
      }
    }
  },
  "playingOnPlayer": "Playing {name} on {playerName}",
  "@playingOnPlayer": {
    "description": "Status when playing item on specific player",
    "placeholders": {
      "name": {
        "type": "String"
      },
      "playerName": {
        "type": "String"
      }
    }
  },
  "failedToPlayPlaylist": "Failed to play playlist: {error}",
  "@failedToPlayPlaylist": {
    "description": "Error when playing playlist fails",
    "placeholders": {
      "error": {
        "type": "String"
      }
    }
  },
  "failedToPlayAudiobook": "Failed to play audiobook: {error}",
  "@failedToPlayAudiobook": {
    "description": "Error when playing audiobook fails",
    "placeholders": {
      "error": {
        "type": "String"
      }
    }
  },
  "noOtherPlayersAvailable": "No other players available",
  "@noOtherPlayersAvailable": {
    "description": "Message when no other players available for transfer"
  },
  "transferQueue": "Transfer queue",
  "@transferQueue": {
    "description": "Tooltip for transfer queue button"
  },
  "clearQueue": "Clear queue",
  "@clearQueue": {
    "description": "Tooltip for clear queue button"
  },
  "syncingPlayer": "Syncing {playerName}...",
  "@syncingPlayer": {
    "description": "Status when syncing player",
    "placeholders": {
      "playerName": {
        "type": "String"
      }
    }
  },
  "switchPlayer": "Switch Player",
  "@switchPlayer": {
    "description": "Label for switch player action"
  },
  "logsCopiedToClipboard": "Logs copied to clipboard",
  "@logsCopiedToClipboard": {
    "description": "Confirmation when logs copied"
  },
  "auto": "Auto",
  "@auto": {
    "description": "Auto option for language selection"
  },
  "transferQueueTo": "Transfer Queue To",
  "@transferQueueTo": {
    "description": "Title for transfer queue dialog"
  },
  "queueTransferredTo": "Queue transferred to {playerName}",
  "@queueTransferredTo": {
    "description": "Success message when queue transferred",
    "placeholders": {
      "playerName": {
        "type": "String"
      }
    }
  },
  "failedToTransferQueue": "Failed to transfer queue: {error}",
  "@failedToTransferQueue": {
    "description": "Error when queue transfer fails",
    "placeholders": {
      "error": {
        "type": "String"
      }
    }
  },
  "failedToLoadQueue": "Failed to load queue: {error}",
  "@failedToLoadQueue": {
    "description": "Error when queue loading fails",
    "placeholders": {
      "error": {
        "type": "String"
      }
    }
  },
  "transferTo": "Transfer to...",
  "@transferTo": {
    "description": "Label for transfer destination selection"
  },
  "transferQueueToPlayer": "Transfer queue to another player",
  "@transferQueueToPlayer": {
    "description": "Tooltip for transfer queue button"
  },
  "selectPlayerToPlay": "Select a player",
  "@selectPlayerToPlay": {
    "description": "Generic hint for selecting a player in player selector"
  },
  "selectPlayerToPlayAlbum": "Select player to play album",
  "@selectPlayerToPlayAlbum": {
    "description": "Hint for selecting player to play album"
  },
  "selectPlayerToPlayPlaylist": "Select player to play playlist",
  "@selectPlayerToPlayPlaylist": {
    "description": "Hint for selecting player to play playlist"
  },
  "selectPlayerForRadio": "Select player for radio",
  "@selectPlayerForRadio": {
    "description": "Hint for selecting player to start radio"
  },
  "selectPlayerForEpisode": "Select player for episode",
  "@selectPlayerForEpisode": {
    "description": "Hint for selecting player to play episode"
  },
  "selectPlayerForAudiobook": "Select player for audiobook",
  "@selectPlayerForAudiobook": {
    "description": "Hint for selecting player to play audiobook"
  },
  "selectPlayerToAddToQueue": "Select player to add to queue",
  "@selectPlayerToAddToQueue": {
    "description": "Hint for selecting player to add to queue"
  }
 }
@@ -360,6 +360,7 @@
  "english": "Inglés",
  "german": "Alemán",
  "spanish": "Español",
  "french": "Francés",
  "noTracksInPlaylist": "No hay canciones en la lista",
  "sortAlphabetically": "Ordenar alfabéticamente",
  "sortByYear": "Ordenar por año",
@@ -1,4 +1,5 @@
 import 'dart:async';
 import 'dart:ui';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
@@ -33,6 +34,10 @@ final _logger = DebugLogger();
 Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // Initialize SharedPreferences cache early for performance
  await SettingsService.initialize();
  _logger.log('⚡ SharedPreferences cached');
  // Initialize local database
  await DatabaseService.instance.initialize();
  _logger.log('💾 Database initialized');
@@ -71,17 +76,42 @@ Future<void> main() async {
    DeviceOrientation.portraitDown,
  ]);
-  // Set system UI overlay style
+  // Set initial system UI overlay style based on platform brightness
  // SystemUIWrapper will update this dynamically when theme changes
  final platformBrightness = WidgetsBinding.instance.platformDispatcher.platformBrightness;
  final isDark = platformBrightness == Brightness.dark;
  SystemChrome.setSystemUIOverlayStyle(
-    const SystemUiOverlayStyle(
+    SystemUiOverlayStyle(
      statusBarColor: Colors.transparent,
-      statusBarIconBrightness: Brightness.light,
+      statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
-      systemNavigationBarColor: Color(0xFF1a1a1a),
+      systemNavigationBarColor: isDark ? const Color(0xFF1a1a1a) : const Color(0xFFF5F5F5),
-      systemNavigationBarIconBrightness: Brightness.light,
+      systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
    ),
  );
-  runApp(const MusicAssistantApp());
+  // Set up Flutter error boundary to catch and log widget build errors
  FlutterError.onError = (FlutterErrorDetails details) {
    _logger.error('Flutter error: ${details.exceptionAsString()}', context: 'FlutterError');
    _logger.error('Stack trace:\n${details.stack}', context: 'FlutterError');
    // Still report to Flutter's default handler in debug mode
    FlutterError.presentError(details);
  };
  // Catch errors from the platform dispatcher (platform channel errors)
  PlatformDispatcher.instance.onError = (error, stack) {
    _logger.error('Platform error: $error', context: 'PlatformDispatcher');
    _logger.error('Stack trace:\n$stack', context: 'PlatformDispatcher');
    return true; // Handled
  };
  // Wrap app in zone to catch async errors
  runZonedGuarded(
    () => runApp(const MusicAssistantApp()),
    (error, stackTrace) {
      _logger.error('Uncaught async error: $error', context: 'ZoneError');
      _logger.error('Stack trace:\n$stackTrace', context: 'ZoneError');
    },
  );
 }
 class MusicAssistantApp extends StatefulWidget {
@@ -176,7 +206,7 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
  @override
  Future<bool> didPopRoute() async {
    // Intercept back button at app level - runs BEFORE Navigator processes it
-    // Priority order: device list > expanded player > normal navigation
+    // Priority order: device list > queue panel > expanded player > normal navigation
    // Device list has highest priority - dismiss it first
    if (GlobalPlayerOverlay.isPlayerRevealVisible) {
@@ -184,9 +214,18 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
      return true; // We handled it, don't let Navigator process it
    }
    // Queue panel second - close it before collapsing player
    // Use target state (not animation value) to handle rapid open-close timing
    // Use withHaptic: false because Android back gesture provides system haptic
    if (GlobalPlayerOverlay.isQueuePanelTargetOpen) {
      GlobalPlayerOverlay.closeQueuePanel(withHaptic: false);
      return true; // We handled it, don't let Navigator process it
    }
    // Then check expanded player
    // No haptic - Android back gesture provides its own
    if (GlobalPlayerOverlay.isPlayerExpanded) {
-      GlobalPlayerOverlay.collapsePlayer();
+      GlobalPlayerOverlay.collapsePlayer(withHaptic: false);
      return true; // We handled it, don't let Navigator process it
    }
@@ -263,6 +302,29 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
                  ],
                  supportedLocales: S.supportedLocales,
                  locale: localeProvider.locale,
                  // Fallback to English when locale is not supported
                  localeListResolutionCallback: (locales, supportedLocales) {
                    // If user has set a specific locale, try to use it
                    if (localeProvider.locale != null) {
                      for (final supported in supportedLocales) {
                        if (supported.languageCode == localeProvider.locale!.languageCode) {
                          return supported;
                        }
                      }
                    }
                    // Try to match system locales
                    if (locales != null) {
                      for (final locale in locales) {
                        for (final supported in supportedLocales) {
                          if (supported.languageCode == locale.languageCode) {
                            return supported;
                          }
                        }
                      }
                    }
                    // Fallback to English (not German)
                    return const Locale('en');
                  },
                  themeMode: themeProvider.themeMode,
                  theme: AppTheme.lightTheme(colorScheme: lightColorScheme),
                  darkTheme: AppTheme.darkTheme(colorScheme: darkColorScheme),
@@ -339,8 +401,8 @@ class _SystemUIWrapperState extends State<SystemUIWrapper> {
          statusBarColor: Colors.transparent,
          statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
          systemNavigationBarColor: isDark
-              ? widget.darkColorScheme.background
+              ? widget.darkColorScheme.surface
-              : widget.lightColorScheme.background,
+              : widget.lightColorScheme.surface,
          systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
        ),
      );
@@ -16,6 +16,10 @@ class ProviderMapping {
  final String providerInstance;
  final bool available;
  final Map<String, dynamic>? audioFormat;
  /// Whether this item is in the library for this specific provider instance.
  /// True = this provider "owns" the item (user added it from this account)
  /// False = item exists but wasn't added from this provider
  final bool inLibrary;
  ProviderMapping({
    required this.itemId,
@@ -23,6 +27,7 @@ class ProviderMapping {
    required this.providerInstance,
    required this.available,
    this.audioFormat,
    this.inLibrary = true,
  });
  factory ProviderMapping.fromJson(Map<String, dynamic> json) {
@@ -32,6 +37,8 @@ class ProviderMapping {
      providerInstance: json['provider_instance'] as String? ?? '',
      available: json['available'] as bool? ?? true,
      audioFormat: json['audio_format'] as Map<String, dynamic>?,
      // Parse in_library field - MA uses 1/0 or true/false
      inLibrary: json['in_library'] == true || json['in_library'] == 1,
    );
  }
@@ -42,6 +49,7 @@ class ProviderMapping {
      'provider_instance': providerInstance,
      'available': available,
      if (audioFormat != null) 'audio_format': audioFormat,
      'in_library': inLibrary,
    };
  }
 }
@@ -118,6 +126,17 @@ class MediaItem {
      if (duration != null) 'duration': duration!.inSeconds,
    };
  }
  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is MediaItem &&
          runtimeType == other.runtimeType &&
          itemId == other.itemId &&
          provider == other.provider;
  @override
  int get hashCode => Object.hash(itemId, provider);
 }
 class Artist extends MediaItem {
@@ -0,0 +1,128 @@
 /// Represents a music provider instance from Music Assistant.
 ///
 /// Each provider (like Spotify, Tidal) can have multiple instances
 /// (e.g., two different Spotify accounts). This class represents
 /// a single provider instance with its unique ID.
 class ProviderInstance {
  /// Unique identifier for this provider instance (e.g., "spotify--abc123")
  final String instanceId;
  /// The provider domain/type (e.g., "spotify", "tidal", "qobuz")
  final String domain;
  /// Display name for this instance (e.g., "Spotify (John's Account)")
  final String name;
  /// Whether this provider is currently available/connected
  final bool available;
  ProviderInstance({
    required this.instanceId,
    required this.domain,
    required this.name,
    required this.available,
  });
  /// Provider capabilities - maps domain to supported content types
  /// This determines which tabs/categories show which providers
  static const Map<String, Set<String>> providerCapabilities = {
    // Music streaming services (support artists, albums, tracks, playlists)
    // Spotify also has audiobooks and podcasts
    'spotify': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
    'tidal': {'artists', 'albums', 'tracks', 'playlists'},
    'qobuz': {'artists', 'albums', 'tracks', 'playlists'},
    'deezer': {'artists', 'albums', 'tracks', 'playlists'},
    'ytmusic': {'artists', 'albums', 'tracks', 'playlists', 'podcasts'},
    'soundcloud': {'artists', 'albums', 'tracks', 'playlists'},
    'apple_music': {'artists', 'albums', 'tracks', 'playlists', 'podcasts'},
    'amazon_music': {'artists', 'albums', 'tracks', 'playlists'},
    // Self-hosted media servers (can have music, audiobooks, and podcasts)
    'plex': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
    'jellyfin': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
    'emby': {'artists', 'albums', 'tracks', 'playlists', 'audiobooks', 'podcasts'},
    // Music-only servers
    'subsonic': {'artists', 'albums', 'tracks', 'playlists'},
    'opensubsonic': {'artists', 'albums', 'tracks', 'playlists'},
    'navidrome': {'artists', 'albums', 'tracks', 'playlists'},
    'filesystem': {'artists', 'albums', 'tracks', 'playlists'},
    // Audiobook and podcast providers
    'audiobookshelf': {'audiobooks', 'podcasts'},
    'itunes_podcasts': {'podcasts'},
    // Radio providers (tunein also has podcasts)
    'tunein': {'radio', 'podcasts'},
    'radiobrowser': {'radio'},
    // Player/system providers (no library content)
    'snapcast': <String>{},
    'fully_kiosk': <String>{},
  };
  /// Known music provider domains that provide library content
  static const Set<String> musicProviderDomains = {
    // Streaming services
    'spotify',
    'tidal',
    'qobuz',
    'deezer',
    'ytmusic',
    'soundcloud',
    'apple_music',
    'amazon_music',
    // Self-hosted / local
    'plex',
    'subsonic',
    'opensubsonic',
    'jellyfin',
    'emby',
    'navidrome',
    'audiobookshelf',
    'filesystem',
    'itunes_podcasts',
    // Other
    'tunein',
    'radiobrowser',
    'snapcast',
    'fully_kiosk',
  };
  /// Whether this is a music provider (vs. player provider, metadata provider, etc.)
  bool get isMusicProvider => musicProviderDomains.contains(domain);
  /// Get supported content types for this provider
  Set<String> get supportedContentTypes =>
      providerCapabilities[domain] ?? <String>{};
  /// Check if this provider supports a specific content type/category
  bool supportsContentType(String category) =>
      supportedContentTypes.contains(category);
  factory ProviderInstance.fromJson(Map<String, dynamic> json) {
    return ProviderInstance(
      instanceId: json['instance_id'] as String? ?? '',
      domain: json['domain'] as String? ?? json['type'] as String? ?? '',
      name: json['name'] as String? ?? json['instance_id'] as String? ?? 'Unknown',
      available: json['available'] as bool? ?? true,
    );
  }
  Map<String, dynamic> toJson() {
    return {
      'instance_id': instanceId,
      'domain': domain,
      'name': name,
      'available': available,
    };
  }
  @override
  String toString() => 'ProviderInstance($instanceId: $name)';
  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is ProviderInstance &&
          runtimeType == other.runtimeType &&
          instanceId == other.instanceId;
  @override
  int get hashCode => instanceId.hashCode;
 }
@@ -2,168 +2,80 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 import '../services/music_assistant_api.dart';
 import '../services/settings_service.dart';
 import '../services/database_service.dart';
 import '../services/profile_service.dart';
 import '../services/debug_logger.dart';
 import '../services/error_handler.dart';
 import '../services/auth/auth_manager.dart';
 import '../services/cache_service.dart';
-/// Provider for managing connection state to Music Assistant server
+/// Callback types for connection events
-/// Handles WebSocket connection, authentication, and reconnection
+typedef OnConnected = Future<void> Function();
 typedef OnAuthenticated = Future<void> Function();
 typedef OnDisconnected = void Function();
 /// Provider for connection state management.
 ///
 /// Extracted from MusicAssistantProvider to handle:
 /// - WebSocket connection lifecycle
 /// - Authentication flow (MA token, credentials)
 /// - Reconnection logic
 /// - Connection state broadcasting
 ///
 /// Note: This is a partial extraction. Full integration requires updating
 /// all consumers to use this provider directly.
 class ConnectionProvider with ChangeNotifier {
  MusicAssistantAPI? _api;
  final AuthManager _authManager = AuthManager();
  final DebugLogger _logger = DebugLogger();
-  final CacheService _cacheService = CacheService();
+  final AuthManager _authManager = AuthManager();
-  MAConnectionState _connectionState = MAConnectionState.disconnected;
+  MusicAssistantAPI? _api;
  String? _serverUrl;
  String? _error;
  MAConnectionState _connectionState = MAConnectionState.disconnected;
-  // Callbacks for post-connection initialization
+  StreamSubscription? _connectionStateSubscription;
  VoidCallback? onConnected;
  VoidCallback? onAuthenticated;
  VoidCallback? onDisconnected;
-  MAConnectionState get connectionState => _connectionState;
+  // Callbacks for connection events - set by the facade provider
-  String? get serverUrl => _serverUrl;
+  OnConnected? onConnected;
-  String? get error => _error;
+  OnAuthenticated? onAuthenticated;
-  bool get isConnected => _connectionState == MAConnectionState.connected ||
+  OnDisconnected? onDisconnected;
-                          _connectionState == MAConnectionState.authenticated;
+
  // User settings captured during authentication
  List<String> _providerFilter = [];
  List<String> _playerFilter = [];
  // ============================================================================
  // GETTERS
  // ============================================================================
  MusicAssistantAPI? get api => _api;
  AuthManager get authManager => _authManager;
-  CacheService get cacheService => _cacheService;
+  String? get serverUrl => _serverUrl;
  String? get error => _error;
  MAConnectionState get connectionState => _connectionState;
-  ConnectionProvider() {
+  bool get isConnected =>
-    _initialize();
+      _connectionState == MAConnectionState.connected ||
-  }
+      _connectionState == MAConnectionState.authenticated;
-  Future<void> _initialize() async {
+  List<String> get providerFilter => _providerFilter;
-    _serverUrl = await SettingsService.getServerUrl();
+  List<String> get playerFilter => _playerFilter;
    if (_serverUrl != null && _serverUrl!.isNotEmpty) {
      await _restoreAuthCredentials();
      await connectToServer(_serverUrl!);
    }
  }
-  /// Restore auth credentials from persistent storage
+  // ============================================================================
-  Future<void> _restoreAuthCredentials() async {
+  // CONNECTION
-    final savedCredentials = await SettingsService.getAuthCredentials();
+  // ============================================================================
    if (savedCredentials != null) {
      _logger.log('🔐 Restoring saved auth credentials...');
      _authManager.deserializeCredentials(savedCredentials);
      _logger.log('🔐 Auth credentials restored: ${_authManager.currentStrategy?.name ?? "none"}');
    } else {
      _logger.log('🔐 No saved auth credentials found');
    }
  }
-  /// Handle Music Assistant native authentication after WebSocket connection
+  /// Connect to the Music Assistant server
-  Future<bool> handleMaAuthentication() async {
+  Future<void> connect(String serverUrl) async {
    if (_api == null) return false;
    try {
      // First, try stored MA token
      final storedToken = await SettingsService.getMaAuthToken();
      if (storedToken != null) {
        _logger.log('🔐 Trying stored MA token...');
        final success = await _api!.authenticateWithToken(storedToken);
        if (success) {
          _logger.log('✅ MA authentication with stored token successful');
          await _fetchAndSetUserProfileName();
          return true;
        }
        _logger.log('⚠️ Stored MA token invalid, clearing...');
        await SettingsService.clearMaAuthToken();
      }
      // No valid token - try stored credentials
      final username = await SettingsService.getUsername();
      final password = await SettingsService.getPassword();
      if (username != null && password != null && username.isNotEmpty && password.isNotEmpty) {
        _logger.log('🔐 Trying stored credentials...');
        final accessToken = await _api!.loginWithCredentials(username, password);
        if (accessToken != null) {
          _logger.log('✅ MA login with stored credentials successful');
          final longLivedToken = await _api!.createLongLivedToken();
          if (longLivedToken != null) {
            await SettingsService.setMaAuthToken(longLivedToken);
            _logger.log('✅ Saved new long-lived MA token');
          } else {
            await SettingsService.setMaAuthToken(accessToken);
          }
          await _fetchAndSetUserProfileName();
          return true;
        }
      }
      _logger.log('❌ MA authentication failed - no valid token or credentials');
      return false;
    } catch (e) {
      _logger.log('❌ MA authentication error: $e');
      return false;
    }
  }
  /// Fetch user profile from MA and set owner name + create/activate local profile
  Future<void> _fetchAndSetUserProfileName() async {
    if (_api == null) return;
    try {
      final userInfo = await _api!.getCurrentUserInfo();
      if (userInfo == null) {
        _logger.log('⚠️ Could not fetch user profile');
        return;
      }
      final displayName = userInfo['display_name'] as String?;
      final username = userInfo['username'] as String?;
      _logger.log('🔍 Profile data: display_name="$displayName", username="$username"');
      final profileName = (displayName != null && displayName.isNotEmpty)
          ? displayName
          : username;
      if (profileName != null && profileName.isNotEmpty) {
        await SettingsService.setOwnerName(profileName);
        _logger.log('✅ Set owner name from MA profile: $profileName');
        // Create/activate profile in local database
        if (DatabaseService.instance.isInitialized && username != null) {
          await ProfileService.instance.onMaAuthenticated(
            username: username,
            displayName: displayName,
          );
          _logger.log('✅ Local profile activated: $username');
        }
      } else {
        _logger.log('⚠️ No valid name in profile');
      }
    } catch (e) {
      _logger.log('⚠️ Could not fetch user profile (non-fatal): $e');
    }
  }
  Future<void> connectToServer(String serverUrl) async {
    try {
      _error = null;
      _serverUrl = serverUrl;
      await SettingsService.setServerUrl(serverUrl);
-      // Disconnect existing connection
+      // Dispose the old API to stop any pending reconnects
-      await _api?.disconnect();
+      _api?.dispose();
      _api = MusicAssistantAPI(serverUrl, _authManager);
-      // Listen to connection state changes
+      _connectionStateSubscription?.cancel();
-      _api!.connectionState.listen(
+      _connectionStateSubscription = _api!.connectionState.listen(
        (state) async {
          _connectionState = state;
          notifyListeners();
@@ -173,9 +85,8 @@ class ConnectionProvider with ChangeNotifier {
            if (_api!.authRequired && !_api!.isAuthenticated) {
              _logger.log('🔐 MA auth required, attempting authentication...');
-              final authenticated = await handleMaAuthentication();
+              final authenticated = await _handleAuthentication();
              if (!authenticated) {
                _logger.log('❌ MA authentication failed - stopping connection flow');
                _error = 'Authentication required. Please log in again.';
                notifyListeners();
                return;
@@ -183,15 +94,13 @@ class ConnectionProvider with ChangeNotifier {
              return;
            }
-            // No auth required - notify connected
+            // No auth required, trigger callback
-            onConnected?.call();
+            await onConnected?.call();
          } else if (state == MAConnectionState.authenticated) {
            _logger.log('✅ MA authentication successful');
-            onAuthenticated?.call();
+            await onAuthenticated?.call();
          } else if (state == MAConnectionState.disconnected) {
-            // DON'T clear caches on disconnect - keep showing cached data
+            _logger.log('📡 Disconnected - keeping cached data for instant resume');
            // This allows instant UI display when app resumes or reconnects
            // Caches will be refreshed when connection is restored
            onDisconnected?.call();
          }
        },
@@ -214,44 +123,122 @@ class ConnectionProvider with ChangeNotifier {
    }
  }
  Future<bool> _handleAuthentication() async {
    if (_api == null) return false;
    try {
      final storedToken = await SettingsService.getMaAuthToken();
      if (storedToken != null) {
        _logger.log('🔐 Trying stored MA token...');
        final success = await _api!.authenticateWithToken(storedToken);
        if (success) {
          _logger.log('✅ MA authentication with stored token successful');
          await _fetchUserSettings();
          return true;
        }
        _logger.log('⚠️ Stored MA token invalid, clearing...');
        await SettingsService.clearMaAuthToken();
      }
      final username = await SettingsService.getUsername();
      final password = await SettingsService.getPassword();
      if (username != null &&
          password != null &&
          username.isNotEmpty &&
          password.isNotEmpty) {
        _logger.log('🔐 Trying stored credentials...');
        final accessToken = await _api!.loginWithCredentials(username, password);
        if (accessToken != null) {
          _logger.log('✅ MA login with stored credentials successful');
          final longLivedToken = await _api!.createLongLivedToken();
          if (longLivedToken != null) {
            await SettingsService.setMaAuthToken(longLivedToken);
            _logger.log('✅ Saved new long-lived MA token');
          } else {
            await SettingsService.setMaAuthToken(accessToken);
          }
          await _fetchUserSettings();
          return true;
        }
      }
      _logger.log('❌ MA authentication failed - no valid token or credentials');
      return false;
    } catch (e) {
      _logger.log('❌ MA authentication error: $e');
      return false;
    }
  }
  Future<void> _fetchUserSettings() async {
    if (_api == null) return;
    try {
      final userInfo = await _api!.getCurrentUserInfo();
      if (userInfo == null) return;
      // Set profile name
      final displayName = userInfo['display_name'] as String?;
      final username = userInfo['username'] as String?;
      final profileName =
          (displayName != null && displayName.isNotEmpty) ? displayName : username;
      if (profileName != null && profileName.isNotEmpty) {
        await SettingsService.setOwnerName(profileName);
        _logger.log('✅ Set owner name from MA profile: $profileName');
      }
      // Capture provider filter
      final providerFilterRaw = userInfo['provider_filter'];
      if (providerFilterRaw is List) {
        _providerFilter = providerFilterRaw.cast<String>().toList();
        if (_providerFilter.isNotEmpty) {
          _logger.log(
              '🔒 Provider filter active: ${_providerFilter.length} providers allowed');
        }
      } else {
        _providerFilter = [];
      }
      // Capture player filter
      final playerFilterRaw = userInfo['player_filter'];
      if (playerFilterRaw is List) {
        _playerFilter = playerFilterRaw.cast<String>().toList();
        if (_playerFilter.isNotEmpty) {
          _logger.log(
              '🔒 Player filter active: ${_playerFilter.length} players allowed');
        }
      } else {
        _playerFilter = [];
      }
    } catch (e) {
      _logger.log('⚠️ Could not fetch user settings (non-fatal): $e');
    }
  }
  /// Disconnect from the server
  Future<void> disconnect() async {
    _connectionStateSubscription?.cancel();
    await _api?.disconnect();
    _connectionState = MAConnectionState.disconnected;
    // DON'T clear caches on disconnect - keep showing cached data for instant reconnect
    notifyListeners();
  }
-  /// Clear all caches and state (for logout or server change)
+  /// Check connection and reconnect if needed
  void clearCachesOnLogout() {
    _cacheService.clearAll();
    notifyListeners();
  }
  /// Check connection and reconnect if needed (called when app resumes)
  Future<void> checkAndReconnect() async {
-    _logger.log('🔄 checkAndReconnect called - state: $_connectionState');
+    if (_serverUrl != null && !isConnected) {
-
+      _logger.log('🔄 Attempting reconnection...');
-    if (_serverUrl == null) {
+      await connect(_serverUrl!);
      _logger.log('🔄 No server URL saved, skipping reconnect');
      return;
    }
    if (_connectionState != MAConnectionState.connected &&
        _connectionState != MAConnectionState.authenticated) {
      _logger.log('🔄 Not connected, attempting reconnect to $_serverUrl');
      try {
        await connectToServer(_serverUrl!);
        _logger.log('🔄 Reconnection successful');
      } catch (e) {
        _logger.log('🔄 Reconnection failed: $e');
      }
    } else {
      _logger.log('🔄 Already connected, connection verified');
    }
  }
  @override
  void dispose() {
    _connectionStateSubscription?.cancel();
    _api?.dispose();
    super.dispose();
  }
@@ -1,392 +0,0 @@
 import 'package:flutter/foundation.dart';
 import '../models/media_item.dart';
 import '../services/music_assistant_api.dart';
 import '../services/debug_logger.dart';
 import '../services/error_handler.dart';
 import '../services/cache_service.dart';
 import '../services/settings_service.dart';
 import '../constants/timings.dart';
 /// Provider for managing library data (artists, albums, tracks, playlists)
 class LibraryProvider with ChangeNotifier {
  final DebugLogger _logger = DebugLogger();
  final CacheService _cacheService;
  MusicAssistantAPI? _api;
  List<Artist> _artists = [];
  List<Album> _albums = [];
  List<Track> _tracks = [];
  bool _isLoading = false;
  String? _error;
  // Search state persistence
  String _lastSearchQuery = '';
  Map<String, List<MediaItem>> _lastSearchResults = {
    'artists': [],
    'albums': [],
    'tracks': [],
  };
  // Getters
  List<Artist> get artists => _artists;
  List<Album> get albums => _albums;
  List<Track> get tracks => _tracks;
  bool get isLoading => _isLoading;
  String? get error => _error;
  String get lastSearchQuery => _lastSearchQuery;
  Map<String, List<MediaItem>> get lastSearchResults => _lastSearchResults;
  LibraryProvider(this._cacheService);
  /// Initialize with API reference after connection
  void initialize(MusicAssistantAPI api) {
    _api = api;
  }
  void saveSearchState(String query, Map<String, List<MediaItem>> results) {
    _lastSearchQuery = query;
    _lastSearchResults = results;
  }
  void clearSearchState() {
    _lastSearchQuery = '';
    _lastSearchResults = {
      'artists': [],
      'albums': [],
      'tracks': [],
    };
  }
  // ============================================================================
  // HOME SCREEN DATA
  // ============================================================================
  /// Get recently played albums with caching
  Future<List<Album>> getRecentAlbumsWithCache({bool forceRefresh = false}) async {
    if (_cacheService.isRecentAlbumsCacheValid(forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached recent albums');
      return _cacheService.getCachedRecentAlbums()!;
    }
    if (_api == null) return _cacheService.getCachedRecentAlbums() ?? [];
    try {
      _logger.log('🔄 Fetching fresh recent albums...');
      final albums = await _api!.getRecentAlbums(limit: LibraryConstants.defaultRecentLimit);
      _cacheService.setCachedRecentAlbums(albums);
      return albums;
    } catch (e) {
      _logger.log('❌ Failed to fetch recent albums: $e');
      return _cacheService.getCachedRecentAlbums() ?? [];
    }
  }
  /// Get discover artists (random) with caching
  Future<List<Artist>> getDiscoverArtistsWithCache({bool forceRefresh = false}) async {
    if (_cacheService.isDiscoverArtistsCacheValid(forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached discover artists');
      return _cacheService.getCachedDiscoverArtists()!;
    }
    if (_api == null) return _cacheService.getCachedDiscoverArtists() ?? [];
    try {
      _logger.log('🔄 Fetching fresh discover artists...');
      final artists = await _api!.getRandomArtists(limit: LibraryConstants.defaultRecentLimit);
      _cacheService.setCachedDiscoverArtists(artists);
      return artists;
    } catch (e) {
      _logger.log('❌ Failed to fetch discover artists: $e');
      return _cacheService.getCachedDiscoverArtists() ?? [];
    }
  }
  /// Get discover albums (random) with caching
  Future<List<Album>> getDiscoverAlbumsWithCache({bool forceRefresh = false}) async {
    if (_cacheService.isDiscoverAlbumsCacheValid(forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached discover albums');
      return _cacheService.getCachedDiscoverAlbums()!;
    }
    if (_api == null) return _cacheService.getCachedDiscoverAlbums() ?? [];
    try {
      _logger.log('🔄 Fetching fresh discover albums...');
      final albums = await _api!.getRandomAlbums(limit: LibraryConstants.defaultRecentLimit);
      _cacheService.setCachedDiscoverAlbums(albums);
      return albums;
    } catch (e) {
      _logger.log('❌ Failed to fetch discover albums: $e');
      return _cacheService.getCachedDiscoverAlbums() ?? [];
    }
  }
  /// Invalidate home screen cache (call on pull-to-refresh)
  void invalidateHomeCache() {
    _cacheService.invalidateHomeCache();
  }
  // ============================================================================
  // LIBRARY DATA
  // ============================================================================
  Future<void> loadLibrary() async {
    if (_api == null) return;
    try {
      _isLoading = true;
      _error = null;
      notifyListeners();
      // Read artist filter setting - when ON, only fetch artists that have albums
      final showOnlyArtistsWithAlbums = await SettingsService.getShowOnlyArtistsWithAlbums();
      _logger.log('🎨 loadLibrary using albumArtistsOnly: $showOnlyArtistsWithAlbums');
      final results = await Future.wait([
        _api!.getArtists(limit: LibraryConstants.maxLibraryItems, albumArtistsOnly: showOnlyArtistsWithAlbums),
        _api!.getAlbums(limit: LibraryConstants.maxLibraryItems),
        _api!.getTracks(limit: LibraryConstants.maxLibraryItems),
      ]);
      _artists = results[0] as List<Artist>;
      _albums = results[1] as List<Album>;
      _tracks = results[2] as List<Track>;
      _isLoading = false;
      notifyListeners();
    } catch (e) {
      final errorInfo = ErrorHandler.handleError(e, context: 'Load library');
      _error = errorInfo.userMessage;
      _isLoading = false;
      notifyListeners();
    }
  }
  Future<void> loadArtists({int? limit, int? offset, String? search}) async {
    if (_api == null) return;
    try {
      _isLoading = true;
      _error = null;
      notifyListeners();
      // Read artist filter setting - when ON, only fetch artists that have albums
      final showOnlyArtistsWithAlbums = await SettingsService.getShowOnlyArtistsWithAlbums();
      _artists = await _api!.getArtists(
        limit: limit ?? LibraryConstants.maxLibraryItems,
        offset: offset,
        search: search,
        albumArtistsOnly: showOnlyArtistsWithAlbums,
      );
      _isLoading = false;
      notifyListeners();
    } catch (e) {
      final errorInfo = ErrorHandler.handleError(e, context: 'Load artists');
      _error = errorInfo.userMessage;
      _isLoading = false;
      notifyListeners();
    }
  }
  Future<void> loadAlbums({int? limit, int? offset, String? search, String? artistId}) async {
    if (_api == null) return;
    try {
      _isLoading = true;
      _error = null;
      notifyListeners();
      _albums = await _api!.getAlbums(
        limit: limit ?? LibraryConstants.maxLibraryItems,
        offset: offset,
        search: search,
        artistId: artistId,
      );
      _isLoading = false;
      notifyListeners();
    } catch (e) {
      final errorInfo = ErrorHandler.handleError(e, context: 'Load albums');
      _error = errorInfo.userMessage;
      _isLoading = false;
      notifyListeners();
    }
  }
  // ============================================================================
  // DETAIL SCREEN DATA
  // ============================================================================
  /// Get album tracks with caching
  Future<List<Track>> getAlbumTracksWithCache(String provider, String itemId, {bool forceRefresh = false}) async {
    final cacheKey = '${provider}_$itemId';
    if (_cacheService.isAlbumTracksCacheValid(cacheKey, forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached album tracks for $cacheKey');
      return _cacheService.getCachedAlbumTracks(cacheKey)!;
    }
    if (_api == null) return _cacheService.getCachedAlbumTracks(cacheKey) ?? [];
    try {
      _logger.log('🔄 Fetching fresh album tracks for $cacheKey...');
      final tracks = await _api!.getAlbumTracks(provider, itemId);
      _cacheService.setCachedAlbumTracks(cacheKey, tracks);
      return tracks;
    } catch (e) {
      _logger.log('❌ Failed to fetch album tracks: $e');
      return _cacheService.getCachedAlbumTracks(cacheKey) ?? [];
    }
  }
  /// Get playlist tracks with caching
  Future<List<Track>> getPlaylistTracksWithCache(String provider, String itemId, {bool forceRefresh = false}) async {
    final cacheKey = '${provider}_$itemId';
    if (_cacheService.isPlaylistTracksCacheValid(cacheKey, forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached playlist tracks for $cacheKey');
      return _cacheService.getCachedPlaylistTracks(cacheKey)!;
    }
    if (_api == null) return _cacheService.getCachedPlaylistTracks(cacheKey) ?? [];
    try {
      _logger.log('🔄 Fetching fresh playlist tracks for $cacheKey...');
      final tracks = await _api!.getPlaylistTracks(provider, itemId);
      _cacheService.setCachedPlaylistTracks(cacheKey, tracks);
      return tracks;
    } catch (e) {
      _logger.log('❌ Failed to fetch playlist tracks: $e');
      return _cacheService.getCachedPlaylistTracks(cacheKey) ?? [];
    }
  }
  /// Get artist albums with caching
  Future<List<Album>> getArtistAlbumsWithCache(String artistName, {bool forceRefresh = false}) async {
    final cacheKey = artistName.toLowerCase();
    if (_cacheService.isArtistAlbumsCacheValid(cacheKey, forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached artist albums for "$artistName"');
      return _cacheService.getCachedArtistAlbums(cacheKey)!;
    }
    if (_api == null) return _cacheService.getCachedArtistAlbums(cacheKey) ?? [];
    try {
      _logger.log('🔄 Fetching albums for artist "$artistName"...');
      final libraryAlbums = await _api!.getAlbums();
      final artistAlbums = libraryAlbums.where((album) {
        final albumArtists = album.artists;
        if (albumArtists == null || albumArtists.isEmpty) return false;
        return albumArtists.any((a) => a.name.toLowerCase() == artistName.toLowerCase());
      }).toList();
      final searchResults = await _api!.search(artistName);
      final searchAlbums = searchResults['albums'] as List<MediaItem>? ?? [];
      final providerAlbums = searchAlbums.whereType<Album>().where((album) {
        final albumArtists = album.artists;
        if (albumArtists == null || albumArtists.isEmpty) return false;
        return albumArtists.any((a) => a.name.toLowerCase() == artistName.toLowerCase());
      }).toList();
      final allAlbums = <Album>[];
      final seenNames = <String>{};
      for (final album in [...artistAlbums, ...providerAlbums]) {
        final key = album.name.toLowerCase();
        if (!seenNames.contains(key)) {
          seenNames.add(key);
          allAlbums.add(album);
        }
      }
      _cacheService.setCachedArtistAlbums(cacheKey, allAlbums);
      return allAlbums;
    } catch (e) {
      _logger.log('❌ Failed to fetch artist albums: $e');
      return _cacheService.getCachedArtistAlbums(cacheKey) ?? [];
    }
  }
  /// Invalidate album tracks cache
  void invalidateAlbumTracksCache(String albumId) {
    _cacheService.invalidateAlbumTracksCache(albumId);
  }
  /// Invalidate playlist tracks cache
  void invalidatePlaylistTracksCache(String playlistId) {
    _cacheService.invalidatePlaylistTracksCache(playlistId);
  }
  // ============================================================================
  // SEARCH
  // ============================================================================
  /// Search with caching
  Future<Map<String, List<MediaItem>>> searchWithCache(String query, {bool forceRefresh = false}) async {
    final cacheKey = query.toLowerCase().trim();
    if (cacheKey.isEmpty) return {'artists': [], 'albums': [], 'tracks': []};
    if (_cacheService.isSearchCacheValid(cacheKey, forceRefresh: forceRefresh)) {
      _logger.log('📦 Using cached search results for "$query"');
      return _cacheService.getCachedSearchResults(cacheKey)!;
    }
    if (_api == null) {
      return _cacheService.getCachedSearchResults(cacheKey) ?? {'artists': [], 'albums': [], 'tracks': []};
    }
    try {
      _logger.log('🔄 Searching for "$query"...');
      final results = await _api!.search(query);
      final cachedResults = <String, List<MediaItem>>{
        'artists': results['artists'] ?? [],
        'albums': results['albums'] ?? [],
        'tracks': results['tracks'] ?? [],
      };
      _cacheService.setCachedSearchResults(cacheKey, cachedResults);
      return cachedResults;
    } catch (e) {
      _logger.log('❌ Search failed: $e');
      return _cacheService.getCachedSearchResults(cacheKey) ?? {'artists': [], 'albums': [], 'tracks': []};
    }
  }
  Future<Map<String, List<MediaItem>>> search(String query, {bool libraryOnly = false}) async {
    if (_api == null) return {'artists': [], 'albums': [], 'tracks': []};
    try {
      return await _api!.search(query, libraryOnly: libraryOnly);
    } catch (e) {
      ErrorHandler.logError('Search', e);
      return {'artists': [], 'albums': [], 'tracks': []};
    }
  }
  Future<List<Track>> getAlbumTracks(String provider, String itemId) async {
    if (_api == null) return [];
    try {
      return await _api!.getAlbumTracks(provider, itemId);
    } catch (e) {
      ErrorHandler.logError('Get album tracks', e);
      return [];
    }
  }
  void clearState() {
    _artists = [];
    _albums = [];
    _tracks = [];
    _isLoading = false;
    _error = null;
    clearSearchState();
    notifyListeners();
  }
 }
@@ -31,6 +31,10 @@ class LocaleProvider extends ChangeNotifier {
        return 'English';
      case 'de':
        return 'Deutsch';
      case 'es':
        return 'Español';
      case 'fr':
        return 'Français';
      case null:
        return 'System';
      default:
@@ -1,964 +0,0 @@
 import 'dart:async';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/painting.dart';
 import '../models/media_item.dart';
 import '../models/player.dart';
 import '../services/music_assistant_api.dart';
 import '../services/settings_service.dart';
 import '../services/debug_logger.dart';
 import '../services/error_handler.dart';
 import '../services/local_player_service.dart';
 import '../services/auth/auth_manager.dart';
 import '../services/device_id_service.dart';
 import '../services/cache_service.dart';
 import '../constants/timings.dart';
 import '../main.dart' show audioHandler;
 /// Provider for managing player state, selection, and controls
 class PlayerProvider with ChangeNotifier {
  final DebugLogger _logger = DebugLogger();
  late final LocalPlayerService _localPlayer;
  final CacheService _cacheService;
  // Dependencies injected from parent provider
  MusicAssistantAPI? _api;
  AuthManager? _authManager;
  String? _serverUrl;
  // Player selection
  Player? _selectedPlayer;
  List<Player> _availablePlayers = [];
  Track? _currentTrack;
  Timer? _playerStateTimer;
  Timer? _adjacentPlayerCacheTimer;
  // Local Playback
  bool _isLocalPlayerPowered = true;
  StreamSubscription? _localPlayerEventSubscription;
  StreamSubscription? _playerUpdatedEventSubscription;
  Timer? _localPlayerStateReportTimer;
  // Pending metadata from player_updated events
  TrackMetadata? _pendingTrackMetadata;
  TrackMetadata? _currentNotificationMetadata;
  // Registration guard
  Completer<void>? _registrationInProgress;
  // Getters
  Player? get selectedPlayer => _selectedPlayer;
  List<Player> get availablePlayers => _availablePlayers;
  Track? get currentTrack => _currentTrack;
  bool get isLocalPlayerPowered => _isLocalPlayerPowered;
  /// Get cached track for a player (used for smooth swipe transitions)
  Track? getCachedTrackForPlayer(String playerId) => _cacheService.getCachedTrackForPlayer(playerId);
  PlayerProvider(this._cacheService, AuthManager authManager) {
    _authManager = authManager;
    _localPlayer = LocalPlayerService(authManager);
  }
  /// Initialize with API reference after connection
  void initialize(MusicAssistantAPI api, String serverUrl) {
    _api = api;
    _serverUrl = serverUrl;
  }
  /// Set up event listeners after connection
  Future<void> setupEventListeners() async {
    if (_api == null) return;
    // Listen to built-in player events
    _localPlayerEventSubscription?.cancel();
    _localPlayerEventSubscription = _api!.builtinPlayerEvents.listen(
      _handleLocalPlayerEvent,
      onError: (error) {
        _logger.log('Builtin player event stream error: $error');
      },
    );
    // Listen to player_updated events
    _playerUpdatedEventSubscription?.cancel();
    _playerUpdatedEventSubscription = _api!.playerUpdatedEvents.listen(
      _handlePlayerUpdatedEvent,
      onError: (error) {
        _logger.log('Player updated event stream error: $error');
      },
    );
  }
  /// Initialize local playback
  Future<void> initializeLocalPlayback() async {
    await _localPlayer.initialize();
    _isLocalPlayerPowered = true;
    // Wire up skip button callbacks
    audioHandler.onSkipToNext = () {
      _logger.log('🎵 Notification: Skip to next pressed');
      nextTrackSelectedPlayer();
    };
    audioHandler.onSkipToPrevious = () {
      _logger.log('🎵 Notification: Skip to previous pressed');
      previousTrackSelectedPlayer();
    };
    if (_api != null) {
      await registerLocalPlayer();
    }
  }
  /// Try to adopt an existing ghost player
  Future<bool> tryAdoptGhostPlayer() async {
    if (_api == null) return false;
    try {
      final isFresh = await DeviceIdService.isFreshInstallation();
      if (!isFresh) {
        _logger.log('👻 Not a fresh install, skipping ghost adoption');
        return false;
      }
      final ownerName = await SettingsService.getOwnerName();
      if (ownerName == null || ownerName.isEmpty) {
        _logger.log('👻 No owner name set, cannot adopt ghost player');
        return false;
      }
      _logger.log('👻 Fresh install detected, searching for adoptable ghost for "$ownerName"...');
      final adoptableId = await _api!.findAdoptableGhostPlayer(ownerName);
      if (adoptableId == null) {
        _logger.log('👻 No matching ghost player found - will generate new ID');
        return false;
      }
      _logger.log('👻 Found adoptable ghost: $adoptableId');
      await DeviceIdService.adoptPlayerId(adoptableId);
      _logger.log('✅ Successfully adopted ghost player');
      return true;
    } catch (e) {
      _logger.log('⚠️ Ghost adoption failed (non-fatal): $e');
      return false;
    }
  }
  /// Register local player with MA server
  Future<void> registerLocalPlayer() async {
    if (_api == null) return;
    if (_registrationInProgress != null) {
      _logger.log('⏳ Registration already in progress, waiting...');
      return _registrationInProgress!.future;
    }
    _registrationInProgress = Completer<void>();
    try {
      final playerId = await DeviceIdService.getOrCreateDevicePlayerId();
      _logger.log('🆔 Using player ID: $playerId');
      await SettingsService.setBuiltinPlayerId(playerId);
      final name = await SettingsService.getLocalPlayerName();
      final existingPlayers = await _api!.getPlayers();
      final existingPlayer = existingPlayers.where((p) => p.playerId == playerId).firstOrNull;
      if (existingPlayer != null && existingPlayer.available) {
        _logger.log('✅ Player already registered and available: $playerId');
        _startReportingLocalPlayerState();
        if (_registrationInProgress != null && !_registrationInProgress!.isCompleted) {
          _registrationInProgress!.complete();
        }
        _registrationInProgress = null;
        return;
      } else if (existingPlayer != null && !existingPlayer.available) {
        _logger.log('⚠️ Player exists but unavailable (stale), re-registering: $playerId');
      } else {
        _logger.log('🆔 Player not found in MA, registering as new');
      }
      _logger.log('🎵 Registering player with MA: id=$playerId, name=$name');
      await _api!.registerBuiltinPlayer(playerId, name);
      _logger.log('✅ Player registration complete');
      _startReportingLocalPlayerState();
      if (_registrationInProgress != null && !_registrationInProgress!.isCompleted) {
        _registrationInProgress!.complete();
      }
      _registrationInProgress = null;
    } catch (e) {
      _logger.log('❌ CRITICAL: Player registration failed: $e');
      if (_registrationInProgress != null && !_registrationInProgress!.isCompleted) {
        _registrationInProgress!.completeError(e);
      }
      _registrationInProgress = null;
      rethrow;
    }
  }
  void _startReportingLocalPlayerState() {
    _localPlayerStateReportTimer?.cancel();
    _localPlayerStateReportTimer = Timer.periodic(Timings.localPlayerReportInterval, (_) async {
      try {
        await _reportLocalPlayerState();
      } catch (e) {
        _logger.log('Error reporting local player state (will retry): $e');
      }
    });
  }
  Future<void> _reportLocalPlayerState() async {
    if (_api == null) return;
    // Don't try to report state if not authenticated - avoids spamming errors
    if (_api!.currentConnectionState != MAConnectionState.authenticated) return;
    final playerId = await SettingsService.getBuiltinPlayerId();
    if (playerId == null) return;
    final isPlaying = _localPlayer.isPlaying;
    final position = _localPlayer.position.inSeconds;
    final volume = (_localPlayer.volume * 100).round();
    final isPaused = !isPlaying && position > 0;
    await _api!.updateBuiltinPlayerState(
      playerId,
      powered: _isLocalPlayerPowered,
      playing: isPlaying,
      paused: isPaused,
      position: position,
      volume: volume,
      muted: _localPlayer.volume == 0.0,
    );
  }
  Future<void> _handleLocalPlayerEvent(Map<String, dynamic> event) async {
    _logger.log('📥 Local player event received: ${event['type'] ?? event['command']}');
    try {
      final eventPlayerId = event['player_id'] as String?;
      final myPlayerId = await SettingsService.getBuiltinPlayerId();
      if (eventPlayerId != null && myPlayerId != null && eventPlayerId != myPlayerId) {
        _logger.log('🚫 Ignoring event for different player: $eventPlayerId');
        return;
      }
      final command = (event['type'] as String?) ?? (event['command'] as String?);
      switch (command) {
        case 'play_media':
          final urlPath = event['media_url'] as String? ?? event['url'] as String?;
          if (urlPath != null && _serverUrl != null) {
            String fullUrl;
            if (urlPath.startsWith('http')) {
              fullUrl = urlPath;
            } else {
              var baseUrl = _serverUrl!;
              if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
                baseUrl = 'https://$baseUrl';
              }
              baseUrl = baseUrl.endsWith('/') ? baseUrl.substring(0, baseUrl.length - 1) : baseUrl;
              final path = urlPath.startsWith('/') ? urlPath : '/$urlPath';
              fullUrl = '$baseUrl$path';
            }
            TrackMetadata metadata;
            if (_pendingTrackMetadata != null) {
              metadata = _pendingTrackMetadata!;
            } else {
              final trackName = event['track_name'] as String? ?? event['name'] as String? ?? 'Unknown Track';
              final artistName = event['artist_name'] as String? ?? event['artist'] as String? ?? 'Unknown Artist';
              final albumName = event['album_name'] as String? ?? event['album'] as String?;
              var artworkUrl = event['image_url'] as String? ?? event['artwork_url'] as String?;
              final durationSecs = event['duration'] as int?;
              if (artworkUrl != null && artworkUrl.startsWith('http://')) {
                artworkUrl = artworkUrl.replaceFirst('http://', 'https://');
              }
              metadata = TrackMetadata(
                title: trackName,
                artist: artistName,
                album: albumName,
                artworkUrl: artworkUrl,
                duration: durationSecs != null ? Duration(seconds: durationSecs) : null,
              );
            }
            _localPlayer.setCurrentTrackMetadata(metadata);
            _currentNotificationMetadata = metadata;
            await _localPlayer.playUrl(fullUrl);
          }
          break;
        case 'stop':
          await _localPlayer.stop();
          break;
        case 'pause':
          await _localPlayer.pause();
          break;
        case 'play':
          await _localPlayer.play();
          break;
        case 'seek':
          final position = event['position'] as int?;
          if (position != null) {
            await _localPlayer.seek(Duration(seconds: position));
          }
          break;
        case 'volume_set':
          final volume = event['volume_level'] as int?;
          if (volume != null) {
            await _localPlayer.setVolume(volume / 100.0);
          }
          break;
        case 'power_on':
        case 'power_off':
        case 'power':
          bool? newPowerState;
          if (command == 'power_on') {
            newPowerState = true;
          } else if (command == 'power_off') {
            newPowerState = false;
          } else {
            newPowerState = event['powered'] as bool?;
          }
          if (newPowerState != null) {
            _isLocalPlayerPowered = newPowerState;
            if (!_isLocalPlayerPowered) {
              await _localPlayer.stop();
            }
          }
          break;
      }
      await _reportLocalPlayerState();
    } catch (e) {
      _logger.log('Error handling local player event: $e');
    }
  }
  Future<void> _handlePlayerUpdatedEvent(Map<String, dynamic> event) async {
    try {
      final playerId = event['player_id'] as String?;
      if (playerId == null) return;
      if (_selectedPlayer != null && playerId == _selectedPlayer!.playerId) {
        _updatePlayerState();
      }
      final currentMedia = event['current_media'] as Map<String, dynamic>?;
      final playerName = event['name'] as String? ?? playerId;
      if (currentMedia != null) {
        final mediaType = currentMedia['media_type'] as String?;
        if (mediaType != 'flow_stream') {
          final durationSecs = (currentMedia['duration'] as num?)?.toInt();
          final albumName = currentMedia['album'] as String?;
          final imageUrl = currentMedia['image_url'] as String?;
          Map<String, dynamic>? metadata;
          if (imageUrl != null && _serverUrl != null) {
            var finalImageUrl = imageUrl;
            try {
              final imgUri = Uri.parse(imageUrl);
              final queryString = imgUri.query;
              var baseUrl = _serverUrl!;
              if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
                baseUrl = 'https://$baseUrl';
              }
              if (baseUrl.endsWith('/')) {
                baseUrl = baseUrl.substring(0, baseUrl.length - 1);
              }
              finalImageUrl = '$baseUrl/imageproxy?$queryString';
            } catch (e) {
              // Use original URL
            }
            metadata = {
              'images': [{'path': finalImageUrl, 'provider': 'direct'}]
            };
          }
          final trackFromEvent = Track(
            itemId: currentMedia['queue_item_id'] as String? ?? '',
            provider: 'library',
            name: currentMedia['title'] as String? ?? 'Unknown Track',
            uri: currentMedia['uri'] as String?,
            duration: durationSecs != null ? Duration(seconds: durationSecs) : null,
            artists: [Artist(itemId: '', provider: 'library', name: currentMedia['artist'] as String? ?? 'Unknown Artist')],
            album: albumName != null ? Album(itemId: '', provider: 'library', name: albumName) : null,
            metadata: metadata,
          );
          _cacheService.setCachedTrackForPlayer(playerId, trackFromEvent);
          if (_selectedPlayer != null && playerId == _selectedPlayer!.playerId) {
            _currentTrack = trackFromEvent;
          }
          _logger.log('📋 Cached track for $playerName: ${trackFromEvent.name}');
          if (imageUrl != null) {
            final images = metadata?['images'] as List?;
            if (images != null && images.isNotEmpty) {
              final imagePath = images[0]['path'] as String?;
              if (imagePath != null) {
                _precacheImage(imagePath);
              }
            }
          }
          notifyListeners();
        }
      }
      // Handle notification metadata for local player
      final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
      if (builtinPlayerId == null || playerId != builtinPlayerId) return;
      if (currentMedia == null) return;
      final title = currentMedia['title'] as String? ?? 'Unknown Track';
      final artist = currentMedia['artist'] as String? ?? 'Unknown Artist';
      final album = currentMedia['album'] as String?;
      var imageUrl = currentMedia['image_url'] as String?;
      final durationSecs = (currentMedia['duration'] as num?)?.toInt();
      if (imageUrl != null && _serverUrl != null) {
        try {
          final imgUri = Uri.parse(imageUrl);
          final queryString = imgUri.query;
          var baseUrl = _serverUrl!;
          if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
            baseUrl = 'https://$baseUrl';
          }
          if (baseUrl.endsWith('/')) {
            baseUrl = baseUrl.substring(0, baseUrl.length - 1);
          }
          imageUrl = '$baseUrl/imageproxy?$queryString';
        } catch (e) {
          if (imageUrl != null && imageUrl.startsWith('http://')) {
            imageUrl = imageUrl.replaceFirst('http://', 'https://');
          }
        }
      }
      final newMetadata = TrackMetadata(
        title: title,
        artist: artist,
        album: album,
        artworkUrl: imageUrl,
        duration: durationSecs != null ? Duration(seconds: durationSecs) : null,
      );
      final mediaType = currentMedia['media_type'] as String?;
      if (mediaType == 'flow_stream') return;
      _pendingTrackMetadata = newMetadata;
      final notificationNeedsUpdate = _currentNotificationMetadata != null &&
          (_currentNotificationMetadata!.title != title ||
           _currentNotificationMetadata!.artist != artist);
      if (_localPlayer.isPlaying && notificationNeedsUpdate) {
        await _localPlayer.updateNotificationWhilePlaying(newMetadata);
        _currentNotificationMetadata = newMetadata;
      }
    } catch (e) {
      _logger.log('Error handling player_updated event: $e');
    }
  }
  // ============================================================================
  // PLAYER SELECTION
  // ============================================================================
  Future<void> loadAndSelectPlayers({bool forceRefresh = false}) async {
    if (_api == null) return;
    try {
      if (!forceRefresh && _cacheService.isPlayersCacheValid() && _availablePlayers.isNotEmpty) {
        return;
      }
      final allPlayers = await _api!.getPlayers();
      final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
      _logger.log('🎛️ getPlayers returned ${allPlayers.length} players');
      int filteredCount = 0;
      _availablePlayers = allPlayers.where((player) {
        final nameLower = player.name.toLowerCase();
        if (nameLower.contains('music assistant mobile')) {
          filteredCount++;
          return false;
        }
        // Filter out MA Web UI's built-in player (provider is 'builtin_player' and starts with 'ma_')
        // Note: We check BOTH conditions to avoid filtering snapcast/other players that may have 'ma_' prefix
        if (player.provider == 'builtin_player' && player.playerId.startsWith('ma_')) {
          filteredCount++;
          return false;
        }
        // Also filter "This Device" named players without proper provider
        if (nameLower == 'this device') {
          filteredCount++;
          return false;
        }
        if (player.playerId.startsWith('ensemble_')) {
          if (builtinPlayerId == null || player.playerId != builtinPlayerId) {
            filteredCount++;
            return false;
          }
        }
        if (!player.available) {
          if (builtinPlayerId != null && player.playerId == builtinPlayerId) {
            return true;
          }
          filteredCount++;
          return false;
        }
        return true;
      }).toList();
      _availablePlayers.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));
      _cacheService.updatePlayersLastFetched();
      _logger.log('🎛️ After filtering: ${_availablePlayers.length} players available');
      if (_availablePlayers.isNotEmpty) {
        Player? playerToSelect;
        if (_selectedPlayer != null) {
          final stillAvailable = _availablePlayers.any(
            (p) => p.playerId == _selectedPlayer!.playerId && p.available,
          );
          if (stillAvailable) {
            playerToSelect = _availablePlayers.firstWhere(
              (p) => p.playerId == _selectedPlayer!.playerId,
            );
          }
        }
        if (playerToSelect == null) {
          final lastSelectedPlayerId = await SettingsService.getLastSelectedPlayerId();
          // Priority 1: Last selected player
          if (lastSelectedPlayerId != null) {
            playerToSelect = _availablePlayers.cast<Player?>().firstWhere(
              (p) => p!.playerId == lastSelectedPlayerId && p.available,
              orElse: () => null,
            );
          }
          // Priority 2: Built-in (local) player
          if (playerToSelect == null && builtinPlayerId != null) {
            playerToSelect = _availablePlayers.cast<Player?>().firstWhere(
              (p) => p!.playerId == builtinPlayerId && p.available,
              orElse: () => null,
            );
          }
          // Priority 3: Currently playing player (exclude external sources - not playing MA content)
          if (playerToSelect == null) {
            playerToSelect = _availablePlayers.cast<Player?>().firstWhere(
              (p) => p!.state == 'playing' && p.available && !p.isExternalSource,
              orElse: () => null,
            );
          }
          if (playerToSelect == null) {
            playerToSelect = _availablePlayers.firstWhere(
              (p) => p.available,
              orElse: () => _availablePlayers.first,
            );
          }
        }
        selectPlayer(playerToSelect);
      }
      _preloadAdjacentPlayers(preloadAll: true);
    } catch (e) {
      ErrorHandler.logError('Load and select players', e);
    }
  }
  void selectPlayer(Player player, {bool skipNotify = false}) {
    _selectedPlayer = player;
    SettingsService.setLastSelectedPlayerId(player.playerId);
    _startPlayerStatePolling();
    _preloadAdjacentPlayers();
    if (!skipNotify) {
      notifyListeners();
    }
  }
  Future<void> _preloadAdjacentPlayers({bool preloadAll = false}) async {
    if (_api == null) return;
    final players = _availablePlayers.where((p) => p.available).toList();
    if (players.isEmpty) return;
    if (preloadAll) {
      _logger.log('🖼️ Preloading track info for all ${players.length} players...');
      await Future.wait(players.map((player) => _preloadPlayerTrack(player)));
      _logger.log('🖼️ Preloading complete');
      return;
    }
    if (_selectedPlayer == null || players.length <= 1) return;
    final currentIndex = players.indexWhere((p) => p.playerId == _selectedPlayer!.playerId);
    if (currentIndex == -1) return;
    final prevIndex = currentIndex <= 0 ? players.length - 1 : currentIndex - 1;
    final nextIndex = currentIndex >= players.length - 1 ? 0 : currentIndex + 1;
    final playersToPreload = <Player>{};
    if (prevIndex != currentIndex) playersToPreload.add(players[prevIndex]);
    if (nextIndex != currentIndex) playersToPreload.add(players[nextIndex]);
    for (final player in playersToPreload) {
      _preloadPlayerTrack(player);
    }
  }
  Future<void> _preloadPlayerTrack(Player player) async {
    if (_api == null) return;
    try {
      if (!player.available || !player.powered) {
        _cacheService.setCachedTrackForPlayer(player.playerId, null);
        return;
      }
      final queue = await _api!.getQueue(player.playerId);
      if (queue != null && queue.currentItem != null) {
        final track = queue.currentItem!.track;
        final existingTrack = _cacheService.getCachedTrackForPlayer(player.playerId);
        final existingHasImage = existingTrack?.metadata?['images'] != null;
        final newHasImage = track.metadata?['images'] != null;
        if (!existingHasImage || newHasImage) {
          _cacheService.setCachedTrackForPlayer(player.playerId, track);
        }
        final artworkUrl512 = _api!.getImageUrl(existingHasImage ? existingTrack! : track, size: 512);
        if (artworkUrl512 != null) {
          await _precacheImage(artworkUrl512);
        }
      } else {
        final existingTrack = _cacheService.getCachedTrackForPlayer(player.playerId);
        if (existingTrack?.metadata?['images'] == null) {
          _cacheService.setCachedTrackForPlayer(player.playerId, null);
        }
      }
    } catch (e) {
      _logger.log('Error preloading player track for ${player.name}: $e');
    }
  }
  Future<void> _precacheImage(String url) async {
    try {
      final imageProvider = NetworkImage(url);
      final imageStream = imageProvider.resolve(const ImageConfiguration());
      final completer = Completer<void>();
      late ImageStreamListener listener;
      listener = ImageStreamListener(
        (ImageInfo info, bool synchronousCall) {
          if (!completer.isCompleted) completer.complete();
          imageStream.removeListener(listener);
        },
        onError: (exception, stackTrace) {
          if (!completer.isCompleted) completer.completeError(exception);
          imageStream.removeListener(listener);
        },
      );
      imageStream.addListener(listener);
      await completer.future.timeout(const Duration(seconds: 10), onTimeout: () {
        imageStream.removeListener(listener);
      });
    } catch (e) {
      _logger.log('Image precache failed for $url: $e');
    }
  }
  Future<void> preloadAllPlayerTracks() async {
    if (_api == null) return;
    final players = _availablePlayers.where((p) => p.available).toList();
    await Future.wait(players.map((player) => _preloadPlayerTrack(player)));
  }
  void _startPlayerStatePolling() {
    _playerStateTimer?.cancel();
    if (_selectedPlayer == null) return;
    _playerStateTimer = Timer.periodic(Timings.playerPollingInterval, (_) async {
      try {
        await _updatePlayerState();
      } catch (e) {
        _logger.log('Error updating player state (will retry): $e');
      }
    });
    _updatePlayerState();
  }
  Future<void> _updatePlayerState() async {
    if (_selectedPlayer == null || _api == null) return;
    try {
      bool stateChanged = false;
      final allPlayers = await _api!.getPlayers();
      final updatedPlayer = allPlayers.firstWhere(
        (p) => p.playerId == _selectedPlayer!.playerId,
        orElse: () => _selectedPlayer!,
      );
      _selectedPlayer = updatedPlayer;
      stateChanged = true;
      final isPlayingOrPaused = _selectedPlayer!.state == 'playing' || _selectedPlayer!.state == 'paused';
      final isIdleWithContent = _selectedPlayer!.state == 'idle' && _selectedPlayer!.powered;
      final shouldShowTrack = _selectedPlayer!.available && (isPlayingOrPaused || isIdleWithContent);
      if (!shouldShowTrack) {
        if (_currentTrack != null) {
          _currentTrack = null;
          stateChanged = true;
        }
        if (stateChanged) notifyListeners();
        return;
      }
      final queue = await _api!.getQueue(_selectedPlayer!.playerId);
      if (queue != null && queue.currentItem != null) {
        if (_currentTrack == null ||
            _currentTrack!.uri != queue.currentItem!.track.uri ||
            _currentTrack!.name != queue.currentItem!.track.name) {
          _currentTrack = queue.currentItem!.track;
          stateChanged = true;
          final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
          if (builtinPlayerId != null && _selectedPlayer!.playerId == builtinPlayerId) {
            final track = _currentTrack!;
            final artworkUrl = _api?.getImageUrl(track, size: 512);
            _localPlayer.updateNotification(
              id: track.uri ?? track.itemId,
              title: track.name,
              artist: track.artistsString,
              album: track.album?.name,
              artworkUrl: artworkUrl,
              duration: track.duration,
            );
          }
        }
      } else {
        if (_currentTrack != null) {
          _currentTrack = null;
          stateChanged = true;
        }
      }
      if (stateChanged) notifyListeners();
    } catch (e) {
      _logger.log('❌ Error updating player state: $e');
    }
  }
  // ============================================================================
  // PLAYER CONTROLS
  // ============================================================================
  Future<void> playPauseSelectedPlayer() async {
    if (_selectedPlayer == null || _api == null) return;
    if (_selectedPlayer!.isPlaying) {
      await _api!.pausePlayer(_selectedPlayer!.playerId);
    } else {
      await _api!.resumePlayer(_selectedPlayer!.playerId);
    }
    await refreshPlayers();
  }
  Future<void> nextTrackSelectedPlayer() async {
    if (_selectedPlayer == null || _api == null) return;
    await _api!.nextTrack(_selectedPlayer!.playerId);
    await Future.delayed(Timings.trackChangeDelay);
    await _updatePlayerState();
  }
  Future<void> previousTrackSelectedPlayer() async {
    if (_selectedPlayer == null || _api == null) return;
    await _api!.previousTrack(_selectedPlayer!.playerId);
    await Future.delayed(Timings.trackChangeDelay);
    await _updatePlayerState();
  }
  Future<void> refreshPlayers() async {
    final previousState = _selectedPlayer?.state;
    final previousVolume = _selectedPlayer?.volumeLevel;
    await loadAndSelectPlayers(forceRefresh: true);
    bool stateChanged = false;
    if (_selectedPlayer != null && _availablePlayers.isNotEmpty) {
      try {
        final updatedPlayer = _availablePlayers.firstWhere(
          (p) => p.playerId == _selectedPlayer!.playerId,
        );
        if (updatedPlayer.state != previousState || updatedPlayer.volumeLevel != previousVolume) {
          stateChanged = true;
        }
        _selectedPlayer = updatedPlayer;
      } catch (e) {
        stateChanged = true;
      }
    }
    if (stateChanged) notifyListeners();
  }
  Future<void> togglePower(String playerId) async {
    if (_api == null) return;
    try {
      final localPlayerId = await SettingsService.getBuiltinPlayerId();
      final isLocalPlayer = localPlayerId != null && playerId == localPlayerId;
      if (isLocalPlayer) {
        _isLocalPlayerPowered = !_isLocalPlayerPowered;
        if (!_isLocalPlayerPowered) {
          await _localPlayer.stop();
        }
        await _reportLocalPlayerState();
        await refreshPlayers();
      } else {
        final player = _availablePlayers.firstWhere(
          (p) => p.playerId == playerId,
          orElse: () => _selectedPlayer != null && _selectedPlayer!.playerId == playerId
              ? _selectedPlayer!
              : throw Exception("Player not found"),
        );
        await _api!.setPower(playerId, !player.powered);
        await refreshPlayers();
      }
    } catch (e) {
      ErrorHandler.logError('Toggle power', e);
    }
  }
  Future<void> setVolume(String playerId, int volumeLevel) async {
    if (_api == null) return;
    try {
      await _api!.setVolume(playerId, volumeLevel);
    } catch (e) {
      ErrorHandler.logError('Set volume', e);
      rethrow;
    }
  }
  Future<void> setMute(String playerId, bool muted) async {
    if (_api == null) return;
    try {
      await _api!.setMute(playerId, muted);
      await refreshPlayers();
    } catch (e) {
      ErrorHandler.logError('Set mute', e);
      rethrow;
    }
  }
  Future<void> seek(String playerId, int position) async {
    if (_api == null) return;
    try {
      await _api!.seek(playerId, position);
    } catch (e) {
      ErrorHandler.logError('Seek', e);
      rethrow;
    }
  }
  Future<void> toggleShuffle(String queueId, bool shuffleEnabled) async {
    if (_api == null) return;
    try {
      await _api!.toggleShuffle(queueId, shuffleEnabled);
    } catch (e) {
      ErrorHandler.logError('Toggle shuffle', e);
      rethrow;
    }
  }
  Future<void> setRepeatMode(String queueId, String mode) async {
    if (_api == null) return;
    try {
      await _api!.setRepeatMode(queueId, mode);
    } catch (e) {
      ErrorHandler.logError('Set repeat mode', e);
      rethrow;
    }
  }
  Future<void> cycleRepeatMode(String queueId, String? currentMode) async {
    String nextMode;
    switch (currentMode) {
      case 'off':
      case null:
        nextMode = 'all';
        break;
      case 'all':
        nextMode = 'one';
        break;
      case 'one':
        nextMode = 'off';
        break;
      default:
        nextMode = 'off';
    }
    await setRepeatMode(queueId, nextMode);
  }
  void clearState() {
    _playerStateTimer?.cancel();
    _playerStateTimer = null;
    _localPlayerStateReportTimer?.cancel();
    _localPlayerEventSubscription?.cancel();
    _playerUpdatedEventSubscription?.cancel();
    _availablePlayers = [];
    _selectedPlayer = null;
    _currentTrack = null;
  }
  @override
  void dispose() {
    clearState();
    super.dispose();
  }
 }
@@ -0,0 +1,129 @@
 import 'dart:async';
 import 'package:flutter/foundation.dart';
 import '../services/debug_logger.dart';
 /// Callback type for when sleep timer expires and should pause playback
 typedef OnSleepTimerExpired = void Function();
 /// Provider for sleep timer functionality.
 ///
 /// Extracted from MusicAssistantProvider to reduce complexity and improve testability.
 /// This provider manages:
 /// - Timed sleep (pause after X minutes)
 /// - End of track sleep (pause when current track ends)
 class SleepTimerProvider with ChangeNotifier {
  final DebugLogger _logger = DebugLogger();
  Timer? _sleepTimer;
  DateTime? _sleepTimerEndTime;
  int? _sleepTimerMinutes; // null = off, -1 = end of track, positive = minutes
  Timer? _sleepTimerDisplayTimer;
  /// Callback to pause playback when timer expires
  OnSleepTimerExpired? onExpired;
  // ============================================================================
  // GETTERS
  // ============================================================================
  /// Whether a sleep timer is currently active
  bool get isActive => _sleepTimerMinutes != null;
  /// Current timer setting: null = off, -1 = end of track, positive = minutes
  int? get minutes => _sleepTimerMinutes;
  /// Time remaining until sleep timer expires (null if end-of-track mode or inactive)
  Duration? get remaining {
    if (_sleepTimerEndTime == null) return null;
    final remaining = _sleepTimerEndTime!.difference(DateTime.now());
    return remaining.isNegative ? Duration.zero : remaining;
  }
  // ============================================================================
  // TIMER CONTROL
  // ============================================================================
  /// Set sleep timer. Pass null to turn off, -1 for end of track, or minutes.
  void setTimer(int? minutes) {
    // Cancel any existing timer
    _cancelInternal();
    _sleepTimerMinutes = minutes;
    if (minutes == null) {
      // Timer off
      _logger.log('😴 Sleep timer: OFF');
      notifyListeners();
      return;
    }
    if (minutes == -1) {
      // End of track - handled in player state updates
      _sleepTimerEndTime = null; // No fixed end time
      _logger.log('😴 Sleep timer: End of track');
      notifyListeners();
      return;
    }
    // Set timer for specified minutes
    _sleepTimerEndTime = DateTime.now().add(Duration(minutes: minutes));
    _logger.log('😴 Sleep timer: $minutes minutes (until $_sleepTimerEndTime)');
    // Create the actual timer
    _sleepTimer = Timer(Duration(minutes: minutes), _onTimerExpired);
    // Start display update timer (every second for countdown)
    _sleepTimerDisplayTimer = Timer.periodic(const Duration(seconds: 1), (_) {
      notifyListeners(); // Update UI with remaining time
    });
    notifyListeners();
  }
  /// Cancel sleep timer
  void cancel() {
    _cancelInternal();
    _sleepTimerMinutes = null;
    _sleepTimerEndTime = null;
    _logger.log('😴 Sleep timer: Cancelled');
    notifyListeners();
  }
  void _cancelInternal() {
    _sleepTimer?.cancel();
    _sleepTimer = null;
    _sleepTimerDisplayTimer?.cancel();
    _sleepTimerDisplayTimer = null;
  }
  void _onTimerExpired() {
    _logger.log('😴 Sleep timer expired - pausing playback');
    _cancelInternal();
    _sleepTimerMinutes = null;
    _sleepTimerEndTime = null;
    // Trigger the callback to pause playback
    onExpired?.call();
    notifyListeners();
  }
  /// Called when track ends - checks if "end of track" sleep timer is active
  void checkEndOfTrack() {
    if (_sleepTimerMinutes == -1) {
      _logger.log('😴 End of track sleep timer triggered');
      _sleepTimerMinutes = null;
      // Trigger the callback to pause playback
      onExpired?.call();
      notifyListeners();
    }
  }
  @override
  void dispose() {
    _cancelInternal();
    super.dispose();
  }
 }
@@ -10,8 +10,8 @@ import '../services/metadata_service.dart';
 import '../services/debug_logger.dart';
 import '../services/recently_played_service.dart';
 import '../widgets/global_player_overlay.dart';
 import '../widgets/player_picker_sheet.dart';
 import '../l10n/app_localizations.dart';
 import '../theme/design_tokens.dart';
 import 'artist_details_screen.dart';
 class AlbumDetailsScreen extends StatefulWidget {
@@ -222,7 +222,6 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
    try {
      final newState = !_isInLibrary;
      bool success;
      if (newState) {
        // Add to library - MUST use non-library provider
@@ -253,12 +252,35 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
          }
        }
        // OPTIMISTIC UPDATE: Update UI immediately
        setState(() {
          _isInLibrary = newState;
        });
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(S.of(context)!.addedToLibrary),
              duration: const Duration(seconds: 1),
            ),
          );
        }
        _logger.log('Adding album to library: provider=$actualProvider, itemId=$actualItemId');
-        success = await maProvider.addToLibrary(
+        // Fire and forget - API call happens in background
        maProvider.addToLibrary(
          mediaType: 'album',
          provider: actualProvider,
          itemId: actualItemId,
-        );
+        ).catchError((e) {
          _logger.log('❌ Failed to add album to library: $e');
          // Revert on failure
          if (mounted) {
            setState(() {
              _isInLibrary = !newState;
            });
          }
        });
      } else {
        // Remove from library
        int? libraryItemId;
@@ -279,13 +301,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
          return;
        }
-        success = await maProvider.removeFromLibrary(
+        // OPTIMISTIC UPDATE: Update UI immediately
          mediaType: 'album',
          libraryItemId: libraryItemId,
        );
      }
      if (success) {
        setState(() {
          _isInLibrary = newState;
        });
@@ -293,13 +309,25 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
-              content: Text(
+              content: Text(S.of(context)!.removedFromLibrary),
                _isInLibrary ? S.of(context)!.addedToLibrary : S.of(context)!.removedFromLibrary,
              ),
              duration: const Duration(seconds: 1),
            ),
          );
        }
        // Fire and forget - API call happens in background
        maProvider.removeFromLibrary(
          mediaType: 'album',
          libraryItemId: libraryItemId,
        ).catchError((e) {
          _logger.log('❌ Failed to remove album from library: $e');
          // Revert on failure
          if (mounted) {
            setState(() {
              _isInLibrary = !newState;
            });
          }
        });
      }
    } catch (e) {
      _logger.log('Error toggling album library: $e');
@@ -529,12 +557,12 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            Text(
              S.of(context)!.addAlbumToQueueOn,
              style: Theme.of(context).textTheme.titleLarge,
            ),
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            if (players.isEmpty)
              Padding(
                padding: const EdgeInsets.all(32.0),
@@ -609,12 +637,12 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            Text(
              S.of(context)!.addToQueueOn,
              style: Theme.of(context).textTheme.titleLarge,
            ),
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            if (players.isEmpty)
              Padding(
                padding: const EdgeInsets.all(32.0),
@@ -672,8 +700,8 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
  void _navigateToArtist() {
    // Navigate to the first artist if available
-    if (widget.album.artists != null && widget.album.artists!.isNotEmpty) {
+    if (_displayAlbum.artists != null && _displayAlbum.artists!.isNotEmpty) {
-      final artist = widget.album.artists!.first;
+      final artist = _displayAlbum.artists!.first;
      final maProvider = context.read<MusicAssistantProvider>();
      final imageUrl = maProvider.getImageUrl(artist, size: 256);
      Navigator.push(
@@ -902,7 +930,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                      ),
                    ),
                  ),
-                  const SizedBox(height: 8),
+                  Spacing.vGap8,
                  Hero(
                    tag: HeroTags.artistName + (widget.album.uri ?? widget.album.itemId) + _heroTagSuffix,
                    child: Material(
@@ -913,7 +941,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                        child: Padding(
                          padding: const EdgeInsets.symmetric(vertical: 4.0),
                          child: Text(
-                            widget.album.artistsString,
+                            _displayAlbum.artistsString,
                            style: textTheme.titleMedium?.copyWith(
                              color: colorScheme.onBackground.withOpacity(0.7),
                            ),
@@ -922,7 +950,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                      ),
                    ),
                  ),
-                  const SizedBox(height: 16),
+                  Spacing.vGap16,
                  // Album Description
                  if (_albumDescription != null && _albumDescription!.isNotEmpty) ...[
                    InkWell(
@@ -944,7 +972,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                        ),
                      ),
                    ),
-                    const SizedBox(height: 8),
+                    Spacing.vGap8,
                  ],
                  Row(
                    children: [
@@ -1015,7 +1043,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                          style: FilledButton.styleFrom(
                            padding: EdgeInsets.zero,
                            shape: RoundedRectangleBorder(
-                              borderRadius: BorderRadius.circular(25), // Circular
+                              borderRadius: BorderRadius.circular(Radii.xxl), // Circular
                            ),
                          ),
                          child: Icon(
@@ -1193,7 +1221,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                                        style: FilledButton.styleFrom(
                                          padding: EdgeInsets.zero,
                                          shape: RoundedRectangleBorder(
-                                            borderRadius: BorderRadius.circular(22),
+                                            borderRadius: BorderRadius.circular(Radii.xxl),
                                          ),
                                        ),
                                        child: Icon(
@@ -1216,7 +1244,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                childCount: _tracks.length,
              ),
            ),
-          const SliverToBoxAdapter(child: SizedBox(height: 164)), // Space for bottom nav + mini player
+          SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)), // Space for bottom nav + mini player
        ],
      );
          },
@@ -1228,13 +1256,8 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
  void _showPlayAlbumFromHereMenu(BuildContext context, int startIndex) {
    final maProvider = context.read<MusicAssistantProvider>();
-    GlobalPlayerOverlay.hidePlayer();
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-
+      contextHint: S.of(context)!.selectPlayerToPlayAlbum,
    showPlayerPickerSheet(
      context: context,
      title: S.of(context)!.playOn,
      players: maProvider.availablePlayers,
      selectedPlayer: maProvider.selectedPlayer,
      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
        await maProvider.playTracks(
@@ -1243,48 +1266,32 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
          startIndex: startIndex,
        );
      },
-    ).whenComplete(() {
+    );
      GlobalPlayerOverlay.showPlayer();
    });
  }
  void _showPlayRadioMenu(BuildContext context, int trackIndex) {
    final maProvider = context.read<MusicAssistantProvider>();
    final track = _tracks[trackIndex];
-    GlobalPlayerOverlay.hidePlayer();
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-
+      contextHint: S.of(context)!.selectPlayerForRadio,
    showPlayerPickerSheet(
      context: context,
      title: S.of(context)!.playOn,
      players: maProvider.availablePlayers,
      selectedPlayer: maProvider.selectedPlayer,
      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
        await maProvider.playRadio(player.playerId, track);
      },
-    ).whenComplete(() {
+    );
      GlobalPlayerOverlay.showPlayer();
    });
  }
  void _showPlayOnMenu(BuildContext context) {
    final maProvider = context.read<MusicAssistantProvider>();
-    GlobalPlayerOverlay.hidePlayer();
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-
+      contextHint: S.of(context)!.selectPlayerToPlayAlbum,
    showPlayerPickerSheet(
      context: context,
      title: S.of(context)!.playOn,
      players: maProvider.availablePlayers,
      selectedPlayer: maProvider.selectedPlayer,
      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
        await maProvider.playTracks(player.playerId, _tracks);
      },
-    ).whenComplete(() {
+    );
      GlobalPlayerOverlay.showPlayer();
    });
  }
  String _formatDuration(Duration duration) {
@@ -13,6 +13,7 @@ import '../services/settings_service.dart';
 import '../services/debug_logger.dart';
 import '../utils/page_transitions.dart';
 import '../l10n/app_localizations.dart';
 import '../theme/design_tokens.dart';
 class ArtistDetailsScreen extends StatefulWidget {
  final Artist artist;
@@ -307,7 +308,6 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
    try {
      final newState = !_isInLibrary;
      bool success;
      if (newState) {
        // Add to library - MUST use non-library provider
@@ -338,12 +338,35 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
          }
        }
        // OPTIMISTIC UPDATE: Update UI immediately
        setState(() {
          _isInLibrary = newState;
        });
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(S.of(context)!.addedToLibrary),
              duration: const Duration(seconds: 1),
            ),
          );
        }
        _logger.log('Adding artist to library: provider=$actualProvider, itemId=$actualItemId');
-        success = await maProvider.addToLibrary(
+        // Fire and forget - API call happens in background
        maProvider.addToLibrary(
          mediaType: 'artist',
          provider: actualProvider,
          itemId: actualItemId,
-        );
+        ).catchError((e) {
          _logger.log('❌ Failed to add artist to library: $e');
          // Revert on failure
          if (mounted) {
            setState(() {
              _isInLibrary = !newState;
            });
          }
        });
      } else {
        // Remove from library
        int? libraryItemId;
@@ -364,13 +387,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
          return;
        }
-        success = await maProvider.removeFromLibrary(
+        // OPTIMISTIC UPDATE: Update UI immediately
          mediaType: 'artist',
          libraryItemId: libraryItemId,
        );
      }
      if (success) {
        setState(() {
          _isInLibrary = newState;
        });
@@ -378,13 +395,25 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
-              content: Text(
+              content: Text(S.of(context)!.removedFromLibrary),
                _isInLibrary ? S.of(context)!.addedToLibrary : S.of(context)!.removedFromLibrary,
              ),
              duration: const Duration(seconds: 1),
            ),
          );
        }
        // Fire and forget - API call happens in background
        maProvider.removeFromLibrary(
          mediaType: 'artist',
          libraryItemId: libraryItemId,
        ).catchError((e) {
          _logger.log('❌ Failed to remove artist from library: $e');
          // Revert on failure
          if (mounted) {
            setState(() {
              _isInLibrary = !newState;
            });
          }
        });
      }
    } catch (e) {
      _logger.log('Error toggling artist library: $e');
@@ -401,171 +430,73 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
  void _showRadioMenu(BuildContext context) {
    final maProvider = context.read<MusicAssistantProvider>();
    final players = maProvider.availablePlayers;
-    // Slide mini player down out of the way
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-    GlobalPlayerOverlay.hidePlayer();
+      contextHint: S.of(context)!.selectPlayerForRadio,
-
+      onPlayerSelected: (player) async {
-    showModalBottomSheet(
+        try {
-      context: context,
+          await maProvider.playArtistRadio(player.playerId, widget.artist);
-      backgroundColor: Colors.transparent,
+          if (mounted) {
-      builder: (context) => Container(
+            ScaffoldMessenger.of(context).showSnackBar(
-        decoration: BoxDecoration(
+              SnackBar(
-          color: Theme.of(context).colorScheme.surface,
+                content: Text(S.of(context)!.startingRadioOnPlayer(widget.artist.name, player.name)),
-          borderRadius: const BorderRadius.vertical(top: Radius.circular(20)),
+                duration: const Duration(seconds: 1),
        ),
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            const SizedBox(height: 16),
            Text(
              S.of(context)!.startRadioOn(widget.artist.name),
              style: Theme.of(context).textTheme.titleLarge,
            ),
            const SizedBox(height: 16),
            if (players.isEmpty)
              Padding(
                padding: const EdgeInsets.all(32.0),
                child: Text(S.of(context)!.noPlayersAvailable),
              )
            else
              Flexible(
                child: ListView.builder(
                  shrinkWrap: true,
                  itemCount: players.length,
                  itemBuilder: (context, index) {
                    final player = players[index];
                    return ListTile(
                      leading: Icon(
                        Icons.speaker,
                        color: Theme.of(context).colorScheme.onSurface,
                      ),
                      title: Text(player.name),
                      onTap: () async {
                        Navigator.pop(context);
                        try {
                          await maProvider.playArtistRadio(player.playerId, widget.artist);
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
                              SnackBar(
                                content: Text(S.of(context)!.startingRadioOnPlayer(widget.artist.name, player.name)),
                                duration: const Duration(seconds: 1),
                              ),
                            );
                          }
                        } catch (e) {
                          _logger.log('Error starting artist radio on player: $e');
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
                              SnackBar(
                                content: Text(S.of(context)!.failedToStartRadio(e.toString())),
                                backgroundColor: Colors.red,
                              ),
                            );
                          }
                        }
                      },
                    );
                  },
                ),
              ),
-            SizedBox(height: MediaQuery.of(context).padding.bottom + 16),
+            );
-          ],
+          }
-        ),
+        } catch (e) {
-      ),
+          _logger.log('Error starting artist radio on player: $e');
-    ).whenComplete(() {
+          if (mounted) {
-      // Slide mini player back up when sheet is dismissed
+            ScaffoldMessenger.of(context).showSnackBar(
-      GlobalPlayerOverlay.showPlayer();
+              SnackBar(
-    });
+                content: Text(S.of(context)!.failedToStartRadio(e.toString())),
                backgroundColor: Colors.red,
              ),
            );
          }
        }
      },
    );
  }
  void _showAddToQueueMenu(BuildContext context) {
    final maProvider = context.read<MusicAssistantProvider>();
    final players = maProvider.availablePlayers;
-    // Slide mini player down out of the way
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-    GlobalPlayerOverlay.hidePlayer();
+      contextHint: S.of(context)!.selectPlayerToAddToQueue,
-
+      onPlayerSelected: (player) async {
-    showModalBottomSheet(
+        final api = maProvider.api;
-      context: context,
+        if (api == null) {
-      backgroundColor: Colors.transparent,
+          if (mounted) {
-      builder: (context) => Container(
+            ScaffoldMessenger.of(context).showSnackBar(
-        decoration: BoxDecoration(
+              SnackBar(content: Text(S.of(context)!.notConnected)),
-          color: Theme.of(context).colorScheme.surface,
+            );
-          borderRadius: const BorderRadius.vertical(top: Radius.circular(20)),
+          }
-        ),
+          return;
-        child: Column(
+        }
-          mainAxisSize: MainAxisSize.min,
+        try {
-          children: [
+          await api.playArtistRadioToQueue(player.playerId, widget.artist);
-            const SizedBox(height: 16),
+          if (mounted) {
-            Text(
+            ScaffoldMessenger.of(context).showSnackBar(
-              S.of(context)!.addToQueueOn,
+              SnackBar(
-              style: Theme.of(context).textTheme.titleLarge,
+                content: Text(S.of(context)!.addedRadioToQueue(widget.artist.name)),
-            ),
+                duration: const Duration(seconds: 1),
            const SizedBox(height: 16),
            if (players.isEmpty)
              Padding(
                padding: const EdgeInsets.all(32.0),
                child: Text(S.of(context)!.noPlayersAvailable),
              )
            else
              Flexible(
                child: ListView.builder(
                  shrinkWrap: true,
                  itemCount: players.length,
                  itemBuilder: (context, index) {
                    final player = players[index];
                    return ListTile(
                      leading: Icon(
                        Icons.speaker,
                        color: Theme.of(context).colorScheme.onSurface,
                      ),
                      title: Text(player.name),
                      onTap: () async {
                        Navigator.pop(context);
                        final api = maProvider.api;
                        if (api == null) {
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
                              SnackBar(content: Text(S.of(context)!.notConnected)),
                            );
                          }
                          return;
                        }
                        try {
                          await api.playArtistRadioToQueue(player.playerId, widget.artist);
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
                              SnackBar(
                                content: Text(S.of(context)!.addedRadioToQueue(widget.artist.name)),
                                duration: const Duration(seconds: 1),
                              ),
                            );
                          }
                        } catch (e) {
                          _logger.log('Error adding artist radio to queue: $e');
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
                              SnackBar(
                                content: Text(S.of(context)!.failedToAddToQueue(e.toString())),
                                backgroundColor: Colors.red,
                              ),
                            );
                          }
                        }
                      },
                    );
                  },
                ),
              ),
-            SizedBox(height: MediaQuery.of(context).padding.bottom + 16),
+            );
-          ],
+          }
-        ),
+        } catch (e) {
-      ),
+          _logger.log('Error adding artist radio to queue: $e');
-    ).whenComplete(() {
+          if (mounted) {
-      // Slide mini player back up when sheet is dismissed
+            ScaffoldMessenger.of(context).showSnackBar(
-      GlobalPlayerOverlay.showPlayer();
+              SnackBar(
-    });
+                content: Text(S.of(context)!.failedToAddToQueue(e.toString())),
                backgroundColor: Colors.red,
              ),
            );
          }
        }
      },
    );
  }
  Future<void> _loadArtistImage() async {
@@ -786,7 +717,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                      ),
                    ),
                  ),
-                  const SizedBox(height: 16),
+                  Spacing.vGap16,
                  if (_artistDescription != null && _artistDescription!.isNotEmpty) ...[
                    InkWell(
                      onTap: () {
@@ -807,7 +738,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                        ),
                      ),
                    ),
-                    const SizedBox(height: 8),
+                    Spacing.vGap8,
                  ],
                  // Action Buttons Row
                  Row(
@@ -861,7 +792,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                          style: FilledButton.styleFrom(
                            padding: EdgeInsets.zero,
                            shape: RoundedRectangleBorder(
-                              borderRadius: BorderRadius.circular(25),
+                              borderRadius: BorderRadius.circular(Radii.xxl),
                            ),
                          ),
                          child: Icon(
@@ -897,7 +828,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                      ),
                    ],
                  ),
-                  const SizedBox(height: 16),
+                  Spacing.vGap16,
                ],
              ),
            ),
@@ -947,7 +878,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                        onPressed: _toggleSortOrder,
                        visualDensity: VisualDensity.compact,
                        padding: EdgeInsets.zero,
-                        constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                        constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
                      ),
                      // View mode toggle
                      IconButton(
@@ -968,7 +899,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                        onPressed: _cycleViewMode,
                        visualDensity: VisualDensity.compact,
                        padding: EdgeInsets.zero,
-                        constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                        constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
                      ),
                    ],
                  ),
@@ -1004,7 +935,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                          onPressed: _toggleSortOrder,
                          visualDensity: VisualDensity.compact,
                          padding: EdgeInsets.zero,
-                          constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                          constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
                        ),
                        IconButton(
                          icon: Icon(
@@ -1024,7 +955,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                          onPressed: _cycleViewMode,
                          visualDensity: VisualDensity.compact,
                          padding: EdgeInsets.zero,
-                          constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                          constraints: const BoxConstraints(minWidth: 44, minHeight: 44),
                        ),
                      ],
                    ],
@@ -1032,7 +963,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
                ),
              ),
              _buildAlbumSliver(_providerAlbums),
-              const SliverToBoxAdapter(child: SizedBox(height: 140)), // Space for bottom nav + mini player
+              SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)), // Space for bottom nav + mini player
            ],
          ],
        ],
@@ -1104,7 +1035,7 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
              ),
            ),
          ),
-          const SizedBox(height: 8),
+          Spacing.vGap8,
          Hero(
            tag: HeroTags.albumTitle + (album.uri ?? album.itemId) + '_$heroSuffix',
            child: Material(
@@ -150,10 +150,16 @@ class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
      },
      child: Scaffold(
        backgroundColor: colorScheme.surface,
-        body: CustomScrollView(
+        body: LayoutBuilder(
          builder: (context, constraints) {
            // Responsive cover size: 70% of screen width, clamped between 160-280 (same as artist detail)
            final coverSize = (constraints.maxWidth * 0.7).clamp(160.0, 280.0);
            final expandedHeight = coverSize + 100;
            return CustomScrollView(
          slivers: [
            SliverAppBar(
-              expandedHeight: 200,
+              expandedHeight: expandedHeight,
              pinned: true,
              backgroundColor: colorScheme.surface,
              leading: IconButton(
@@ -172,37 +178,41 @@ class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
                    Hero(
                      tag: HeroTags.authorImage + widget.authorName + _heroTagSuffix,
                      child: Container(
-                        width: 200,
+                        width: coverSize,
-                        height: 200,
+                        height: coverSize,
                        decoration: BoxDecoration(
                          color: colorScheme.primaryContainer,
                          shape: BoxShape.circle,
                        ),
-                        child: ClipOval(
+                        child: Stack(
-                          child: _authorImageUrl != null
+                          alignment: Alignment.center,
-                              ? CachedNetworkImage(
+                          children: [
-                                  imageUrl: _authorImageUrl!,
+                            // Icon always present underneath
-                                  fit: BoxFit.cover,
+                            Icon(
-                                  width: 200,
+                              MdiIcons.accountOutline,
-                                  height: 200,
+                              size: coverSize * 0.5,
-                                  fadeInDuration: Duration.zero,
+                              color: colorScheme.onPrimaryContainer,
-                                  fadeOutDuration: Duration.zero,
+                            ),
-                                  placeholder: (_, __) => Icon(
+                            // Image covers icon when loaded
-                                    MdiIcons.accountOutline,
+                            if (_authorImageUrl != null)
-                                    size: 100,
+                              SizedBox(
-                                    color: colorScheme.onPrimaryContainer,
+                                width: coverSize,
                                height: coverSize,
                                child: ClipOval(
                                  child: CachedNetworkImage(
                                    imageUrl: _authorImageUrl!,
                                    fit: BoxFit.cover,
                                    width: coverSize,
                                    height: coverSize,
                                    memCacheWidth: 256,
                                    fadeInDuration: Duration.zero,
                                    fadeOutDuration: Duration.zero,
                                    placeholder: (_, __) => const SizedBox.shrink(),
                                    errorWidget: (_, __, ___) => const SizedBox.shrink(),
                                  ),
                                  errorWidget: (_, __, ___) => Icon(
                                    MdiIcons.accountOutline,
                                    size: 100,
                                    color: colorScheme.onPrimaryContainer,
                                  ),
                                )
                              : Icon(
                                  MdiIcons.accountOutline,
                                  size: 100,
                                  color: colorScheme.onPrimaryContainer,
                                ),
                              ),
                          ],
                        ),
                      ),
                    ),
@@ -287,8 +297,10 @@ class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
              ),
            ),
            _buildAudiobookSliver(),
-            const SliverToBoxAdapter(child: SizedBox(height: 140)),
+            SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)),
          ],
            );
          },
        ),
      ),
    );
@@ -5,13 +5,13 @@ import 'package:material_design_icons_flutter/material_design_icons_flutter.dart
 import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
 import '../widgets/global_player_overlay.dart';
 import '../widgets/player_picker_sheet.dart';
 import '../theme/palette_helper.dart';
 import '../theme/theme_provider.dart';
 import '../services/debug_logger.dart';
 import '../services/recently_played_service.dart';
 import '../constants/hero_tags.dart';
 import '../l10n/app_localizations.dart';
 import '../theme/design_tokens.dart';
 class AudiobookDetailScreen extends StatefulWidget {
  final Audiobook audiobook;
@@ -211,13 +211,8 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
  void _showPlayOnMenu(BuildContext context) {
    final maProvider = context.read<MusicAssistantProvider>();
-    GlobalPlayerOverlay.hidePlayer();
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-
+      contextHint: S.of(context)!.selectPlayerForAudiobook,
    showPlayerPickerSheet(
      context: context,
      title: S.of(context)!.playOn,
      players: maProvider.availablePlayers,
      selectedPlayer: maProvider.selectedPlayer,
      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
        maProvider.setCurrentAudiobook(_audiobook);
@@ -226,9 +221,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
          widget.audiobook,
        );
      },
-    ).whenComplete(() {
+    );
      GlobalPlayerOverlay.showPlayer();
    });
  }
  Future<void> _markAsFinished() async {
@@ -566,7 +559,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
                        ),
                      ),
                    ),
-                    const SizedBox(height: 8),
+                    Spacing.vGap8,
                    // Author
                    Text(
@@ -588,7 +581,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
                    ],
                    // Duration & Progress
-                    const SizedBox(height: 16),
+                    Spacing.vGap16,
                    Row(
                      children: [
                        if (book.duration != null) ...[
@@ -712,7 +705,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
                            style: FilledButton.styleFrom(
                              padding: EdgeInsets.zero,
                              shape: RoundedRectangleBorder(
-                                borderRadius: BorderRadius.circular(25),
+                                borderRadius: BorderRadius.circular(Radii.xxl),
                              ),
                            ),
                            child: Icon(
@@ -736,7 +729,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
                          fontWeight: FontWeight.bold,
                        ),
                      ),
-                      const SizedBox(height: 8),
+                      Spacing.vGap8,
                      InkWell(
                        onTap: () {
                          setState(() {
@@ -767,7 +760,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
                        fontWeight: FontWeight.bold,
                      ),
                    ),
-                    const SizedBox(height: 8),
+                    Spacing.vGap8,
                  ],
                ),
              ),
@@ -777,7 +770,7 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
            // Use MA chapters if available, otherwise use ABS chapters
            ..._buildChapterSection(book, colorScheme, textTheme),
-            const SliverToBoxAdapter(child: SizedBox(height: 140)),
+            SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)),
          ],
        );
          },
@@ -68,6 +68,12 @@ class _HomeScreenState extends State<HomeScreen> {
              return;
            }
            // If queue panel is open, close it first (before collapsing player)
            if (GlobalPlayerOverlay.isQueuePanelOpen) {
              GlobalPlayerOverlay.closeQueuePanel();
              return;
            }
            // If global player is expanded, collapse it first
            if (GlobalPlayerOverlay.isPlayerExpanded) {
              GlobalPlayerOverlay.collapsePlayer();
@@ -4,8 +4,12 @@ import 'package:cached_network_image/cached_network_image.dart';
 import '../providers/music_assistant_provider.dart';
 import '../models/media_item.dart';
 import '../widgets/common/empty_state.dart';
 import '../constants/hero_tags.dart';
 import '../theme/theme_provider.dart';
 import '../utils/page_transitions.dart';
 import 'playlist_details_screen.dart';
 import '../l10n/app_localizations.dart';
 import '../theme/design_tokens.dart';
 class LibraryPlaylistsScreen extends StatefulWidget {
  const LibraryPlaylistsScreen({super.key});
@@ -104,34 +108,55 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
    final colorScheme = Theme.of(context).colorScheme;
    final textTheme = Theme.of(context).textTheme;
    // Unique suffix for this context to avoid hero tag conflicts
    const heroSuffix = '_playlists';
    return RepaintBoundary(
      child: ListTile(
        key: ValueKey(playlist.itemId),
-        leading: Container(
+        leading: Hero(
-          width: 48,
+          tag: HeroTags.playlistCover + (playlist.uri ?? playlist.itemId) + heroSuffix,
-          height: 48,
+          child: ClipRRect(
          decoration: BoxDecoration(
            color: colorScheme.surfaceVariant,
            borderRadius: BorderRadius.circular(8),
-            image: imageUrl != null
+            child: Container(
-                ? DecorationImage(
+              width: 48,
-                    image: CachedNetworkImageProvider(imageUrl),
+              height: 48,
-                    fit: BoxFit.cover,
+              color: colorScheme.surfaceContainerHighest,
-                  )
+              child: imageUrl != null
-                : null,
+                  ? CachedNetworkImage(
                      imageUrl: imageUrl,
                      fit: BoxFit.cover,
                      memCacheWidth: 96,
                      memCacheHeight: 96,
                      fadeInDuration: Duration.zero,
                      fadeOutDuration: Duration.zero,
                      placeholder: (_, __) => const SizedBox(),
                      errorWidget: (_, __, ___) => Icon(
                        Icons.playlist_play_rounded,
                        color: colorScheme.onSurfaceVariant,
                      ),
                    )
                  : Icon(
                      Icons.playlist_play_rounded,
                      color: colorScheme.onSurfaceVariant,
                    ),
            ),
          ),
          child: imageUrl == null
              ? Icon(Icons.playlist_play_rounded, color: colorScheme.onSurfaceVariant)
              : null,
        ),
-        title: Text(
+        title: Hero(
-          playlist.name,
+          tag: HeroTags.playlistTitle + (playlist.uri ?? playlist.itemId) + heroSuffix,
-          style: textTheme.titleMedium?.copyWith(
+          child: Material(
-            color: colorScheme.onSurface,
+            color: Colors.transparent,
-            fontWeight: FontWeight.w500,
+            child: Text(
              playlist.name,
              style: textTheme.titleMedium?.copyWith(
                color: colorScheme.onSurface,
                fontWeight: FontWeight.w500,
              ),
              maxLines: 1,
              overflow: TextOverflow.ellipsis,
            ),
          ),
          maxLines: 1,
          overflow: TextOverflow.ellipsis,
        ),
        subtitle: Text(
          playlist.trackCount != null
@@ -144,16 +169,17 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
          overflow: TextOverflow.ellipsis,
        ),
        trailing: playlist.favorite == true
-            ? const Icon(Icons.favorite, color: Colors.red, size: 20)
+            ? const Icon(Icons.favorite, color: StatusColors.favorite, size: 20)
            : null,
        onTap: () {
          updateAdaptiveColorsFromImage(context, imageUrl);
          Navigator.push(
            context,
-            MaterialPageRoute(
+            FadeSlidePageRoute(
-              builder: (context) => PlaylistDetailsScreen(
+              child: PlaylistDetailsScreen(
                playlist: playlist,
-                provider: playlist.provider,
+                heroTagSuffix: 'playlists',
-                itemId: playlist.itemId,
+                initialImageUrl: imageUrl,
              ),
            ),
          );
@@ -13,6 +13,9 @@ import '../widgets/artist_row.dart';
 import '../widgets/track_row.dart';
 import '../widgets/audiobook_row.dart';
 import '../widgets/series_row.dart';
 import '../widgets/playlist_row.dart';
 import '../widgets/radio_station_row.dart';
 import '../widgets/podcast_row.dart';
 import '../widgets/common/disconnected_state.dart';
 import 'settings_screen.dart';
 import 'search_screen.dart';
@@ -35,6 +38,9 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
  bool _showFavoriteAlbums = false;
  bool _showFavoriteArtists = false;
  bool _showFavoriteTracks = false;
  bool _showFavoritePlaylists = false;
  bool _showFavoriteRadioStations = false;
  bool _showFavoritePodcasts = false;
  // Audiobook rows (default off)
  bool _showContinueListeningAudiobooks = false;
  bool _showDiscoverAudiobooks = false;
@@ -45,19 +51,89 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
  @override
  bool get wantKeepAlive => true;
  // Track if we had empty favorites on first load (to know when to refresh)
  bool _hadEmptyFavoritesOnLoad = false;
  SyncStatus? _lastSyncStatus;
  int _lastArtistCount = 0;
  MusicAssistantProvider? _providerListeningTo;
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _loadSettings();
    // Listen to sync completion to refresh favorite rows when data becomes available
    SyncService.instance.addListener(_onSyncChanged);
    _lastSyncStatus = SyncService.instance.status;
    _checkInitialFavoriteState();
  }
  @override
  void dispose() {
    SyncService.instance.removeListener(_onSyncChanged);
    // Clean up provider listener if attached
    _providerListeningTo?.removeListener(_onProviderChanged);
    _providerListeningTo = null;
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }
  /// Check if favorites are empty on initial load (so we know to refresh after sync)
  void _checkInitialFavoriteState() {
    // Schedule after first frame to ensure provider is accessible
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (!mounted) return;
      final provider = context.read<MusicAssistantProvider>();
      _lastArtistCount = provider.artists.length;
      // Check if artists list is empty - favorites will also be empty
      if (_lastArtistCount == 0) {
        _hadEmptyFavoritesOnLoad = true;
        _logger.log('📋 Home: favorites empty on load, will refresh after sync');
        // Also listen to provider for when cache loads (before sync completes)
        _providerListeningTo = provider;
        provider.addListener(_onProviderChanged);
      }
    });
  }
  /// Called when MusicAssistantProvider changes (for cache load detection)
  void _onProviderChanged() {
    if (!mounted || !_hadEmptyFavoritesOnLoad || _providerListeningTo == null) return;
    final currentCount = _providerListeningTo!.artists.length;
    // If artists went from 0 to non-zero, refresh
    if (_lastArtistCount == 0 && currentCount > 0) {
      _logger.log('🔄 Home: artists loaded from cache ($currentCount), refreshing rows');
      _hadEmptyFavoritesOnLoad = false;
      _providerListeningTo!.removeListener(_onProviderChanged);
      _providerListeningTo = null;
      setState(() {
        _refreshKey = UniqueKey();
      });
    }
    _lastArtistCount = currentCount;
  }
  /// Called when SyncService status changes
  void _onSyncChanged() {
    final newStatus = SyncService.instance.status;
    // When sync completes and we had empty favorites, refresh to show new data
    if (_lastSyncStatus == SyncStatus.syncing &&
        newStatus == SyncStatus.completed &&
        _hadEmptyFavoritesOnLoad) {
      _logger.log('🔄 Home: sync completed, refreshing favorite rows');
      _hadEmptyFavoritesOnLoad = false;
      // Clean up provider listener if still attached
      _providerListeningTo?.removeListener(_onProviderChanged);
      _providerListeningTo = null;
      if (mounted) {
        setState(() {
          _refreshKey = UniqueKey();
        });
      }
    }
    _lastSyncStatus = newStatus;
  }
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    // Reload settings when app resumes (coming back from settings)
@@ -73,6 +149,9 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
    final showFavAlbums = await SettingsService.getShowFavoriteAlbums();
    final showFavArtists = await SettingsService.getShowFavoriteArtists();
    final showFavTracks = await SettingsService.getShowFavoriteTracks();
    final showFavPlaylists = await SettingsService.getShowFavoritePlaylists();
    final showFavRadio = await SettingsService.getShowFavoriteRadioStations();
    final showFavPodcasts = await SettingsService.getShowFavoritePodcasts();
    final showContAudiobooks = await SettingsService.getShowContinueListeningAudiobooks();
    final showDiscAudiobooks = await SettingsService.getShowDiscoverAudiobooks();
    final showDiscSeries = await SettingsService.getShowDiscoverSeries();
@@ -85,6 +164,9 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
        _showFavoriteAlbums = showFavAlbums;
        _showFavoriteArtists = showFavArtists;
        _showFavoriteTracks = showFavTracks;
        _showFavoritePlaylists = showFavPlaylists;
        _showFavoriteRadioStations = showFavRadio;
        _showFavoritePodcasts = showFavPodcasts;
        _showContinueListeningAudiobooks = showContAudiobooks;
        _showDiscoverAudiobooks = showDiscAudiobooks;
        _showDiscoverSeries = showDiscSeries;
@@ -238,15 +320,50 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
  }
  /// Count how many rows are currently enabled
  int _countEnabledRows() {
    int count = 0;
    for (final rowId in _homeRowOrder) {
      if (_isRowEnabled(rowId)) count++;
    }
    return count;
  }
  /// Check if a specific row is enabled
  bool _isRowEnabled(String rowId) {
    switch (rowId) {
      case 'recent-albums': return _showRecentAlbums;
      case 'discover-artists': return _showDiscoverArtists;
      case 'discover-albums': return _showDiscoverAlbums;
      case 'continue-listening': return _showContinueListeningAudiobooks;
      case 'discover-audiobooks': return _showDiscoverAudiobooks;
      case 'discover-series': return _showDiscoverSeries;
      case 'favorite-albums': return _showFavoriteAlbums;
      case 'favorite-artists': return _showFavoriteArtists;
      case 'favorite-tracks': return _showFavoriteTracks;
      case 'favorite-playlists': return _showFavoritePlaylists;
      case 'favorite-radio-stations': return _showFavoriteRadioStations;
      case 'favorite-podcasts': return _showFavoritePodcasts;
      default: return false;
    }
  }
  Widget _buildConnectedView(
      BuildContext context, MusicAssistantProvider provider) {
    // Use LayoutBuilder to get available screen height
    return LayoutBuilder(
      builder: (context, constraints) {
-        // Simple calculation: available height divided by 3 rows
+        // Each row is always 1/3 of screen height
-        // Each row includes its title, artwork, and info
+        // 1 row = 1/3, 2 rows = 2/3, 3 rows = full screen, 4+ rows scroll
        final availableHeight = constraints.maxHeight - BottomSpacing.withMiniPlayer;
-        final rowHeight = (availableHeight + 8) / 3;
+
        // Account for margins between rows (2px each)
        // Only adjust for margins when ≤3 rows (so they fit exactly without scroll)
        // For 4+ rows, use original calculation so 4th row stays hidden (scrollable)
        const marginSize = 2.0;
        final enabledRows = _countEnabledRows();
        final marginsInView = enabledRows > 1 && enabledRows <= 3 ? (enabledRows - 1) * marginSize : 0.0;
        final rowHeight = (availableHeight - marginsInView) / 3;
        // Use Android 12+ stretch overscroll effect
        return NotificationListener<ScrollNotification>(
@@ -288,6 +405,10 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
    for (final rowId in _homeRowOrder) {
      final widget = _buildRowWidget(rowId, provider, rowHeight);
      if (widget != null) {
        // Add spacing between rows (not before first row)
        if (rows.isNotEmpty) {
          rows.add(const SizedBox(height: 2.0));
        }
        rows.add(widget);
      }
    }
@@ -330,7 +451,8 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
        return AudiobookRow(
          key: const ValueKey('continue-listening'),
          title: S.of(context)!.continueListening,
-          loadAudiobooks: () => provider.getInProgressAudiobooks(),
+          loadAudiobooks: () => provider.getInProgressAudiobooksWithCache(),
          getCachedAudiobooks: () => provider.getCachedInProgressAudiobooks(),
          rowHeight: rowHeight,
        );
      case 'discover-audiobooks':
@@ -338,7 +460,8 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
        return AudiobookRow(
          key: const ValueKey('discover-audiobooks'),
          title: S.of(context)!.discoverAudiobooks,
-          loadAudiobooks: () => provider.getDiscoverAudiobooks(),
+          loadAudiobooks: () => provider.getDiscoverAudiobooksWithCache(),
          getCachedAudiobooks: () => provider.getCachedDiscoverAudiobooks(),
          rowHeight: rowHeight,
        );
      case 'discover-series':
@@ -346,7 +469,8 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
        return SeriesRow(
          key: const ValueKey('discover-series'),
          title: S.of(context)!.discoverSeries,
-          loadSeries: () => provider.getDiscoverSeries(),
+          loadSeries: () => provider.getDiscoverSeriesWithCache(),
          getCachedSeries: () => provider.getCachedDiscoverSeries(),
          rowHeight: rowHeight,
        );
      case 'favorite-albums':
@@ -373,6 +497,33 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
          loadTracks: () => provider.getFavoriteTracks(),
          rowHeight: rowHeight,
        );
      case 'favorite-playlists':
        if (!_showFavoritePlaylists) return null;
        return PlaylistRow(
          key: const ValueKey('favorite-playlists'),
          title: S.of(context)!.favoritePlaylists,
          loadPlaylists: () => provider.getFavoritePlaylists(),
          heroTagSuffix: 'home',
          rowHeight: rowHeight,
        );
      case 'favorite-radio-stations':
        if (!_showFavoriteRadioStations) return null;
        return RadioStationRow(
          key: const ValueKey('favorite-radio-stations'),
          title: S.of(context)!.favoriteRadioStations,
          loadRadioStations: () => provider.getFavoriteRadioStations(),
          heroTagSuffix: 'home',
          rowHeight: rowHeight,
        );
      case 'favorite-podcasts':
        if (!_showFavoritePodcasts) return null;
        return PodcastRow(
          key: const ValueKey('favorite-podcasts'),
          title: S.of(context)!.favoritePodcasts,
          loadPodcasts: () => provider.getFavoritePodcasts(),
          heroTagSuffix: 'home',
          rowHeight: rowHeight,
        );
      default:
        return null;
    }
@@ -5,7 +5,6 @@ import 'package:material_design_icons_flutter/material_design_icons_flutter.dart
 import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
 import '../widgets/global_player_overlay.dart';
 import '../widgets/player_picker_sheet.dart';
 import '../theme/palette_helper.dart';
 import '../theme/theme_provider.dart';
 import '../services/debug_logger.dart';
@@ -66,7 +65,6 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
    try {
      final newState = !_isInLibrary;
      bool success;
      if (newState) {
        // Add to library - MUST use non-library provider
@@ -97,12 +95,35 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
          }
        }
        // OPTIMISTIC UPDATE: Update UI immediately
        setState(() {
          _isInLibrary = newState;
        });
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
              content: Text(S.of(context)!.addedToLibrary),
              duration: const Duration(seconds: 1),
            ),
          );
        }
        _logger.log('Adding podcast to library: provider=$actualProvider, itemId=$actualItemId');
-        success = await maProvider.addToLibrary(
+        // Fire and forget - API call happens in background
        maProvider.addToLibrary(
          mediaType: 'podcast',
          provider: actualProvider,
          itemId: actualItemId,
-        );
+        ).catchError((e) {
          _logger.log('❌ Failed to add podcast to library: $e');
          // Revert on failure
          if (mounted) {
            setState(() {
              _isInLibrary = !newState;
            });
          }
        });
      } else {
        // Remove from library
        int? libraryItemId;
@@ -123,13 +144,7 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
          return;
        }
-        success = await maProvider.removeFromLibrary(
+        // OPTIMISTIC UPDATE: Update UI immediately
          mediaType: 'podcast',
          libraryItemId: libraryItemId,
        );
      }
      if (success) {
        setState(() {
          _isInLibrary = newState;
        });
@@ -137,13 +152,25 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(
-              content: Text(
+              content: Text(S.of(context)!.removedFromLibrary),
                _isInLibrary ? S.of(context)!.addedToLibrary : S.of(context)!.removedFromLibrary,
              ),
              duration: const Duration(seconds: 1),
            ),
          );
        }
        // Fire and forget - API call happens in background
        maProvider.removeFromLibrary(
          mediaType: 'podcast',
          libraryItemId: libraryItemId,
        ).catchError((e) {
          _logger.log('❌ Failed to remove podcast from library: $e');
          // Revert on failure
          if (mounted) {
            setState(() {
              _isInLibrary = !newState;
            });
          }
        });
      }
    } catch (e) {
      _logger.log('Error toggling podcast library: $e');
@@ -190,10 +217,38 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
    try {
      final maProvider = context.read<MusicAssistantProvider>();
      if (maProvider.api != null) {
-        final episodes = await maProvider.api!.getPodcastEpisodes(
+        List<MediaItem> episodes = [];
-          widget.podcast.itemId,
+
-          provider: widget.podcast.provider,
+        // Try loading with the podcast's own ID and provider first
-        );
+        try {
          episodes = await maProvider.api!.getPodcastEpisodes(
            widget.podcast.itemId,
            provider: widget.podcast.provider,
          );
        } catch (e) {
          _logger.log('🎙️ Primary episode load failed: $e');
        }
        // If that failed and we have provider mappings, try those
        if (episodes.isEmpty && widget.podcast.providerMappings != null) {
          for (final mapping in widget.podcast.providerMappings!) {
            if (mapping.itemId.isNotEmpty && mapping.providerInstance.isNotEmpty) {
              try {
                _logger.log('🎙️ Trying provider mapping: ${mapping.providerInstance}');
                episodes = await maProvider.api!.getPodcastEpisodes(
                  mapping.itemId,
                  provider: mapping.providerInstance,
                );
                if (episodes.isNotEmpty) {
                  _logger.log('🎙️ Loaded episodes via provider mapping');
                  break;
                }
              } catch (e) {
                _logger.log('🎙️ Provider mapping failed: $e');
              }
            }
          }
        }
        if (mounted) {
          _logger.log('🎙️ Loaded ${episodes.length} episodes for ${widget.podcast.name}');
@@ -225,6 +280,8 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
    if (selectedPlayer != null) {
      try {
        // Set podcast context before playing so player UI shows correct podcast name
        maProvider.setCurrentPodcastName(widget.podcast.name);
        await maProvider.api?.playPodcastEpisode(selectedPlayer.playerId, episode);
        if (mounted) {
          ScaffoldMessenger.of(context).showSnackBar(
@@ -250,20 +307,15 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
  void _showPlayOnMenu(BuildContext context, MediaItem episode) {
    final maProvider = context.read<MusicAssistantProvider>();
-    GlobalPlayerOverlay.hidePlayer();
+    GlobalPlayerOverlay.showPlayerSelectorForAction(
-
+      contextHint: S.of(context)!.selectPlayerForEpisode,
    showPlayerPickerSheet(
      context: context,
      title: S.of(context)!.playOn,
      players: maProvider.availablePlayers,
      selectedPlayer: maProvider.selectedPlayer,
      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
        // Set podcast context before playing so player UI shows correct podcast name
        maProvider.setCurrentPodcastName(widget.podcast.name);
        await maProvider.api?.playPodcastEpisode(player.playerId, episode);
      },
-    ).whenComplete(() {
+    );
      GlobalPlayerOverlay.showPlayer();
    });
  }
  String _formatDuration(Duration? duration) {
@@ -856,8 +908,8 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
                  ),
                // Bottom padding for mini player
-                const SliverToBoxAdapter(
+                SliverToBoxAdapter(
-                  child: SizedBox(height: 100),
+                  child: SizedBox(height: BottomSpacing.withMiniPlayer),
                ),
              ],
            );
@@ -4,6 +4,7 @@ import '../providers/music_assistant_provider.dart';
 import '../models/player.dart';
 import '../services/debug_logger.dart';
 import '../widgets/common/empty_state.dart';
 import '../widgets/player_picker_sheet.dart';
 import '../l10n/app_localizations.dart';
 class QueueScreen extends StatefulWidget {
@@ -67,6 +68,68 @@ class _QueueScreenState extends State<QueueScreen> {
    }
  }
  Future<void> _handleTransferQueue(MusicAssistantProvider maProvider) async {
    final player = maProvider.selectedPlayer;
    if (player == null) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(content: Text(S.of(context)!.noPlayerSelected)),
      );
      return;
    }
    // Get available players, excluding the current source player
    final allPlayers = maProvider.availablePlayers;
    final targetPlayers = allPlayers
        .where((p) => p.playerId != player.playerId && p.available)
        .toList();
    if (targetPlayers.isEmpty) {
      ScaffoldMessenger.of(context).showSnackBar(
        SnackBar(
          content: Text(S.of(context)!.noOtherPlayersAvailable),
          duration: const Duration(seconds: 2),
        ),
      );
      return;
    }
    // Show player picker sheet
    await showPlayerPickerSheet(
      context: context,
      title: S.of(context)!.transferQueueTo,
      players: targetPlayers,
      onPlayerSelected: (targetPlayer) async {
        try {
          await maProvider.api?.transferQueue(
            sourceQueueId: player.playerId,
            targetQueueId: targetPlayer.playerId,
            autoPlay: true,
          );
          if (mounted) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text(S.of(context)!.queueTransferredTo(targetPlayer.name)),
                duration: const Duration(seconds: 2),
              ),
            );
          }
        } catch (e) {
          _logger.log('Error transferring queue: $e');
          if (mounted) {
            ScaffoldMessenger.of(context).showSnackBar(
              SnackBar(
                content: Text(S.of(context)!.failedToTransferQueue(e.toString())),
                backgroundColor: Colors.red.shade700,
                duration: const Duration(seconds: 3),
              ),
            );
          }
        }
      },
    );
  }
  @override
  Widget build(BuildContext context) {
    final maProvider = context.watch<MusicAssistantProvider>();
@@ -87,6 +150,11 @@ class _QueueScreenState extends State<QueueScreen> {
        ),
        centerTitle: true,
        actions: [
          IconButton(
            icon: const Icon(Icons.swap_horiz_rounded),
            tooltip: S.of(context)!.transferQueue,
            onPressed: () => _handleTransferQueue(maProvider),
          ),
          IconButton(
            icon: const Icon(Icons.refresh),
            onPressed: _loadQueue,
@@ -29,22 +29,21 @@ class _SettingsScreenState extends State<SettingsScreen> {
  bool _showFavoriteAlbums = false;
  bool _showFavoriteArtists = false;
  bool _showFavoriteTracks = false;
  bool _showFavoritePlaylists = false;
  bool _showFavoriteRadioStations = false;
  bool _showFavoritePodcasts = false;
  // Audiobook home rows (default off)
  bool _showContinueListeningAudiobooks = false;
  bool _showDiscoverAudiobooks = false;
  bool _showDiscoverSeries = false;
  // Home row order
  List<String> _homeRowOrder = List.from(SettingsService.defaultHomeRowOrder);
  // Audiobook libraries
  List<Map<String, String>> _discoveredLibraries = [];
  Map<String, bool> _libraryEnabled = {};
  // Player settings
  bool _preferLocalPlayer = false;
  bool _smartSortPlayers = false;
  bool _volumePrecisionMode = true;
  // Hint settings
  bool _showHints = true;
  // Library settings
  bool _showOnlyArtistsWithAlbums = false;
  @override
  void initState() {
@@ -70,6 +69,9 @@ class _SettingsScreenState extends State<SettingsScreen> {
    final showFavAlbums = await SettingsService.getShowFavoriteAlbums();
    final showFavArtists = await SettingsService.getShowFavoriteArtists();
    final showFavTracks = await SettingsService.getShowFavoriteTracks();
    final showFavPlaylists = await SettingsService.getShowFavoritePlaylists();
    final showFavRadio = await SettingsService.getShowFavoriteRadioStations();
    final showFavPodcasts = await SettingsService.getShowFavoritePodcasts();
    // Load audiobook home row settings
    final showContinueAudiobooks = await SettingsService.getShowContinueListeningAudiobooks();
@@ -79,26 +81,14 @@ class _SettingsScreenState extends State<SettingsScreen> {
    // Load home row order
    final rowOrder = await SettingsService.getHomeRowOrder();
    // Load audiobook library settings
    final discovered = await SettingsService.getDiscoveredAbsLibraries() ?? [];
    final enabled = await SettingsService.getEnabledAbsLibraries();
    final libraryEnabled = <String, bool>{};
    for (final lib in discovered) {
      final path = lib['path'] ?? '';
      // null means all enabled
      libraryEnabled[path] = enabled == null || enabled.contains(path);
    }
    // Load player settings
    final preferLocal = await SettingsService.getPreferLocalPlayer();
    final smartSort = await SettingsService.getSmartSortPlayers();
    final volumePrecision = await SettingsService.getVolumePrecisionMode();
    // Load hint settings
    final showHints = await SettingsService.getShowHints();
    // Load library settings
    final showOnlyArtistsWithAlbums = await SettingsService.getShowOnlyArtistsWithAlbums();
    if (mounted) {
      setState(() {
        _showRecentAlbums = showRecent;
@@ -107,16 +97,17 @@ class _SettingsScreenState extends State<SettingsScreen> {
        _showFavoriteAlbums = showFavAlbums;
        _showFavoriteArtists = showFavArtists;
        _showFavoriteTracks = showFavTracks;
        _showFavoritePlaylists = showFavPlaylists;
        _showFavoriteRadioStations = showFavRadio;
        _showFavoritePodcasts = showFavPodcasts;
        _showContinueListeningAudiobooks = showContinueAudiobooks;
        _showDiscoverAudiobooks = showDiscAudiobooks;
        _showDiscoverSeries = showDiscSeries;
        _homeRowOrder = rowOrder;
        _discoveredLibraries = discovered;
        _libraryEnabled = libraryEnabled;
        _preferLocalPlayer = preferLocal;
        _smartSortPlayers = smartSort;
        _volumePrecisionMode = volumePrecision;
        _showHints = showHints;
        _showOnlyArtistsWithAlbums = showOnlyArtistsWithAlbums;
      });
    }
  }
@@ -150,6 +141,12 @@ class _SettingsScreenState extends State<SettingsScreen> {
        return {'title': s.favoriteArtists, 'subtitle': s.showFavoriteArtists};
      case 'favorite-tracks':
        return {'title': s.favoriteTracks, 'subtitle': s.showFavoriteTracks};
      case 'favorite-playlists':
        return {'title': s.favoritePlaylists, 'subtitle': s.showFavoritePlaylists};
      case 'favorite-radio-stations':
        return {'title': s.favoriteRadioStations, 'subtitle': s.showFavoriteRadioStations};
      case 'favorite-podcasts':
        return {'title': s.favoritePodcasts, 'subtitle': s.showFavoritePodcasts};
      default:
        return {'title': rowId, 'subtitle': ''};
    }
@@ -176,6 +173,12 @@ class _SettingsScreenState extends State<SettingsScreen> {
        return _showFavoriteArtists;
      case 'favorite-tracks':
        return _showFavoriteTracks;
      case 'favorite-playlists':
        return _showFavoritePlaylists;
      case 'favorite-radio-stations':
        return _showFavoriteRadioStations;
      case 'favorite-podcasts':
        return _showFavoritePodcasts;
      default:
        return false;
    }
@@ -221,6 +224,18 @@ class _SettingsScreenState extends State<SettingsScreen> {
          _showFavoriteTracks = value;
          SettingsService.setShowFavoriteTracks(value);
          break;
        case 'favorite-playlists':
          _showFavoritePlaylists = value;
          SettingsService.setShowFavoritePlaylists(value);
          break;
        case 'favorite-radio-stations':
          _showFavoriteRadioStations = value;
          SettingsService.setShowFavoriteRadioStations(value);
          break;
        case 'favorite-podcasts':
          _showFavoritePodcasts = value;
          SettingsService.setShowFavoritePodcasts(value);
          break;
      }
    });
  }
@@ -287,13 +302,26 @@ class _SettingsScreenState extends State<SettingsScreen> {
          crossAxisAlignment: CrossAxisAlignment.center,
          children: [
            // Logo - same size as login screen (50% of screen width)
            // Use color filter to make logo dark in light theme
            Padding(
              padding: const EdgeInsets.only(top: 8.0, bottom: 48.0),
-              child: Image.asset(
+              child: Theme.of(context).brightness == Brightness.light
-                'assets/images/ensemble_icon_transparent.png',
+                  ? ColorFiltered(
-                width: MediaQuery.of(context).size.width * 0.5,
+                      colorFilter: const ColorFilter.mode(
-                fit: BoxFit.contain,
+                        Color(0xFF1a1a1a), // Dark color for light theme
-              ),
+                        BlendMode.srcIn,
                      ),
                      child: Image.asset(
                        'assets/images/ensemble_icon_transparent.png',
                        width: MediaQuery.of(context).size.width * 0.5,
                        fit: BoxFit.contain,
                      ),
                    )
                  : Image.asset(
                      'assets/images/ensemble_icon_transparent.png',
                      width: MediaQuery.of(context).size.width * 0.5,
                      fit: BoxFit.contain,
                    ),
            ),
            // Connection status box - centered with border radius like theme boxes
@@ -600,7 +628,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
                            children: [
                              RadioListTile<String?>(
                                title: Text(S.of(context)!.system),
-                                subtitle: const Text('Auto'),
+                                subtitle: Text(S.of(context)!.auto),
                                value: null,
                                groupValue: localeProvider.locale?.languageCode,
                                onChanged: (value) {
@@ -609,7 +637,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
                                },
                              ),
                              RadioListTile<String?>(
-                                title: const Text('English'),
+                                title: Text(S.of(context)!.english),
                                value: 'en',
                                groupValue: localeProvider.locale?.languageCode,
                                onChanged: (value) {
@@ -618,7 +646,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
                                },
                              ),
                              RadioListTile<String?>(
-                                title: const Text('Deutsch'),
+                                title: Text(S.of(context)!.german),
                                value: 'de',
                                groupValue: localeProvider.locale?.languageCode,
                                onChanged: (value) {
@@ -627,7 +655,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
                                },
                              ),
                              RadioListTile<String?>(
-                                title: const Text('Español'),
+                                title: Text(S.of(context)!.spanish),
                                value: 'es',
                                groupValue: localeProvider.locale?.languageCode,
                                onChanged: (value) {
@@ -635,6 +663,15 @@ class _SettingsScreenState extends State<SettingsScreen> {
                                  Navigator.pop(dialogContext);
                                },
                              ),
                              RadioListTile<String?>(
                                title: Text(S.of(context)!.french),
                                value: 'fr',
                                groupValue: localeProvider.locale?.languageCode,
                                onChanged: (value) {
                                  localeProvider.setLocale(const Locale('fr'));
                                  Navigator.pop(dialogContext);
                                },
                              ),
                            ],
                          ),
                        );
@@ -708,6 +745,31 @@ class _SettingsScreenState extends State<SettingsScreen> {
                contentPadding: EdgeInsets.zero,
              ),
            ),
            const SizedBox(height: 8),
            Container(
              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
              decoration: BoxDecoration(
                color: colorScheme.surfaceVariant.withOpacity(0.3),
                borderRadius: BorderRadius.circular(12),
              ),
              child: SwitchListTile(
                title: Text(
                  'Volume precision mode',
                  style: TextStyle(color: colorScheme.onSurface),
                ),
                subtitle: Text(
                  'Hold still while adjusting volume for fine control',
                  style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
                ),
                value: _volumePrecisionMode,
                onChanged: (value) {
                  setState(() => _volumePrecisionMode = value);
                  SettingsService.setVolumePrecisionMode(value);
                },
                activeColor: colorScheme.primary,
                contentPadding: EdgeInsets.zero,
              ),
            ),
            const SizedBox(height: 32),
@@ -751,49 +813,6 @@ class _SettingsScreenState extends State<SettingsScreen> {
            const SizedBox(height: 32),
            // Library section
            Text(
              S.of(context)!.library,
              style: textTheme.titleMedium?.copyWith(
                color: colorScheme.onBackground,
                fontWeight: FontWeight.bold,
              ),
            ),
            const SizedBox(height: 16),
            Container(
              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
              decoration: BoxDecoration(
                color: colorScheme.surfaceVariant.withOpacity(0.3),
                borderRadius: BorderRadius.circular(12),
              ),
              child: SwitchListTile(
                title: Text(
                  'Show only artists with albums',
                  style: TextStyle(color: colorScheme.onSurface),
                ),
                subtitle: Text(
                  'Hide artists that have no albums in your library',
                  style: TextStyle(
                    color: colorScheme.onSurface.withOpacity(0.6),
                    fontSize: 12,
                  ),
                ),
                value: _showOnlyArtistsWithAlbums,
                onChanged: (value) async {
                  setState(() => _showOnlyArtistsWithAlbums = value);
                  await SettingsService.setShowOnlyArtistsWithAlbums(value);
                  // Force sync library to apply the new filter at API level
                  if (mounted) {
                    context.read<MusicAssistantProvider>().forceLibrarySync();
                  }
                },
                activeColor: colorScheme.primary,
                contentPadding: EdgeInsets.zero,
              ),
            ),
            const SizedBox(height: 32),
            // Home Screen section
            Text(
              S.of(context)!.homeScreen,
@@ -970,76 +989,6 @@ class _SettingsScreenState extends State<SettingsScreen> {
            const SizedBox(height: 32),
            // Audiobook Libraries section
            if (_discoveredLibraries.isNotEmpty) ...[
              Text(
                S.of(context)!.audiobookLibraries,
                style: textTheme.titleMedium?.copyWith(
                  color: colorScheme.onBackground,
                  fontWeight: FontWeight.bold,
                ),
              ),
              const SizedBox(height: 8),
              Text(
                S.of(context)!.chooseAudiobookLibraries,
                style: textTheme.bodySmall?.copyWith(
                  color: colorScheme.onBackground.withOpacity(0.6),
                ),
              ),
              const SizedBox(height: 16),
              Container(
                decoration: BoxDecoration(
                  color: colorScheme.surfaceVariant.withOpacity(0.3),
                  borderRadius: BorderRadius.circular(12),
                ),
                child: Column(
                  children: _discoveredLibraries.asMap().entries.map((entry) {
                    final index = entry.key;
                    final library = entry.value;
                    final path = library['path'] ?? '';
                    final name = library['name'] ?? S.of(context)!.unknownLibrary;
                    final isEnabled = _libraryEnabled[path] ?? true;
                    return Column(
                      children: [
                        SwitchListTile(
                          title: Text(
                            name,
                            style: TextStyle(color: colorScheme.onSurface),
                          ),
                          value: isEnabled,
                          onChanged: (value) async {
                            setState(() {
                              _libraryEnabled[path] = value;
                            });
                            await SettingsService.toggleAbsLibrary(path, value);
                            if (mounted) {
                              ScaffoldMessenger.of(context).showSnackBar(
                                SnackBar(
                                  content: Text(S.of(context)!.pullToRefresh),
                                  duration: const Duration(seconds: 2),
                                ),
                              );
                            }
                          },
                          activeColor: colorScheme.primary,
                        ),
                        if (index < _discoveredLibraries.length - 1)
                          Divider(
                            height: 1,
                            indent: 16,
                            endIndent: 16,
                            color: colorScheme.onSurface.withOpacity(0.1),
                          ),
                      ],
                    );
                  }).toList(),
                ),
              ),
              const SizedBox(height: 32),
            ],
            SizedBox(
              width: double.infinity,
              height: 50,
@@ -20,9 +20,15 @@ class CacheService {
  List<Album>? _cachedRecentAlbums;
  List<Artist>? _cachedDiscoverArtists;
  List<Album>? _cachedDiscoverAlbums;
  List<Audiobook>? _cachedInProgressAudiobooks;
  List<Audiobook>? _cachedDiscoverAudiobooks;
  List<AudiobookSeries>? _cachedDiscoverSeries;
  DateTime? _recentAlbumsLastFetched;
  DateTime? _discoverArtistsLastFetched;
  DateTime? _discoverAlbumsLastFetched;
  DateTime? _inProgressAudiobooksLastFetched;
  DateTime? _discoverAudiobooksLastFetched;
  DateTime? _discoverSeriesLastFetched;
  // Detail screen caching
  final Map<String, List<Track>> _albumTracksCache = {};
@@ -112,11 +118,82 @@ class CacheService {
    _persistHomeRowToDatabase('discover_albums', albums.map((a) => a.toJson()).toList());
  }
  /// Check if in-progress audiobooks cache is valid
  bool isInProgressAudiobooksCacheValid({bool forceRefresh = false}) {
    if (forceRefresh) return false;
    final now = DateTime.now();
    return _cachedInProgressAudiobooks != null &&
        _inProgressAudiobooksLastFetched != null &&
        now.difference(_inProgressAudiobooksLastFetched!) < Timings.homeRowCacheDuration;
  }
  /// Get cached in-progress audiobooks
  List<Audiobook>? getCachedInProgressAudiobooks() => _cachedInProgressAudiobooks;
  /// Set cached in-progress audiobooks
  void setCachedInProgressAudiobooks(List<Audiobook> audiobooks) {
    _cachedInProgressAudiobooks = audiobooks;
    _inProgressAudiobooksLastFetched = DateTime.now();
    _logger.log('✅ Cached ${audiobooks.length} in-progress audiobooks');
  }
  /// Check if discover audiobooks cache is valid
  bool isDiscoverAudiobooksCacheValid({bool forceRefresh = false}) {
    if (forceRefresh) return false;
    final now = DateTime.now();
    return _cachedDiscoverAudiobooks != null &&
        _discoverAudiobooksLastFetched != null &&
        now.difference(_discoverAudiobooksLastFetched!) < Timings.homeRowCacheDuration;
  }
  /// Get cached discover audiobooks
  List<Audiobook>? getCachedDiscoverAudiobooks() => _cachedDiscoverAudiobooks;
  /// Set cached discover audiobooks
  void setCachedDiscoverAudiobooks(List<Audiobook> audiobooks) {
    _cachedDiscoverAudiobooks = audiobooks;
    _discoverAudiobooksLastFetched = DateTime.now();
    _logger.log('✅ Cached ${audiobooks.length} discover audiobooks');
  }
  /// Check if discover series cache is valid
  bool isDiscoverSeriesCacheValid({bool forceRefresh = false}) {
    if (forceRefresh) return false;
    final now = DateTime.now();
    return _cachedDiscoverSeries != null &&
        _discoverSeriesLastFetched != null &&
        now.difference(_discoverSeriesLastFetched!) < Timings.homeRowCacheDuration;
  }
  /// Get cached discover series
  List<AudiobookSeries>? getCachedDiscoverSeries() => _cachedDiscoverSeries;
  /// Set cached discover series
  void setCachedDiscoverSeries(List<AudiobookSeries> series) {
    _cachedDiscoverSeries = series;
    _discoverSeriesLastFetched = DateTime.now();
    _logger.log('✅ Cached ${series.length} discover series');
  }
  /// Invalidate audiobook caches
  void invalidateAudiobookCaches() {
    _cachedInProgressAudiobooks = null;
    _inProgressAudiobooksLastFetched = null;
    _cachedDiscoverAudiobooks = null;
    _discoverAudiobooksLastFetched = null;
    _cachedDiscoverSeries = null;
    _discoverSeriesLastFetched = null;
    _logger.log('🗑️ Audiobook caches invalidated');
  }
  /// Invalidate home screen cache (call on pull-to-refresh)
  void invalidateHomeCache() {
    _recentAlbumsLastFetched = null;
    _discoverArtistsLastFetched = null;
    _discoverAlbumsLastFetched = null;
    _inProgressAudiobooksLastFetched = null;
    _discoverAudiobooksLastFetched = null;
    _discoverSeriesLastFetched = null;
    _logger.log('🗑️ Home screen cache invalidated');
  }
@@ -136,6 +213,20 @@ class CacheService {
    _logger.log('🗑️ Home artist caches invalidated');
  }
  /// Clear discover caches (call when provider filter changes)
  /// This ensures discover rows are refetched with the new provider filter
  void clearDiscoverCaches() {
    _cachedDiscoverArtists = null;
    _discoverArtistsLastFetched = null;
    _cachedDiscoverAlbums = null;
    _discoverAlbumsLastFetched = null;
    _cachedRecentAlbums = null;
    _recentAlbumsLastFetched = null;
    _searchCache.clear();
    _searchCacheTime.clear();
    _logger.log('🗑️ Discover caches cleared for provider filter change');
  }
  // ============================================================================
  // DETAIL SCREEN CACHING
  // ============================================================================
@@ -107,15 +107,18 @@ class DatabaseService {
  // ============================================
  /// Cache an item with JSON serialization
  /// [sourceProvider] - optional provider instance ID that provided this item (for client-side filtering)
  Future<void> cacheItem<T>({
    required String itemType,
    required String itemId,
    required Map<String, dynamic> data,
    String? sourceProvider,
  }) {
    return db.cacheItem(
      itemType: itemType,
      itemId: itemId,
      data: jsonEncode(data),
      sourceProvider: sourceProvider,
    );
  }
@@ -132,6 +135,29 @@ class DatabaseService {
    }).where((item) => item.isNotEmpty).toList();
  }
  /// Get cached items with source provider info for client-side filtering
  /// Returns list of (data, sourceProviders) tuples
  Future<List<(Map<String, dynamic>, List<String>)>> getCachedItemsWithProviders(String itemType) async {
    final items = await db.getCachedItems(itemType);
    return items.map((item) {
      try {
        final data = jsonDecode(item.data) as Map<String, dynamic>;
        List<String> providers = [];
        try {
          if (item.sourceProviders.isNotEmpty && item.sourceProviders != '[]') {
            providers = List<String>.from(
              jsonDecode(item.sourceProviders) as List,
            );
          }
        } catch (_) {}
        return (data, providers);
      } catch (e) {
        _logger.log('Error decoding cached item: $e');
        return (<String, dynamic>{}, <String>[]);
      }
    }).where((item) => item.$1.isNotEmpty).toList();
  }
  /// Get a single cached item
  Future<Map<String, dynamic>?> getCachedItem(String itemType, String itemId) async {
    final item = await db.getCachedItem(itemType, itemId);
@@ -167,6 +193,13 @@ class DatabaseService {
    return db.markItemsDeleted(itemType, [itemId]);
  }
  /// Batch cache multiple items efficiently
  /// Uses drift's batch API for much better performance on large datasets.
  /// Items are automatically chunked into batches of 500.
  Future<void> batchCacheItems(List<BatchCacheItem> items) {
    return db.batchCacheItems(items);
  }
  // ============================================
  // Player Cache Convenience Methods
  // ============================================
@@ -2,14 +2,19 @@ import 'dart:convert';
 import 'package:http/http.dart' as http;
 import 'debug_logger.dart';
 import 'settings_service.dart';
 import '../utils/lru_cache.dart';
 class MetadataService {
  static final _logger = DebugLogger();
  // Cache to avoid repeated API calls for the same artist/album
  static final Map<String, String> _cache = {};
-  // Cache for artist images
+  // LRU caches to avoid repeated API calls and prevent unbounded memory growth
-  static final Map<String, String?> _artistImageCache = {};
+  // Using NullableLruCache for caches that store null values (failed lookups)
  /// Cache for artist/album descriptions (100 entries)
  static final LruCache<String, String> _descriptionCache = LruCache(maxSize: 100);
  /// Cache for artist images - includes null entries for failed lookups (200 entries)
  static final NullableLruCache<String, String> _artistImageCache = NullableLruCache(maxSize: 200);
  /// Fetches artist biography/description with fallback chain:
  /// 1. Music Assistant metadata (passed in)
@@ -34,8 +39,8 @@ class MetadataService {
    // Check cache
    final cacheKey = 'artist:$artistName';
-    if (_cache.containsKey(cacheKey)) {
+    if (_descriptionCache.containsKey(cacheKey)) {
-      return _cache[cacheKey];
+      return _descriptionCache[cacheKey];
    }
    // Try Last.fm API
@@ -43,7 +48,7 @@ class MetadataService {
    if (lastFmKey != null && lastFmKey.isNotEmpty) {
      final lastFmDesc = await _fetchFromLastFm(artistName, null, lastFmKey);
      if (lastFmDesc != null) {
-        _cache[cacheKey] = lastFmDesc;
+        _descriptionCache[cacheKey] = lastFmDesc;
        return lastFmDesc;
      }
    }
@@ -53,7 +58,7 @@ class MetadataService {
    if (audioDbKey != null && audioDbKey.isNotEmpty) {
      final audioDbDesc = await _fetchFromTheAudioDb(artistName, audioDbKey);
      if (audioDbDesc != null) {
-        _cache[cacheKey] = audioDbDesc;
+        _descriptionCache[cacheKey] = audioDbDesc;
        return audioDbDesc;
      }
    }
@@ -83,8 +88,8 @@ class MetadataService {
    // Check cache
    final cacheKey = 'album:$artistName:$albumName';
-    if (_cache.containsKey(cacheKey)) {
+    if (_descriptionCache.containsKey(cacheKey)) {
-      return _cache[cacheKey];
+      return _descriptionCache[cacheKey];
    }
    // Try Last.fm API (TheAudioDB doesn't have good album info)
@@ -92,7 +97,7 @@ class MetadataService {
    if (lastFmKey != null && lastFmKey.isNotEmpty) {
      final lastFmDesc = await _fetchFromLastFm(artistName, albumName, lastFmKey);
      if (lastFmDesc != null) {
-        _cache[cacheKey] = lastFmDesc;
+        _descriptionCache[cacheKey] = lastFmDesc;
        return lastFmDesc;
      }
    }
@@ -251,11 +256,11 @@ class MetadataService {
    return null;
  }
-  // Cache for album images
+  /// Cache for album images - includes null entries for failed lookups (200 entries)
-  static final Map<String, String?> _albumImageCache = {};
+  static final NullableLruCache<String, String> _albumImageCache = NullableLruCache(maxSize: 200);
-  // Cache for author images (audiobooks)
+  /// Cache for author images (audiobooks) - includes null entries for failed lookups (100 entries)
-  static final Map<String, String?> _authorImageCache = {};
+  static final NullableLruCache<String, String> _authorImageCache = NullableLruCache(maxSize: 100);
  /// Fetches album cover URL from Deezer (free, no API key required)
  /// Returns the image URL if found, null otherwise
@@ -326,120 +331,301 @@ class MetadataService {
    return null;
  }
-  /// Fetches author image URL from multiple sources
+  /// Generate name variations for fuzzy matching
-  /// Priority: 1. Audnexus, 2. Open Library, 3. Wikipedia
+  /// Returns a list of name variations to try, in priority order
-  /// Returns the image URL if found, null otherwise
+  static List<String> _generateNameVariations(String authorName) {
-  static Future<String?> getAuthorImageUrl(String authorName) async {
+    final variations = <String>[];
-    // Check cache first
+    final original = authorName.trim();
-    final cacheKey = 'authorImage:$authorName';
+
-    if (_authorImageCache.containsKey(cacheKey)) {
+    // Always try original first
-      return _authorImageCache[cacheKey];
+    variations.add(original);
    // Handle "Lastname, Firstname" format
    if (original.contains(',')) {
      final parts = original.split(',').map((p) => p.trim()).toList();
      if (parts.length == 2) {
        variations.add('${parts[1]} ${parts[0]}'); // "Firstname Lastname"
      }
    }
-    // Try Audnexus (specifically for audiobook authors, uses Audible data)
+    // Normalize and expand initials for better matching
    // Handles messy formats like "J. R.R Tolkien", "J.R.R. Tolkien", etc.
    String normalized = original;
    // First, normalize spacing around periods in initials: "R.R" -> "R. R", "J. R" -> "J. R"
    // Match single letter followed by period and optional space, then another letter
    normalized = normalized.replaceAllMapped(
      RegExp(r'([A-Z])\.(\s?)([A-Z])'),
      (m) => '${m.group(1)}. ${m.group(3)}',
    );
    // Also handle single letters without periods followed by period-letter: "R.R" in "J. R.R"
    // This catches the case where we have "R.R" as a unit
    normalized = normalized.replaceAllMapped(
      RegExp(r'(\s)([A-Z])\.([A-Z])'),
      (m) => '${m.group(1)}${m.group(2)}. ${m.group(3)}.',
    );
    // Add periods to standalone single uppercase letters (initials without periods)
    // "J. R. R Tolkien" -> "J. R. R. Tolkien"
    normalized = normalized.replaceAllMapped(
      RegExp(r'(\s)([A-Z])(\s)'),
      (m) => '${m.group(1)}${m.group(2)}.${m.group(3)}',
    );
    if (normalized != original && !variations.contains(normalized)) {
      variations.add(normalized);
    }
    // Remove common titles
    final titles = ['Dr.', 'Dr', 'Mr.', 'Mr', 'Mrs.', 'Mrs', 'Ms.', 'Ms',
                    'Prof.', 'Prof', 'Professor', 'Sir', 'Dame', 'Lord', 'Lady'];
    String withoutTitle = original;
    for (final title in titles) {
      if (withoutTitle.toLowerCase().startsWith(title.toLowerCase() + ' ')) {
        withoutTitle = withoutTitle.substring(title.length).trim();
        if (withoutTitle != original) {
          variations.add(withoutTitle);
        }
        break;
      }
    }
    // Remove suffixes
    final suffixes = [', Jr.', ', Jr', ' Jr.', ' Jr', ', Sr.', ', Sr', ' Sr.', ' Sr',
                      ', III', ' III', ', II', ' II', ', IV', ' IV', ', PhD', ', Ph.D.'];
    String withoutSuffix = withoutTitle;
    for (final suffix in suffixes) {
      if (withoutSuffix.toLowerCase().endsWith(suffix.toLowerCase())) {
        withoutSuffix = withoutSuffix.substring(0, withoutSuffix.length - suffix.length).trim();
        if (withoutSuffix != withoutTitle && !variations.contains(withoutSuffix)) {
          variations.add(withoutSuffix);
        }
        break;
      }
    }
    // Split into parts for further variations (use normalized name for better splitting)
    final nameToSplit = normalized != original ? normalized : withoutSuffix;
    final parts = nameToSplit.split(RegExp(r'\s+')).where((p) => p.isNotEmpty).toList();
    if (parts.length >= 2) {
      // Try first + last only (skip middle names/initials)
      final firstLast = '${parts.first} ${parts.last}';
      if (!variations.contains(firstLast)) {
        variations.add(firstLast);
      }
      // Check if name starts with initials (single letter or letter with period)
      bool isInitial(String s) => s.length == 1 || (s.length == 2 && s.endsWith('.'));
      // If first part looks like an initial, try just the last name
      if (isInitial(parts.first)) {
        if (!variations.contains(parts.last)) {
          variations.add(parts.last);
        }
      }
      // Handle multiple initials like "J. K. Rowling" or "J. R. R. Tolkien"
      // Find where initials end and actual name begins
      int initialsEnd = 0;
      for (int i = 0; i < parts.length - 1; i++) {
        if (isInitial(parts[i])) {
          initialsEnd = i + 1;
        } else {
          break;
        }
      }
      if (initialsEnd > 0 && initialsEnd < parts.length) {
        // Try the non-initial part of the name
        final restOfName = parts.sublist(initialsEnd).join(' ');
        if (restOfName.isNotEmpty && !variations.contains(restOfName)) {
          variations.add(restOfName);
        }
        // Also try initials without periods + last name (e.g., "JRR Tolkien", "JK Rowling")
        final initialsNoPeriods = parts.sublist(0, initialsEnd)
            .map((s) => s.replaceAll('.', ''))
            .join('');
        final compactInitials = '$initialsNoPeriods ${parts.last}';
        if (!variations.contains(compactInitials)) {
          variations.add(compactInitials);
        }
      }
    }
    // Remove duplicates while preserving order
    return variations.toSet().toList();
  }
  /// Try to fetch author image from Audnexus
  /// Audnexus requires a two-step process:
  /// 1. Search by name to get the ASIN
  /// 2. Fetch full author details by ASIN to get the image
  static Future<String?> _tryAudnexus(String name) async {
    try {
-      final audnexusUri = Uri.https(
+      // Step 1: Search for author to get ASIN
-        'api.audnex.us',
+      final searchUri = Uri.https('api.audnex.us', '/authors', {'name': name});
-        '/authors',
+      final searchResponse = await http.get(searchUri).timeout(const Duration(seconds: 5));
        {'name': authorName},
      );
-      final audnexusResponse = await http.get(audnexusUri).timeout(const Duration(seconds: 5));
+      if (searchResponse.statusCode == 200) {
        final searchData = json.decode(searchResponse.body);
        if (searchData is List && searchData.isNotEmpty) {
          // Find the best match - prefer exact name matches
          String? bestAsin;
          final nameLower = name.toLowerCase().replaceAll(RegExp(r'[.\s]+'), '');
-      if (audnexusResponse.statusCode == 200) {
+          for (final result in searchData) {
-        final data = json.decode(audnexusResponse.body);
+            final resultName = (result['name'] as String?)?.toLowerCase().replaceAll(RegExp(r'[.\s]+'), '');
-        // Audnexus returns an array of authors
+            final asin = result['asin'] as String?;
-        if (data is List && data.isNotEmpty) {
+            if (asin != null) {
-          final author = data[0];
+              if (resultName == nameLower) {
-          final imageUrl = author['image'] as String?;
+                bestAsin = asin;
-          if (imageUrl != null && imageUrl.isNotEmpty) {
+                break; // Exact match found
-            _authorImageCache[cacheKey] = imageUrl;
+              }
-            return imageUrl;
+              bestAsin ??= asin; // Keep first result as fallback
            }
          }
          if (bestAsin != null) {
            // Step 2: Fetch full author details by ASIN
            final detailsUri = Uri.https('api.audnex.us', '/authors/$bestAsin');
            final detailsResponse = await http.get(detailsUri).timeout(const Duration(seconds: 5));
            if (detailsResponse.statusCode == 200) {
              final detailsData = json.decode(detailsResponse.body);
              final imageUrl = detailsData['image'] as String?;
              if (imageUrl != null && imageUrl.isNotEmpty) {
                return imageUrl;
              }
            }
          }
        }
      }
    } catch (e) {
-      _logger.warning('Audnexus author image error: $e', context: 'Metadata');
+      _logger.warning('Audnexus author image error for "$name": $e', context: 'Metadata');
    }
    return null;
  }
-    // Fall back to Open Library API
+  /// Try to fetch author image from Open Library
  static Future<String?> _tryOpenLibrary(String name) async {
    try {
-      final uri = Uri.https(
+      final uri = Uri.https('openlibrary.org', '/search/authors.json', {
-        'openlibrary.org',
+        'q': name,
-        '/search/authors.json',
+        'limit': '1',
-        {
+      });
          'q': authorName,
          'limit': '1',
        },
      );
      final response = await http.get(uri).timeout(const Duration(seconds: 5));
      if (response.statusCode == 200) {
        final data = json.decode(response.body);
        final authors = data['docs'] as List?;
        if (authors != null && authors.isNotEmpty) {
-          final author = authors[0];
+          final authorKey = authors[0]['key'] as String?;
          final authorKey = author['key'] as String?;
          if (authorKey != null) {
            // Open Library author images are available at:
            // https://covers.openlibrary.org/a/olid/{OLID}-L.jpg
            final olid = authorKey.replaceAll('/authors/', '');
            final imageUrl = 'https://covers.openlibrary.org/a/olid/$olid-L.jpg';
-            // Verify the image actually exists (Open Library returns 404 for missing images)
+            // Verify image exists - Open Library returns 302 redirects for valid images
            try {
-              final imageCheck = await http.head(Uri.parse(imageUrl)).timeout(const Duration(seconds: 3));
+              final check = await http.head(Uri.parse(imageUrl)).timeout(const Duration(seconds: 3));
-              if (imageCheck.statusCode == 200) {
+              // Accept 200 (direct), 301/302 (redirect to archive.org), or 307/308 (temporary redirect)
-                _authorImageCache[cacheKey] = imageUrl;
+              if (check.statusCode == 200 || check.statusCode == 301 ||
                  check.statusCode == 302 || check.statusCode == 307 || check.statusCode == 308) {
                return imageUrl;
              }
-            } catch (_) {
+            } catch (_) {}
-              // Image doesn't exist, continue to cache null
+          }
        }
      }
    } catch (e) {
      _logger.warning('Open Library author image error for "$name": $e', context: 'Metadata');
    }
    return null;
  }
  /// Try to fetch author image from Wikidata (structured Wikipedia data)
  static Future<String?> _tryWikidata(String name) async {
    try {
      // Search for entity by name
      final searchUri = Uri.https('www.wikidata.org', '/w/api.php', {
        'action': 'wbsearchentities',
        'search': name,
        'language': 'en',
        'type': 'item',
        'limit': '3',
        'format': 'json',
      });
      final searchResponse = await http.get(searchUri).timeout(const Duration(seconds: 5));
      if (searchResponse.statusCode == 200) {
        final searchData = json.decode(searchResponse.body);
        final results = searchData['search'] as List?;
        // Try each result to find one with an image
        for (final result in results ?? []) {
          final entityId = result['id'] as String?;
          if (entityId == null) continue;
          // Get the image property (P18)
          final claimsUri = Uri.https('www.wikidata.org', '/w/api.php', {
            'action': 'wbgetclaims',
            'entity': entityId,
            'property': 'P18', // P18 is the "image" property
            'format': 'json',
          });
          final claimsResponse = await http.get(claimsUri).timeout(const Duration(seconds: 5));
          if (claimsResponse.statusCode == 200) {
            final claimsData = json.decode(claimsResponse.body);
            final claims = claimsData['claims'] as Map<String, dynamic>?;
            final imageProperty = claims?['P18'] as List?;
            if (imageProperty != null && imageProperty.isNotEmpty) {
              final imageName = imageProperty[0]['mainsnak']?['datavalue']?['value'] as String?;
              if (imageName != null && imageName.isNotEmpty) {
                // Convert filename to Wikimedia Commons URL
                final encodedName = Uri.encodeComponent(imageName.replaceAll(' ', '_'));
                return 'https://commons.wikimedia.org/wiki/Special:FilePath/$encodedName?width=500';
              }
            }
          }
        }
      }
    } catch (e) {
-      _logger.warning('Open Library author image error: $e', context: 'Metadata');
+      _logger.warning('Wikidata author image error for "$name": $e', context: 'Metadata');
    }
    return null;
  }
-    // Fall back to Wikipedia API
+  /// Try to fetch author image from Wikipedia
  static Future<String?> _tryWikipedia(String name) async {
    try {
-      // Search for author on Wikipedia
+      // Search for author - "writer author" suffix helps find the right page
-      final searchUri = Uri.https(
+      final searchUri = Uri.https('en.wikipedia.org', '/w/api.php', {
-        'en.wikipedia.org',
+        'action': 'query',
-        '/w/api.php',
+        'list': 'search',
-        {
+        'srsearch': '$name writer author',
-          'action': 'query',
+        'srlimit': '1',
-          'list': 'search',
+        'format': 'json',
-          'srsearch': '$authorName writer',
+      });
          'srlimit': '1',
          'format': 'json',
        },
      );
      final searchResponse = await http.get(searchUri).timeout(const Duration(seconds: 5));
      if (searchResponse.statusCode == 200) {
        final searchData = json.decode(searchResponse.body);
-        final searchResults = searchData['query']?['search'] as List?;
+        final results = searchData['query']?['search'] as List?;
-        if (searchResults != null && searchResults.isNotEmpty) {
+        if (results != null && results.isNotEmpty) {
-          final pageTitle = searchResults[0]['title'] as String?;
+          final pageTitle = results[0]['title'] as String?;
          if (pageTitle != null) {
            // Get page image
-            final imageUri = Uri.https(
+            final imageUri = Uri.https('en.wikipedia.org', '/w/api.php', {
-              'en.wikipedia.org',
+              'action': 'query',
-              '/w/api.php',
+              'titles': pageTitle,
-              {
+              'prop': 'pageimages',
-                'action': 'query',
+              'pithumbsize': '500',
-                'titles': pageTitle,
+              'format': 'json',
-                'prop': 'pageimages',
+            });
                'pithumbsize': '500',
                'format': 'json',
              },
            );
            final imageResponse = await http.get(imageUri).timeout(const Duration(seconds: 5));
            if (imageResponse.statusCode == 200) {
@@ -450,7 +636,6 @@ class MetadataService {
                final thumbnail = page?['thumbnail'] as Map<String, dynamic>?;
                final imageUrl = thumbnail?['source'] as String?;
                if (imageUrl != null && imageUrl.isNotEmpty) {
                  _authorImageCache[cacheKey] = imageUrl;
                  return imageUrl;
                }
              }
@@ -459,7 +644,100 @@ class MetadataService {
        }
      }
    } catch (e) {
-      _logger.warning('Wikipedia author image error: $e', context: 'Metadata');
+      _logger.warning('Wikipedia author image error for "$name": $e', context: 'Metadata');
    }
    return null;
  }
  /// Fetches author image URL from multiple sources with fuzzy name matching
  /// Priority: 1. Audnexus, 2. Open Library, 3. Wikipedia
  /// Tries name variations if exact match fails
  static Future<String?> getAuthorImageUrl(String authorName) async {
    // Check cache first
    final cacheKey = 'authorImage:$authorName';
    if (_authorImageCache.containsKey(cacheKey)) {
      return _authorImageCache[cacheKey];
    }
    // Handle comma-separated author names (e.g., "Neil Gaiman, Dirk Maggs")
    // Try to get image for the first/primary author
    if (authorName.contains(',')) {
      final authors = authorName.split(',').map((s) => s.trim()).where((s) => s.isNotEmpty).toList();
      // Skip if this looks like "Lastname, Firstname" format or has suffixes
      // - Second part is initials (J.R.R., J.K., etc.)
      // - Second part is a suffix (Jr., Sr., III, PhD, etc.)
      final suffixes = ['jr', 'jr.', 'sr', 'sr.', 'ii', 'iii', 'iv', 'phd', 'ph.d.', 'md', 'm.d.'];
      if (authors.length == 2) {
        final secondPart = authors[1].toLowerCase();
        // Check if second part is a suffix or looks like initials
        if (suffixes.contains(secondPart) ||
            RegExp(r'^[a-z]\.?\s*[a-z]?\.?\s*[a-z]?\.?$').hasMatch(secondPart)) {
          // This is "Lastname, First" or "Name, Jr." - don't split
        } else if (authors[0].split(' ').length > 1 && authors[1].split(' ').length > 1) {
          // Both parts have multiple words - likely "Author1, Author2"
          for (final author in authors) {
            final result = await getAuthorImageUrl(author);
            if (result != null) {
              _authorImageCache[cacheKey] = result;
              return result;
            }
          }
          // Don't cache null here - fall through to try the full name
        }
      } else if (authors.length > 2) {
        // Multiple commas = definitely multiple authors
        for (final author in authors) {
          final result = await getAuthorImageUrl(author);
          if (result != null) {
            _authorImageCache[cacheKey] = result;
            return result;
          }
        }
        // Don't cache null - fall through to try full name
      }
    }
    // Generate name variations for fuzzy matching
    final variations = _generateNameVariations(authorName);
    // Try each source with all variations before moving to next source
    // This prioritizes source quality over name variation
    // 1. Try Audnexus (best for audiobook authors)
    for (final name in variations) {
      final result = await _tryAudnexus(name);
      if (result != null) {
        _authorImageCache[cacheKey] = result;
        return result;
      }
    }
    // 2. Try Open Library
    for (final name in variations) {
      final result = await _tryOpenLibrary(name);
      if (result != null) {
        _authorImageCache[cacheKey] = result;
        return result;
      }
    }
    // 3. Try Wikidata (structured data, good for finding exact person)
    for (final name in variations.take(2)) {
      final wikidataResult = await _tryWikidata(name);
      if (wikidataResult != null) {
        _authorImageCache[cacheKey] = wikidataResult;
        return wikidataResult;
      }
    }
    // 4. Try Wikipedia (search-based, good fallback)
    for (final name in variations.take(3)) {
      final wikiResult = await _tryWikipedia(name);
      if (wikiResult != null) {
        _authorImageCache[cacheKey] = wikiResult;
        return wikiResult;
      }
    }
    // Cache the null result to avoid repeated failed lookups
@@ -467,11 +745,90 @@ class MetadataService {
    return null;
  }
-  /// Clears the metadata cache
+  /// Cache for lyrics - uses bounded Map with manual size limiting (500 entries max)
  /// Stores (plainLyrics, syncedLyrics) tuples or null for failed lookups
  static final Map<String, (String?, String?)?> _lyricsCache = {};
  static const int _lyricsCacheMaxSize = 500;
  /// Fetches lyrics from LRCLIB (free, no API key required)
  /// Returns a tuple of (plainLyrics, syncedLyrics) or null if not found
  /// LRCLIB provides both synced (LRC format) and plain lyrics
  static Future<(String?, String?)?> getTrackLyrics({
    required String trackName,
    required String artistName,
    String? albumName,
    int? durationSeconds,
  }) async {
    // Build cache key
    final cacheKey = 'lyrics:$artistName:$trackName';
    if (_lyricsCache.containsKey(cacheKey)) {
      return _lyricsCache[cacheKey];
    }
    // Try LRCLIB API
    try {
      final params = <String, String>{
        'track_name': trackName,
        'artist_name': artistName,
      };
      if (albumName != null && albumName.isNotEmpty) {
        params['album_name'] = albumName;
      }
      if (durationSeconds != null && durationSeconds > 0) {
        params['duration'] = durationSeconds.toString();
      }
      final uri = Uri.https('lrclib.net', '/api/get', params);
      _logger.log('🎤 Fetching lyrics from LRCLIB: $trackName by $artistName');
      final response = await http.get(
        uri,
        headers: {
          'User-Agent': 'Ensemble Music Player (https://github.com/ensemble-app)',
        },
      ).timeout(const Duration(seconds: 5));
      if (response.statusCode == 200) {
        final data = json.decode(response.body);
        final plainLyrics = data['plainLyrics'] as String?;
        final syncedLyrics = data['syncedLyrics'] as String?;
        if ((plainLyrics != null && plainLyrics.isNotEmpty) ||
            (syncedLyrics != null && syncedLyrics.isNotEmpty)) {
          _logger.log('🎤 LRCLIB found lyrics: plain=${plainLyrics?.length ?? 0} chars, synced=${syncedLyrics?.length ?? 0} chars');
          final result = (plainLyrics, syncedLyrics);
          _evictLyricsCacheIfNeeded();
          _lyricsCache[cacheKey] = result;
          return result;
        }
      } else if (response.statusCode == 404) {
        _logger.log('🎤 LRCLIB: No lyrics found for $trackName');
      } else {
        _logger.log('🎤 LRCLIB error: ${response.statusCode}');
      }
    } catch (e) {
      _logger.warning('LRCLIB API error: $e', context: 'Metadata');
    }
    // Cache the null result to avoid repeated failed lookups
    _evictLyricsCacheIfNeeded();
    _lyricsCache[cacheKey] = null;
    return null;
  }
  /// Evict oldest entries from lyrics cache if over max size
  static void _evictLyricsCacheIfNeeded() {
    while (_lyricsCache.length >= _lyricsCacheMaxSize) {
      _lyricsCache.remove(_lyricsCache.keys.first);
    }
  }
  /// Clears all metadata caches
  static void clearCache() {
-    _cache.clear();
+    _descriptionCache.clear();
    _artistImageCache.clear();
    _albumImageCache.clear();
    _authorImageCache.clear();
    _lyricsCache.clear();
  }
 }
@@ -8,6 +8,7 @@ import '../constants/network.dart';
 import '../constants/timings.dart' show Timings, LibraryConstants;
 import '../models/media_item.dart';
 import '../models/player.dart';
 import '../models/provider_instance.dart';
 import 'debug_logger.dart';
 import 'settings_service.dart';
 import 'device_id_service.dart';
@@ -79,13 +80,15 @@ class MusicAssistantAPI {
      return;
    }
-    // If connection is in progress, wait for it instead of starting another
+    // Atomic check-and-set: create new completer first, then check if one exists
    // This ensures no async operations happen between check and set
    final newCompleter = Completer<void>();
    if (_connectionInProgress != null && !_connectionInProgress!.isCompleted) {
      _logger.log('Connection already in progress, waiting...');
      return _connectionInProgress!.future;
    }
-
+    // Set immediately before any async operations to close the race window
-    _connectionInProgress = Completer<void>();
+    _connectionInProgress = newCompleter;
    try {
      _updateConnectionState(MAConnectionState.connecting);
@@ -344,6 +347,14 @@ class MusicAssistantAPI {
      }
    }
    // Prevent memory leaks by limiting pending requests
    if (_pendingRequests.length >= NetworkConstants.maxPendingRequests) {
      throw Exception(
        'Too many pending requests (${_pendingRequests.length}). '
        'Please wait for existing requests to complete.',
      );
    }
    final messageId = _uuid.v4();
    final completer = Completer<Map<String, dynamic>>();
    _pendingRequests[messageId] = completer;
@@ -376,23 +387,31 @@ class MusicAssistantAPI {
    String? search,
    bool? favoriteOnly,
    bool albumArtistsOnly = true,
    String? orderBy,
    List<String>? providerInstanceIds,
  }) async {
    try {
      final args = {
        if (limit != null) 'limit': limit,
        if (offset != null) 'offset': offset,
        if (search != null) 'search': search,
        if (favoriteOnly != null) 'favorite': favoriteOnly,
        'album_artists_only': albumArtistsOnly,
        if (orderBy != null) 'order_by': orderBy,
        if (providerInstanceIds != null && providerInstanceIds.isNotEmpty)
          'provider': providerInstanceIds,
      };
      _logger.log('🔍 API getArtists args: $args');
      final response = await _sendCommand(
        'music/artists/library_items',
-        args: {
+        args: args,
          if (limit != null) 'limit': limit,
          if (offset != null) 'offset': offset,
          if (search != null) 'search': search,
          if (favoriteOnly != null) 'favorite': favoriteOnly,
          'album_artists_only': albumArtistsOnly,
        },
      );
      final items = response['result'] as List<dynamic>?;
      if (items == null) {
        return [];
      }
      _logger.log('🔍 API getArtists returned ${items.length} items');
      return items
          .map((item) => Artist.fromJson(item as Map<String, dynamic>))
          .toList();
@@ -402,7 +421,11 @@ class MusicAssistantAPI {
    }
  }
-  Future<List<Artist>> getRandomArtists({int limit = 10, bool albumArtistsOnly = true}) async {
+  Future<List<Artist>> getRandomArtists({
    int limit = 10,
    bool albumArtistsOnly = true,
    List<String>? providerInstanceIds,
  }) async {
    try {
      final response = await _sendCommand(
        'music/artists/library_items',
@@ -410,6 +433,8 @@ class MusicAssistantAPI {
          'limit': limit,
          'order_by': 'random',
          'album_artists_only': albumArtistsOnly,
          if (providerInstanceIds != null && providerInstanceIds.isNotEmpty)
            'provider': providerInstanceIds,
        },
      );
@@ -431,6 +456,8 @@ class MusicAssistantAPI {
    String? search,
    bool? favoriteOnly,
    String? artistId,
    String? orderBy,
    List<String>? providerInstanceIds,
  }) async {
    try {
      final args = <String, dynamic>{
@@ -439,7 +466,11 @@ class MusicAssistantAPI {
        if (search != null) 'search': search,
        if (favoriteOnly != null) 'favorite': favoriteOnly,
        if (artistId != null) 'artist_id': artistId,
        if (orderBy != null) 'order_by': orderBy,
        if (providerInstanceIds != null && providerInstanceIds.isNotEmpty)
          'provider': providerInstanceIds,
      };
      _logger.log('🔍 API getAlbums args: $args');
      final response = await _sendCommand(
        'music/albums/library_items',
@@ -448,6 +479,7 @@ class MusicAssistantAPI {
      final items = response['result'] as List<dynamic>?;
      if (items == null) return [];
      _logger.log('🔍 API getAlbums returned ${items.length} items');
      return items
          .map((item) => Album.fromJson(item as Map<String, dynamic>))
@@ -465,6 +497,8 @@ class MusicAssistantAPI {
    bool? favoriteOnly,
    String? artistId,
    String? albumId,
    String? orderBy,
    List<String>? providerInstanceIds,
  }) async {
    try {
      final response = await _sendCommand(
@@ -476,6 +510,9 @@ class MusicAssistantAPI {
          if (favoriteOnly != null) 'favorite': favoriteOnly,
          if (artistId != null) 'artist': artistId,
          if (albumId != null) 'album': albumId,
          if (orderBy != null) 'order_by': orderBy,
          if (providerInstanceIds != null && providerInstanceIds.isNotEmpty)
            'provider': providerInstanceIds,
        },
      );
@@ -496,6 +533,7 @@ class MusicAssistantAPI {
    int? limit,
    int? offset,
    bool? favoriteOnly,
    String? orderBy,
  }) async {
    try {
      final response = await _sendCommand(
@@ -504,6 +542,7 @@ class MusicAssistantAPI {
          if (limit != null) 'limit': limit,
          if (offset != null) 'offset': offset,
          if (favoriteOnly != null) 'favorite': favoriteOnly,
          if (orderBy != null) 'order_by': orderBy,
        },
      );
@@ -555,6 +594,7 @@ class MusicAssistantAPI {
    int? limit,
    int? offset,
    bool? favoriteOnly,
    String? orderBy,
  }) async {
    try {
      final response = await _sendCommand(
@@ -563,6 +603,7 @@ class MusicAssistantAPI {
          if (limit != null) 'limit': limit,
          if (offset != null) 'offset': offset,
          if (favoriteOnly != null) 'favorite': favoriteOnly,
          if (orderBy != null) 'order_by': orderBy,
        },
      );
@@ -719,48 +760,113 @@ class MusicAssistantAPI {
    String? search,
    bool? favoriteOnly,
    String? authorId,
    List<String>? providerInstanceIds,
  }) async {
    try {
-      // Check if library filtering is enabled
+      final allAudiobooks = <Audiobook>[];
      final seenIds = <String>{};
      // Check if library filtering is enabled (for ABS providers)
      final enabledLibraries = await SettingsService.getEnabledAbsLibraries();
-      // If specific libraries are enabled, use browse API for filtering
+      // Extract ABS provider IDs from library paths
      final absProviderIds = <String>{};
      if (enabledLibraries != null && enabledLibraries.isNotEmpty) {
-        return await _getAudiobooksFromBrowse(enabledLibraries, favoriteOnly: favoriteOnly);
+        for (final libPath in enabledLibraries) {
-      }
+          final providerEnd = libPath.indexOf('://');
-
+          if (providerEnd != -1) {
-      // Otherwise use the faster MA API (returns all audiobooks)
+            absProviderIds.add(libPath.substring(0, providerEnd));
-      final args = <String, dynamic>{
+          }
        if (limit != null) 'limit': limit,
        if (offset != null) 'offset': offset,
        if (search != null) 'search': search,
        if (favoriteOnly != null) 'favorite': favoriteOnly,
        if (authorId != null) 'author_id': authorId,
      };
      final response = await _sendCommand(
        'music/audiobooks/library_items',
        args: args,
      );
      // Check for error in response
      if (response.containsKey('error_code')) {
        return [];
      }
      final items = response['result'] as List<dynamic>?;
      if (items == null) return [];
      final audiobooks = <Audiobook>[];
      for (int i = 0; i < items.length; i++) {
        try {
          final book = Audiobook.fromJson(items[i] as Map<String, dynamic>);
          audiobooks.add(book);
        } catch (e) {
          // Skip items that fail to parse
        }
      }
-      return audiobooks;
+
      _logger.log('📚 getAudiobooks: absProviderIds=$absProviderIds, providerInstanceIds=$providerInstanceIds');
      // PART 1: Fetch from ABS providers using browse API (for library filtering support)
      if (enabledLibraries != null && enabledLibraries.isNotEmpty) {
        // If specific providers are requested, filter libraries to only matching ABS providers
        var librariesToBrowse = enabledLibraries;
        if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
          librariesToBrowse = enabledLibraries.where((libPath) {
            final providerEnd = libPath.indexOf('://');
            if (providerEnd == -1) return false;
            final providerId = libPath.substring(0, providerEnd);
            return providerInstanceIds.contains(providerId);
          }).toList();
        }
        if (librariesToBrowse.isNotEmpty) {
          final browseBooks = await _getAudiobooksFromBrowse(librariesToBrowse, favoriteOnly: favoriteOnly);
          for (final book in browseBooks) {
            if (!seenIds.contains(book.itemId)) {
              seenIds.add(book.itemId);
              allAudiobooks.add(book);
            }
          }
          _logger.log('📚 Got ${browseBooks.length} audiobooks from ABS browse API');
        }
      }
      // PART 2: Fetch from non-ABS providers using library_items API
      // This gets audiobooks from Spotify, Plex, Jellyfin, etc.
      List<String>? nonAbsProviders;
      if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
        // Filter to only non-ABS providers from the requested list
        nonAbsProviders = providerInstanceIds.where((id) => !absProviderIds.contains(id)).toList();
      } else if (absProviderIds.isNotEmpty) {
        // No specific providers requested, but we have ABS - need to also fetch from non-ABS
        // Pass null to get all, then we'll deduplicate
        nonAbsProviders = null; // Will fetch all
      }
      // Only call library_items API if:
      // 1. No ABS libraries configured (traditional mode), OR
      // 2. We have non-ABS providers to query
      final shouldFetchFromApi = enabledLibraries == null ||
                                  enabledLibraries.isEmpty ||
                                  (nonAbsProviders == null && absProviderIds.isNotEmpty) ||
                                  (nonAbsProviders != null && nonAbsProviders.isNotEmpty);
      if (shouldFetchFromApi) {
        final args = <String, dynamic>{
          if (limit != null) 'limit': limit,
          if (offset != null) 'offset': offset,
          if (search != null) 'search': search,
          if (favoriteOnly != null) 'favorite': favoriteOnly,
          if (authorId != null) 'author_id': authorId,
          if (nonAbsProviders != null && nonAbsProviders.isNotEmpty)
            'provider': nonAbsProviders,
        };
        final response = await _sendCommand(
          'music/audiobooks/library_items',
          args: args,
        );
        if (!response.containsKey('error_code')) {
          final items = response['result'] as List<dynamic>?;
          if (items != null) {
            int addedCount = 0;
            for (int i = 0; i < items.length; i++) {
              try {
                final book = Audiobook.fromJson(items[i] as Map<String, dynamic>);
                // Deduplicate by itemId
                if (!seenIds.contains(book.itemId)) {
                  seenIds.add(book.itemId);
                  allAudiobooks.add(book);
                  addedCount++;
                }
              } catch (e) {
                // Skip items that fail to parse
              }
            }
            _logger.log('📚 Got $addedCount audiobooks from library_items API');
          }
        }
      }
      _logger.log('📚 Total audiobooks: ${allAudiobooks.length}');
      return allAudiobooks;
    } catch (e, stack) {
      _logger.log('Error getting audiobooks: $e');
      _logger.log('Stack: $stack');
@@ -988,6 +1094,51 @@ class MusicAssistantAPI {
    }
  }
  /// Get lyrics for a track
  /// Returns the lyrics text if available, null otherwise
  /// Uses the dedicated metadata/get_track_lyrics endpoint
  Future<String?> getTrackLyrics(Map<String, dynamic> track) async {
    try {
      _logger.log('🎤 Getting lyrics for track: ${track['name']}');
      // Use the dedicated lyrics endpoint
      final response = await _sendCommand(
        'metadata/get_track_lyrics',
        args: {
          'track': track,
        },
      );
      if (response.containsKey('error_code')) {
        _logger.log('🎤 Error getting lyrics: ${response['error_code']}');
        return null;
      }
      // Result is a tuple: [plain_lyrics, synced_lyrics]
      // We prefer synced lyrics if available, otherwise plain
      final result = response['result'];
      if (result is List && result.length >= 2) {
        final plainLyrics = result[0] as String?;
        final syncedLyrics = result[1] as String?;
        if (syncedLyrics != null && syncedLyrics.isNotEmpty) {
          _logger.log('🎤 Found synced lyrics: ${syncedLyrics.length} chars');
          return syncedLyrics;
        }
        if (plainLyrics != null && plainLyrics.isNotEmpty) {
          _logger.log('🎤 Found plain lyrics: ${plainLyrics.length} chars');
          return plainLyrics;
        }
      }
      _logger.log('🎤 No lyrics found in result: $result');
      return null;
    } catch (e) {
      _logger.log('🎤 Error getting lyrics: $e');
      return null;
    }
  }
  /// Browse Music Assistant content by path
  /// Returns a list of browse items (folders or media items)
  Future<List<dynamic>> browse(String? path) async {
@@ -1082,7 +1233,7 @@ class MusicAssistantAPI {
      for (final item in providerRoot) {
        final itemMap = item as Map<String, dynamic>;
        final path = itemMap['path'] as String? ?? '';
-        final name = itemMap['name'] as String? ?? '';
+        final name = (itemMap['name'] as String?) ?? (itemMap['label'] as String?) ?? '';
        if (path != 'root' && name != '..') {
          discoveredLibraries.add({'path': path, 'name': name});
        }
@@ -1101,7 +1252,7 @@ class MusicAssistantAPI {
      for (final libraryItem in providerRoot) {
        final libraryMap = libraryItem as Map<String, dynamic>;
        final libraryPath = libraryMap['path'] as String? ?? '';
-        final libraryName = libraryMap['name'] as String? ?? '';
+        final libraryName = (libraryMap['name'] as String?) ?? (libraryMap['label'] as String?) ?? '';
        // Skip "root" (parent navigation) item
        if (libraryPath == 'root' || libraryName == '..') continue;
@@ -1121,7 +1272,7 @@ class MusicAssistantAPI {
        // Log library contents to find series
        for (final item in libraryContents) {
          final itemMap = item as Map<String, dynamic>;
-          final name = itemMap['name'] as String? ?? '';
+          final name = (itemMap['name'] as String?) ?? (itemMap['label'] as String?) ?? '';
          final path = itemMap['path'] as String? ?? '';
          _logger.log('📚   Library item: name=$name, path=$path');
        }
@@ -1129,10 +1280,11 @@ class MusicAssistantAPI {
        // Look for "Series" folder in the library
        for (final item in libraryContents) {
          final itemMap = item as Map<String, dynamic>;
-          final name = (itemMap['name'] as String? ?? '').toLowerCase();
+          final name = ((itemMap['name'] as String?) ?? (itemMap['label'] as String?) ?? '').toLowerCase();
          final path = itemMap['path'] as String? ?? '';
-          if (name.contains('series') || path.contains('series')) {
+          // Check for "series" in name/path, or abbreviated path ending with "/s"
          if (name.contains('series') || path.contains('series') || path.endsWith('/s')) {
            _logger.log('📚 Found series folder: $path');
            // Browse the series folder
@@ -1141,13 +1293,15 @@ class MusicAssistantAPI {
            for (final seriesItem in seriesItems) {
              final seriesMap = seriesItem as Map<String, dynamic>;
              final seriesName = (seriesMap['name'] as String?) ?? (seriesMap['label'] as String?) ?? '';
              final seriesPath = seriesMap['path'] as String? ?? '';
              // Skip parent navigation
-              if (seriesMap['path'] == 'root' || seriesMap['name'] == '..') continue;
+              if (seriesPath == 'root' || seriesName == '..' || seriesPath.endsWith('://')) continue;
              // Skip actual audiobook items (we only want series folders)
              final mediaType = seriesMap['media_type'] as String?;
              if (mediaType == 'audiobook' || mediaType == 'track') continue;
-              _logger.log('📚 Series: name=${seriesMap['name']}, path=${seriesMap['path']}, media_type=$mediaType');
+              _logger.log('📚 Series: name=$seriesName, path=$seriesPath, media_type=$mediaType');
              allSeries.add(AudiobookSeries.fromJson(seriesMap));
            }
            break; // Found series in this library, move to next library
@@ -1335,13 +1489,18 @@ class MusicAssistantAPI {
  }
  /// Get random albums
-  Future<List<Album>> getRandomAlbums({int limit = 10}) async {
+  Future<List<Album>> getRandomAlbums({
    int limit = 10,
    List<String>? providerInstanceIds,
  }) async {
    try {
      final response = await _sendCommand(
        'music/albums/library_items',
        args: {
          'limit': limit,
          'order_by': 'random',
          if (providerInstanceIds != null && providerInstanceIds.isNotEmpty)
            'provider': providerInstanceIds,
        },
      );
@@ -1457,6 +1616,8 @@ class MusicAssistantAPI {
    int? offset,
    String? search,
    bool? favoriteOnly,
    String? orderBy,
    List<String>? providerInstanceIds,
  }) async {
    try {
      final response = await _sendCommand(
@@ -1466,6 +1627,9 @@ class MusicAssistantAPI {
          if (offset != null) 'offset': offset,
          if (search != null) 'search': search,
          if (favoriteOnly != null) 'favorite': favoriteOnly,
          if (orderBy != null) 'order_by': orderBy,
          if (providerInstanceIds != null && providerInstanceIds.isNotEmpty)
            'provider': providerInstanceIds,
        },
      );
@@ -1487,7 +1651,7 @@ class MusicAssistantAPI {
      final response = await _sendCommand(
        'music/playlist',
        args: {
-          'provider': provider,
+          'provider_instance_id_or_domain': provider,
          'item_id': itemId,
        },
      );
@@ -2453,6 +2617,109 @@ class MusicAssistantAPI {
    }
  }
  /// Delete an item from the queue
  Future<void> queueCommandDeleteItem(String queueId, String itemId) async {
    try {
      await _sendCommand(
        'player_queues/delete_item',
        args: {
          'queue_id': queueId,
          'item_id_or_index': itemId,
        },
      );
    } catch (e) {
      _logger.log('Error deleting queue item: $e');
      rethrow;
    }
  }
  /// Move an item in the queue by a relative position shift
  /// pos_shift > 0: move down, pos_shift < 0: move up, pos_shift = 0: move to next
  Future<void> queueCommandMoveItem(String queueId, String itemId, int posShift) async {
    try {
      await _sendCommand(
        'player_queues/move_item',
        args: {
          'queue_id': queueId,
          'queue_item_id': itemId,
          'pos_shift': posShift,
        },
      );
    } catch (e) {
      _logger.log('Error moving queue item: $e');
      rethrow;
    }
  }
  /// Play a specific item in the queue by its queue_item_id
  Future<void> queueCommandPlayIndex(String queueId, String queueItemId) async {
    try {
      await _sendCommand(
        'player_queues/play_index',
        args: {
          'queue_id': queueId,
          'index': queueItemId,
        },
      );
    } catch (e) {
      _logger.log('Error playing queue item: $e');
      rethrow;
    }
  }
  /// Clear all items from the queue
  Future<void> queueCommandClear(String queueId) async {
    try {
      await _sendCommand(
        'player_queues/clear',
        args: {
          'queue_id': queueId,
        },
      );
    } catch (e) {
      _logger.log('Error clearing queue: $e');
      rethrow;
    }
  }
  /// Transfer the current queue to another player
  /// This moves the entire playback queue from source player to target player,
  /// including shuffle and repeat settings.
  ///
  /// [sourceQueueId] - The queue ID of the source player (optional, uses first playing player if null)
  /// [targetQueueId] - The queue ID of the target player (required)
  /// [autoPlay] - Whether to automatically start playback on the target player (default: true)
  Future<void> transferQueue({
    String? sourceQueueId,
    required String targetQueueId,
    bool autoPlay = true,
  }) async {
    try {
      _logger.log('🔄 Transferring queue to player: $targetQueueId (source: ${sourceQueueId ?? "auto"}, autoPlay: $autoPlay)');
      final args = <String, dynamic>{
        'target_queue_id': targetQueueId,
        'auto_play': autoPlay,
      };
      // Only include source_queue_id if explicitly provided
      // When null, MA will use the first playing player
      if (sourceQueueId != null) {
        args['source_queue_id'] = sourceQueueId;
      }
      await _sendCommand(
        'player_queues/transfer',
        args: args,
      );
      _logger.log('✅ Queue transferred successfully');
    } catch (e) {
      _logger.log('❌ Error transferring queue: $e');
      rethrow;
    }
  }
  // ============================================================================
  // BUILT-IN PLAYER MANAGEMENT
  // ============================================================================
@@ -2496,6 +2763,23 @@ class MusicAssistantAPI {
    return _eventStreams['media_item_deleted']!.stream;
  }
  /// Stream of queue_updated events (for queue metadata changes)
  Stream<Map<String, dynamic>> get queueUpdatedEvents {
    if (!_eventStreams.containsKey('queue_updated')) {
      _eventStreams['queue_updated'] = StreamController<Map<String, dynamic>>.broadcast();
    }
    return _eventStreams['queue_updated']!.stream;
  }
  /// Stream of queue_items_updated events (for queue item add/remove/reorder)
  /// This is critical for keeping queue UI in sync, especially in radio mode
  Stream<Map<String, dynamic>> get queueItemsUpdatedEvents {
    if (!_eventStreams.containsKey('queue_items_updated')) {
      _eventStreams['queue_items_updated'] = StreamController<Map<String, dynamic>>.broadcast();
    }
    return _eventStreams['queue_items_updated']!.stream;
  }
  /// Register this device as a player with retry logic
  /// CRITICAL: This creates a player config in MA's settings.json
  /// The server expects: player_id and player_name
@@ -3146,14 +3430,6 @@ class MusicAssistantAPI {
        _logger.log('⚠️ Could not load provider manifests: $e');
      }
      // Fetch provider instances (active providers)
      try {
        await _sendCommand('providers');
        _logger.log('✓ Provider instances loaded');
      } catch (e) {
        _logger.log('⚠️ Could not load provider instances: $e');
      }
      _logger.log('✅ Initial state fetch complete');
    } catch (e) {
      _logger.log('❌ Error fetching state: $e');
@@ -3161,6 +3437,39 @@ class MusicAssistantAPI {
    }
  }
  /// Get all music provider instances configured in Music Assistant
  /// Returns only music providers (spotify, tidal, filesystem, etc.) not player/metadata providers
  Future<List<ProviderInstance>> getMusicProviders() async {
    try {
      final response = await _sendCommand('providers');
      final result = response['result'];
      if (result == null) {
        _logger.log('⚠️ providers command returned no result');
        return [];
      }
      final List<dynamic> providers = result is List ? result : [];
      final musicProviders = <ProviderInstance>[];
      for (final providerData in providers) {
        if (providerData is Map<String, dynamic>) {
          final instance = ProviderInstance.fromJson(providerData);
          // Only include music providers (not player providers, metadata providers, etc.)
          if (instance.isMusicProvider) {
            musicProviders.add(instance);
          }
        }
      }
      _logger.log('🎵 Found ${musicProviders.length} music providers: ${musicProviders.map((p) => p.name).join(", ")}');
      return musicProviders;
    } catch (e) {
      _logger.log('❌ Error getting music providers: $e');
      return [];
    }
  }
  /// Get current authenticated user's profile
  /// Returns user info including display_name, username, groups, etc.
  Future<Map<String, dynamic>?> getCurrentUserInfo() async {
@@ -3296,6 +3605,9 @@ class MusicAssistantAPI {
      return;
    }
    // Cancel all pending requests before reconnecting to prevent memory leaks
    _cancelPendingRequests('Connection lost, reconnecting');
    await Future.delayed(Timings.reconnectDelay);
    // Check again after delay
@@ -100,6 +100,7 @@ class PositionTracker {
    Duration? duration,
    double? serverTimestamp,
  }) {
    _logger.log('⏱️ PositionTracker.updateFromServer: pos=${position.toStringAsFixed(1)}s, isPlaying=$isPlaying, playerId=$playerId');
    final bool playerChanged = _playerId != playerId;
    final bool playStateChanged = _isPlaying != isPlaying;
    final bool durationChanged = duration != null && _duration != duration;
@@ -155,17 +156,34 @@ class PositionTracker {
    // 3. Position jumped significantly (seek or track change) - BUT NOT if it's a suspicious reset
    //    AND NOT if the timestamp is stale (stale data shouldn't override interpolated position)
    // 4. We're not playing (paused state should reflect server position)
    // 5. Anchor is getting stale (> 20 seconds old) - prevents position freezing at _maxAnchorAge cap
    //
    // Key insight: When timestamp is stale, the raw position from server is likely outdated.
    // Our interpolated position is probably more accurate, so don't let stale data override it.
    // HOWEVER, if our anchor itself is getting old, we need to refresh it to prevent freezing.
    final anchorAge = DateTime.now().difference(_anchorTime);
    final anchorIsGettingStale = anchorAge.inSeconds > 20;
    // When anchor is stale, always refresh it - the suspicious reset check should
    // only prevent us from trusting the SERVER's position, not from refreshing
    // our own interpolated anchor. The newAnchorPos logic below handles using
    // interpolated position for stale anchors with suspicious server data.
    final shouldUpdateAnchor = playerChanged
        || playStateChanged
        || (positionDiff > 2 && !isSuspiciousReset && !hasStaleTimestamp)
-        || !isPlaying;
+        || !isPlaying
        || anchorIsGettingStale;
    if (shouldUpdateAnchor) {
-      _anchorPosition = anchorPos;
+      // When refreshing due to stale anchor (not player/state change), use interpolated position
      // to avoid backward jumps from outdated server data
      final newAnchorPos = anchorIsGettingStale && !playerChanged && !playStateChanged && isPlaying
          ? currentInterpolated  // Keep our interpolated position, just refresh the anchor time
          : anchorPos;           // Use server position for other cases
      _logger.log('⏱️ PositionTracker: Anchor updated ${_anchorPosition.toStringAsFixed(1)}s -> ${newAnchorPos.toStringAsFixed(1)}s (playerChanged=$playerChanged, playStateChanged=$playStateChanged, positionDiff=${positionDiff.toStringAsFixed(1)}, suspiciousReset=$isSuspiciousReset, anchorStale=$anchorIsGettingStale)');
      _anchorPosition = newAnchorPos;
      _anchorTime = DateTime.now();
    } else if (positionDiff > 2) {
      _logger.log('⏱️ PositionTracker: Anchor NOT updated (suspiciousReset=$isSuspiciousReset, staleTimestamp=$hasStaleTimestamp, interpolated=${currentInterpolated.toStringAsFixed(1)}s)');
    }
    _isPlaying = isPlaying;
@@ -209,6 +227,7 @@ class PositionTracker {
  /// Clear tracker state (e.g., when disconnecting)
  void clear() {
    _logger.log('⏱️ PositionTracker.clear() called');
    _stopInterpolationTimer();
    _playerId = null;
    _isPlaying = false;
@@ -218,9 +237,20 @@ class PositionTracker {
  }
  void _startInterpolationTimer() {
-    if (_interpolationTimer != null) return;
+    if (_interpolationTimer != null) {
      _logger.log('⏱️ PositionTracker: Timer already running, skipping start');
      return;
    }
-    _interpolationTimer = Timer.periodic(const Duration(milliseconds: 250), (_) {
+    _logger.log('⏱️ PositionTracker: Starting interpolation timer (anchor=${_anchorPosition.toStringAsFixed(1)}s)');
    _interpolationTimer = Timer.periodic(const Duration(milliseconds: 250), (timer) {
      // Log every 4 ticks (1 second) if no emission happened
      if (timer.tick % 4 == 0) {
        final pos = currentPosition;
        if (pos.inSeconds == _lastEmittedSeconds) {
          _logger.log('⏱️ PositionTracker: Timer tick ${timer.tick}, pos=${pos.inSeconds}s unchanged');
        }
      }
      _emitPosition();
    });
@@ -229,6 +259,7 @@ class PositionTracker {
  }
  void _stopInterpolationTimer() {
    _logger.log('⏱️ PositionTracker: Stopping interpolation timer (was ${_interpolationTimer != null ? "running" : "null"})');
    _interpolationTimer?.cancel();
    _interpolationTimer = null;
  }
@@ -240,6 +271,7 @@ class PositionTracker {
    // Only emit if second changed (reduces unnecessary updates)
    if (seconds != _lastEmittedSeconds) {
      _lastEmittedSeconds = seconds;
      _logger.log('⏱️ PositionTracker: Emitting position ${seconds}s (anchor=${_anchorPosition.toStringAsFixed(1)}s, playing=$_isPlaying)');
      _positionController.add(pos);
    }
  }
@@ -20,7 +20,17 @@ class SecureStorageService {
  // Auth Token (for stream requests)
  static Future<String?> getAuthToken() async {
-    return await _storage.read(key: _keyAuthToken);
+    try {
      return await _storage.read(key: _keyAuthToken);
    } catch (e) {
      // Handle decryption errors (e.g., after keystore/signature change)
      if (e.toString().contains('BadPaddingException') ||
          e.toString().contains('BAD_DECRYPT')) {
        await _storage.delete(key: _keyAuthToken);
        return null;
      }
      rethrow;
    }
  }
  static Future<void> setAuthToken(String? token) async {
@@ -33,7 +43,17 @@ class SecureStorageService {
  // Music Assistant Native Auth Token (long-lived token)
  static Future<String?> getMaAuthToken() async {
-    return await _storage.read(key: _keyMaAuthToken);
+    try {
      return await _storage.read(key: _keyMaAuthToken);
    } catch (e) {
      // Handle decryption errors (e.g., after keystore/signature change)
      if (e.toString().contains('BadPaddingException') ||
          e.toString().contains('BAD_DECRYPT')) {
        await _storage.delete(key: _keyMaAuthToken);
        return null;
      }
      rethrow;
    }
  }
  static Future<void> setMaAuthToken(String? token) async {
@@ -50,7 +70,18 @@ class SecureStorageService {
  // Auth Credentials (serialized auth strategy credentials)
  static Future<Map<String, dynamic>?> getAuthCredentials() async {
-    final json = await _storage.read(key: _keyAuthCredentials);
+    String? json;
    try {
      json = await _storage.read(key: _keyAuthCredentials);
    } catch (e) {
      // Handle decryption errors (e.g., after keystore/signature change)
      if (e.toString().contains('BadPaddingException') ||
          e.toString().contains('BAD_DECRYPT')) {
        await _storage.delete(key: _keyAuthCredentials);
        return null;
      }
      rethrow;
    }
    if (json == null) return null;
    try {
      return jsonDecode(json) as Map<String, dynamic>;
@@ -69,7 +100,17 @@ class SecureStorageService {
  // Password
  static Future<String?> getPassword() async {
-    return await _storage.read(key: _keyPassword);
+    try {
      return await _storage.read(key: _keyPassword);
    } catch (e) {
      // Handle decryption errors (e.g., after keystore/signature change)
      if (e.toString().contains('BadPaddingException') ||
          e.toString().contains('BAD_DECRYPT')) {
        await _storage.delete(key: _keyPassword);
        return null;
      }
      rethrow;
    }
  }
  static Future<void> setPassword(String? password) async {
@@ -82,7 +123,17 @@ class SecureStorageService {
  // Audiobookshelf API Token
  static Future<String?> getAbsApiToken() async {
-    return await _storage.read(key: _keyAbsApiToken);
+    try {
      return await _storage.read(key: _keyAbsApiToken);
    } catch (e) {
      // Handle decryption errors (e.g., after keystore/signature change)
      if (e.toString().contains('BadPaddingException') ||
          e.toString().contains('BAD_DECRYPT')) {
        await _storage.delete(key: _keyAbsApiToken);
        return null;
      }
      rethrow;
    }
  }
  static Future<void> setAbsApiToken(String? token) async {
@@ -98,12 +149,21 @@ class SecureStorageService {
    await _storage.deleteAll();
  }
  // Migration completed flag key
  static const String _keyMigrationCompleted = 'secure_storage_migration_completed';
  /// Migrate credentials from SharedPreferences to secure storage.
  /// Call this once during app upgrade to migrate existing users.
  /// Uses a flag to skip migration on subsequent runs for performance.
  static Future<void> migrateFromSharedPreferences() async {
    // Import SharedPreferences for migration
    final SharedPreferences prefs = await SharedPreferences.getInstance();
    // Skip if migration already completed
    if (prefs.getBool(_keyMigrationCompleted) == true) {
      return;
    }
    // Migrate auth token
    final authToken = prefs.getString('auth_token');
    if (authToken != null && authToken.isNotEmpty) {
@@ -144,5 +204,8 @@ class SecureStorageService {
      await setAbsApiToken(absApiToken);
      await prefs.remove('abs_api_token');
    }
    // Mark migration as completed to skip on future runs
    await prefs.setBool(_keyMigrationCompleted, true);
  }
 }
@@ -1,6 +1,7 @@
 import 'dart:async';
 import 'dart:convert';
 import 'package:flutter/foundation.dart';
 import '../database/database.dart' show BatchCacheItem;
 import '../models/media_item.dart';
 import 'database_service.dart';
 import 'debug_logger.dart';
@@ -17,6 +18,7 @@ enum SyncStatus {
 /// Service for background library synchronization
 /// Loads from database cache first, then syncs from MA API in background
 /// Supports per-provider sync for accurate client-side filtering
 class SyncService with ChangeNotifier {
  static SyncService? _instance;
  static final _logger = DebugLogger();
@@ -42,6 +44,13 @@ class SyncService with ChangeNotifier {
  List<Audiobook> _cachedAudiobooks = [];
  List<Playlist> _cachedPlaylists = [];
  // Source provider tracking for client-side filtering
  // Maps itemId -> list of provider instance IDs that provided the item
  Map<String, List<String>> _albumSourceProviders = {};
  Map<String, List<String>> _artistSourceProviders = {};
  Map<String, List<String>> _audiobookSourceProviders = {};
  Map<String, List<String>> _playlistSourceProviders = {};
  // Getters
  SyncStatus get status => _status;
  String? get lastError => _lastError;
@@ -54,8 +63,15 @@ class SyncService with ChangeNotifier {
  bool get hasCache => _cachedAlbums.isNotEmpty || _cachedArtists.isNotEmpty ||
                       _cachedAudiobooks.isNotEmpty || _cachedPlaylists.isNotEmpty;
  // Source provider getters for client-side filtering
  Map<String, List<String>> get albumSourceProviders => _albumSourceProviders;
  Map<String, List<String>> get artistSourceProviders => _artistSourceProviders;
  Map<String, List<String>> get audiobookSourceProviders => _audiobookSourceProviders;
  Map<String, List<String>> get playlistSourceProviders => _playlistSourceProviders;
  /// Load library data from database cache (instant)
  /// Call this on app startup for immediate data
  /// Also loads source provider info for client-side filtering
  Future<void> loadFromCache() async {
    if (!_db.isInitialized) {
      _logger.log('⚠️ Database not initialized, skipping cache load');
@@ -65,52 +81,73 @@ class SyncService with ChangeNotifier {
    try {
      _logger.log('📦 Loading library from database cache...');
-      // Load albums from cache
+      // Load albums from cache with source providers
-      final albumData = await _db.getCachedItems('album');
+      final albumDataWithProviders = await _db.getCachedItemsWithProviders('album');
-      _cachedAlbums = albumData.map((data) {
+      _cachedAlbums = [];
      _albumSourceProviders = {};
      for (final (data, providers) in albumDataWithProviders) {
        try {
-          return Album.fromJson(data);
+          final album = Album.fromJson(data);
          _cachedAlbums.add(album);
          if (providers.isNotEmpty) {
            _albumSourceProviders[album.itemId] = providers;
          }
        } catch (e) {
          _logger.log('⚠️ Failed to parse cached album: $e');
          return null;
        }
-      }).whereType<Album>().toList();
+      }
-      // Load artists from cache
+      // Load artists from cache with source providers
-      final artistData = await _db.getCachedItems('artist');
+      final artistDataWithProviders = await _db.getCachedItemsWithProviders('artist');
-      _cachedArtists = artistData.map((data) {
+      _cachedArtists = [];
      _artistSourceProviders = {};
      for (final (data, providers) in artistDataWithProviders) {
        try {
-          return Artist.fromJson(data);
+          final artist = Artist.fromJson(data);
          _cachedArtists.add(artist);
          if (providers.isNotEmpty) {
            _artistSourceProviders[artist.itemId] = providers;
          }
        } catch (e) {
          _logger.log('⚠️ Failed to parse cached artist: $e');
          return null;
        }
-      }).whereType<Artist>().toList();
+      }
-      // Load audiobooks from cache
+      // Load audiobooks from cache with source providers
-      final audiobookData = await _db.getCachedItems('audiobook');
+      final audiobookDataWithProviders = await _db.getCachedItemsWithProviders('audiobook');
-      _cachedAudiobooks = audiobookData.map((data) {
+      _cachedAudiobooks = [];
      _audiobookSourceProviders = {};
      for (final (data, providers) in audiobookDataWithProviders) {
        try {
-          return Audiobook.fromJson(data);
+          final audiobook = Audiobook.fromJson(data);
          _cachedAudiobooks.add(audiobook);
          if (providers.isNotEmpty) {
            _audiobookSourceProviders[audiobook.itemId] = providers;
          }
        } catch (e) {
          _logger.log('⚠️ Failed to parse cached audiobook: $e');
          return null;
        }
-      }).whereType<Audiobook>().toList();
+      }
-      // Load playlists from cache
+      // Load playlists from cache with source providers
-      final playlistData = await _db.getCachedItems('playlist');
+      final playlistDataWithProviders = await _db.getCachedItemsWithProviders('playlist');
-      _cachedPlaylists = playlistData.map((data) {
+      _cachedPlaylists = [];
      _playlistSourceProviders = {};
      for (final (data, providers) in playlistDataWithProviders) {
        try {
-          return Playlist.fromJson(data);
+          final playlist = Playlist.fromJson(data);
          _cachedPlaylists.add(playlist);
          if (providers.isNotEmpty) {
            _playlistSourceProviders[playlist.itemId] = providers;
          }
        } catch (e) {
          _logger.log('⚠️ Failed to parse cached playlist: $e');
          return null;
        }
-      }).whereType<Playlist>().toList();
+      }
      _logger.log('📦 Loaded ${_cachedAlbums.length} albums, ${_cachedArtists.length} artists, '
                  '${_cachedAudiobooks.length} audiobooks, ${_cachedPlaylists.length} playlists from cache');
      _logger.log('📦 Source providers: ${_albumSourceProviders.length} albums, ${_artistSourceProviders.length} artists tracked');
      notifyListeners();
    } catch (e) {
      _logger.log('❌ Failed to load from cache: $e');
@@ -119,7 +156,12 @@ class SyncService with ChangeNotifier {
  /// Sync library data from MA API in background
  /// Updates database cache and notifies listeners when complete
-  Future<void> syncFromApi(MusicAssistantAPI api, {bool force = false}) async {
+  /// [providerInstanceIds] - list of provider IDs to sync (fetches each provider separately for accurate source tracking)
  Future<void> syncFromApi(
    MusicAssistantAPI api, {
    bool force = false,
    List<String>? providerInstanceIds,
  }) async {
    if (_isSyncing) {
      _logger.log('🔄 Sync already in progress, skipping');
      return;
@@ -155,33 +197,140 @@ class SyncService with ChangeNotifier {
      final showOnlyArtistsWithAlbums = await SettingsService.getShowOnlyArtistsWithAlbums();
      _logger.log('🎨 Sync using albumArtistsOnly: $showOnlyArtistsWithAlbums');
-      // Fetch fresh data from MA API (in parallel for speed)
+      // Only clear cache for full syncs (no specific providers)
-      final results = await Future.wait([
+      // Partial syncs preserve items from disabled providers for instant toggle-on
-        api.getAlbums(limit: 1000),
+      final isPartialSync = providerInstanceIds != null && providerInstanceIds.isNotEmpty;
-        api.getArtists(limit: 1000, albumArtistsOnly: showOnlyArtistsWithAlbums),
+      if (!isPartialSync) {
-        api.getAudiobooks(limit: 1000),
+        await _db.clearCacheForType('album');
-        api.getPlaylists(limit: 1000),
+        await _db.clearCacheForType('artist');
-      ]);
+        await _db.clearCacheForType('audiobook');
        await _db.clearCacheForType('playlist');
      }
-      final albums = results[0] as List<Album>;
+      // Build NEW source tracking maps - don't modify existing until sync is complete
-      final artists = results[1] as List<Artist>;
+      // This prevents UI flicker from partial tracking during sync
-      final audiobooks = results[2] as List<Audiobook>;
+      final syncingProviders = providerInstanceIds?.toSet() ?? <String>{};
-      final playlists = results[3] as List<Playlist>;
+      final newAlbumSourceProviders = <String, List<String>>{};
      final newArtistSourceProviders = <String, List<String>>{};
      final newAudiobookSourceProviders = <String, List<String>>{};
      final newPlaylistSourceProviders = <String, List<String>>{};
-      _logger.log('📥 Fetched ${albums.length} albums, ${artists.length} artists, '
+      // For partial syncs, copy tracking from non-syncing providers
-                  '${audiobooks.length} audiobooks, ${playlists.length} playlists from MA');
+      if (isPartialSync) {
        for (final entry in _albumSourceProviders.entries) {
          final preserved = entry.value.where((p) => !syncingProviders.contains(p)).toList();
          if (preserved.isNotEmpty) newAlbumSourceProviders[entry.key] = preserved;
        }
        for (final entry in _artistSourceProviders.entries) {
          final preserved = entry.value.where((p) => !syncingProviders.contains(p)).toList();
          if (preserved.isNotEmpty) newArtistSourceProviders[entry.key] = preserved;
        }
        for (final entry in _audiobookSourceProviders.entries) {
          final preserved = entry.value.where((p) => !syncingProviders.contains(p)).toList();
          if (preserved.isNotEmpty) newAudiobookSourceProviders[entry.key] = preserved;
        }
        for (final entry in _playlistSourceProviders.entries) {
          final preserved = entry.value.where((p) => !syncingProviders.contains(p)).toList();
          if (preserved.isNotEmpty) newPlaylistSourceProviders[entry.key] = preserved;
        }
      }
-      // Clear old cache before saving fresh data (removes stale items)
+      // Collect all items (deduped by itemId, but tracking all source providers)
-      await _db.clearCacheForType('album');
+      final albumMap = <String, Album>{};
-      await _db.clearCacheForType('artist');
+      final artistMap = <String, Artist>{};
-      await _db.clearCacheForType('audiobook');
+      final audiobookMap = <String, Audiobook>{};
-      await _db.clearCacheForType('playlist');
+      final playlistMap = <String, Playlist>{};
-      // Save to database cache
+      // If specific providers are requested, sync each separately for accurate source tracking
-      await _saveAlbumsToCache(albums);
+      if (providerInstanceIds != null && providerInstanceIds.isNotEmpty) {
-      await _saveArtistsToCache(artists);
+        _logger.log('🔒 Per-provider sync for ${providerInstanceIds.length} providers');
-      await _saveAudiobooksToCache(audiobooks);
+
-      await _savePlaylistsToCache(playlists);
+        for (final providerId in providerInstanceIds) {
          _logger.log('  📡 Syncing provider: $providerId');
          // Fetch from this specific provider
          final results = await Future.wait([
            api.getAlbums(limit: 1000, providerInstanceIds: [providerId]),
            api.getArtists(limit: 1000, albumArtistsOnly: showOnlyArtistsWithAlbums, providerInstanceIds: [providerId]),
            api.getAudiobooks(limit: 1000, providerInstanceIds: [providerId]),
            api.getPlaylists(limit: 1000, providerInstanceIds: [providerId]),
          ]);
          final albums = results[0] as List<Album>;
          final artists = results[1] as List<Artist>;
          final audiobooks = results[2] as List<Audiobook>;
          final playlists = results[3] as List<Playlist>;
          _logger.log('  📥 Got ${albums.length} albums, ${artists.length} artists, ${audiobooks.length} audiobooks from $providerId');
          // Add to maps and track source provider in NEW tracking maps
          for (final album in albums) {
            albumMap[album.itemId] = album;
            newAlbumSourceProviders.putIfAbsent(album.itemId, () => []);
            if (!newAlbumSourceProviders[album.itemId]!.contains(providerId)) {
              newAlbumSourceProviders[album.itemId]!.add(providerId);
            }
          }
          for (final artist in artists) {
            artistMap[artist.itemId] = artist;
            newArtistSourceProviders.putIfAbsent(artist.itemId, () => []);
            if (!newArtistSourceProviders[artist.itemId]!.contains(providerId)) {
              newArtistSourceProviders[artist.itemId]!.add(providerId);
            }
          }
          for (final audiobook in audiobooks) {
            audiobookMap[audiobook.itemId] = audiobook;
            newAudiobookSourceProviders.putIfAbsent(audiobook.itemId, () => []);
            if (!newAudiobookSourceProviders[audiobook.itemId]!.contains(providerId)) {
              newAudiobookSourceProviders[audiobook.itemId]!.add(providerId);
            }
          }
          for (final playlist in playlists) {
            playlistMap[playlist.itemId] = playlist;
            newPlaylistSourceProviders.putIfAbsent(playlist.itemId, () => []);
            if (!newPlaylistSourceProviders[playlist.itemId]!.contains(providerId)) {
              newPlaylistSourceProviders[playlist.itemId]!.add(providerId);
            }
          }
        }
      } else {
        // No provider filter - fetch all at once (faster, but no source tracking)
        _logger.log('📡 Fetching from all providers (no source tracking)');
        final results = await Future.wait([
          api.getAlbums(limit: 1000),
          api.getArtists(limit: 1000, albumArtistsOnly: showOnlyArtistsWithAlbums),
          api.getAudiobooks(limit: 1000),
          api.getPlaylists(limit: 1000),
        ]);
        for (final album in results[0] as List<Album>) {
          albumMap[album.itemId] = album;
        }
        for (final artist in results[1] as List<Artist>) {
          artistMap[artist.itemId] = artist;
        }
        for (final audiobook in results[2] as List<Audiobook>) {
          audiobookMap[audiobook.itemId] = audiobook;
        }
        for (final playlist in results[3] as List<Playlist>) {
          playlistMap[playlist.itemId] = playlist;
        }
      }
      final albums = albumMap.values.toList();
      final artists = artistMap.values.toList();
      final audiobooks = audiobookMap.values.toList();
      final playlists = playlistMap.values.toList();
      _logger.log('📥 Total: ${albums.length} albums, ${artists.length} artists, '
                  '${audiobooks.length} audiobooks, ${playlists.length} playlists');
      // Save to database cache with source provider info (using NEW tracking maps)
      await _saveAlbumsToCache(albums, newAlbumSourceProviders);
      await _saveArtistsToCache(artists, newArtistSourceProviders);
      await _saveAudiobooksToCache(audiobooks, newAudiobookSourceProviders);
      await _savePlaylistsToCache(playlists, newPlaylistSourceProviders);
      // Update sync metadata
      await _db.updateSyncMetadata('albums', albums.length);
@@ -190,14 +339,49 @@ class SyncService with ChangeNotifier {
      await _db.updateSyncMetadata('playlists', playlists.length);
      // Update in-memory cache
-      _cachedAlbums = albums;
+      if (isPartialSync) {
-      _cachedArtists = artists;
+        // Partial sync: merge with existing cache to preserve items from disabled providers
-      _cachedAudiobooks = audiobooks;
+        final albumIds = albums.map((a) => a.itemId).toSet();
-      _cachedPlaylists = playlists;
+        final artistIds = artists.map((a) => a.itemId).toSet();
        final audiobookIds = audiobooks.map((a) => a.itemId).toSet();
        final playlistIds = playlists.map((p) => p.itemId).toSet();
        // Keep items not in current sync, add/update items from sync
        _cachedAlbums = [
          ..._cachedAlbums.where((a) => !albumIds.contains(a.itemId)),
          ...albums,
        ];
        _cachedArtists = [
          ..._cachedArtists.where((a) => !artistIds.contains(a.itemId)),
          ...artists,
        ];
        _cachedAudiobooks = [
          ..._cachedAudiobooks.where((a) => !audiobookIds.contains(a.itemId)),
          ...audiobooks,
        ];
        _cachedPlaylists = [
          ..._cachedPlaylists.where((p) => !playlistIds.contains(p.itemId)),
          ...playlists,
        ];
      } else {
        // Full sync: replace entire cache
        _cachedAlbums = albums;
        _cachedArtists = artists;
        _cachedAudiobooks = audiobooks;
        _cachedPlaylists = playlists;
      }
      // Atomically swap in the new source tracking maps
      // This ensures filtering always sees complete data, never partial
      _albumSourceProviders = newAlbumSourceProviders;
      _artistSourceProviders = newArtistSourceProviders;
      _audiobookSourceProviders = newAudiobookSourceProviders;
      _playlistSourceProviders = newPlaylistSourceProviders;
      _lastSyncTime = DateTime.now();
      _status = SyncStatus.completed;
      _logger.log('✅ Library sync complete');
      _logger.log('📊 Source tracking: ${_albumSourceProviders.length} albums, ${_artistSourceProviders.length} artists, ${_audiobookSourceProviders.length} audiobooks have provider info');
    } catch (e) {
      _logger.log('❌ Library sync failed: $e');
      _status = SyncStatus.error;
@@ -208,73 +392,90 @@ class SyncService with ChangeNotifier {
    }
  }
-  /// Save albums to database cache
+  /// Save albums to database cache with source provider tracking (batched)
-  Future<void> _saveAlbumsToCache(List<Album> albums) async {
+  Future<void> _saveAlbumsToCache(List<Album> albums, Map<String, List<String>> sourceProviders) async {
    final batchItems = <BatchCacheItem>[];
    for (final album in albums) {
-      try {
+      final providers = sourceProviders[album.itemId] ?? <String>[];
-        await _db.cacheItem(
+      batchItems.add(BatchCacheItem(
-          itemType: 'album',
+        itemType: 'album',
-          itemId: album.itemId,
+        itemId: album.itemId,
-          data: album.toJson(),
+        data: jsonEncode(album.toJson()),
-        );
+        sourceProviders: providers,
-      } catch (e) {
+      ));
-        _logger.log('⚠️ Failed to cache album ${album.name}: $e');
+    }
-      }
+    try {
      await _db.batchCacheItems(batchItems);
      _logger.log('💾 Batch saved ${albums.length} albums to cache');
    } catch (e) {
      _logger.log('⚠️ Failed to batch cache albums: $e');
    }
    _logger.log('💾 Saved ${albums.length} albums to cache');
  }
-  /// Save artists to database cache
+  /// Save artists to database cache with source provider tracking (batched)
-  Future<void> _saveArtistsToCache(List<Artist> artists) async {
+  Future<void> _saveArtistsToCache(List<Artist> artists, Map<String, List<String>> sourceProviders) async {
    final batchItems = <BatchCacheItem>[];
    for (final artist in artists) {
-      try {
+      final providers = sourceProviders[artist.itemId] ?? <String>[];
-        await _db.cacheItem(
+      batchItems.add(BatchCacheItem(
-          itemType: 'artist',
+        itemType: 'artist',
-          itemId: artist.itemId,
+        itemId: artist.itemId,
-          data: artist.toJson(),
+        data: jsonEncode(artist.toJson()),
-        );
+        sourceProviders: providers,
-      } catch (e) {
+      ));
-        _logger.log('⚠️ Failed to cache artist ${artist.name}: $e');
+    }
-      }
+    try {
      await _db.batchCacheItems(batchItems);
      _logger.log('💾 Batch saved ${artists.length} artists to cache');
    } catch (e) {
      _logger.log('⚠️ Failed to batch cache artists: $e');
    }
    _logger.log('💾 Saved ${artists.length} artists to cache');
  }
-  /// Save audiobooks to database cache
+  /// Save audiobooks to database cache with source provider tracking (batched)
-  Future<void> _saveAudiobooksToCache(List<Audiobook> audiobooks) async {
+  Future<void> _saveAudiobooksToCache(List<Audiobook> audiobooks, Map<String, List<String>> sourceProviders) async {
    final batchItems = <BatchCacheItem>[];
    for (final audiobook in audiobooks) {
-      try {
+      final providers = sourceProviders[audiobook.itemId] ?? <String>[];
-        await _db.cacheItem(
+      batchItems.add(BatchCacheItem(
-          itemType: 'audiobook',
+        itemType: 'audiobook',
-          itemId: audiobook.itemId,
+        itemId: audiobook.itemId,
-          data: audiobook.toJson(),
+        data: jsonEncode(audiobook.toJson()),
-        );
+        sourceProviders: providers,
-      } catch (e) {
+      ));
-        _logger.log('⚠️ Failed to cache audiobook ${audiobook.name}: $e');
+    }
-      }
+    try {
      await _db.batchCacheItems(batchItems);
      _logger.log('💾 Batch saved ${audiobooks.length} audiobooks to cache');
    } catch (e) {
      _logger.log('⚠️ Failed to batch cache audiobooks: $e');
    }
    _logger.log('💾 Saved ${audiobooks.length} audiobooks to cache');
  }
-  /// Save playlists to database cache
+  /// Save playlists to database cache with source provider tracking (batched)
-  Future<void> _savePlaylistsToCache(List<Playlist> playlists) async {
+  Future<void> _savePlaylistsToCache(List<Playlist> playlists, Map<String, List<String>> sourceProviders) async {
    final batchItems = <BatchCacheItem>[];
    for (final playlist in playlists) {
-      try {
+      final providers = sourceProviders[playlist.itemId] ?? <String>[];
-        await _db.cacheItem(
+      batchItems.add(BatchCacheItem(
-          itemType: 'playlist',
+        itemType: 'playlist',
-          itemId: playlist.itemId,
+        itemId: playlist.itemId,
-          data: playlist.toJson(),
+        data: jsonEncode(playlist.toJson()),
-        );
+        sourceProviders: providers,
-      } catch (e) {
+      ));
-        _logger.log('⚠️ Failed to cache playlist ${playlist.name}: $e');
+    }
-      }
+    try {
      await _db.batchCacheItems(batchItems);
      _logger.log('💾 Batch saved ${playlists.length} playlists to cache');
    } catch (e) {
      _logger.log('⚠️ Failed to batch cache playlists: $e');
    }
    _logger.log('💾 Saved ${playlists.length} playlists to cache');
  }
  /// Force a fresh sync (for pull-to-refresh)
-  Future<void> forceSync(MusicAssistantAPI api) async {
+  /// [providerInstanceIds] - optional list of provider IDs to filter by (null = all providers)
-    await syncFromApi(api, force: true);
+  Future<void> forceSync(MusicAssistantAPI api, {List<String>? providerInstanceIds}) async {
    await syncFromApi(api, force: true, providerInstanceIds: providerInstanceIds);
  }
  /// Clear all cached data
@@ -286,12 +487,82 @@ class SyncService with ChangeNotifier {
    _cachedArtists = [];
    _cachedAudiobooks = [];
    _cachedPlaylists = [];
    _albumSourceProviders = {};
    _artistSourceProviders = {};
    _audiobookSourceProviders = {};
    _playlistSourceProviders = {};
    _lastSyncTime = null;
    _status = SyncStatus.idle;
    notifyListeners();
    _logger.log('🗑️ Library cache cleared');
  }
  // ============================================
  // Client-side filtering methods
  // ============================================
  /// Filter albums by source provider (instant, no network)
  /// Empty enabledProviderIds = all providers enabled, show everything
  /// Items without source tracking are HIDDEN (strict mode) to ensure accurate filtering
  List<Album> getAlbumsFilteredByProviders(Set<String> enabledProviderIds) {
    // Empty set = all providers enabled, show everything
    if (enabledProviderIds.isEmpty) {
      return _cachedAlbums;
    }
    return _cachedAlbums.where((album) {
      final sources = _albumSourceProviders[album.itemId];
      // STRICT MODE: Hide items without tracking to ensure accurate filtering
      if (sources == null || sources.isEmpty) return false;
      return sources.any((s) => enabledProviderIds.contains(s));
    }).toList();
  }
  /// Filter artists by source provider (instant, no network)
  List<Artist> getArtistsFilteredByProviders(Set<String> enabledProviderIds) {
    if (enabledProviderIds.isEmpty) {
      return _cachedArtists;
    }
    return _cachedArtists.where((artist) {
      final sources = _artistSourceProviders[artist.itemId];
      // STRICT MODE: Hide items without tracking
      if (sources == null || sources.isEmpty) return false;
      return sources.any((s) => enabledProviderIds.contains(s));
    }).toList();
  }
  /// Filter audiobooks by source provider (instant, no network)
  List<Audiobook> getAudiobooksFilteredByProviders(Set<String> enabledProviderIds) {
    if (enabledProviderIds.isEmpty) {
      return _cachedAudiobooks;
    }
    return _cachedAudiobooks.where((audiobook) {
      final sources = _audiobookSourceProviders[audiobook.itemId];
      // STRICT MODE: Hide items without tracking
      if (sources == null || sources.isEmpty) return false;
      return sources.any((s) => enabledProviderIds.contains(s));
    }).toList();
  }
  /// Filter playlists by source provider (instant, no network)
  List<Playlist> getPlaylistsFilteredByProviders(Set<String> enabledProviderIds) {
    if (enabledProviderIds.isEmpty) {
      return _cachedPlaylists;
    }
    return _cachedPlaylists.where((playlist) {
      final sources = _playlistSourceProviders[playlist.itemId];
      // STRICT MODE: Hide items without tracking
      if (sources == null || sources.isEmpty) return false;
      return sources.any((s) => enabledProviderIds.contains(s));
    }).toList();
  }
  /// Check if we have source provider tracking data
  bool get hasSourceTracking =>
      _albumSourceProviders.isNotEmpty ||
      _artistSourceProviders.isNotEmpty ||
      _audiobookSourceProviders.isNotEmpty ||
      _playlistSourceProviders.isNotEmpty;
  /// Get albums (from cache or empty if not loaded)
  List<Album> getAlbums() => _cachedAlbums;
@@ -124,3 +124,69 @@ class Durations {
  static const Duration normal = Duration(milliseconds: 300);
  static const Duration slow = Duration(milliseconds: 500);
 }
 /// Button size tokens
 class ButtonSizes {
  ButtonSizes._();
  // Touch target sizes
  // WCAG 2.1 Level AA requires minimum 44x44, Level AAA requires 48x48
  // Material Design recommends 48x48 minimum
  // WARNING: sm and md are below WCAG minimum - use only for non-interactive elements
  /// 32x32 - NOT WCAG compliant, use only for decorative/non-interactive elements
  @Deprecated('Use xl (48x48) for touch targets to meet WCAG accessibility guidelines')
  static const double sm = 32.0;
  /// 36x36 - NOT WCAG compliant, use only for dense layouts where space is critical
  @Deprecated('Use xl (48x48) for touch targets to meet WCAG accessibility guidelines')
  static const double md = 36.0;
  /// 44x44 - Meets WCAG Level AA minimum
  static const double lg = 44.0;
  /// 48x48 - Meets WCAG Level AAA and Material Design recommended minimum
  static const double xl = 48.0;
  /// 56x56 - Comfortable touch target for primary actions
  static const double xxl = 56.0;
  /// Minimum WCAG-compliant touch target size (48x48)
  static const double minAccessible = 48.0;
  // Icon sizes within buttons
  static const double iconSm = 16.0;
  static const double iconMd = 18.0;
  static const double iconLg = 20.0;
  static const double iconXl = 24.0;
 }
 /// Semantic status colors for consistent feedback
 /// Use with Theme brightness for proper contrast
 class StatusColors {
  StatusColors._();
  // Success states
  static const Color success = Color(0xFF4CAF50);
  static const Color successLight = Color(0xFF81C784);
  static const Color successDark = Color(0xFF388E3C);
  // Error states
  static const Color error = Color(0xFFF44336);
  static const Color errorLight = Color(0xFFE57373);
  static const Color errorDark = Color(0xFFD32F2F);
  // Warning states
  static const Color warning = Color(0xFFFF9800);
  static const Color warningLight = Color(0xFFFFB74D);
  static const Color warningDark = Color(0xFFF57C00);
  // Info states
  static const Color info = Color(0xFF2196F3);
  static const Color infoLight = Color(0xFF64B5F6);
  static const Color infoDark = Color(0xFF1976D2);
  // Favorites (heart icon)
  static const Color favorite = Color(0xFFF44336);
  static const Color favoriteActive = Color(0xFFE53935);
 }
@@ -9,6 +9,7 @@ final _themeLogger = DebugLogger();
 /// Global function to update adaptive colors from an image URL
 /// This can be called from anywhere in the app (e.g., when tapping an album/artist)
 /// Sets isOnDetailScreen=true so nav bar will also use adaptive colors
 Future<void> updateAdaptiveColorsFromImage(BuildContext context, String? imageUrl) async {
  if (imageUrl == null || imageUrl.isEmpty) return;
@@ -16,7 +17,7 @@ Future<void> updateAdaptiveColorsFromImage(BuildContext context, String? imageUr
    final colorSchemes = await PaletteHelper.extractColorSchemes(CachedNetworkImageProvider(imageUrl));
    if (colorSchemes != null && context.mounted) {
      final themeProvider = context.read<ThemeProvider>();
-      themeProvider.updateAdaptiveColors(colorSchemes.$1, colorSchemes.$2);
+      themeProvider.updateAdaptiveColors(colorSchemes.$1, colorSchemes.$2, isFromDetailScreen: true);
    }
  } catch (e) {
    // Silently fail - colors will update when track plays
@@ -42,6 +43,10 @@ class ThemeProvider extends ChangeNotifier {
  ColorScheme? _adaptiveLightScheme;
  ColorScheme? _adaptiveDarkScheme;
  // Track if we're on a detail screen (vs just player-extracted colors)
  // When true, nav bar should use adaptive colors even when player is collapsed
  bool _isOnDetailScreen = false;
  ThemeProvider() {
    _loadSettings();
  }
@@ -55,12 +60,14 @@ class ThemeProvider extends ChangeNotifier {
  AdaptiveColors? get adaptiveColors => _adaptiveColors;
  ColorScheme? get adaptiveLightScheme => _adaptiveLightScheme;
  ColorScheme? get adaptiveDarkScheme => _adaptiveDarkScheme;
  bool get isOnDetailScreen => _isOnDetailScreen;
  /// Get the current adaptive primary color (for bottom nav highlight, etc.)
  Color get adaptivePrimaryColor => _adaptiveColors?.primary ?? _customColor;
  /// Get the current adaptive surface color (for bottom nav background, etc.)
  /// Returns a subtle tinted surface based on the adaptive colors
  /// NOTE: Prefer getAdaptiveSurfaceColorFor() which respects light/dark mode
  Color? get adaptiveSurfaceColor {
    if (_adaptiveColors == null) return null;
    // Use the miniPlayer color but darkened for a subtle tinted background
@@ -68,6 +75,20 @@ class ThemeProvider extends ChangeNotifier {
    return hsl.withLightness((hsl.lightness * 0.4).clamp(0.08, 0.15)).toColor();
  }
  /// Get adaptive surface color for the given brightness (light/dark mode aware)
  /// Returns the same color as the expanded player background (scheme.surface)
  Color? getAdaptiveSurfaceColorFor(Brightness brightness) {
    // Pick scheme based on current mode
    final scheme = brightness == Brightness.dark
        ? _adaptiveDarkScheme
        : _adaptiveLightScheme;
    if (scheme == null) return null;
    // Use surface - same as expanded player background (line 1234 in expandable_player.dart)
    return scheme.surface;
  }
  Future<void> _loadSettings() async {
    final themeModeString = await SettingsService.getThemeMode();
    _themeMode = _parseThemeMode(themeModeString);
@@ -147,10 +168,18 @@ class ThemeProvider extends ChangeNotifier {
  }
  /// Update adaptive colors from album art
-  void updateAdaptiveColors(ColorScheme? lightScheme, ColorScheme? darkScheme) {
+  /// [isFromDetailScreen] - if true, this is from navigating to a detail screen
  /// and the nav bar should use adaptive colors even when player is collapsed
  void updateAdaptiveColors(ColorScheme? lightScheme, ColorScheme? darkScheme, {bool isFromDetailScreen = false}) {
    _adaptiveLightScheme = lightScheme;
    _adaptiveDarkScheme = darkScheme;
    // Only set detail screen flag if explicitly from a detail screen navigation
    // Player-extracted colors should NOT set this flag
    if (isFromDetailScreen) {
      _isOnDetailScreen = true;
    }
    // Extract AdaptiveColors from the schemes
    if (darkScheme != null) {
      _adaptiveColors = AdaptiveColors(
@@ -166,11 +195,12 @@ class ThemeProvider extends ChangeNotifier {
    notifyListeners();
  }
-  /// Clear adaptive colors (when no track is playing)
+  /// Clear adaptive colors (when navigating back from detail screen or no track playing)
  void clearAdaptiveColors() {
    _adaptiveColors = null;
    _adaptiveLightScheme = null;
    _adaptiveDarkScheme = null;
    _isOnDetailScreen = false;
    notifyListeners();
  }
 }
@@ -0,0 +1,46 @@
 /// Extension methods for formatting Duration values.
 ///
 /// Provides consistent duration formatting across the codebase,
 /// replacing duplicate _formatDuration() implementations.
 extension DurationFormatter on Duration {
  /// Format duration as "H:MM:SS" or "M:SS" depending on length.
  ///
  /// Examples:
  /// - 45 seconds -> "0:45"
  /// - 3 minutes, 45 seconds -> "3:45"
  /// - 1 hour, 3 minutes, 45 seconds -> "1:03:45"
  String toFormattedString() {
    final hours = inHours;
    final minutes = inMinutes % 60;
    final seconds = inSeconds % 60;
    if (hours > 0) {
      return '$hours:${minutes.toString().padLeft(2, '0')}:${seconds.toString().padLeft(2, '0')}';
    }
    return '$minutes:${seconds.toString().padLeft(2, '0')}';
  }
  /// Format duration as "M:SS" (no hours, minutes not padded).
  ///
  /// Use this for shorter content like songs where hours are unlikely.
  String toMinutesSeconds() {
    final totalSeconds = inSeconds;
    final minutes = totalSeconds ~/ 60;
    final seconds = totalSeconds % 60;
    return '$minutes:${seconds.toString().padLeft(2, '0')}';
  }
 }
 /// Format an integer number of seconds as "H:MM:SS" or "M:SS".
 ///
 /// This is a standalone function for cases where you have raw seconds
 /// rather than a Duration object.
 String formatDurationSeconds(int seconds) {
  return Duration(seconds: seconds).toFormattedString();
 }
 /// Format a nullable Duration, returning empty string if null.
 String formatDurationOrEmpty(Duration? duration) {
  if (duration == null) return '';
  return duration.toMinutesSeconds();
 }
@@ -0,0 +1,139 @@
 import 'dart:collection';
 /// A simple Least Recently Used (LRU) cache implementation.
 ///
 /// When the cache reaches its maximum size, the least recently used entries
 /// are automatically evicted to make room for new entries.
 ///
 /// Usage:
 /// ```dart
 /// final cache = LruCache<String, String>(maxSize: 100);
 /// cache.put('key', 'value');
 /// final value = cache.get('key');
 /// ```
 class LruCache<K, V> {
  /// Maximum number of entries to store
  final int maxSize;
  /// Internal storage using LinkedHashMap for O(1) LRU operations
  final LinkedHashMap<K, V> _cache = LinkedHashMap<K, V>();
  /// Creates an LRU cache with the specified maximum size.
  ///
  /// [maxSize] must be greater than 0.
  LruCache({required this.maxSize}) : assert(maxSize > 0);
  /// Returns the number of entries currently in the cache.
  int get length => _cache.length;
  /// Returns true if the cache is empty.
  bool get isEmpty => _cache.isEmpty;
  /// Returns true if the cache is not empty.
  bool get isNotEmpty => _cache.isNotEmpty;
  /// Returns true if the cache contains an entry for [key].
  bool containsKey(K key) => _cache.containsKey(key);
  /// Returns the value for [key], or null if not found.
  ///
  /// This operation marks the entry as recently used.
  V? get(K key) {
    if (!_cache.containsKey(key)) {
      return null;
    }
    // Move to end (most recently used) by removing and re-adding
    final value = _cache.remove(key);
    _cache[key] = value as V;
    return value;
  }
  /// Returns the value for [key] without marking it as recently used.
  ///
  /// Use this when you need to check a value without affecting LRU order.
  V? peek(K key) => _cache[key];
  /// Stores [value] for [key] in the cache.
  ///
  /// If [key] already exists, the value is updated and marked as recently used.
  /// If the cache is full, the least recently used entry is evicted.
  void put(K key, V value) {
    // If key exists, remove it first (will be re-added at end)
    if (_cache.containsKey(key)) {
      _cache.remove(key);
    } else if (_cache.length >= maxSize) {
      // Cache is full, remove least recently used (first entry)
      _cache.remove(_cache.keys.first);
    }
    _cache[key] = value;
  }
  /// Operator access for getting values (same as [get]).
  V? operator [](K key) => get(key);
  /// Operator access for setting values (same as [put]).
  void operator []=(K key, V value) => put(key, value);
  /// Removes the entry for [key] if it exists.
  ///
  /// Returns the removed value, or null if [key] was not in the cache.
  V? remove(K key) => _cache.remove(key);
  /// Removes all entries from the cache.
  void clear() => _cache.clear();
  /// Returns all keys currently in the cache.
  Iterable<K> get keys => _cache.keys;
  /// Returns all values currently in the cache.
  Iterable<V> get values => _cache.values;
  /// Returns all entries currently in the cache.
  Iterable<MapEntry<K, V>> get entries => _cache.entries;
 }
 /// An LRU cache that can store null values and distinguish them from missing entries.
 ///
 /// Regular LruCache returns null for both missing keys and keys with null values.
 /// This class uses a wrapper to distinguish between the two cases.
 class NullableLruCache<K, V> {
  final LruCache<K, _CacheEntry<V>> _cache;
  /// Creates a nullable LRU cache with the specified maximum size.
  NullableLruCache({required int maxSize}) : _cache = LruCache(maxSize: maxSize);
  /// Returns the number of entries currently in the cache.
  int get length => _cache.length;
  /// Returns true if the cache contains an entry for [key].
  bool containsKey(K key) => _cache.containsKey(key);
  /// Returns the value for [key], or null if not found.
  ///
  /// Note: This will also return null if the cached value is null.
  /// Use [containsKey] to distinguish between missing and null values.
  V? get(K key) => _cache.get(key)?.value;
  /// Stores [value] for [key] in the cache.
  ///
  /// The value can be null.
  void put(K key, V? value) => _cache.put(key, _CacheEntry(value));
  /// Operator access for getting values.
  V? operator [](K key) => get(key);
  /// Operator access for setting values.
  void operator []=(K key, V? value) => put(key, value);
  /// Removes the entry for [key] if it exists.
  V? remove(K key) => _cache.remove(key)?.value;
  /// Removes all entries from the cache.
  void clear() => _cache.clear();
 }
 /// Wrapper to store nullable values in the cache
 class _CacheEntry<V> {
  final V? value;
  _CacheEntry(this.value);
 }
@@ -0,0 +1,137 @@
 import 'dart:math';
 /// Fuzzy string matching using Jaro-Winkler similarity.
 ///
 /// Jaro-Winkler is optimized for short strings like artist/song names
 /// and gives extra weight to matching prefixes (common typos occur mid-word).
 class FuzzyMatcher {
  /// Calculate Jaro-Winkler similarity between two strings.
  ///
  /// Returns a value between 0.0 (no similarity) and 1.0 (exact match).
  ///
  /// Jaro-Winkler gives bonus weight to strings that match from the beginning,
  /// which is useful for handling typos like "Beetles" vs "Beatles".
  double jaroWinklerSimilarity(String s1, String s2) {
    if (s1 == s2) return 1.0;
    if (s1.isEmpty || s2.isEmpty) return 0.0;
    final jaro = _jaroSimilarity(s1, s2);
    // Winkler modification: boost score for common prefix
    int prefixLength = 0;
    const maxPrefix = 4; // Standard Winkler prefix length
    final minLen = min(s1.length, s2.length);
    final prefixLimit = min(maxPrefix, minLen);
    for (int i = 0; i < prefixLimit; i++) {
      if (s1[i] == s2[i]) {
        prefixLength++;
      } else {
        break;
      }
    }
    const scalingFactor = 0.1; // Standard Winkler scaling factor
    return jaro + (prefixLength * scalingFactor * (1 - jaro));
  }
  /// Calculate base Jaro similarity.
  double _jaroSimilarity(String s1, String s2) {
    final s1Len = s1.length;
    final s2Len = s2.length;
    // Match window: characters within this distance can match
    final matchWindow = (max(s1Len, s2Len) / 2 - 1).floor();
    if (matchWindow < 0) return 0.0;
    final s1Matches = List.filled(s1Len, false);
    final s2Matches = List.filled(s2Len, false);
    int matches = 0;
    int transpositions = 0;
    // Find matching characters
    for (int i = 0; i < s1Len; i++) {
      final start = max(0, i - matchWindow);
      final end = min(s2Len, i + matchWindow + 1);
      for (int j = start; j < end; j++) {
        if (s2Matches[j] || s1[i] != s2[j]) continue;
        s1Matches[i] = true;
        s2Matches[j] = true;
        matches++;
        break;
      }
    }
    if (matches == 0) return 0.0;
    // Count transpositions
    int k = 0;
    for (int i = 0; i < s1Len; i++) {
      if (!s1Matches[i]) continue;
      while (!s2Matches[k]) {
        k++;
      }
      if (s1[i] != s2[k]) transpositions++;
      k++;
    }
    // Jaro similarity formula
    return (matches / s1Len +
            matches / s2Len +
            (matches - transpositions / 2) / matches) /
        3;
  }
  /// Find the best match score between query tokens and text tokens.
  ///
  /// Useful for matching individual words when full string matching fails.
  /// Returns the highest similarity score found between any token pair.
  double bestTokenMatch(List<String> queryTokens, List<String> textTokens) {
    if (queryTokens.isEmpty || textTokens.isEmpty) return 0.0;
    double bestScore = 0.0;
    for (final queryToken in queryTokens) {
      for (final textToken in textTokens) {
        final score = jaroWinklerSimilarity(queryToken, textToken);
        if (score > bestScore) {
          bestScore = score;
          // Early exit if we find a perfect match
          if (score == 1.0) return 1.0;
        }
      }
    }
    return bestScore;
  }
  /// Check if two strings are a fuzzy match within a threshold.
  bool isFuzzyMatch(String s1, String s2, {double threshold = 0.85}) {
    return jaroWinklerSimilarity(s1, s2) >= threshold;
  }
  /// Calculate average token match score.
  ///
  /// For each query token, finds the best matching text token,
  /// then averages all best matches. Useful for multi-word queries.
  double averageTokenMatch(List<String> queryTokens, List<String> textTokens) {
    if (queryTokens.isEmpty || textTokens.isEmpty) return 0.0;
    double totalScore = 0.0;
    for (final queryToken in queryTokens) {
      double bestForToken = 0.0;
      for (final textToken in textTokens) {
        final score = jaroWinklerSimilarity(queryToken, textToken);
        if (score > bestForToken) {
          bestForToken = score;
        }
      }
      totalScore += bestForToken;
    }
    return totalScore / queryTokens.length;
  }
 }
@@ -0,0 +1,96 @@
 /// N-gram based string matching for partial matches.
 ///
 /// Uses character bigrams (2-grams) to find partial string matches
 /// when exact and fuzzy matching fail.
 class NgramMatcher {
  /// Generate character bigrams from text.
  ///
  /// Example: "hello" -> ["he", "el", "ll", "lo"]
  ///
  /// For strings shorter than 2 characters, returns the string itself.
  List<String> generateBigrams(String text) {
    if (text.length < 2) return text.isNotEmpty ? [text] : [];
    final bigrams = <String>[];
    for (int i = 0; i < text.length - 1; i++) {
      bigrams.add(text.substring(i, i + 2));
    }
    return bigrams;
  }
  /// Generate character trigrams from text.
  ///
  /// Example: "hello" -> ["hel", "ell", "llo"]
  List<String> generateTrigrams(String text) {
    if (text.length < 3) return text.isNotEmpty ? [text] : [];
    final trigrams = <String>[];
    for (int i = 0; i < text.length - 2; i++) {
      trigrams.add(text.substring(i, i + 3));
    }
    return trigrams;
  }
  /// Calculate bigram similarity using Dice coefficient.
  ///
  /// Dice coefficient: 2 * |intersection| / (|set1| + |set2|)
  /// Returns a value between 0.0 and 1.0.
  double bigramSimilarity(String s1, String s2) {
    final lower1 = s1.toLowerCase();
    final lower2 = s2.toLowerCase();
    final bigrams1 = generateBigrams(lower1);
    final bigrams2 = generateBigrams(lower2);
    if (bigrams1.isEmpty || bigrams2.isEmpty) return 0.0;
    final set1 = bigrams1.toSet();
    final set2 = bigrams2.toSet();
    final intersection = set1.intersection(set2).length;
    // Dice coefficient
    return (2 * intersection) / (set1.length + set2.length);
  }
  /// Calculate Jaccard similarity between bigram sets.
  ///
  /// Jaccard: |intersection| / |union|
  /// More conservative than Dice coefficient.
  double jaccardSimilarity(String s1, String s2) {
    final lower1 = s1.toLowerCase();
    final lower2 = s2.toLowerCase();
    final bigrams1 = generateBigrams(lower1).toSet();
    final bigrams2 = generateBigrams(lower2).toSet();
    if (bigrams1.isEmpty || bigrams2.isEmpty) return 0.0;
    final intersection = bigrams1.intersection(bigrams2).length;
    final union = bigrams1.union(bigrams2).length;
    return intersection / union;
  }
  /// Check if query partially matches text via bigrams.
  ///
  /// Uses Dice coefficient with configurable threshold.
  bool hasPartialMatch(String query, String text, {double threshold = 0.5}) {
    return bigramSimilarity(query, text) >= threshold;
  }
  /// Calculate containment coefficient.
  ///
  /// Measures how many of the query's bigrams are in the text.
  /// Useful when query is expected to be shorter than text.
  /// Returns |intersection| / |query bigrams|
  double containmentScore(String query, String text) {
    final queryBigrams = generateBigrams(query.toLowerCase()).toSet();
    final textBigrams = generateBigrams(text.toLowerCase()).toSet();
    if (queryBigrams.isEmpty) return 0.0;
    final intersection = queryBigrams.intersection(textBigrams).length;
    return intersection / queryBigrams.length;
  }
 }
@@ -0,0 +1,86 @@
 /// Configuration for search scoring weights and thresholds.
 ///
 /// All scores are designed to work with the existing sorting system
 /// where higher scores indicate better matches.
 class ScoringConfig {
  // Base scores for match types (primary name matching)
  final double exactMatch;
  final double exactMatchNoStopwords;
  final double startsWithMatch;
  final double startsWithNoStopwords;
  final double wordBoundaryMatch;
  final double wordBoundaryNoStopwords;
  final double reverseContainsMatch;
  final double reverseContainsNoStopwords;
  final double containsMatch;
  final double containsNoStopwords;
  final double fuzzyMatchHigh;
  final double fuzzyMatchMedium;
  final double ngramMatch;
  final double baseline;
  // Bonuses (additive)
  final double libraryBonus;
  final double favoriteBonus;
  final double artistFieldExactBonus;
  final double artistFieldPartialBonus;
  final double albumFieldBonus;
  final double authorFieldExactBonus;
  final double authorFieldPartialBonus;
  final double narratorFieldBonus;
  final double creatorFieldExactBonus;
  final double creatorFieldPartialBonus;
  final double descriptionBonus;
  // Thresholds
  final double fuzzyHighThreshold;
  final double fuzzyMediumThreshold;
  final double ngramThreshold;
  // Minimum lengths for matching
  final int minReverseMatchLength;
  final int minTokenLength;
  const ScoringConfig({
    // Primary match scores
    this.exactMatch = 100,
    this.exactMatchNoStopwords = 95,
    this.startsWithMatch = 85,
    this.startsWithNoStopwords = 80,
    this.wordBoundaryMatch = 70,
    this.wordBoundaryNoStopwords = 65,
    this.reverseContainsMatch = 60,
    this.reverseContainsNoStopwords = 55,
    this.containsMatch = 50,
    this.containsNoStopwords = 45,
    this.fuzzyMatchHigh = 40,
    this.fuzzyMatchMedium = 35,
    this.ngramMatch = 25,
    this.baseline = 20,
    // Bonuses
    this.libraryBonus = 10,
    this.favoriteBonus = 5,
    this.artistFieldExactBonus = 15,
    this.artistFieldPartialBonus = 8,
    this.albumFieldBonus = 5,
    this.authorFieldExactBonus = 15,
    this.authorFieldPartialBonus = 8,
    this.narratorFieldBonus = 5,
    this.creatorFieldExactBonus = 15,
    this.creatorFieldPartialBonus = 8,
    this.descriptionBonus = 5,
    // Thresholds
    this.fuzzyHighThreshold = 0.90,
    this.fuzzyMediumThreshold = 0.85,
    this.ngramThreshold = 0.5,
    // Minimum lengths
    this.minReverseMatchLength = 3,
    this.minTokenLength = 3,
  });
  /// Default configuration
  static const ScoringConfig defaults = ScoringConfig();
 }
@@ -0,0 +1,333 @@
 /// Search scoring system for ranking search results.
 ///
 /// Provides advanced text matching including:
 /// - Stopword removal ("the Ramones" finds "Ramones")
 /// - Fuzzy matching (typo tolerance)
 /// - N-gram matching (partial matches)
 /// - Reverse matching (query contains result)
 library;
 export 'scoring_config.dart';
 export 'text_normalizer.dart';
 export 'fuzzy_matcher.dart';
 export 'ngram_matcher.dart';
 import 'dart:math';
 import '../../models/media_item.dart';
 import 'scoring_config.dart';
 import 'text_normalizer.dart';
 import 'fuzzy_matcher.dart';
 import 'ngram_matcher.dart';
 /// Main search scorer that combines all matching strategies.
 ///
 /// Usage:
 /// ```dart
 /// final scorer = SearchScorer();
 /// final score = scorer.scoreItem(mediaItem, query);
 /// ```
 class SearchScorer {
  final TextNormalizer _normalizer;
  final FuzzyMatcher _fuzzyMatcher;
  final NgramMatcher _ngramMatcher;
  final ScoringConfig _config;
  // Cache for normalized query (reused across items in same search)
  String? _cachedQueryString;
  NormalizedQuery? _cachedQuery;
  SearchScorer({ScoringConfig? config})
      : _normalizer = TextNormalizer(),
        _fuzzyMatcher = FuzzyMatcher(),
        _ngramMatcher = NgramMatcher(),
        _config = config ?? ScoringConfig.defaults;
  /// Access to the normalizer for external use
  TextNormalizer get normalizer => _normalizer;
  /// Clear the query cache (call when starting a new search)
  void clearCache() {
    _cachedQueryString = null;
    _cachedQuery = null;
  }
  /// Score a media item against a search query.
  ///
  /// Returns a score where higher values indicate better matches.
  /// Score components:
  /// - Primary name matching (0-100)
  /// - Secondary field bonuses (0-20)
  /// - Library/favorite bonuses (0-15)
  double scoreItem(MediaItem item, String query) {
    // Use cached normalized query if available
    if (_cachedQueryString != query) {
      _cachedQueryString = query;
      _cachedQuery = _normalizer.normalizeQuery(query);
    }
    final nq = _cachedQuery!;
    if (nq.isEmpty) return 0;
    final nameLower = item.name.toLowerCase();
    final nameNoStopwords = _normalizer.normalizeTextNoStopwords(item.name);
    // Calculate primary score based on name matching
    double score = _calculatePrimaryScore(nameLower, nameNoStopwords, nq);
    // Add secondary field bonuses based on media type
    score += _calculateSecondaryScore(item, nq);
    // Add library/favorite bonuses
    score += _calculateBonuses(item);
    return score;
  }
  /// Calculate primary score based on name matching.
  double _calculatePrimaryScore(
    String nameLower,
    String nameNoStopwords,
    NormalizedQuery nq,
  ) {
    // Tier 1: Exact match (highest priority)
    if (nameLower == nq.normalized) {
      return _config.exactMatch;
    }
    if (nameNoStopwords == nq.withoutStopwords) {
      return _config.exactMatchNoStopwords;
    }
    // Tier 2: Starts with
    if (nameLower.startsWith(nq.normalized)) {
      return _config.startsWithMatch;
    }
    if (nameNoStopwords.startsWith(nq.withoutStopwords)) {
      return _config.startsWithNoStopwords;
    }
    // Tier 3: Word boundary match
    if (_matchesWordBoundary(nameLower, nq.normalized)) {
      return _config.wordBoundaryMatch;
    }
    if (_matchesWordBoundary(nameNoStopwords, nq.withoutStopwords)) {
      return _config.wordBoundaryNoStopwords;
    }
    // Tier 4: Reverse contains (result name IN query)
    // This solves "the ramones" finding "Ramones"
    if (_reverseContains(nq.normalized, nameLower)) {
      return _config.reverseContainsMatch;
    }
    if (_reverseContains(nq.withoutStopwords, nameNoStopwords)) {
      return _config.reverseContainsNoStopwords;
    }
    // Tier 5: Contains anywhere
    if (nameLower.contains(nq.normalized)) {
      return _config.containsMatch;
    }
    if (nameNoStopwords.contains(nq.withoutStopwords)) {
      return _config.containsNoStopwords;
    }
    // Tier 6: Fuzzy matching (typo tolerance)
    final fuzzyScore = _fuzzyMatcher.jaroWinklerSimilarity(
      nq.withoutStopwords,
      nameNoStopwords,
    );
    if (fuzzyScore >= _config.fuzzyHighThreshold) {
      // Scale score based on similarity (0.90-1.0 -> 40-45)
      return _config.fuzzyMatchHigh +
          ((fuzzyScore - _config.fuzzyHighThreshold) * 50);
    }
    if (fuzzyScore >= _config.fuzzyMediumThreshold) {
      return _config.fuzzyMatchMedium;
    }
    // Tier 7: Token-level fuzzy (individual words)
    final tokenFuzzy = _fuzzyMatcher.bestTokenMatch(
      nq.tokensNoStop,
      _normalizer.tokenize(nameNoStopwords),
    );
    if (tokenFuzzy >= _config.fuzzyHighThreshold) {
      return _config.fuzzyMatchMedium;
    }
    // Tier 8: N-gram partial matching
    final ngramScore = _ngramMatcher.bigramSimilarity(
      nq.withoutStopwords,
      nameNoStopwords,
    );
    if (ngramScore >= _config.ngramThreshold) {
      // Scale: 0.5-1.0 -> 25-35
      return _config.ngramMatch + (ngramScore * 10);
    }
    // Baseline: Music Assistant API returned it, so some relevance
    return _config.baseline;
  }
  /// Check if query matches at word boundary in text.
  bool _matchesWordBoundary(String text, String query) {
    if (query.contains(' ')) {
      // Multi-word query: check if at start or after space
      if (text.startsWith(query)) return true;
      if (text.contains(' $query')) return true;
      return false;
    }
    // Single-word query: check if any word starts with query
    final words = text.split(RegExp(r'\s+'));
    for (final word in words) {
      if (word.startsWith(query)) return true;
    }
    return false;
  }
  /// Check if text is contained within query (reverse matching).
  ///
  /// Solves: "the ramones" query finding "Ramones" artist
  bool _reverseContains(String query, String text) {
    if (text.length < _config.minReverseMatchLength) return false;
    // Direct containment
    if (query.contains(text)) return true;
    // Token-level: any query token equals text
    final queryTokens = query.split(RegExp(r'\s+'));
    for (final token in queryTokens) {
      if (token.length >= _config.minReverseMatchLength && text == token) {
        return true;
      }
    }
    return false;
  }
  /// Calculate secondary field bonuses based on media type.
  double _calculateSecondaryScore(MediaItem item, NormalizedQuery nq) {
    double bonus = 0;
    if (item is Album) {
      bonus += _scoreArtistField(item.artistsString, nq);
    } else if (item is Track) {
      bonus += _scoreArtistField(item.artistsString, nq);
      // Also check album name
      if (item.album?.name != null) {
        final albumLower = item.album!.name.toLowerCase();
        if (albumLower.contains(nq.withoutStopwords)) {
          bonus += _config.albumFieldBonus;
        }
      }
    } else if (item is Audiobook) {
      // Check authors
      final authorLower = item.authorsString.toLowerCase();
      if (authorLower == nq.withoutStopwords) {
        bonus += _config.authorFieldExactBonus;
      } else if (authorLower.contains(nq.withoutStopwords)) {
        bonus += _config.authorFieldPartialBonus;
      }
      // Check narrators
      final narratorLower = item.narratorsString.toLowerCase();
      if (narratorLower.contains(nq.withoutStopwords)) {
        bonus += _config.narratorFieldBonus;
      }
    } else if (item.mediaType == MediaType.podcast || item.mediaType == MediaType.podcastEpisode) {
      bonus += _scorePodcastFields(item, nq);
    }
    return bonus;
  }
  /// Score artist field for albums and tracks.
  double _scoreArtistField(String artistsString, NormalizedQuery nq) {
    final artistLower = artistsString.toLowerCase();
    if (artistLower == nq.withoutStopwords) {
      return _config.artistFieldExactBonus;
    }
    if (artistLower.contains(nq.withoutStopwords)) {
      return _config.artistFieldPartialBonus;
    }
    return 0;
  }
  /// Score podcast-specific fields (creator, description).
  double _scorePodcastFields(MediaItem item, NormalizedQuery nq) {
    double bonus = 0;
    final metadata = item.metadata;
    if (metadata != null) {
      // Check creator fields
      final creatorFields = [
        metadata['author'] as String?,
        metadata['publisher'] as String?,
        metadata['owner'] as String?,
        metadata['creator'] as String?,
      ].where((s) => s != null && s.isNotEmpty).map((s) => s!.toLowerCase());
      bool foundExact = false;
      bool foundContains = false;
      for (final field in creatorFields) {
        if (field == nq.withoutStopwords) {
          foundExact = true;
          break;
        } else if (field.contains(nq.withoutStopwords)) {
          foundContains = true;
        }
      }
      if (foundExact) {
        bonus += _config.creatorFieldExactBonus;
      } else if (foundContains) {
        bonus += _config.creatorFieldPartialBonus;
      }
      // Check description
      final description =
          (metadata['description'] as String? ?? '').toLowerCase();
      if (description.contains(nq.withoutStopwords)) {
        bonus += _config.descriptionBonus;
      }
    }
    // Fallback: podcast name prominence check
    if (bonus == 0) {
      final nameLower = item.name.toLowerCase();
      if (nameLower.contains(nq.withoutStopwords)) {
        if (nq.withoutStopwords.contains(' ')) {
          // Multi-word query prominence
          final prominence = nq.withoutStopwords.length / nameLower.length;
          if (prominence >= 0.5) {
            bonus += _config.creatorFieldExactBonus;
          } else if (prominence >= 0.3) {
            bonus += _config.creatorFieldPartialBonus + 4;
          } else {
            bonus += _config.creatorFieldPartialBonus;
          }
        } else {
          bonus += _config.descriptionBonus;
        }
      }
    }
    return bonus;
  }
  /// Calculate library and favorite bonuses.
  double _calculateBonuses(MediaItem item) {
    double bonus = 0;
    // Library bonus (Album has inLibrary property)
    if (item is Album && item.inLibrary) {
      bonus += _config.libraryBonus;
    }
    // Favorite bonus
    if (item.favorite == true) {
      bonus += _config.favoriteBonus;
    }
    return bonus;
  }
 }
@@ -0,0 +1,114 @@
 /// Text normalization utilities for search scoring.
 ///
 /// Handles query normalization, stopword removal, and tokenization.
 /// Represents a normalized search query with various forms for matching.
 class NormalizedQuery {
  /// Original query as entered by user
  final String original;
  /// Lowercased and trimmed query
  final String normalized;
  /// Query with stopwords removed
  final String withoutStopwords;
  /// Individual tokens from normalized query
  final List<String> tokens;
  /// Tokens with stopwords removed
  final List<String> tokensNoStop;
  const NormalizedQuery({
    required this.original,
    required this.normalized,
    required this.withoutStopwords,
    required this.tokens,
    required this.tokensNoStop,
  });
  /// Whether the query is empty after normalization
  bool get isEmpty => normalized.isEmpty;
  /// Whether stopword removal changed the query
  bool get hasStopwordsRemoved => normalized != withoutStopwords;
 }
 /// Normalizes text and queries for search matching.
 class TextNormalizer {
  /// Common English stopwords relevant to music/media searches.
  ///
  /// Intentionally minimal to avoid over-filtering:
  /// - Articles that commonly prefix artist/album names
  /// - Common prepositions that add noise
  static const Set<String> _stopwords = {
    // Articles
    'the',
    'a',
    'an',
    // Common prepositions in music/media context
    'of',
    'and',
    'in',
    'on',
    'at',
    'to',
    'for',
    'with',
    'by',
    // Common noise words
    'is',
    'are',
    'was',
    'be',
  };
  /// Normalize a search query into multiple forms for matching.
  ///
  /// Returns a [NormalizedQuery] containing:
  /// - Original query
  /// - Lowercased/trimmed version
  /// - Version with stopwords removed
  /// - Tokenized versions
  NormalizedQuery normalizeQuery(String query) {
    final normalized = query.toLowerCase().trim();
    final tokens = tokenize(normalized);
    final tokensNoStop = tokens.where((t) => !_stopwords.contains(t)).toList();
    // If all tokens were stopwords, preserve original tokens
    // e.g., "The The" (band name) shouldn't become empty
    final effectiveTokensNoStop =
        tokensNoStop.isEmpty ? tokens : tokensNoStop;
    final withoutStopwords = effectiveTokensNoStop.join(' ');
    return NormalizedQuery(
      original: query,
      normalized: normalized,
      withoutStopwords: withoutStopwords,
      tokens: tokens,
      tokensNoStop: effectiveTokensNoStop,
    );
  }
  /// Normalize text for comparison (lowercase, trim).
  String normalizeText(String text) {
    return text.toLowerCase().trim();
  }
  /// Normalize text with stopwords removed.
  String normalizeTextNoStopwords(String text) {
    final tokens = tokenize(text.toLowerCase().trim());
    final filtered = tokens.where((t) => !_stopwords.contains(t)).toList();
    return filtered.isEmpty ? text.toLowerCase().trim() : filtered.join(' ');
  }
  /// Split text into tokens on whitespace.
  List<String> tokenize(String text) {
    return text.split(RegExp(r'\s+')).where((t) => t.isNotEmpty).toList();
  }
  /// Check if a word is a stopword.
  bool isStopword(String word) {
    return _stopwords.contains(word.toLowerCase());
  }
 }
@@ -6,6 +6,7 @@ import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
 import '../screens/album_details_screen.dart';
 import '../constants/hero_tags.dart';
 import '../constants/timings.dart';
 import '../theme/theme_provider.dart';
 import '../utils/page_transitions.dart';
 import '../services/metadata_service.dart';
@@ -36,6 +37,7 @@ class _AlbumCardState extends State<AlbumCard> {
  bool _maImageFailed = false;
  String? _cachedMaImageUrl;
  Timer? _fallbackTimer;
  bool _isNavigating = false;
  /// Delay before fetching fallback images to avoid requests during fast scroll
  static const _fallbackDelay = Duration(milliseconds: 200);
@@ -117,6 +119,10 @@ class _AlbumCardState extends State<AlbumCard> {
    return RepaintBoundary(
      child: GestureDetector(
        onTap: widget.onTap ?? () {
          // Prevent double-tap navigation
          if (_isNavigating) return;
          _isNavigating = true;
          // Update adaptive colors immediately on tap
          updateAdaptiveColorsFromImage(context, imageUrl);
          Navigator.push(
@@ -128,7 +134,12 @@ class _AlbumCardState extends State<AlbumCard> {
                initialImageUrl: imageUrl,
              ),
            ),
-          );
+          ).then((_) {
            // Reset after navigation debounce delay
            Future.delayed(Timings.navigationDebounce, () {
              if (mounted) _isNavigating = false;
            });
          });
        },
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
@@ -38,6 +38,12 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
  @override
  void initState() {
    super.initState();
    // Get cached data synchronously BEFORE first build (no spinner flash)
    final cached = widget.getCachedAlbums?.call();
    if (cached != null && cached.isNotEmpty) {
      _albums = cached;
      _isLoading = false;
    }
    _loadAlbums();
  }
@@ -45,18 +51,7 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
    if (_hasLoaded) return;
    _hasLoaded = true;
-    // 1. Try to get cached data synchronously for instant display
+    // Load fresh data (always update - fresh data may have images that cached data lacks)
    final cachedAlbums = widget.getCachedAlbums?.call();
    if (cachedAlbums != null && cachedAlbums.isNotEmpty) {
      if (mounted) {
        setState(() {
          _albums = cachedAlbums;
          _isLoading = false;
        });
      }
    }
    // 2. Load fresh data (always update - fresh data may have images that cached data lacks)
    try {
      final freshAlbums = await widget.loadAlbums();
      if (mounted && freshAlbums.isNotEmpty) {
@@ -6,6 +6,7 @@ import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
 import '../screens/artist_details_screen.dart';
 import '../constants/hero_tags.dart';
 import '../constants/timings.dart';
 import '../theme/theme_provider.dart';
 import '../utils/page_transitions.dart';
 import '../services/metadata_service.dart';
@@ -38,6 +39,7 @@ class _ArtistCardState extends State<ArtistCard> {
  bool _maImageFailed = false;
  String? _cachedMaImageUrl;
  Timer? _fallbackTimer;
  bool _isNavigating = false;
  /// Delay before fetching fallback images to avoid requests during fast scroll
  static const _fallbackDelay = Duration(milliseconds: 200);
@@ -110,6 +112,10 @@ class _ArtistCardState extends State<ArtistCard> {
    return RepaintBoundary(
      child: GestureDetector(
        onTap: widget.onTap ?? () {
          // Prevent double-tap navigation
          if (_isNavigating) return;
          _isNavigating = true;
          // Update adaptive colors immediately on tap
          updateAdaptiveColorsFromImage(context, imageUrl);
          Navigator.push(
@@ -121,7 +127,12 @@ class _ArtistCardState extends State<ArtistCard> {
                initialImageUrl: imageUrl,
              ),
            ),
-          );
+          ).then((_) {
            // Reset after navigation debounce delay
            Future.delayed(Timings.navigationDebounce, () {
              if (mounted) _isNavigating = false;
            });
          });
        },
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.center,
@@ -38,6 +38,12 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
  @override
  void initState() {
    super.initState();
    // Get cached data synchronously BEFORE first build (no spinner flash)
    final cached = widget.getCachedArtists?.call();
    if (cached != null && cached.isNotEmpty) {
      _artists = cached;
      _isLoading = false;
    }
    _loadArtists();
  }
@@ -45,18 +51,7 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
    if (_hasLoaded) return;
    _hasLoaded = true;
-    // 1. Try to get cached data synchronously for instant display
+    // Load fresh data (always update - fresh data may have images that cached data lacks)
    final cachedArtists = widget.getCachedArtists?.call();
    if (cachedArtists != null && cachedArtists.isNotEmpty) {
      if (mounted) {
        setState(() {
          _artists = cachedArtists;
          _isLoading = false;
        });
      }
    }
    // 2. Load fresh data (always update - fresh data may have images that cached data lacks)
    try {
      final freshArtists = await widget.loadArtists();
      if (mounted && freshArtists.isNotEmpty) {
@@ -14,6 +14,8 @@ class AudiobookRow extends StatefulWidget {
  final Future<List<Audiobook>> Function() loadAudiobooks;
  final String? heroTagSuffix;
  final double? rowHeight;
  /// Optional: synchronous getter for cached data (for instant display)
  final List<Audiobook>? Function()? getCachedAudiobooks;
  const AudiobookRow({
    super.key,
@@ -21,6 +23,7 @@ class AudiobookRow extends StatefulWidget {
    required this.loadAudiobooks,
    this.heroTagSuffix,
    this.rowHeight,
    this.getCachedAudiobooks,
  });
  @override
@@ -28,8 +31,8 @@ class AudiobookRow extends StatefulWidget {
 }
 class _AudiobookRowState extends State<AudiobookRow> with AutomaticKeepAliveClientMixin {
-  late Future<List<Audiobook>> _audiobooksFuture;
+  List<Audiobook> _audiobooks = [];
-  List<Audiobook>? _cachedAudiobooks;
+  bool _isLoading = true;
  bool _hasLoaded = false;
  bool _hasPrecachedAudiobooks = false;
@@ -39,18 +42,36 @@ class _AudiobookRowState extends State<AudiobookRow> with AutomaticKeepAliveClie
  @override
  void initState() {
    super.initState();
-    _loadAudiobooksOnce();
+    // Get cached data synchronously BEFORE first build (no spinner flash)
    final cached = widget.getCachedAudiobooks?.call();
    if (cached != null && cached.isNotEmpty) {
      _audiobooks = cached;
      _isLoading = false;
    }
    _loadAudiobooks();
  }
-  void _loadAudiobooksOnce() {
+  Future<void> _loadAudiobooks() async {
-    if (!_hasLoaded) {
+    if (_hasLoaded) return;
-      _audiobooksFuture = widget.loadAudiobooks().then((audiobooks) {
+    _hasLoaded = true;
-        _cachedAudiobooks = audiobooks;
+
-        // Pre-cache images for smooth Hero animations
+    // Load fresh data (always update - fresh data may have updated progress)
-        _precacheAudiobookImages(audiobooks);
+    try {
-        return audiobooks;
+      final freshAudiobooks = await widget.loadAudiobooks();
-      });
+      if (mounted && freshAudiobooks.isNotEmpty) {
-      _hasLoaded = true;
+        setState(() {
          _audiobooks = freshAudiobooks;
          _isLoading = false;
        });
        // Pre-cache images for smooth hero animations
        _precacheAudiobookImages(freshAudiobooks);
      }
    } catch (e) {
      // Silent failure - keep showing cached data
    }
    if (mounted && _isLoading) {
      setState(() => _isLoading = false);
    }
  }
@@ -80,10 +101,57 @@ class _AudiobookRowState extends State<AudiobookRow> with AutomaticKeepAliveClie
  static final _logger = DebugLogger();
  Widget _buildContent(double contentHeight, ColorScheme colorScheme, MusicAssistantProvider maProvider) {
    // Only show loading if we have no data at all
    if (_audiobooks.isEmpty && _isLoading) {
      return const Center(child: CircularProgressIndicator());
    }
    if (_audiobooks.isEmpty) {
      return Center(
        child: Text(
          'No audiobooks found',
          style: TextStyle(color: colorScheme.onSurface.withOpacity(0.5)),
        ),
      );
    }
    const textAreaHeight = 44.0;
    final artworkSize = contentHeight - textAreaHeight;
    final cardWidth = artworkSize;
    final itemExtent = cardWidth + 12;
    return ScrollConfiguration(
      behavior: const _StretchScrollBehavior(),
      child: ListView.builder(
        scrollDirection: Axis.horizontal,
        padding: const EdgeInsets.symmetric(horizontal: 12.0),
        itemCount: _audiobooks.length,
        itemExtent: itemExtent,
        cacheExtent: 500,
        addAutomaticKeepAlives: false,
        addRepaintBoundaries: false,
        itemBuilder: (context, index) {
          final audiobook = _audiobooks[index];
          return Container(
            key: ValueKey(audiobook.uri ?? audiobook.itemId),
            width: cardWidth,
            margin: const EdgeInsets.symmetric(horizontal: 6.0),
            child: _AudiobookCard(
              audiobook: audiobook,
              heroTagSuffix: widget.heroTagSuffix ?? 'home_${widget.title.replaceAll(' ', '_').toLowerCase()}',
              maProvider: maProvider,
            ),
          );
        },
      ),
    );
  }
  @override
  Widget build(BuildContext context) {
    _logger.startBuild('AudiobookRow:${widget.title}');
-    super.build(context);
+    super.build(context); // Required for AutomaticKeepAliveClientMixin
    final textTheme = Theme.of(context).textTheme;
    final colorScheme = Theme.of(context).colorScheme;
    final maProvider = context.read<MusicAssistantProvider>();
@@ -109,62 +177,7 @@ class _AudiobookRowState extends State<AudiobookRow> with AutomaticKeepAliveClie
              ),
            ),
            Expanded(
-              child: FutureBuilder<List<Audiobook>>(
+              child: _buildContent(contentHeight, colorScheme, maProvider),
                future: _audiobooksFuture,
                builder: (context, snapshot) {
                  final audiobooks = snapshot.data ?? _cachedAudiobooks;
                  if (audiobooks == null && snapshot.connectionState == ConnectionState.waiting) {
                    return const Center(child: CircularProgressIndicator());
                  }
                  if (snapshot.hasError && audiobooks == null) {
                    return Center(
                      child: Text('Error: ${snapshot.error}'),
                    );
                  }
                  if (audiobooks == null || audiobooks.isEmpty) {
                    return Center(
                      child: Text(
                        'No audiobooks found',
                        style: TextStyle(color: colorScheme.onSurface.withOpacity(0.5)),
                      ),
                    );
                  }
                  const textAreaHeight = 44.0;
                  final artworkSize = contentHeight - textAreaHeight;
                  final cardWidth = artworkSize;
                  final itemExtent = cardWidth + 12;
                  return ScrollConfiguration(
                    behavior: const _StretchScrollBehavior(),
                    child: ListView.builder(
                      scrollDirection: Axis.horizontal,
                      padding: const EdgeInsets.symmetric(horizontal: 12.0),
                      itemCount: audiobooks.length,
                      itemExtent: itemExtent,
                      cacheExtent: 500,
                      addAutomaticKeepAlives: false,
                      addRepaintBoundaries: false,
                      itemBuilder: (context, index) {
                        final audiobook = audiobooks[index];
                        return Container(
                          key: ValueKey(audiobook.uri ?? audiobook.itemId),
                          width: cardWidth,
                          margin: const EdgeInsets.symmetric(horizontal: 6.0),
                          child: _AudiobookCard(
                            audiobook: audiobook,
                            heroTagSuffix: widget.heroTagSuffix ?? 'home_${widget.title.replaceAll(' ', '_').toLowerCase()}',
                            maProvider: maProvider,
                          ),
                        );
                      },
                    ),
                  );
                },
              ),
            ),
          ],
        ),
@@ -103,39 +103,48 @@ class EmptyState extends StatelessWidget {
  Widget build(BuildContext context) {
    final colorScheme = Theme.of(context).colorScheme;
-    return Center(
+    // Wrap in scrollable to allow PageView horizontal swipe detection
-      child: Padding(
+    return LayoutBuilder(
-        padding: Spacing.paddingAll24,
+      builder: (context, constraints) => SingleChildScrollView(
-        child: Column(
+        physics: const AlwaysScrollableScrollPhysics(),
-          mainAxisAlignment: MainAxisAlignment.center,
+        child: ConstrainedBox(
-          children: [
+          constraints: BoxConstraints(minHeight: constraints.maxHeight),
-            Icon(
+          child: Center(
-              icon,
+            child: Padding(
-              size: iconSize,
+              padding: Spacing.paddingAll24,
-              color: colorScheme.onSurface.withOpacity(0.38),
+              child: Column(
-            ),
+                mainAxisAlignment: MainAxisAlignment.center,
-            Spacing.vGap16,
+                children: [
-            Text(
+                  Icon(
-              message,
+                    icon,
-              style: TextStyle(
+                    size: iconSize,
-                color: colorScheme.onSurface.withOpacity(0.6),
+                    color: colorScheme.onSurface.withOpacity(0.38),
-                fontSize: 16,
+                  ),
                  Spacing.vGap16,
                  Text(
                    message,
                    style: TextStyle(
                      color: colorScheme.onSurface.withOpacity(0.6),
                      fontSize: 16,
                    ),
                    textAlign: TextAlign.center,
                  ),
                  if (actionLabel != null && onAction != null) ...[
                    Spacing.vGap24,
                    ElevatedButton.icon(
                      onPressed: onAction,
                      icon: const Icon(Icons.refresh_rounded),
                      label: Text(actionLabel!),
                      style: ElevatedButton.styleFrom(
                        backgroundColor: colorScheme.surfaceVariant,
                        foregroundColor: colorScheme.onSurfaceVariant,
                      ),
                    ),
                  ],
                ],
              ),
              textAlign: TextAlign.center,
            ),
-            if (actionLabel != null && onAction != null) ...[
+          ),
              Spacing.vGap24,
              ElevatedButton.icon(
                onPressed: onAction,
                icon: const Icon(Icons.refresh_rounded),
                label: Text(actionLabel!),
                style: ElevatedButton.styleFrom(
                  backgroundColor: colorScheme.surfaceVariant,
                  foregroundColor: colorScheme.onSurfaceVariant,
                ),
              ),
            ],
          ],
        ),
      ),
    );
@@ -162,51 +171,60 @@ class _CustomEmptyState extends EmptyState {
    final colorScheme = Theme.of(context).colorScheme;
    final s = S.of(context)!;
-    return Center(
+    // Wrap in scrollable to allow PageView horizontal swipe detection
-      child: Padding(
+    return LayoutBuilder(
-        padding: Spacing.paddingAll24,
+      builder: (context, constraints) => SingleChildScrollView(
-        child: Column(
+        physics: const AlwaysScrollableScrollPhysics(),
-          mainAxisAlignment: MainAxisAlignment.center,
+        child: ConstrainedBox(
-          children: [
+          constraints: BoxConstraints(minHeight: constraints.maxHeight),
-            Icon(
+          child: Center(
-              icon,
+            child: Padding(
-              size: iconSize,
+              padding: Spacing.paddingAll24,
-              color: colorScheme.onSurface.withOpacity(0.38),
+              child: Column(
                mainAxisAlignment: MainAxisAlignment.center,
                children: [
                  Icon(
                    icon,
                    size: iconSize,
                    color: colorScheme.onSurface.withOpacity(0.38),
                  ),
                  Spacing.vGap16,
                  Text(
                    title,
                    style: TextStyle(
                      color: colorScheme.onSurface.withOpacity(0.6),
                      fontSize: 16,
                      fontWeight: FontWeight.w500,
                    ),
                    textAlign: TextAlign.center,
                  ),
                  if (subtitle != null) ...[
                    Spacing.vGap8,
                    Text(
                      subtitle!,
                      style: TextStyle(
                        color: colorScheme.onSurface.withOpacity(0.4),
                        fontSize: 14,
                      ),
                      textAlign: TextAlign.center,
                    ),
                  ],
                  if (onRefresh != null) ...[
                    Spacing.vGap24,
                    ElevatedButton.icon(
                      onPressed: onRefresh,
                      icon: const Icon(Icons.refresh_rounded),
                      label: Text(s.refresh),
                      style: ElevatedButton.styleFrom(
                        backgroundColor: colorScheme.surfaceVariant,
                        foregroundColor: colorScheme.onSurfaceVariant,
                      ),
                    ),
                  ],
                ],
              ),
            ),
-            Spacing.vGap16,
+          ),
            Text(
              title,
              style: TextStyle(
                color: colorScheme.onSurface.withOpacity(0.6),
                fontSize: 16,
                fontWeight: FontWeight.w500,
              ),
              textAlign: TextAlign.center,
            ),
            if (subtitle != null) ...[
              Spacing.vGap8,
              Text(
                subtitle!,
                style: TextStyle(
                  color: colorScheme.onSurface.withOpacity(0.4),
                  fontSize: 14,
                ),
                textAlign: TextAlign.center,
              ),
            ],
            if (onRefresh != null) ...[
              Spacing.vGap24,
              ElevatedButton.icon(
                onPressed: onRefresh,
                icon: const Icon(Icons.refresh_rounded),
                label: Text(s.refresh),
                style: ElevatedButton.styleFrom(
                  backgroundColor: colorScheme.surfaceVariant,
                  foregroundColor: colorScheme.onSurfaceVariant,
                ),
              ),
            ],
          ],
        ),
      ),
    );
@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import '../../l10n/app_localizations.dart';
 import '../../services/debug_logger.dart';
 import '../../theme/design_tokens.dart';
@@ -72,9 +73,9 @@ class DebugConsole extends StatelessWidget {
            padding: EdgeInsets.zero,
            minimumSize: const Size(40, 20),
          ),
-          child: const Text(
+          child: Text(
-            'Clear',
+            S.of(context)!.clear,
-            style: TextStyle(fontSize: 10, color: Colors.green),
+            style: const TextStyle(fontSize: 10, color: Colors.green),
          ),
        ),
      ],
@@ -86,17 +87,17 @@ class DebugConsole extends StatelessWidget {
    if (logs.isNotEmpty) {
      Clipboard.setData(ClipboardData(text: logs));
      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(
+        SnackBar(
-          content: Text('Logs copied to clipboard'),
+          content: Text(S.of(context)!.logsCopied),
          backgroundColor: Colors.green,
-          duration: Duration(seconds: 2),
+          duration: const Duration(seconds: 2),
        ),
      );
    } else {
      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(
+        SnackBar(
-          content: Text('No logs to copy'),
+          content: Text(S.of(context)!.noLogsToCopy),
-          duration: Duration(seconds: 2),
+          duration: const Duration(seconds: 2),
        ),
      );
    }
@@ -8,6 +8,7 @@ import '../providers/music_assistant_provider.dart';
 import '../providers/navigation_provider.dart';
 import '../services/settings_service.dart';
 import '../theme/theme_provider.dart';
 import 'expandable_player.dart';
 import 'player/mini_player_content.dart' show MiniPlayerLayout;
 import 'player/player_reveal_overlay.dart';
@@ -67,13 +68,14 @@ class BottomSpacing {
  static double get withMiniPlayer => navBarHeight + miniPlayerHeight + 22.0;
 }
-/// ValueNotifier for player expansion progress (0.0 to 1.0) and background color
+/// ValueNotifier for player expansion progress (0.0 to 1.0) and colors
 class PlayerExpansionState {
  final double progress;
  final Color? backgroundColor;
-  PlayerExpansionState(this.progress, this.backgroundColor);
+  final Color? primaryColor;
  PlayerExpansionState(this.progress, this.backgroundColor, this.primaryColor);
 }
-final playerExpansionNotifier = ValueNotifier<PlayerExpansionState>(PlayerExpansionState(0.0, null));
+final playerExpansionNotifier = ValueNotifier<PlayerExpansionState>(PlayerExpansionState(0.0, null, null));
 /// Wrapper widget that provides a global player overlay above all navigation.
 ///
@@ -91,14 +93,36 @@ class GlobalPlayerOverlay extends StatefulWidget {
  State<GlobalPlayerOverlay> createState() => _GlobalPlayerOverlayState();
  /// Collapse the player if it's expanded
-  static void collapsePlayer() {
+  /// [withHaptic]: Set to false for Android back gesture (system provides haptic)
-    globalPlayerKey.currentState?.collapse();
+  static void collapsePlayer({bool withHaptic = true}) {
    globalPlayerKey.currentState?.collapse(withHaptic: withHaptic);
  }
  /// Force collapse player to mini state, instantly closing queue panel if open.
  /// Used for queue transfer where we want to go directly to mini player.
  static void forceCollapsePlayer() {
    globalPlayerKey.currentState?.forceCollapse();
  }
  /// Check if the player is currently expanded
  static bool get isPlayerExpanded =>
      globalPlayerKey.currentState?.isExpanded ?? false;
  /// Check if the queue panel is currently open (animation value > 0.5)
  static bool get isQueuePanelOpen =>
      globalPlayerKey.currentState?.isQueuePanelOpen ?? false;
  /// Check if the queue panel is intended to be open (target state)
  /// Use this for back gesture handling to avoid timing issues during animations
  static bool get isQueuePanelTargetOpen =>
      globalPlayerKey.currentState?.isQueuePanelTargetOpen ?? false;
  /// Close the queue panel if open
  /// [withHaptic]: Set to false for Android back gesture (system provides haptic)
  static void closeQueuePanel({bool withHaptic = true}) {
    globalPlayerKey.currentState?.closeQueuePanel(withHaptic: withHaptic);
  }
  /// Get the current expansion progress (0.0 to 1.0)
  static double get expansionProgress =>
      globalPlayerKey.currentState?.expansionProgress ?? 0.0;
@@ -141,6 +165,21 @@ class GlobalPlayerOverlay extends StatefulWidget {
  /// Check if the player reveal is currently visible
  static bool get isPlayerRevealVisible =>
      _overlayStateKey.currentState?._isRevealVisible ?? false;
  /// Show player selector for a "Play On" action.
  /// Instead of the default hints, shows a contextual hint like "Select player to play album".
  /// When a player is tapped, calls onPlayerSelected instead of switching to that player.
  static void showPlayerSelectorForAction({
    required String contextHint,
    required void Function(dynamic player) onPlayerSelected,
    IconData? hintIcon,
  }) {
    _overlayStateKey.currentState?._showPlayerSelectorForAction(
      contextHint: contextHint,
      onPlayerSelected: onPlayerSelected,
      hintIcon: hintIcon,
    );
  }
 }
 class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
@@ -185,6 +224,11 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
  // Key for the reveal overlay
  final _revealKey = GlobalKey<PlayerRevealOverlayState>();
  // State for "Play On" action - stored here so it can be passed to PlayerRevealOverlay
  void Function(dynamic player)? _pendingPlayerAction;
  String? _pendingContextHint;
  IconData? _pendingHintIcon;
  @override
  void initState() {
    super.initState();
@@ -371,6 +415,7 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
  void _hidePlayerReveal() {
    if (!_isRevealVisible) return;
    _bounceOffsetNotifier.value = 0;
    _clearPendingAction(); // Clear pending action when overlay is dismissed
    setState(() {
      _isRevealVisible = false;
      _isOnboardingReveal = false;
@@ -390,6 +435,29 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
    _singleBounceController.forward();
  }
  /// Clear pending action state (called when overlay is dismissed)
  void _clearPendingAction() {
    _pendingPlayerAction = null;
    _pendingContextHint = null;
    _pendingHintIcon = null;
  }
  /// Show player selector for a "Play On" action.
  /// Stores the pending action and shows the reveal overlay with context hint.
  void _showPlayerSelectorForAction({
    required String contextHint,
    required void Function(dynamic player) onPlayerSelected,
    IconData? hintIcon,
  }) {
    // Store pending action state
    _pendingPlayerAction = onPlayerSelected;
    _pendingContextHint = contextHint;
    _pendingHintIcon = hintIcon;
    // Show the reveal overlay
    _showPlayerReveal();
  }
  /// End hint mode (called when user taps skip button)
  void _endHintMode() {
    if (!_isHintModeActive) return;
@@ -409,15 +477,17 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
    final theme = Theme.of(context);
    final colorScheme = theme.colorScheme;
-    // Watch provider to trigger rebuilds when connection state changes
+    // PERF: Use select() to only rebuild when connection state or player changes
-    final provider = context.watch<MusicAssistantProvider>();
+    final (isConnected, hasSelectedPlayer) = context.select<MusicAssistantProvider, (bool, bool)>(
      (p) => (p.isConnected, p.selectedPlayer != null),
    );
    // Compute whether this is a first-time user ready for welcome screen.
    // This is SYNCHRONOUS - no setState needed - so it works in the same frame.
    final isFirstTimeUserReady = _settingsLoaded &&
        !_hasCompletedOnboarding &&
-        provider.isConnected &&
+        isConnected &&
-        provider.selectedPlayer != null;
+        hasSelectedPlayer;
    // Show welcome backdrop if:
    // 1. Already in hint mode (_isHintModeActive), OR
@@ -463,7 +533,7 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
        // Hide when: not connected, no player selected, OR showing welcome screen
        // For first-time users, selectedPlayer becomes non-null at the same time
        // as shouldShowWelcomeBackdrop becomes true, preventing any gap.
-        if (provider.isConnected && provider.selectedPlayer != null && !shouldShowWelcomeBackdrop)
+        if (isConnected && hasSelectedPlayer && !shouldShowWelcomeBackdrop)
          Positioned(
            left: 0,
            right: 0,
@@ -473,88 +543,115 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
              builder: (context, _) {
                return Consumer<ThemeProvider>(
                builder: (context, themeProvider, _) {
                  // Use adaptive primary color for bottom nav when adaptive theme is enabled
                  final sourceColor = themeProvider.adaptiveTheme
                      ? themeProvider.adaptivePrimaryColor
                      : colorScheme.primary;
                  // Use cached color computation to avoid expensive HSL operations during scroll
                  final isDark = Theme.of(context).brightness == Brightness.dark;
                  final navSelectedColor = _cachedNavColor.getAdjustedColor(sourceColor, isDark);
                  // Base background: use adaptive surface color if available, otherwise default surface
                  final baseBgColor = (themeProvider.adaptiveTheme && themeProvider.adaptiveSurfaceColor != null)
                      ? themeProvider.adaptiveSurfaceColor!
                      : colorScheme.surface;
                  return ValueListenableBuilder<PlayerExpansionState>(
                    valueListenable: playerExpansionNotifier,
-                    // Pass BottomNavigationBar as child to avoid rebuilding it every frame
+                    builder: (context, expansionState, _) {
-                    child: BottomNavigationBar(
+                      // Nav bar color logic - only use adaptive colors when:
-                      currentIndex: navigationProvider.selectedIndex,
+                      // 1. Player is expanding/expanded, OR
-                      onTap: (index) {
+                      // 2. On a detail screen (isOnDetailScreen)
-                        if (GlobalPlayerOverlay.isPlayerExpanded) {
+                      // On home screen with collapsed player: always use default theme colors
-                          GlobalPlayerOverlay.collapsePlayer();
+                      final bool useAdaptiveColors = themeProvider.adaptiveTheme &&
-                        }
+                          (expansionState.progress > 0 || themeProvider.isOnDetailScreen);
                        navigationProvider.navigatorKey.currentState?.popUntil((route) => route.isFirst);
                        if (index == 3) {
                          GlobalPlayerOverlay.hidePlayer();
                        } else if (navigationProvider.selectedIndex == 3) {
                          GlobalPlayerOverlay.showPlayer();
                        }
                        navigationProvider.setSelectedIndex(index);
                      },
                      backgroundColor: Colors.transparent,
                      selectedItemColor: navSelectedColor,
                      unselectedItemColor: colorScheme.onSurface.withOpacity(0.54),
                      elevation: 0,
                      type: BottomNavigationBarType.fixed,
                      selectedFontSize: 12,
                      unselectedFontSize: 12,
                      items: [
                        BottomNavigationBarItem(
                          icon: const Icon(Icons.home_outlined),
                          activeIcon: const Icon(Icons.home_rounded),
                          label: S.of(context)!.home,
                        ),
                        BottomNavigationBarItem(
                          icon: const Icon(Icons.library_music_outlined),
                          activeIcon: const Icon(Icons.library_music_rounded),
                          label: S.of(context)!.library,
                        ),
                        BottomNavigationBarItem(
                          icon: const Icon(Icons.search_rounded),
                          activeIcon: const Icon(Icons.search_rounded),
                          label: S.of(context)!.search,
                        ),
                        BottomNavigationBarItem(
                          icon: const Icon(Icons.settings_outlined),
                          activeIcon: const Icon(Icons.settings_rounded),
                          label: S.of(context)!.settings,
                        ),
                      ],
                    ),
                    builder: (context, expansionState, navBar) {
                      // Only compute colors during animation - this is the hot path
                      final navBgColor = expansionState.progress > 0 && expansionState.backgroundColor != null
                          ? Color.lerp(baseBgColor, expansionState.backgroundColor, expansionState.progress)!
                          : baseBgColor;
-                      // Use AnimatedContainer for smoother transitions instead of rebuilding
+                      // Nav bar background color
-                      return Container(
+                      final Color navBgColor;
-                        decoration: BoxDecoration(
+                      if (expansionState.progress > 0 && expansionState.backgroundColor != null) {
-                          color: navBgColor,
+                        // Player is expanding - blend from surface to player's adaptive color
-                          boxShadow: expansionState.progress < 0.5
+                        navBgColor = Color.lerp(colorScheme.surface, expansionState.backgroundColor, expansionState.progress)!;
-                              ? [
+                      } else if (useAdaptiveColors) {
-                                  BoxShadow(
+                        // On a detail screen - use adaptive surface color for nav bar
-                                    color: Colors.black.withOpacity(0.1),
+                        final adaptiveBg = themeProvider.getAdaptiveSurfaceColorFor(Theme.of(context).brightness);
-                                    blurRadius: 10,
+                        navBgColor = adaptiveBg ?? colorScheme.surface;
-                                    offset: const Offset(0, -2),
+                      } else {
                        // Home screen with collapsed player - use default surface color
                        navBgColor = colorScheme.surface;
                      }
                      // Icon color - only use adaptive colors when appropriate
                      final Color baseSourceColor = (useAdaptiveColors && themeProvider.adaptiveColors != null)
                          ? themeProvider.adaptiveColors!.primary
                          : colorScheme.primary;
                      // Blend icon color with player's primary color during expansion
                      Color sourceColor = baseSourceColor;
                      if (themeProvider.adaptiveTheme && expansionState.progress > 0 && expansionState.primaryColor != null) {
                        sourceColor = Color.lerp(baseSourceColor, expansionState.primaryColor!, expansionState.progress)!;
                      }
                      final navSelectedColor = _cachedNavColor.getAdjustedColor(sourceColor, isDark);
                      // Fade out and slide down nav bar as player expands
                      // Use IgnorePointer when faded to prevent accidental taps
                      final navOpacity = (1.0 - expansionState.progress * 2).clamp(0.0, 1.0);
                      final navSlideDown = expansionState.progress * 20; // Slide down 20px as it fades
                      return IgnorePointer(
                        ignoring: navOpacity < 0.1,
                        child: Transform.translate(
                          offset: Offset(0, navSlideDown),
                          child: Opacity(
                            opacity: navOpacity,
                            child: Container(
                              decoration: BoxDecoration(
                                color: navBgColor,
                                boxShadow: expansionState.progress < 0.5
                                    ? [
                                        BoxShadow(
                                          color: Colors.black.withOpacity(0.1),
                                          blurRadius: 10,
                                          offset: const Offset(0, -2),
                                        ),
                                      ]
                                    : null,
                              ),
                              child: BottomNavigationBar(
                                currentIndex: navigationProvider.selectedIndex,
                                onTap: (index) {
                                  if (GlobalPlayerOverlay.isPlayerExpanded) {
                                    GlobalPlayerOverlay.collapsePlayer();
                                  }
                                  navigationProvider.navigatorKey.currentState?.popUntil((route) => route.isFirst);
                                  if (index == 3) {
                                    GlobalPlayerOverlay.hidePlayer();
                                  } else if (navigationProvider.selectedIndex == 3) {
                                    GlobalPlayerOverlay.showPlayer();
                                  }
                                  navigationProvider.setSelectedIndex(index);
                                },
                                backgroundColor: Colors.transparent,
                                selectedItemColor: navSelectedColor,
                                unselectedItemColor: colorScheme.onSurface.withOpacity(0.54),
                                elevation: 0,
                                type: BottomNavigationBarType.fixed,
                                selectedFontSize: 12,
                                unselectedFontSize: 12,
                                items: [
                                  BottomNavigationBarItem(
                                    icon: const Icon(Icons.home_outlined),
                                    activeIcon: const Icon(Icons.home_rounded),
                                    label: S.of(context)!.home,
                                  ),
-                                ]
+                                  BottomNavigationBarItem(
-                              : null,
+                                    icon: const Icon(Icons.library_music_outlined),
                                    activeIcon: const Icon(Icons.library_music_rounded),
                                    label: S.of(context)!.library,
                                  ),
                                  BottomNavigationBarItem(
                                    icon: const Icon(Icons.search_rounded),
                                    activeIcon: const Icon(Icons.search_rounded),
                                    label: S.of(context)!.search,
                                  ),
                                  BottomNavigationBarItem(
                                    icon: const Icon(Icons.settings_outlined),
                                    activeIcon: const Icon(Icons.settings_rounded),
                                    label: S.of(context)!.settings,
                                  ),
                                ],
                              ),
                            ),
                          ),
                        ),
                        child: navBar, // Reuse pre-built navigation bar
                      );
                    },
                  );
@@ -589,11 +686,15 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
              duration: const Duration(seconds: 3),
              curve: const Interval(0.67, 1.0, curve: Curves.easeOut),
              builder: (context, opacity, child) {
                // Use theme-appropriate background color for seamless transition
                final isDark = Theme.of(context).brightness == Brightness.dark;
                final backdropColor = isDark
                    ? const Color(0xFF1a1a1a)  // Dark theme background
                    : colorScheme.surface;      // Light theme surface
                return BackdropFilter(
                  filter: ImageFilter.blur(sigmaX: 8.0, sigmaY: 8.0),
                  child: Container(
-                    // Use same dark color as connection screen for seamless transition
+                    color: backdropColor.withOpacity(opacity),
                    color: const Color(0xFF1a1a1a).withOpacity(opacity),
                  ),
                );
              },
@@ -689,6 +790,10 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
            miniPlayerBottom: BottomSpacing.navBarHeight + MediaQuery.of(context).viewPadding.bottom + 12,
            miniPlayerHeight: 64,
            showOnboardingHints: _isOnboardingReveal,
            // Pass pending action parameters for "Play On" functionality
            onPlayerSelected: _pendingPlayerAction,
            contextHint: _pendingContextHint,
            contextHintIcon: _pendingHintIcon,
          ),
        // Global player overlay - renders ON TOP so cards slide behind it
@@ -702,6 +807,13 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
          builder: (context, state, child) {
            // Only show player if connected and has a selected player
            if (!state.isConnected || !state.hasPlayer) {
              // Reset expansion state to prevent stale values from causing
              // invisible/non-interactive nav bar when connection restores.
              // This fixes a bug where expanded player state persisted after
              // disconnect, making nav bar opacity=0 and ignoring taps.
              if (playerExpansionNotifier.value.progress != 0.0) {
                playerExpansionNotifier.value = PlayerExpansionState(0.0, null, null);
              }
              return const SizedBox.shrink();
            }
@@ -2,6 +2,9 @@ import 'package:flutter/material.dart';
 /// A scrollbar that shows a letter popup when dragging, for fast navigation
 /// through alphabetically sorted lists.
 ///
 /// Scrolls PROPORTIONALLY (like a normal scrollbar) and shows which letter
 /// section you're currently in via a popup indicator.
 class LetterScrollbar extends StatefulWidget {
  /// The scrollable child widget (ListView, GridView, etc.)
  final Widget child;
@@ -9,16 +12,34 @@ class LetterScrollbar extends StatefulWidget {
  /// The scroll controller for the child
  final ScrollController controller;
-  /// List of items to extract letters from (must be sorted alphabetically)
+  /// List of strings to extract letters from (should match visual sort order).
-  /// Each item's first character is used to determine the letter
+  /// Each item's first character is used to determine the letter shown in the popup.
  final List<String> items;
-  /// Callback when user taps/drags to a specific index
+  /// Callback when user taps/drags to a specific index.
  final void Function(int index)? onScrollToIndex;
  /// Callback when drag state changes (for disabling scroll-to-hide)
  final void Function(bool isDragging)? onDragStateChanged;
  /// Fixed item height for lists. Enables precise scroll calculation.
  final double? itemExtent;
  /// Number of columns for grid layouts.
  final int? crossAxisCount;
  /// Aspect ratio of grid children (width / height).
  final double? childAspectRatio;
  /// Spacing between grid rows (mainAxisSpacing)
  final double? mainAxisSpacing;
  /// Horizontal padding of the scrollable area
  final double? horizontalPadding;
  /// Bottom padding to prevent scrollbar from going behind bottom nav/mini player
  final double bottomPadding;
  const LetterScrollbar({
    super.key,
    required this.child,
@@ -26,6 +47,12 @@ class LetterScrollbar extends StatefulWidget {
    required this.items,
    this.onScrollToIndex,
    this.onDragStateChanged,
    this.itemExtent,
    this.crossAxisCount,
    this.childAspectRatio,
    this.mainAxisSpacing,
    this.horizontalPadding,
    this.bottomPadding = 0,
  });
  @override
@@ -55,87 +82,54 @@ class _LetterScrollbarState extends State<LetterScrollbar> {
      final position = widget.controller.position;
      if (position.maxScrollExtent > 0) {
        final newFraction = (position.pixels / position.maxScrollExtent).clamp(0.0, 1.0);
        // PERF: Only rebuild if fraction changed by more than 1% to reduce rebuilds
        if ((newFraction - _scrollFraction).abs() > 0.01) {
          setState(() {
            _scrollFraction = newFraction;
            _currentLetter = _getLetterAtFraction(newFraction);
          });
        }
      }
    }
  }
-  // Build a map of letter -> first index for that letter
+  /// Normalizes a character to a letter for the scrollbar.
-  Map<String, int> get _letterIndexMap {
+  String _normalizeToLetter(String char) {
-    final map = <String, int>{};
+    if (char.isEmpty) return '';
-    for (int i = 0; i < widget.items.length; i++) {
+    final upper = char[0].toUpperCase();
-      final item = widget.items[i];
+    if (upper.codeUnitAt(0) >= 65 && upper.codeUnitAt(0) <= 90) {
-      if (item.isNotEmpty) {
+      return upper;
        final letter = item[0].toUpperCase();
        if (!map.containsKey(letter)) {
          map[letter] = i;
        }
      }
    }
-    return map;
+    return '#';
  }
-  String _getLetterAtPosition(double position, double maxHeight) {
+  /// Get the letter at a given scroll fraction (0.0 to 1.0)
-    if (widget.items.isEmpty || maxHeight <= 0) return '';
+  String _getLetterAtFraction(double fraction) {
    if (widget.items.isEmpty) return '';
-    // Calculate which item index corresponds to this position
+    final index = (fraction * (widget.items.length - 1)).round().clamp(0, widget.items.length - 1);
-    final fraction = (position / maxHeight).clamp(0.0, 1.0);
+    if (index < widget.items.length) {
    final index = (fraction * (widget.items.length - 1)).round();
    if (index >= 0 && index < widget.items.length) {
      final item = widget.items[index];
      if (item.isNotEmpty) {
-        return item[0].toUpperCase();
+        return _normalizeToLetter(item[0]);
      }
    }
    return '';
  }
  void _scrollToLetter(String letter) {
    final letterMap = _letterIndexMap;
    if (letterMap.containsKey(letter)) {
      final index = letterMap[letter]!;
      if (widget.onScrollToIndex != null) {
        widget.onScrollToIndex!(index);
      } else {
        // Estimate scroll position based on index
        // This is approximate - works better with fixed height items
        final scrollController = widget.controller;
        if (scrollController.hasClients) {
          final maxScroll = scrollController.position.maxScrollExtent;
          final fraction = index / widget.items.length;
          final targetScroll = (fraction * maxScroll).clamp(0.0, maxScroll);
          // Update scroll fraction immediately for smooth thumb tracking
          setState(() {
            _scrollFraction = fraction;
          });
          scrollController.jumpTo(targetScroll);
        }
      }
    }
  }
  void _handleDragStart(DragStartDetails details) {
    setState(() {
      _isDragging = true;
      _dragPosition = details.localPosition.dy;
    });
    widget.onDragStateChanged?.call(true);
-    _updateLetterAndScroll(details.localPosition.dy);
+    _scrollToPosition(details.localPosition.dy);
  }
  void _handleDragUpdate(DragUpdateDetails details) {
    setState(() {
      _dragPosition = details.localPosition.dy;
    });
-    _updateLetterAndScroll(details.localPosition.dy);
+    _scrollToPosition(details.localPosition.dy);
  }
  void _handleDragEnd(DragEndDetails details) {
@@ -145,18 +139,35 @@ class _LetterScrollbarState extends State<LetterScrollbar> {
    widget.onDragStateChanged?.call(false);
  }
-  void _updateLetterAndScroll(double position) {
+  /// Scroll proportionally based on drag position
  void _scrollToPosition(double position) {
    final renderBox = context.findRenderObject() as RenderBox?;
-    if (renderBox != null) {
+    if (renderBox == null || !widget.controller.hasClients) return;
-      final height = renderBox.size.height;
+
-      final letter = _getLetterAtPosition(position, height);
+    // Account for bottom padding in the effective track height
-      if (letter.isNotEmpty && letter != _currentLetter) {
+    final totalHeight = renderBox.size.height;
-        setState(() {
+    final effectiveHeight = totalHeight - widget.bottomPadding;
-          _currentLetter = letter;
+    if (effectiveHeight <= 0) return;
-        });
+
-        _scrollToLetter(letter);
+    // Calculate scroll fraction from position (clamped to effective area)
    final clampedPosition = position.clamp(0.0, effectiveHeight);
    final fraction = clampedPosition / effectiveHeight;
    // Get letter for display
    final letter = _getLetterAtFraction(fraction);
    // Scroll proportionally
    final maxScroll = widget.controller.position.maxScrollExtent;
    final targetScroll = (fraction * maxScroll).clamp(0.0, maxScroll);
    setState(() {
      _scrollFraction = fraction;
      if (letter.isNotEmpty) {
        _currentLetter = letter;
      }
-    }
+    });
    widget.controller.jumpTo(targetScroll);
  }
  @override
@@ -168,12 +179,12 @@ class _LetterScrollbarState extends State<LetterScrollbar> {
        // The scrollable content
        widget.child,
-        // The draggable scrollbar area (right edge) - wider grab area
+        // The draggable scrollbar area (right edge)
        Positioned(
          right: 0,
          top: 0,
-          bottom: 0,
+          bottom: widget.bottomPadding,
-          width: 32, // Wider grab area
+          width: 32,
          child: GestureDetector(
            onVerticalDragStart: _handleDragStart,
            onVerticalDragUpdate: _handleDragUpdate,
@@ -196,11 +207,11 @@ class _LetterScrollbarState extends State<LetterScrollbar> {
                final trackHeight = constraints.maxHeight;
                final thumbHeight = _isDragging ? 60.0 : 40.0;
                final availableTrack = trackHeight - thumbHeight;
-                final thumbTop = availableTrack * _scrollFraction;
+                final thumbTop = (availableTrack * _scrollFraction).clamp(0.0, availableTrack);
                return Stack(
                  children: [
-                    // Thumb that tracks scroll position - use AnimatedPositioned for smooth motion
+                    // Thumb that tracks scroll position
                    AnimatedPositioned(
                      duration: const Duration(milliseconds: 50),
                      curve: Curves.linear,
@@ -229,7 +240,10 @@ class _LetterScrollbarState extends State<LetterScrollbar> {
        if (_isDragging && _currentLetter.isNotEmpty)
          Positioned(
            right: 48,
-            top: _dragPosition - 28,
+            top: (_dragPosition - 28).clamp(
              0.0,
              (context.findRenderObject() as RenderBox?)?.size.height ?? 500 - 56 - widget.bottomPadding,
            ),
            child: Material(
              elevation: 4,
              color: colorScheme.primaryContainer,
--- a/Show More
+++ b/Show More