chore: Bump version to 2.8.9-beta

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
refactor: Move audiobook libraries toggle from settings to library menu
2026-01-18 09:37:44 +00:00 · 2026-01-18 09:33:27 +00:00 · 2026-01-18 08:58:31 +00:00 · 2026-01-18 08:36:50 +00:00 · 2026-01-18 07:56:47 +00:00 · 2026-01-17 23:10:15 +00:00
143 changed files with 54928 additions and 5092 deletions
@@ -4,10 +4,13 @@ on:
  push:
    branches:
      - main
+      - master
      - 'claude/**'
+      - 'feature/**'
  pull_request:
    branches:
      - main
+      - master
  workflow_dispatch:

 jobs:
@@ -32,9 +35,25 @@ 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

+      - name: Generate code (Drift database)
+        run: dart run build_runner build --delete-conflicting-outputs
+
+      - name: Generate localizations
+        run: flutter gen-l10n
+
      - name: Generate launcher icons
        run: flutter pub run flutter_launcher_icons

@@ -56,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)
@@ -0,0 +1,391 @@
+# Ensemble Codebase Intensive Audit Prompt
+
+## Overview
+
+You are tasked with conducting an intensive, comprehensive audit of the **Ensemble** Flutter application - a Music Assistant client for Android with multi-device synchronization, local playback, and Sendspin raw audio streaming capabilities.
+
+**Codebase Statistics:**
+- 90 Dart files, ~40,583 lines of code
+- 18 screens, 27 services, 6 providers
+- Architecture: Provider pattern with ChangeNotifier
+- Audio: just_audio + flutter_pcm_sound + audio_service
+- Networking: WebSocket (JSON-RPC) + HTTP + Sendspin binary protocol
+
+---
+
+## Audit Scope
+
+Perform a thorough audit covering ALL of the following areas. For each issue found, provide:
+1. **File path and line number(s)**
+2. **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+3. **Description** of the issue
+4. **Impact** if left unfixed
+5. **Recommended fix** with code example where applicable
+
+---
+
+## SECTION 1: SECURITY AUDIT
+
+### 1.1 Credential Storage (CRITICAL PRIORITY)
+Audit `/lib/services/settings_service.dart` for:
+- [ ] Plaintext password storage in SharedPreferences (lines 209-222)
+- [ ] Auth tokens stored without encryption
+- [ ] Serialized credentials in JSON format (lines 169-190)
+
+**Expected Finding:** Credentials stored insecurely. Recommend flutter_secure_storage.
+
+### 1.2 Certificate Validation
+Audit `/lib/services/auth/auth_manager.dart` for:
+- [ ] HTTPS redirect handling for local IPs
+- [ ] Certificate validation disabled scenarios
+- [ ] MITM vulnerability exposure
+
+### 1.3 Authentication Strategies
+Audit all files in `/lib/services/auth/`:
+- [ ] `basic_auth_strategy.dart` - Base64 encoding (not encryption)
+- [ ] `authelia_strategy.dart` - Session cookie handling, timing attack (line 159)
+- [ ] `ma_auth_strategy.dart` - Token refresh mechanism
+- [ ] `no_auth_strategy.dart` - Public server exposure
+
+### 1.4 Input Validation
+Audit `/lib/services/music_assistant_api.dart`:
+- [ ] URI construction without validation (lines 1346-1360)
+- [ ] Provider/itemId injection risks
+- [ ] WebSocket message validation
+
+### 1.5 Information Disclosure
+- [ ] Debug logs exposing sensitive data (check all `_logger.log()` calls)
+- [ ] Server version exposure via `server_info`
+- [ ] Error messages leaking technical details
+
+---
+
+## SECTION 2: MEMORY MANAGEMENT AUDIT
+
+### 2.1 Static Memory Leaks
+Audit `/lib/models/player.dart`:
+- [ ] `_playerCreationTimes` static map (lines 96-144) - grows unbounded
+- [ ] Cleanup only removes 50 of 100+ entries
+
+### 2.2 Unbounded Caches
+Audit `/lib/services/cache_service.dart`:
+- [ ] `_albumTracksCache` - no size limit
+- [ ] `_artistAlbumsCache` - no TTL expiration
+- [ ] `_searchCache` - never evicted
+- [ ] `_playerTrackCache` - only cleared on disconnect
+
+### 2.3 Stream/Timer Cleanup
+Audit `/lib/providers/music_assistant_provider.dart`:
+- [ ] `_playerStateTimer` disposal (line 4435-4445)
+- [ ] `_notificationPositionTimer` multiple creation paths (lines 2925-2940)
+- [ ] `_localPlayerEventSubscription` cleanup
+- [ ] `_playerUpdatedEventSubscription` cleanup
+- [ ] `_playerAddedEventSubscription` cleanup
+
+Audit `/lib/services/hardware_volume_service.dart`:
+- [ ] `_volumeUpController` never closed (lines 74-85)
+- [ ] `_volumeDownController` never closed
+
+### 2.4 Stream Subscription Leaks
+Audit `/lib/providers/music_assistant_provider.dart`:
+- [ ] `_api!.connectionState.listen()` - subscription not stored
+- [ ] Old subscriptions not cancelled before new API instance
+
+---
+
+## SECTION 3: RACE CONDITION AUDIT
+
+### 3.1 Player State Dual Updates
+Audit `/lib/providers/music_assistant_provider.dart`:
+- [ ] Timer polling (every 5s) vs WebSocket events racing
+- [ ] `_updatePlayerState()` called from both paths
+- [ ] No mutex/lock protection
+
+### 3.2 Async Method Reentrancy
+Audit `selectPlayer()` method:
+- [ ] `async` method without guard against concurrent calls
+- [ ] `_selectedPlayer` modified before and after `await`
+- [ ] State could change during await
+
+### 3.3 Fire-and-Forget Operations
+Search for `unawaited(` and `() async {` patterns:
+- [ ] `_persistPlaybackState()` - database save not awaited
+- [ ] Pause operations fire-and-forget (lines 3876-3894)
+- [ ] Preload operations (line 2707)
+
+### 3.4 PCM Player State Machine
+Audit `/lib/services/pcm_audio_player.dart`:
+- [ ] 9-state machine with complex transitions (lines 32-37)
+- [ ] Auto-recovery race condition (lines 215-229)
+- [ ] Feed loop during pause transition (lines 174-179)
+
+---
+
+## SECTION 4: ERROR HANDLING AUDIT
+
+### 4.1 Silent Exception Handlers (CRITICAL)
+Find all instances of:
+```dart
+} catch (e) {}
+} catch (_) {}
+```
+
+Known locations:
+- [ ] `music_assistant_provider.dart` (multiple)
+- [ ] `player_provider.dart` (3 instances)
+- [ ] `recently_played_service.dart`
+
+### 4.2 Missing Error Recovery
+- [ ] No exponential backoff on connection retry
+- [ ] No retry logic for failed API calls
+- [ ] WebSocket timeout handling (30 seconds - too long?)
+
+### 4.3 Null Safety Violations
+Find all `!` (null assertion) operators:
+- [ ] `search_screen.dart` (20+ instances)
+- [ ] `models/media_item.dart`
+- [ ] `models/player.dart`
+- [ ] `item.mediaItem! as Artist` patterns
+
+---
+
+## SECTION 5: ARCHITECTURAL ISSUES
+
+### 5.1 God Class
+Audit `/lib/providers/music_assistant_provider.dart`:
+- [ ] 4,469 lines - violates Single Responsibility
+- [ ] 386 conditional branches
+- [ ] Mixing: connection, players, library, sync, audio, position tracking
+
+**Recommend splitting into:**
+- ConnectionProvider (~500 LOC)
+- PlayerManager (~800 LOC)
+- LibraryProvider (~1000 LOC)
+- LocalPlaybackManager (~600 LOC)
+
+### 5.2 Oversized Widget Files
+- [ ] `expandable_player.dart` - 2,485 lines (should be <500)
+- [ ] `global_player_overlay.dart` - 737 lines
+- [ ] `new_library_screen.dart` - 2,521 lines
+
+### 5.3 Global Key Anti-Pattern
+Audit `/lib/widgets/global_player_overlay.dart`:
+- [ ] `globalPlayerKey` for state access
+- [ ] `_overlayStateKey` for overlay state
+- [ ] Should use Provider/context instead
+
+### 5.4 Primitive Obsession
+- [ ] View modes as strings ('grid2', 'grid3', 'list')
+- [ ] Media types as strings ('track', 'album', 'artist')
+- [ ] Should be strongly-typed enums
+
+---
+
+## SECTION 6: CODE QUALITY ISSUES
+
+### 6.1 Testing (CRITICAL)
+- [ ] **ZERO test files exist** - confirm this
+- [ ] No unit tests, widget tests, or integration tests
+- [ ] flutter_test dependency exists but unused
+
+### 6.2 Hardcoded Values
+Find and document all:
+- [ ] Color hex codes (50+ instances of `Color(0xFF...`)
+- [ ] Duration values not using `Timings` constants
+- [ ] Magic numbers (16, 4, 5, 100, 50)
+- [ ] String literals for media types
+
+### 6.3 Mixed Async Patterns
+- [ ] `.then()` chains alongside async/await
+- [ ] `.whenComplete()` usage
+- [ ] Consolidate to async/await
+
+### 6.4 Dead Code
+- [ ] `@Deprecated` methods still implemented
+- [ ] `animation_debugger.dart` - dev-only?
+- [ ] Unused imports
+
+### 6.5 TODO Comments
+Document all actionable TODOs:
+- [ ] `queue_screen.dart:214` - queue item removal
+- [ ] `audiobook_detail_screen.dart:261,312` - progress sync
+- [ ] `music_assistant_provider.dart:793,799` - playlist modification
+
+---
+
+## SECTION 7: UI/UX AUDIT
+
+### 7.1 Accessibility (CRITICAL)
+Audit for missing:
+- [ ] `Semantics` widgets on interactive elements
+- [ ] `Tooltip` on icon buttons
+- [ ] Screen reader support
+- [ ] Touch target sizes (minimum 48dp)
+- [ ] Color contrast validation (WCAG AA)
+
+### 7.2 Performance Issues
+Audit `/lib/widgets/expandable_player.dart`:
+- [ ] No `RepaintBoundary` wrappers
+- [ ] 55+ `setState()` calls
+- [ ] 3 AnimationControllers with multiple listeners
+- [ ] Title height cache invalidation (lines 118+)
+
+### 7.3 Double Opacity Bug
+Audit `/lib/widgets/player/player_controls.dart`:
+```dart
+color: (shuffle == true ? primaryColor : textColor.withOpacity(0.5))
+    .withOpacity(expandedElementsOpacity),
+```
+- [ ] Double `.withOpacity()` application
+
+### 7.4 Missing Features
+- [ ] No landscape orientation support
+- [ ] No tablet layout optimization
+- [ ] No loading skeleton animations
+- [ ] No haptic feedback (except one location)
+
+---
+
+## SECTION 8: AUDIO PLAYBACK AUDIT
+
+### 8.1 Position Interpolation
+Audit `/lib/services/position_tracker.dart`:
+- [ ] No timeout on anchor updates - unbounded drift possible
+- [ ] Duration interpolation can exceed track duration
+- [ ] Stale timestamp handling (>30 seconds)
+
+### 8.2 Sendspin Protocol
+Audit `/lib/services/sendspin_service.dart`:
+- [ ] Proxy auth retry without deduplication (lines 188-209)
+- [ ] WebSocket binary frame parsing
+- [ ] Clock synchronization accuracy
+
+### 8.3 Audio Resource Cleanup
+Audit `/lib/services/audio/massiv_audio_handler.dart`:
+- [ ] Audio session interrupt listeners not disposed
+- [ ] Audio focus not explicitly released
+
+### 8.4 Mixed Playback Modes
+- [ ] just_audio initialized but unused during Sendspin
+- [ ] Resource allocation for unused player
+- [ ] Potential audio focus conflicts
+
+---
+
+## SECTION 9: NETWORKING AUDIT
+
+### 9.1 WebSocket Lifecycle
+Audit `/lib/services/music_assistant_api.dart`:
+- [ ] Heartbeat interval (30s) - appropriate?
+- [ ] Reconnection logic and timing
+- [ ] Pending request cleanup on disconnect
+
+### 9.2 Caching Strategy
+- [ ] No incremental/delta sync (full library every 5 minutes)
+- [ ] Cache staleness not communicated to UI
+- [ ] No query result pagination (fetches up to 5000 items)
+
+### 9.3 Rate Limiting
+- [ ] No client-side rate limiting
+- [ ] Search requests not throttled
+- [ ] Could overload server
+
+### 9.4 Offline Support
+Audit `/lib/services/offline_action_queue.dart`:
+- [ ] Queue execution not atomic (lines 118-130)
+- [ ] Action could execute twice on crash
+- [ ] Queue stored unencrypted
+
+---
+
+## SECTION 10: DATABASE AUDIT
+
+### 10.1 Schema Review
+Audit `/lib/database/database.dart`:
+- [ ] Table indexes for query performance
+- [ ] Foreign key constraints
+- [ ] Migration strategy
+
+### 10.2 Query Patterns
+- [ ] N+1 query prevention
+- [ ] Transaction usage for atomic operations
+- [ ] Connection pooling
+
+### 10.3 Data Consistency
+- [ ] Tier 1 (DB) vs Tier 2 (API sync) race conditions
+- [ ] User modifications during background sync
+- [ ] Conflict resolution strategy
+
+---
+
+## Deliverables
+
+After completing the audit, provide:
+
+### 1. Executive Summary
+- Overall code quality score (1-10)
+- Top 5 critical issues requiring immediate attention
+- Estimated technical debt in developer-hours
+
+### 2. Issue Tracker
+Create a prioritized list of all issues found:
+| ID | Severity | Category | File:Line | Description | Effort |
+|----|----------|----------|-----------|-------------|--------|
+
+### 3. Recommended Roadmap
+Sprint-based plan to address findings:
+- Sprint 1 (Immediate): Security fixes, silent exception handlers
+- Sprint 2-3: God class decomposition, test infrastructure
+- Sprint 4-6: Memory leak fixes, accessibility
+- Long-term: Performance optimization, monitoring
+
+### 4. Code Examples
+For each CRITICAL and HIGH severity issue, provide:
+- Current problematic code
+- Recommended refactored code
+- Migration steps
+
+---
+
+## Files to Prioritize
+
+Start your audit with these critical files:
+
+1. `/lib/providers/music_assistant_provider.dart` (4,469 LOC) - God class
+2. `/lib/services/settings_service.dart` - Credential storage
+3. `/lib/services/music_assistant_api.dart` (2,929 LOC) - Networking
+4. `/lib/widgets/expandable_player.dart` (2,485 LOC) - UI complexity
+5. `/lib/services/auth/` directory - Security
+6. `/lib/models/player.dart` - Memory leaks
+7. `/lib/services/cache_service.dart` - Unbounded caches
+8. `/lib/services/position_tracker.dart` - Audio sync issues
+
+---
+
+## Known Critical Issues (Pre-Identified)
+
+These issues have been identified and MUST be verified and documented:
+
+1. **CRITICAL: Plaintext credential storage** - SharedPreferences without encryption
+2. **CRITICAL: Zero test coverage** - No unit, widget, or integration tests
+3. **CRITICAL: 4,469 line god class** - MusicAssistantProvider violates SRP
+4. **CRITICAL: Silent exception handlers** - `catch (e) {}` patterns
+5. **HIGH: Static memory leak** - `_playerCreationTimes` unbounded growth
+6. **HIGH: Race conditions** - Player state polling vs events
+7. **HIGH: No accessibility** - Missing Semantics, screen reader support
+8. **HIGH: Certificate validation disabled** - MITM vulnerability for local IPs
+9. **MEDIUM: Double opacity bug** - `.withOpacity().withOpacity()` in player controls
+10. **MEDIUM: Position tracker drift** - No timeout on anchor updates
+
+---
+
+## Audit Execution Notes
+
+- Use `Grep` tool to search for patterns across the codebase
+- Use `Read` tool to examine specific file sections
+- Document line numbers for all findings
+- Provide code snippets for context
+- Cross-reference related issues across files
+- Verify pre-identified issues exist and document their exact locations
+
+**Total estimated audit time: 4-6 hours for thorough coverage**
@@ -0,0 +1,419 @@
+# Ensemble Codebase - Comprehensive Audit Report
+
+**Audit Date:** 2026-01-01
+**Codebase:** Ensemble Flutter App (Music Assistant Client)
+**Version:** 2.7.3-beta+35
+**Total Lines of Code:** ~40,583 Dart
+**Files Analyzed:** 90 Dart files
+
+---
+
+## Executive Summary
+
+### Overall Code Quality Score: 5.5/10
+
+The Ensemble codebase demonstrates **strong architectural foundations** with a well-organized service layer, effective caching strategies, and sophisticated audio handling. However, the audit revealed **critical security vulnerabilities**, **zero test coverage**, and significant **technical debt** that must be addressed before production release.
+
+### Critical Statistics
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Test Coverage | 0% | CRITICAL |
+| God Class Size | 4,469 LOC | CRITICAL |
+| Silent Exception Handlers | 7 | CRITICAL |
+| Plaintext Credentials | 4 locations | CRITICAL |
+| Memory Leak Locations | 6 | HIGH |
+| Race Conditions | 4 | HIGH |
+| Accessibility (Semantics) | 0 widgets | CRITICAL |
+
+---
+
+## Issue Summary by Severity
+
+| Severity | Count | Categories |
+|----------|-------|------------|
+| **CRITICAL** | 12 | Security, Testing, Architecture, Accessibility |
+| **HIGH** | 18 | Memory, Race Conditions, Networking, Audio |
+| **MEDIUM** | 22 | Error Handling, UI, Caching, Code Quality |
+| **LOW** | 14 | Naming, Documentation, Minor Improvements |
+
+---
+
+## CRITICAL ISSUES (Immediate Action Required)
+
+### 1. Plaintext Credential Storage
+**File:** `/lib/services/settings_service.dart`
+**Lines:** 131-143, 147-159, 169-190, 209-222
+
+Passwords and auth tokens stored in SharedPreferences without encryption.
+
+```dart
+// VULNERABLE CODE
+static Future<void> setPassword(String? password) async {
+  final prefs = await SharedPreferences.getInstance();
+  await prefs.setString(_keyPassword, password);  // PLAINTEXT!
+}
+```
+
+**Fix:** Use `flutter_secure_storage` for all sensitive data.
+
+---
+
+### 2. Zero Test Coverage
+**Location:** Entire codebase
+
+No unit tests, widget tests, or integration tests exist. The `flutter_test` dependency is unused.
+
+**Impact:** Cannot safely refactor, high regression risk, no confidence in correctness.
+
+**Fix:** Establish test infrastructure immediately. Start with:
+- Unit tests for `MusicAssistantAPI`, `CacheService`, `ErrorHandler`
+- Widget tests for player controls
+- Integration tests for playback flows
+
+---
+
+### 3. God Class - MusicAssistantProvider
+**File:** `/lib/providers/music_assistant_provider.dart`
+**Size:** 4,469 lines, ~140 methods, 744 conditional branches
+
+Single class handles: connection, players, library, cache, audio, sync, offline queue.
+
+**Fix:** Split into:
+- `ConnectionManager` (~500 LOC)
+- `PlayerManager` (~800 LOC)
+- `LibraryCacheService` (~600 LOC)
+- `SendspinManager` (~400 LOC)
+- `MusicAssistantProvider` - Facade composing above (~800 LOC)
+
+---
+
+### 4. Zero Accessibility Support
+**Files:** `/lib/widgets/`, `/lib/screens/` (all)
+
+- **0** `Semantics` widgets
+- **0** `semanticLabel` properties
+- **1** `Tooltip` (entire app)
+- Screen readers cannot navigate the app
+
+**Fix:** Add Semantics to all interactive elements:
+```dart
+Semantics(
+  button: true,
+  label: isPlaying ? 'Pause playback' : 'Play',
+  child: IconButton(...)
+)
+```
+
+---
+
+### 5. Silent Exception Handlers
+**Locations:** 7 instances across codebase
+
+| File | Line | Code |
+|------|------|------|
+| player_provider.dart | 567, 575, 584 | `catch (e) {}` |
+| music_assistant_provider.dart | 2690 | `catch (e) {}` |
+| music_assistant_api.dart | 2542 | `catch (e) {}` |
+| recently_played_service.dart | 154, 206 | `catch (_) {}` |
+
+**Fix:** Add logging or use `firstWhereOrNull` instead of try/catch around `firstWhere`.
+
+---
+
+### 6. Audio Session Listeners Not Disposed
+**File:** `/lib/services/audio/massiv_audio_handler.dart`
+**Lines:** 45-73
+
+Stream subscriptions created but never cancelled - causes memory leaks and zombie listeners.
+
+**Fix:** Store subscriptions and cancel in dispose():
+```dart
+StreamSubscription? _interruptionSubscription;
+_interruptionSubscription = session.interruptionEventStream.listen(...);
+
+void dispose() {
+  _interruptionSubscription?.cancel();
+}
+```
+
+---
+
+## HIGH SEVERITY ISSUES
+
+### 7. Connection State Subscription Not Stored
+**File:** `/lib/providers/music_assistant_provider.dart:575-614`
+
+The `connectionState.listen()` return value is not stored - causes listener accumulation on reconnect.
+
+---
+
+### 8. Player State Race Condition
+**File:** `/lib/providers/music_assistant_provider.dart`
+
+Timer polling (every 5s) and WebSocket events can race to update `_selectedPlayer` and `_currentTrack` without mutex protection.
+
+---
+
+### 9. Async Method Reentrancy
+**File:** `/lib/providers/music_assistant_provider.dart:2713-2841`
+
+`selectPlayer()` is `void async` with no guard against concurrent calls. Multiple rapid player switches can interleave.
+
+---
+
+### 10. Unbounded Search Cache
+**File:** `/lib/services/cache_service.dart:31-32`
+
+`_searchCache` map has no size limit or proactive TTL eviction. Grows indefinitely with user searches.
+
+---
+
+### 11. Static Memory Leak
+**File:** `/lib/models/player.dart:96, 139-144`
+
+`_playerCreationTimes` static map cleanup only removes 50 of 100+ entries, allowing unbounded growth.
+
+---
+
+### 12. No Database Indexes
+**File:** `/lib/database/database.dart`
+
+No secondary indexes defined. Query performance degrades as database grows.
+
+---
+
+### 13. No Incremental Sync
+**File:** `/lib/services/sync_service.dart:150-165`
+
+Full library fetch (up to 4000 items) on every sync instead of delta updates.
+
+---
+
+### 14. Offline Queue Not Atomic
+**File:** `/lib/services/offline_action_queue.dart:80-108`
+
+Queue persistence happens after all processing - crash during processing loses successful actions.
+
+---
+
+### 15. Auth Retry Without Deduplication
+**File:** `/lib/services/sendspin_service.dart:189-209`
+
+Multiple auth messages can be sent during rapid reconnection attempts.
+
+---
+
+### 16. Pending Requests Not Completed on Disconnect
+**File:** `/lib/services/music_assistant_api.dart:2911`
+
+`_pendingRequests.clear()` abandons Completers without completing them with errors.
+
+---
+
+### 17. HTTP Fallback for Local IPs
+**File:** `/lib/services/auth/auth_manager.dart:51-58`
+
+HTTPS failures silently fall back to HTTP on local networks - MITM vulnerability.
+
+---
+
+### 18. Certificate Validation Bypassed
+**File:** `/lib/services/auth/auth_manager.dart:210-236`
+
+HTTPS redirects explicitly refused for local IPs due to expected certificate failures.
+
+---
+
+## MEDIUM SEVERITY ISSUES
+
+### 19. Double Opacity Bug
+**File:** `/lib/widgets/player/player_controls.dart:62-63, 99-100`
+
+```dart
+// BUG: .withOpacity(0.5).withOpacity(expandedElementsOpacity) compounds opacity
+color: (shuffle == true ? primaryColor : textColor.withOpacity(0.5))
+    .withOpacity(expandedElementsOpacity),
+```
+
+---
+
+### 20. Mixed Async Patterns
+**Locations:** 13 instances
+
+`.then()` chains mixed with `async/await` throughout the codebase.
+
+---
+
+### 21. Hardcoded Colors
+**Locations:** 55 instances
+
+`Color(0xFF604CEC)`, `Color(0xFF1a1a1a)` scattered across theme files and widgets.
+
+---
+
+### 22. View Modes as Strings
+**Locations:** 80+ instances
+
+`'grid2'`, `'grid3'`, `'list'` should be enums.
+
+---
+
+### 23. Fire-and-Forget Pause Commands
+**File:** `/lib/providers/music_assistant_provider.dart:3875-3894`
+
+Server pause command uses `unawaited()` - errors are silently lost.
+
+---
+
+### 24. Position Tracker Anchor Timeout Missing
+**File:** `/lib/services/position_tracker.dart:24-26`
+
+No timeout on stale anchor - interpolation can drift indefinitely.
+
+---
+
+### 25. PCM Buffer No Overflow Protection
+**File:** `/lib/services/pcm_audio_player.dart:68, 236-247`
+
+Audio buffer grows unbounded if data arrives faster than consumption.
+
+---
+
+### 26. No Client-Side Rate Limiting
+**Location:** App-wide
+
+No throttling on API requests during rapid user interactions.
+
+---
+
+### 27. Portrait-Only Lock
+**File:** `/lib/main.dart:64-68`
+
+No landscape orientation support.
+
+---
+
+### 28. Touch Targets Below 48dp
+**Files:** player_controls.dart, queue_panel.dart, player_card.dart
+
+Multiple buttons at 28x28 and 44x44 instead of minimum 48x48.
+
+---
+
+### 29. WCAG Contrast Not Validated
+**File:** `/lib/theme/palette_helper.dart`
+
+Uses 0.4 threshold instead of proper WCAG 4.5:1 contrast ratio calculation.
+
+---
+
+### 30. StreamControllers Not Closed
+**File:** `/lib/services/hardware_volume_service.dart:18-19, 74-85`
+
+`_volumeUpController` and `_volumeDownController` never closed in dispose().
+
+---
+
+## LOW SEVERITY ISSUES
+
+### 31-34. Naming Inconsistencies
+Mixed patterns: `_isLoading` vs `_isLoadingPlaylists`, various cache variable names.
+
+### 35-38. Missing TODO Implementations
+6 actionable TODOs identified (queue removal, audiobook progress sync, playlist modification).
+
+### 39-42. Dead/Unused Code
+- `@Deprecated` methods still implemented
+- `library_stats.dart` appears unused
+- `animation_debugger.dart` disabled by default
+
+### 43-44. Minor Documentation Gaps
+Missing method documentation, no architecture diagram.
+
+---
+
+## Recommended Remediation Roadmap
+
+### Sprint 1 (Week 1-2): Security & Critical Fixes
+1. Migrate credentials to `flutter_secure_storage`
+2. Add logging to all silent catch blocks
+3. Store connection state subscription
+4. Fix audio session listener disposal
+5. Add basic test infrastructure (10% coverage target)
+
+### Sprint 2 (Week 3-4): Memory & Race Conditions
+6. Add mutex to player state updates
+7. Add reentrancy guard to `selectPlayer()`
+8. Implement bounded caches with LRU eviction
+9. Fix static memory leak in Player model
+10. Store and cancel all stream subscriptions
+
+### Sprint 3 (Week 5-6): Architecture Refactoring
+11. Split `MusicAssistantProvider` into 5 smaller classes
+12. Split `expandable_player.dart` into component widgets
+13. Replace GlobalKey anti-patterns with Provider
+14. Convert string constants to enums
+15. Extract hardcoded colors to constants file
+
+### Sprint 4 (Week 7-8): Accessibility & UI
+16. Add Semantics to all interactive elements
+17. Increase touch targets to 48dp minimum
+18. Implement WCAG contrast validation
+19. Fix double opacity bug
+20. Add landscape orientation support
+
+### Sprint 5 (Week 9-10): Performance & Polish
+21. Add database indexes
+22. Implement incremental sync
+23. Add client-side rate limiting
+24. Fix atomic offline queue processing
+25. Achieve 30% test coverage target
+
+---
+
+## Files Requiring Most Attention
+
+| File | LOC | Issues | Priority |
+|------|-----|--------|----------|
+| `music_assistant_provider.dart` | 4,469 | 12 | CRITICAL |
+| `settings_service.dart` | 811 | 4 | CRITICAL |
+| `expandable_player.dart` | 2,485 | 6 | HIGH |
+| `music_assistant_api.dart` | 2,929 | 5 | HIGH |
+| `cache_service.dart` | 370 | 4 | HIGH |
+| `massiv_audio_handler.dart` | 296 | 2 | CRITICAL |
+| `player.dart` | 422 | 2 | HIGH |
+| `auth_manager.dart` | 300 | 3 | HIGH |
+
+---
+
+## Estimated Technical Debt
+
+| Category | Effort (Dev-Days) |
+|----------|-------------------|
+| Security Fixes | 3-5 |
+| Test Infrastructure | 10-15 |
+| Architecture Refactoring | 15-20 |
+| Memory Leak Fixes | 3-5 |
+| Accessibility | 5-8 |
+| UI/UX Polish | 3-5 |
+| Performance | 5-8 |
+| **Total** | **44-66 dev-days** |
+
+---
+
+## Conclusion
+
+The Ensemble app has a solid foundation with well-designed patterns for caching, audio handling, and multi-device synchronization. However, **critical security vulnerabilities** (plaintext credentials), **zero test coverage**, and a **4,469-line god class** represent significant risks that must be addressed before any production deployment.
+
+The most urgent priorities are:
+1. **Secure credential storage** - immediate security risk
+2. **Add test infrastructure** - enables safe refactoring
+3. **Split the god class** - enables maintainability
+4. **Add accessibility** - legal/compliance requirement
+
+With focused effort over 8-10 weeks, the codebase can be brought to production-quality standards.
+
+---
+
+*Audit conducted using 6 parallel specialized sub-agents analyzing security, memory management, race conditions, architecture, UI/UX, and audio/networking.*
@@ -0,0 +1,119 @@
+# Ensemble Codebase Audit Prompt
+
+Run this prompt with Claude Code to perform a comprehensive audit of the Ensemble Flutter app.
+
+---
+
+## Prompt
+
+You are performing a comprehensive code audit on the Ensemble Flutter app. This is a music/audiobook/podcast player app with 93+ Dart files.
+
+**CRITICAL RULES:**
+1. DO NOT remove or break any existing functionality
+2. All changes must be on the current branch: `audit/code-quality-review`
+3. Run `flutter analyze` after each set of changes to verify no regressions
+4. Commit changes in logical, reviewable chunks
+
+**AUDIT PHASES:**
+
+### Phase 1: Code Quality Analysis (Read-Only)
+First, analyze the codebase without making changes. Create a report covering:
+
+1. **Large File Analysis** - Review these files for refactoring opportunities:
+   - `lib/screens/new_library_screen.dart` (122KB)
+   - `lib/screens/search_screen.dart` (129KB)
+   - `lib/widgets/expandable_player.dart` (107KB)
+   - `lib/screens/album_details_screen.dart` (48KB)
+   - `lib/screens/artist_details_screen.dart` (45KB)
+
+2. **Pattern Inconsistencies** - Look for:
+   - Inconsistent naming conventions (camelCase vs snake_case)
+   - Mixed widget composition patterns
+   - Inconsistent error handling approaches
+   - Duplicate code across screens/widgets
+
+3. **Performance Red Flags** - Identify:
+   - Unnecessary rebuilds (missing const constructors)
+   - Heavy computations in build methods
+   - Missing list item caching (ListView.builder vs ListView)
+   - Inefficient state management patterns
+
+4. **Scroll Performance Issues** - Specifically audit:
+   - ScrollController usage and disposal
+   - Sliver implementations
+   - AnimatedBuilder/AnimatedWidget usage
+   - Image loading in scrollable lists
+   - Any jank-inducing patterns
+
+### Phase 2: Quick Wins (Low Risk, High Impact)
+Apply these fixes first:
+
+1. Add missing `const` constructors throughout
+2. Fix any `flutter analyze` warnings
+3. Remove dead code and unused imports
+4. Standardize formatting with `dart format`
+
+### Phase 3: Scroll Animation Optimization
+Focus on smoother scrolling:
+
+1. **Image Optimization**
+   - Ensure CachedNetworkImage is used consistently
+   - Add appropriate cacheWidth/cacheHeight
+   - Implement proper placeholder/error widgets
+
+2. **List Performance**
+   - Convert any ListView to ListView.builder where appropriate
+   - Add itemExtent where possible for fixed-height items
+   - Implement AutomaticKeepAliveClientMixin where needed
+   - Consider RepaintBoundary for complex list items
+
+3. **Animation Smoothing**
+   - Use `Curves.easeOutCubic` or similar for scroll-linked animations
+   - Ensure animations run at 60fps (avoid heavy computations during animation)
+   - Review CustomScrollView/Sliver implementations
+
+### Phase 4: Code Consistency Improvements
+
+1. **Widget Extraction**
+   - Extract repeated UI patterns into reusable widgets
+   - Ensure extracted widgets follow existing naming patterns
+
+2. **State Management**
+   - Verify Provider usage is consistent
+   - Check for proper disposal of controllers/streams
+
+3. **Error Handling**
+   - Standardize try/catch patterns
+   - Ensure consistent loading/error state UI
+
+### Phase 5: Verification
+
+After all changes:
+1. Run `flutter analyze` - must pass with 0 issues
+2. Run `flutter test` if tests exist
+3. Create a summary of all changes made
+4. List any recommendations that were NOT implemented (too risky)
+
+---
+
+## Execution Instructions
+
+```bash
+# Start the audit
+cd /home/home-server/Ensemble
+git checkout audit/code-quality-review
+
+# After each phase, commit your changes
+git add -A && git commit -m "Audit Phase X: [description]"
+
+# Verify no regressions
+flutter analyze
+```
+
+---
+
+## Expected Deliverables
+
+1. `AUDIT_REPORT.md` - Findings from Phase 1
+2. Multiple commits with clear messages for each phase
+3. `AUDIT_SUMMARY.md` - Final summary of all changes and remaining recommendations
@@ -0,0 +1,257 @@
+# Ensemble Codebase Audit Report
+
+**Date**: 2026-01-14
+**Scope**: Full codebase audit (104 Dart files, 18 screens)
+**Focus Areas**: UI Continuity, Performance, Logic/Best Practices
+
+---
+
+## Executive Summary
+
+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:
+
+| Severity | Count | Key Themes |
+|----------|-------|------------|
+| **Critical** | 6 | God classes (5,443 & 4,209 lines), design token adoption, startup blocking |
+| **High** | 15 | Touch targets, batch DB operations, over-notification, code duplication |
+| **Medium** | 25+ | Inconsistencies, memory issues, missing error boundaries |
+| **Low** | 15+ | Minor polish items |
+
+**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
+
+---
+
+## Critical Issues
+
+### 1. God Object: MusicAssistantProvider (5,443 lines)
+**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
+
+### 2. God Object: NewLibraryScreen (4,209 lines)
+**File**: `lib/screens/new_library_screen.dart`
+- 10 scroll controllers
+- 15+ view mode states
+- 15+ sort order states
+- Handles: Music, Books, Podcasts, Radio tabs
+- **Fix**: Extract to ArtistsTab, AlbumsTab, TracksTab, PlaylistsTab, BooksTab, PodcastsTab, RadioTab
+
+### 3. Sequential Blocking Startup (500-1500ms wasted)
+**File**: `lib/main.dart:33-66`
+```dart
+await DatabaseService.instance.initialize();
+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
+
+---
+
+## High Severity Issues
+
+### Performance
+| 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 |
+
+### Architecture
+| Issue | File | Impact |
+|-------|------|--------|
+| State duplication across 4 providers | providers/*.dart | Maintenance burden, sync issues |
+| 8 duplicate `_cycle*ViewMode()` methods | new_library_screen.dart:251-402 | DRY violation |
+| 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 |
+
+### UI/UX
+| 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 |
+
+---
+
+## Medium Severity Issues
+
+### 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
+
+### UI Consistency
+- Border radius varies: 8, 12, 20, 22, 25 for same element types
+- `SizedBox(height: 8)` appears 40+ times instead of `Spacing.vGap8`
+- Hardcoded colors for status (Colors.red, Colors.green)
+- Inconsistent icon sizes across screens
+
+### 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
+
+---
+
+## Quick Wins (High Impact, Low Effort)
+
+| # | Task | File(s) | Effort |
+|---|------|---------|--------|
+| 1 | Replace hardcoded bottom spacing with `BottomSpacing.withMiniPlayer` | Detail screens | 30 min |
+| 2 | Add navigation debounce to card widgets | album_card, artist_card, etc. | 1 hr |
+| 3 | Fix touch targets to 48x48 minimum | new_library_screen.dart | 15 min |
+| 4 | Add migration skip flag for SecureStorage | secure_storage_service.dart | 30 min |
+| 5 | Add Flutter error boundary | main.dart | 30 min |
+| 6 | Use `context.select()` instead of `context.watch()` | global_player_overlay, etc. | 2 hr |
+| 7 | Cache `SharedPreferences.getInstance()` | settings_service.dart | 30 min |
+
+---
+
+## Refactoring Roadmap
+
+### Phase 1: Quick Wins (1-2 days)
+- Fix touch targets
+- Fix bottom spacing
+- Add navigation debounce
+- 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.
+
+---
+
+## Positive Findings
+
+The codebase already demonstrates many good practices:
+
+- **Performance awareness**: `// PERF:` comments, RepaintBoundary (55 occurrences), image caching (80 memCacheWidth/Height)
+- **Caching**: Multi-tier caching with LRU eviction, proper TTLs, proper DB indexes
+- **Error handling**: DebugLogger, RetryHelper, OfflineActionQueue well-implemented
+- **Theme system**: Material You support, adaptive colors from album art
+- **Offline support**: Cache-first loading, graceful degradation
+- **Navigation**: Consistent FadeSlidePageRoute, proper Hero animations (mostly)
+
+---
+
+## Files by Priority
+
+| Priority | File | Lines | Key Issues |
+|----------|------|-------|------------|
+| 1 | music_assistant_provider.dart | 5,443 | God object, over-notification |
+| 2 | new_library_screen.dart | 4,209 | God class, performance, touch targets |
+| 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.
@@ -0,0 +1,57 @@
+# Audit Summary
+
+**Branch:** `audit/code-quality-review`
+**Date:** January 4, 2026
+
+## Changes Applied
+
+### Phase 1: Analysis Complete
+- Created `AUDIT_REPORT.md` with comprehensive findings
+- 4 parallel subagents analyzed const constructors, scroll performance, code duplication, and dead code
+
+### Phase 2: Deprecated API Fixes (18 files)
+- Replaced all `colorScheme.background` with `colorScheme.surface` (Material 3 compliance)
+
+**Files modified:**
+- lib/screens/library_artists_screen.dart
+- lib/screens/library_albums_screen.dart
+- lib/screens/library_playlists_screen.dart
+- lib/screens/library_tracks_screen.dart
+- lib/screens/artist_details_screen.dart
+- lib/screens/new_home_screen.dart
+- lib/screens/login_screen.dart
+- lib/screens/settings_screen.dart
+- lib/screens/album_details_screen.dart
+- lib/screens/search_screen.dart
+- lib/screens/new_library_screen.dart
+
+### Phase 3: Scroll Performance Optimization
+- Added `memCacheWidth` and `memCacheHeight` to CachedNetworkImage instances
+
+**lib/screens/new_library_screen.dart:**
+- Line 1400-1401: Author list tile image (128x128 cache)
+- Line 1487-1488: Author grid card image (256x256 cache)
+- Line 1577-1578: Audiobook list tile cover (256x256 cache)
+- Line 1749-1750: Audiobook grid cover (512x512 cache)
+- Line 1970-1971: Series list tile cover (256x256 cache)
+- Line 2986-2987: Album list tile cover (256x256 cache)
+
+## Recommendations NOT Implemented (Low Priority)
+
+These were identified but NOT changed to preserve functionality:
+
+1. **View mode cycling refactor** - 8 similar functions could be consolidated
+2. **Color constant extraction** - Duplicated colors in 3 files
+3. **EdgeInsets.zero const** - 64 instances (build-time only, minimal impact)
+4. **BorderRadius.circular const** - 40+ instances
+
+## Verification
+
+Changes should be verified by:
+1. GitHub Actions build (triggered automatically)
+2. Manual UI testing of scroll smoothness
+3. Verify no visual regressions in dark/light themes
+
+## Build Trigger
+
+GitHub Actions workflow triggered on branch `audit/code-quality-review`
@@ -20,34 +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
- **Favorites Rows** - Optional rows for Favorite Albums, Artists, and Tracks
+- **Customizable Rows** - Toggle and reorder: Recently Played, Discover Artists, Discover Albums
+- **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
- **Browse Your Collection** - Artists, albums, playlists, and tracks from all your music sources
+### Library
+- **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
- **Artist Details** - View artist albums and top tracks
- **Playlist Support** - Browse and play your playlists
- **Search** - Find music across your entire library
+- **Letter Scrollbar** - Fast navigation through long lists
+
+### Search
+- **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
+- **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
- **Caching** - Fast navigation with cached content
+- **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
@@ -57,15 +86,16 @@ This application was built with AI-assisted development using **Claude Code** an
 ## Screenshots

 <div align="center">
-  <img src="assets/screenshots/1.png" alt="Connection Screen" width="250">
-  <img src="assets/screenshots/2.png" alt="Home Screen" width="250">
-  <img src="assets/screenshots/3.png" alt="Album Details" width="250">
-</div>
-
-<div align="center">
-  <img src="assets/screenshots/4.png" alt="Now Playing" width="250">
-  <img src="assets/screenshots/5.png" alt="Device Selection" width="250">
-  <img src="assets/screenshots/6.png" alt="Settings" width="250">
+  <img src="assets/screenshots/1.png?v=3" alt="Screenshot 1" width="150">
+  <img src="assets/screenshots/2.png?v=3" alt="Screenshot 2" width="150">
+  <img src="assets/screenshots/3.png?v=3" alt="Screenshot 3" width="150">
+  <img src="assets/screenshots/4.png?v=3" alt="Screenshot 4" width="150">
+  <img src="assets/screenshots/5.png?v=3" alt="Screenshot 5" width="150">
+  <img src="assets/screenshots/6.png?v=3" alt="Screenshot 6" width="150">
+  <img src="assets/screenshots/7.png?v=3" alt="Screenshot 7" 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
@@ -75,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

@@ -94,11 +144,10 @@ Ensemble supports multiple authentication methods:

 ## Requirements

- Music Assistant server (v2.7.0 or later recommended)
+- Music Assistant server (v2.7.0 beta 20 or later recommended)
 - Network connectivity to your Music Assistant server
 - Android device (Android 5.0+)
-
-> **Note:** Local device playback (streaming to your phone) is not currently supported on Music Assistant beta 20+. This is due to MA replacing the built-in player with Sendspin. Support will be added once Sendspin is more stable. Remote control of other players works fine.
+- Audiobookshelf provider configured in Music Assistant (for audiobook features)

 ## License

@@ -0,0 +1,52 @@
+# Search Improvements
+
+Branch: `feature/search-improvements`
+
+## Completed
+
+- [x] Add playlists and audiobooks to search results
+  - Parse from MA API response
+  - Filter chips for each type
+  - Tile builders with navigation to detail screens
+
+- [x] Unified Relevance-Based "All" Results
+  - Scoring algorithm implemented:
+    - Exact match: 100 points
+    - Starts with query: 80 points
+    - Contains query (word boundary): 60 points
+    - Contains query (anywhere): 40 points
+    - Fuzzy match: 20 points
+    - Bonus for library items (albums): +10 points
+    - Bonus for favorites: +5 points
+    - Secondary field matching (artist name in albums/tracks)
+  - Merged all results into single sorted list
+  - Type indicators in subtitle (e.g., "Artist • Album")
+
+- [x] Smart Cross-Referencing
+  - Extracts unique artists from matched tracks/albums
+  - Filters to artists whose name contains query words (min 3 chars)
+  - Adds cross-referenced artists with lower relevance score (25)
+  - Avoids duplicates with direct search results
+
+- [x] Past Searches Row
+  - Added SearchHistory table to database (schema v4)
+  - Saves successful searches (deduplicated, max 10)
+  - Displays as ActionChips in empty state
+  - Clicking chip performs that search
+
+## Remaining Ideas (Lower Priority)
+
+- **Library-only toggle:** Add switch to filter search to library items only (MA API supports this)
+- **Voice search:** Add microphone button if platform supports speech recognition
+- **Search suggestions:** Typeahead from library as user types
+- **Quick actions:** Long-press result for play/queue options without navigating
+- **Clear history in settings:** Add option to clear search history
+
+## Files Modified
+
+| File | Changes |
+|------|---------|
+| `lib/database/database.dart` | Added SearchHistory table, schema v4 |
+| `lib/services/database_service.dart` | Added search history methods |
+| `lib/screens/search_screen.dart` | Relevance scoring, cross-refs, history UI |
+| `lib/l10n/app_en.arb` | Added localization strings |
@@ -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,255 @@
+# Audiobooks Integration - Implementation Plan
+
+## Overview
+
+Add audiobook support to Ensemble with automatic user profile separation based on Music Assistant authentication. Includes local database for performance caching and per-user data isolation.
+
+---
+
+## Phase 1: Database Foundation
+
+**Goal:** Add persistent local storage layer using Drift (SQLite)
+
+### Tasks
+- [ ] Add Drift package dependencies (`drift`, `drift_flutter`, `path_provider`)
+- [ ] Create database class with schema version management
+- [ ] Create `profiles` table:
+  ```dart
+  class Profiles extends Table {
+    TextColumn get username => text()();  // MA username (primary key)
+    TextColumn get displayName => text().nullable()();
+    TextColumn get source => text()();  // 'ma_auth' or 'manual'
+    DateTimeColumn get createdAt => dateTime()();
+    BoolColumn get isActive => boolean().withDefault(const Constant(false))();
+  }
+  ```
+- [ ] Create `recently_played` table:
+  ```dart
+  class RecentlyPlayed extends Table {
+    IntColumn get id => integer().autoIncrement()();
+    TextColumn get profileUsername => text().references(Profiles, #username)();
+    TextColumn get mediaId => text()();
+    TextColumn get mediaType => text()();  // 'track', 'album', 'artist', 'audiobook'
+    TextColumn get name => text()();
+    TextColumn get artist => text().nullable()();
+    TextColumn get imageUrl => text().nullable()();
+    DateTimeColumn get playedAt => dateTime()();
+  }
+  ```
+- [ ] Create `library_cache` table for albums/artists/audiobooks
+- [ ] Generate Drift code (`dart run build_runner build`)
+- [ ] Create `DatabaseService` singleton with initialization
+
+### Acceptance Criteria
+- Database initializes on app startup
+- Schema migrations work correctly
+- CRUD operations functional for all tables
+
+---
+
+## Phase 2: Profile System
+
+**Goal:** Auto-create and manage user profiles based on MA authentication
+
+### Tasks
+- [ ] Create `ProfileService` class
+- [ ] On MA login success: check if profile exists for username
+  - If not, create new profile with `displayName` from MA user info
+  - Set as active profile
+- [ ] On manual name entry (no-auth): create/select profile by entered name
+- [ ] Add `getCurrentProfile()` method
+- [ ] Migrate existing `ownerName` to profile on first launch post-update
+- [ ] Add profile indicator to settings screen (show current profile name)
+
+### Acceptance Criteria
+- Profile auto-created on first login
+- Correct profile selected on subsequent logins
+- Existing users migrated seamlessly
+
+---
+
+## Phase 3: Recently Played Migration
+
+**Goal:** Move recently played from memory cache to database, scoped by profile
+
+### Tasks
+- [ ] Update `CacheService` to use database for recently played
+- [ ] Scope all recently played queries by `profileUsername`
+- [ ] Update home screen to load recently played from database
+- [ ] Add `addRecentlyPlayed()` method that records profile + media info
+- [ ] Limit recently played to last 50 items per profile
+- [ ] Remove old memory-based recently played logic
+
+### Acceptance Criteria
+- Recently played persists across app restarts
+- Each profile sees only their own recently played
+- No cross-contamination between profiles
+
+---
+
+## Phase 4: Library Caching
+
+**Goal:** Cache library data locally for instant UI and reduced API calls
+
+### Tasks
+- [ ] Create `SyncService` for background library synchronization
+- [ ] On app launch: load from cache immediately, sync in background
+- [ ] Store albums, artists in `library_cache` table
+- [ ] Add `lastSynced` timestamp to track freshness
+- [ ] Implement delta sync (only fetch changed items if MA supports it)
+- [ ] Add pull-to-refresh that forces full sync
+- [ ] Show subtle sync indicator when background sync in progress
+
+### Acceptance Criteria
+- Home screen loads instantly from cache
+- Library tabs load instantly
+- Background sync updates data without blocking UI
+- Stale data refreshed within reasonable timeframe
+
+---
+
+## Phase 5: Scrollable Library Tabs
+
+**Goal:** Make library tab row scrollable to accommodate more tabs
+
+### Tasks
+- [ ] Convert `TabBar` to scrollable variant (`isScrollable: true`)
+- [ ] Adjust tab styling for scrollable layout
+- [ ] Ensure indicator line spans correctly
+- [ ] Test with varying number of tabs
+- [ ] Add "Books" tab placeholder (disabled until Phase 6)
+
+### Acceptance Criteria
+- Tabs scroll horizontally when they exceed screen width
+- Current tab indicator works correctly
+- Smooth scrolling experience
+
+---
+
+## Phase 6: Audiobooks Tab - Browse by Author
+
+**Goal:** Add Books tab with author → books hierarchy
+
+### Tasks
+- [ ] Add MA API method to fetch audiobooks: `getAudiobooks()`
+- [ ] Add MA API method to fetch audiobook authors
+- [ ] Create `AudiobookAuthor` model
+- [ ] Create `Audiobook` model with fields:
+  - `id`, `name`, `authors`, `narrators`, `description`
+  - `duration`, `imageUrl`, `chapters`, `resumePosition`, `fullyPlayed`
+- [ ] Create `BooksScreen` with author list view
+- [ ] Tapping author expands to show their books
+- [ ] Add to library tab bar
+- [ ] Cache audiobooks in local database
+
+### Acceptance Criteria
+- Books tab shows list of authors
+- Authors expandable to show their audiobooks
+- Audiobook covers and titles display correctly
+- Data cached locally for fast subsequent loads
+
+---
+
+## Phase 7: Audiobook Detail Screen
+
+**Goal:** Full audiobook detail view with metadata and chapters
+
+### Tasks
+- [ ] Create `AudiobookDetailScreen`
+- [ ] Display: cover art, title, author(s), narrator(s)
+- [ ] Display: description (expandable if long)
+- [ ] Display: total duration, progress indicator
+- [ ] Chapter list with:
+  - Chapter title
+  - Duration
+  - Played indicator (based on resume position)
+- [ ] Tapping chapter starts playback from that chapter
+- [ ] "Resume" button that continues from `resume_position_ms`
+- [ ] "Start Over" option
+
+### Acceptance Criteria
+- All metadata displays correctly
+- Chapters show with accurate durations
+- Resume position reflected in UI
+- Can start playback from any chapter
+
+---
+
+## Phase 8: Audiobook Playback Integration
+
+**Goal:** Proper audiobook playback with seek and resume
+
+### Tasks
+- [ ] Implement `playAudiobook(bookId, startPosition?)` method
+- [ ] Use `queueCommandSeek()` to resume at correct position
+- [ ] Update now playing UI to show:
+  - Book title instead of track
+  - Current chapter name
+  - Chapter progress (not just total progress)
+- [ ] Add skip forward/back buttons (30 sec for audiobooks?)
+- [ ] Add chapter skip buttons (next/previous chapter)
+- [ ] Record to recently played when audiobook starts (with 'audiobook' type)
+
+### Acceptance Criteria
+- Audiobooks resume from correct position
+- Chapter information shows in now playing
+- Skip controls work correctly
+- Recently played records audiobook plays
+
+---
+
+## Phase 9: Polish & Edge Cases
+
+**Goal:** Handle edge cases and improve UX
+
+### Tasks
+- [ ] Handle audiobooks with no chapters gracefully
+- [ ] Handle very long audiobooks (20+ hours)
+- [ ] Add "Mark as Finished" option
+- [ ] Add "Mark as Unplayed" option
+- [ ] Ensure offline browsing works for cached audiobooks
+- [ ] Test with various audiobook lengths and chapter counts
+- [ ] Performance testing with large audiobook libraries
+
+### Acceptance Criteria
+- No crashes on edge cases
+- Smooth performance
+- All user actions have appropriate feedback
+
+---
+
+## Future Enhancements (Out of Scope)
+
+- Sleep timer
+- Playback speed control
+- Series support (requires MA provider update)
+- Bookmarks
+- Listening statistics
+- Download for offline playback
+
+---
+
+## Technical Notes
+
+### Database Choice: Drift
+- SQLite wrapper with type-safe queries
+- Good for relational data (profiles → recently_played)
+- Mature, well-documented
+- Supports migrations
+
+### MA API Endpoints Used
+- `music/audiobooks` - List audiobooks
+- `music/audiobook/{id}` - Get audiobook details
+- `player_queues/play_media` - Start playback
+- `player_queues/seek` - Seek to position
+- `music/in_progress_items` - Get items with resume positions
+
+### Profile Data Flow
+```
+MA Login → Get user_info → Check/Create Profile → Set Active → Load Profile Data
+```
+
+### Recently Played Flow
+```
+Play Media → Check Active Profile → Insert RecentlyPlayed Row → Update UI
+```
@@ -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,5 @@
+arb-dir: lib/l10n
+template-arb-file: app_en.arb
+output-localization-file: app_localizations.dart
+synthetic-package: false
+output-class: S
@@ -13,4 +13,34 @@ class HeroTags {

  /// Artist image hero tag prefix
  static const String artistImage = 'artist_image_';
+
+  /// Audiobook cover hero tag prefix
+  static const String audiobookCover = 'audiobook_cover_';
+
+  /// Audiobook title hero tag prefix
+  static const String audiobookTitle = 'audiobook_title_';
+
+  /// Audiobook author name hero tag prefix (for navigating to author screen)
+  static const String audiobookAuthorName = 'audiobook_author_name_';
+
+  /// Audiobook author image hero tag prefix
+  static const String authorImage = 'author_image_';
+
+  /// 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_';
 }
@@ -8,8 +8,10 @@ class Timings {
  /// Player state polling interval (for selected player updates)
  static const Duration playerPollingInterval = Duration(seconds: 5);

-  /// Local player state report interval (for seek bar smoothness)
-  static const Duration localPlayerReportInterval = Duration(seconds: 1);
+  /// Local player state report interval
+  /// Note: Sendspin protocol only requires state on changes, not periodic reports.
+  /// This is mainly for local UI position tracking. Set to 5s to reduce server traffic.
+  static const Duration localPlayerReportInterval = Duration(seconds: 5);

  /// Player list cache duration before refresh
  static const Duration playersCacheDuration = Duration(minutes: 5);
@@ -29,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);
 }
@@ -0,0 +1,698 @@
+import 'package:drift/drift.dart';
+import 'package:drift_flutter/drift_flutter.dart';
+
+part 'database.g.dart';
+
+/// User profiles - auto-created from MA login or manual entry
+class Profiles extends Table {
+  /// MA username or manually entered name (primary key)
+  TextColumn get username => text()();
+
+  /// Display name from MA or same as username
+  TextColumn get displayName => text().nullable()();
+
+  /// How the profile was created: 'ma_auth' or 'manual'
+  TextColumn get source => text().withDefault(const Constant('ma_auth'))();
+
+  /// When the profile was created
+  DateTimeColumn get createdAt => dateTime().withDefault(currentDateAndTime)();
+
+  /// Whether this is the currently active profile
+  BoolColumn get isActive => boolean().withDefault(const Constant(false))();
+
+  @override
+  Set<Column> get primaryKey => {username};
+}
+
+/// Recently played items - scoped by profile
+@TableIndex(name: 'idx_recently_played_profile', columns: {#profileUsername})
+@TableIndex(name: 'idx_recently_played_profile_played', columns: {#profileUsername, #playedAt})
+class RecentlyPlayed extends Table {
+  /// Auto-incrementing ID
+  IntColumn get id => integer().autoIncrement()();
+
+  /// Profile this belongs to
+  TextColumn get profileUsername => text().references(Profiles, #username)();
+
+  /// Media item ID from Music Assistant
+  TextColumn get mediaId => text()();
+
+  /// Type: 'track', 'album', 'artist', 'playlist', 'audiobook'
+  TextColumn get mediaType => text()();
+
+  /// Display name of the item
+  TextColumn get name => text()();
+
+  /// Artist/author name (for display)
+  TextColumn get artistName => text().nullable()();
+
+  /// Image URL for the item
+  TextColumn get imageUrl => text().nullable()();
+
+  /// Additional metadata as JSON (e.g., album name for tracks)
+  TextColumn get metadata => text().nullable()();
+
+  /// When this was played
+  DateTimeColumn get playedAt => dateTime()();
+}
+
+/// Cached library items for fast startup
+@TableIndex(name: 'idx_library_cache_type', columns: {#itemType})
+@TableIndex(name: 'idx_library_cache_type_deleted', columns: {#itemType, #isDeleted})
+class LibraryCache extends Table {
+  /// Composite key: provider + item_id
+  TextColumn get cacheKey => text()();
+
+  /// Type: 'album', 'artist', 'track', 'playlist', 'audiobook', 'audiobook_author'
+  TextColumn get itemType => text()();
+
+  /// The item ID from Music Assistant
+  TextColumn get itemId => text()();
+
+  /// Serialized item data as JSON
+  TextColumn get data => text()();
+
+  /// When this was last synced from MA
+  DateTimeColumn get lastSynced => dateTime()();
+
+  /// 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};
+}
+
+/// Sync metadata - tracks last sync times per data type
+class SyncMetadata extends Table {
+  /// What was synced: 'albums', 'artists', 'audiobooks', etc.
+  TextColumn get syncType => text()();
+
+  /// When the last successful sync completed
+  DateTimeColumn get lastSyncedAt => dateTime()();
+
+  /// Number of items synced
+  IntColumn get itemCount => integer().withDefault(const Constant(0))();
+
+  @override
+  Set<Column> get primaryKey => {syncType};
+}
+
+/// Persisted playback state - survives app restarts and disconnects
+class PlaybackState extends Table {
+  /// Always 'current' - single row table
+  TextColumn get id => text().withDefault(const Constant('current'))();
+
+  /// Selected player ID
+  TextColumn get playerId => text().nullable()();
+
+  /// Selected player name (for display if player unavailable)
+  TextColumn get playerName => text().nullable()();
+
+  /// Current track as JSON
+  TextColumn get currentTrackJson => text().nullable()();
+
+  /// Current position in seconds
+  RealColumn get positionSeconds => real().withDefault(const Constant(0.0))();
+
+  /// Whether playback was active
+  BoolColumn get isPlaying => boolean().withDefault(const Constant(false))();
+
+  /// When this state was saved
+  DateTimeColumn get savedAt => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Cached player list - for instant display on app resume
+class CachedPlayers extends Table {
+  /// Player ID from Music Assistant
+  TextColumn get playerId => text()();
+
+  /// Player data as JSON
+  TextColumn get playerJson => text()();
+
+  /// Current track for this player as JSON (for mini player display)
+  TextColumn get currentTrackJson => text().nullable()();
+
+  /// When this was last updated
+  DateTimeColumn get lastUpdated => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {playerId};
+}
+
+/// Cached queue items for selected player
+@TableIndex(name: 'idx_cached_queue_player', columns: {#playerId})
+@TableIndex(name: 'idx_cached_queue_player_position', columns: {#playerId, #position})
+class CachedQueue extends Table {
+  /// Auto-incrementing ID for ordering
+  IntColumn get id => integer().autoIncrement()();
+
+  /// Player ID this queue belongs to
+  TextColumn get playerId => text()();
+
+  /// Queue item as JSON
+  TextColumn get itemJson => text()();
+
+  /// Position in queue
+  IntColumn get position => integer()();
+}
+
+/// Cached home row data for instant display on startup
+class HomeRowCache extends Table {
+  /// Row type: 'recent_albums', 'discover_artists', 'discover_albums'
+  TextColumn get rowType => text()();
+
+  /// Serialized list of items as JSON array
+  TextColumn get itemsJson => text()();
+
+  /// When this was last updated
+  DateTimeColumn get lastUpdated => dateTime()();
+
+  @override
+  Set<Column> get primaryKey => {rowType};
+}
+
+/// Search history for quick access to recent searches
+class SearchHistory extends Table {
+  /// Auto-incrementing ID
+  IntColumn get id => integer().autoIncrement()();
+
+  /// The search query
+  TextColumn get query => text()();
+
+  /// When the search was performed
+  DateTimeColumn get searchedAt => dateTime()();
+}
+
+@DriftDatabase(tables: [Profiles, RecentlyPlayed, LibraryCache, SyncMetadata, PlaybackState, CachedPlayers, CachedQueue, HomeRowCache, SearchHistory])
+class AppDatabase extends _$AppDatabase {
+  AppDatabase([QueryExecutor? executor]) : super(executor ?? _openConnection());
+
+  @override
+  int get schemaVersion => 6;
+
+  @override
+  MigrationStrategy get migration {
+    return MigrationStrategy(
+      onCreate: (Migrator m) async {
+        await m.createAll();
+      },
+      onUpgrade: (Migrator m, int from, int to) async {
+        // Migration from v1 to v2: Add playback state, cached players, cached queue tables
+        if (from < 2) {
+          await m.createTable(playbackState);
+          await m.createTable(cachedPlayers);
+          await m.createTable(cachedQueue);
+        }
+        // Migration from v2 to v3: Add home row cache table
+        if (from < 3) {
+          await m.createTable(homeRowCache);
+        }
+        // Migration from v3 to v4: Add search history table
+        if (from < 4) {
+          await m.createTable(searchHistory);
+        }
+        // Migration from v4 to v5: Add indexes for query performance
+        if (from < 5) {
+          // RecentlyPlayed indexes
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_recently_played_profile ON recently_played (profile_username)');
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_recently_played_profile_played ON recently_played (profile_username, played_at)');
+          // LibraryCache indexes
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_library_cache_type ON library_cache (item_type)');
+          await customStatement('CREATE INDEX IF NOT EXISTS idx_library_cache_type_deleted ON library_cache (item_type, is_deleted)');
+          // CachedQueue indexes
+          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 '[]'");
+        }
+      },
+    );
+  }
+
+  static QueryExecutor _openConnection() {
+    return driftDatabase(name: 'ensemble_db');
+  }
+
+  // ============================================
+  // Profile Operations
+  // ============================================
+
+  /// Get the currently active profile
+  Future<Profile?> getActiveProfile() async {
+    return (select(profiles)..where((p) => p.isActive.equals(true)))
+        .getSingleOrNull();
+  }
+
+  /// Get a profile by username
+  Future<Profile?> getProfile(String username) async {
+    return (select(profiles)..where((p) => p.username.equals(username)))
+        .getSingleOrNull();
+  }
+
+  /// Create or update a profile and set it as active
+  Future<Profile> setActiveProfile({
+    required String username,
+    String? displayName,
+    required String source,
+  }) async {
+    return transaction(() async {
+      // Deactivate all profiles
+      await (update(profiles)..where((p) => p.isActive.equals(true)))
+          .write(const ProfilesCompanion(isActive: Value(false)));
+
+      // Check if profile exists
+      final existing = await getProfile(username);
+
+      if (existing != null) {
+        // Update and activate existing profile
+        await (update(profiles)..where((p) => p.username.equals(username)))
+            .write(ProfilesCompanion(
+              displayName: Value(displayName ?? existing.displayName),
+              isActive: const Value(true),
+            ));
+      } else {
+        // Create new profile
+        await into(profiles).insert(ProfilesCompanion.insert(
+          username: username,
+          displayName: Value(displayName),
+          source: Value(source),
+          isActive: const Value(true),
+        ));
+      }
+
+      return (await getProfile(username))!;
+    });
+  }
+
+  /// Get all profiles
+  Future<List<Profile>> getAllProfiles() async {
+    return select(profiles).get();
+  }
+
+  // ============================================
+  // Recently Played Operations
+  // ============================================
+
+  /// Add an item to recently played for the active profile
+  Future<void> addRecentlyPlayed({
+    required String mediaId,
+    required String mediaType,
+    required String name,
+    String? artistName,
+    String? imageUrl,
+    String? metadata,
+  }) async {
+    final profile = await getActiveProfile();
+    if (profile == null) return;
+
+    await transaction(() async {
+      // Remove existing entry for this item (to move it to top)
+      await (delete(recentlyPlayed)
+        ..where((r) => r.profileUsername.equals(profile.username))
+        ..where((r) => r.mediaId.equals(mediaId))
+        ..where((r) => r.mediaType.equals(mediaType)))
+        .go();
+
+      // Add new entry
+      await into(recentlyPlayed).insert(RecentlyPlayedCompanion.insert(
+        profileUsername: profile.username,
+        mediaId: mediaId,
+        mediaType: mediaType,
+        name: name,
+        artistName: Value(artistName),
+        imageUrl: Value(imageUrl),
+        metadata: Value(metadata),
+        playedAt: DateTime.now(),
+      ));
+
+      // Keep only last 50 items per profile
+      final allItems = await (select(recentlyPlayed)
+        ..where((r) => r.profileUsername.equals(profile.username))
+        ..orderBy([(r) => OrderingTerm.desc(r.playedAt)]))
+        .get();
+
+      if (allItems.length > 50) {
+        final toDelete = allItems.sublist(50);
+        for (final item in toDelete) {
+          await (delete(recentlyPlayed)..where((r) => r.id.equals(item.id))).go();
+        }
+      }
+    });
+  }
+
+  /// Get recently played items for the active profile
+  Future<List<RecentlyPlayedData>> getRecentlyPlayed({int limit = 20}) async {
+    final profile = await getActiveProfile();
+    if (profile == null) return [];
+
+    return (select(recentlyPlayed)
+      ..where((r) => r.profileUsername.equals(profile.username))
+      ..orderBy([(r) => OrderingTerm.desc(r.playedAt)])
+      ..limit(limit))
+      .get();
+  }
+
+  /// Clear recently played for the active profile
+  Future<void> clearRecentlyPlayed() async {
+    final profile = await getActiveProfile();
+    if (profile == null) return;
+
+    await (delete(recentlyPlayed)
+      ..where((r) => r.profileUsername.equals(profile.username)))
+      .go();
+  }
+
+  // ============================================
+  // Library Cache Operations
+  // ============================================
+
+  /// 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';
+
+    // If sourceProvider is specified, we need to merge with existing providers
+    if (sourceProvider != null) {
+      final existing = await getCachedItem(itemType, itemId);
+      List<String> providers = [];
+      if (existing != null) {
+        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
+  Future<List<LibraryCacheData>> getCachedItems(String itemType) async {
+    return (select(libraryCache)
+      ..where((c) => c.itemType.equals(itemType))
+      ..where((c) => c.isDeleted.equals(false)))
+      .get();
+  }
+
+  /// Get a single cached item
+  Future<LibraryCacheData?> getCachedItem(String itemType, String itemId) async {
+    final cacheKey = '${itemType}_$itemId';
+    return (select(libraryCache)..where((c) => c.cacheKey.equals(cacheKey)))
+        .getSingleOrNull();
+  }
+
+  /// Mark items as deleted (soft delete)
+  Future<void> markItemsDeleted(String itemType, List<String> itemIds) async {
+    for (final itemId in itemIds) {
+      final cacheKey = '${itemType}_$itemId';
+      await (update(libraryCache)..where((c) => c.cacheKey.equals(cacheKey)))
+          .write(const LibraryCacheCompanion(isDeleted: Value(true)));
+    }
+  }
+
+  /// Clear all cached items of a type
+  Future<void> clearCache(String itemType) async {
+    await (delete(libraryCache)..where((c) => c.itemType.equals(itemType))).go();
+  }
+
+  /// Clear entire cache
+  Future<void> clearAllCache() async {
+    await delete(libraryCache).go();
+  }
+
+  // ============================================
+  // Sync Metadata Operations
+  // ============================================
+
+  /// Update sync metadata for a type
+  Future<void> updateSyncMetadata(String syncType, int itemCount) async {
+    await into(syncMetadata).insertOnConflictUpdate(SyncMetadataCompanion.insert(
+      syncType: syncType,
+      lastSyncedAt: DateTime.now(),
+      itemCount: Value(itemCount),
+    ));
+  }
+
+  /// Get last sync time for a type
+  Future<DateTime?> getLastSyncTime(String syncType) async {
+    final meta = await (select(syncMetadata)
+      ..where((s) => s.syncType.equals(syncType)))
+      .getSingleOrNull();
+    return meta?.lastSyncedAt;
+  }
+
+  /// Check if sync is needed (older than duration)
+  Future<bool> needsSync(String syncType, Duration maxAge) async {
+    final lastSync = await getLastSyncTime(syncType);
+    if (lastSync == null) return true;
+    return DateTime.now().difference(lastSync) > maxAge;
+  }
+
+  // ============================================
+  // Playback State Operations
+  // ============================================
+
+  /// Save current playback state
+  Future<void> savePlaybackState({
+    String? playerId,
+    String? playerName,
+    String? currentTrackJson,
+    double positionSeconds = 0.0,
+    bool isPlaying = false,
+  }) async {
+    await into(playbackState).insertOnConflictUpdate(PlaybackStateCompanion.insert(
+      id: const Value('current'),
+      playerId: Value(playerId),
+      playerName: Value(playerName),
+      currentTrackJson: Value(currentTrackJson),
+      positionSeconds: Value(positionSeconds),
+      isPlaying: Value(isPlaying),
+      savedAt: DateTime.now(),
+    ));
+  }
+
+  /// Get saved playback state
+  Future<PlaybackStateData?> getPlaybackState() async {
+    return (select(playbackState)..where((p) => p.id.equals('current')))
+        .getSingleOrNull();
+  }
+
+  /// Clear playback state
+  Future<void> clearPlaybackState() async {
+    await delete(playbackState).go();
+  }
+
+  // ============================================
+  // Cached Players Operations
+  // ============================================
+
+  /// Cache a player with its current track
+  Future<void> cachePlayer({
+    required String playerId,
+    required String playerJson,
+    String? currentTrackJson,
+  }) async {
+    await into(cachedPlayers).insertOnConflictUpdate(CachedPlayersCompanion.insert(
+      playerId: playerId,
+      playerJson: playerJson,
+      currentTrackJson: Value(currentTrackJson),
+      lastUpdated: DateTime.now(),
+    ));
+  }
+
+  /// Cache multiple players at once
+  Future<void> cachePlayers(List<Map<String, dynamic>> players) async {
+    await transaction(() async {
+      for (final player in players) {
+        await into(cachedPlayers).insertOnConflictUpdate(CachedPlayersCompanion.insert(
+          playerId: player['playerId'] as String,
+          playerJson: player['playerJson'] as String,
+          currentTrackJson: Value(player['currentTrackJson'] as String?),
+          lastUpdated: DateTime.now(),
+        ));
+      }
+    });
+  }
+
+  /// Get all cached players
+  Future<List<CachedPlayer>> getCachedPlayers() async {
+    return (select(cachedPlayers)
+      ..orderBy([(p) => OrderingTerm.desc(p.lastUpdated)]))
+      .get();
+  }
+
+  /// Get a specific cached player
+  Future<CachedPlayer?> getCachedPlayer(String playerId) async {
+    return (select(cachedPlayers)..where((p) => p.playerId.equals(playerId)))
+        .getSingleOrNull();
+  }
+
+  /// Update cached track for a player
+  Future<void> updateCachedPlayerTrack(String playerId, String? trackJson) async {
+    await (update(cachedPlayers)..where((p) => p.playerId.equals(playerId)))
+        .write(CachedPlayersCompanion(
+          currentTrackJson: Value(trackJson),
+          lastUpdated: Value(DateTime.now()),
+        ));
+  }
+
+  /// Clear all cached players
+  Future<void> clearCachedPlayers() async {
+    await delete(cachedPlayers).go();
+  }
+
+  // ============================================
+  // Cached Queue Operations
+  // ============================================
+
+  /// Save queue for a player
+  Future<void> saveQueue(String playerId, List<String> itemJsonList) async {
+    await transaction(() async {
+      // Clear existing queue for this player
+      await (delete(cachedQueue)..where((q) => q.playerId.equals(playerId))).go();
+
+      // Insert new queue items
+      for (var i = 0; i < itemJsonList.length; i++) {
+        await into(cachedQueue).insert(CachedQueueCompanion.insert(
+          playerId: playerId,
+          itemJson: itemJsonList[i],
+          position: i,
+        ));
+      }
+    });
+  }
+
+  /// Get cached queue for a player
+  Future<List<CachedQueueData>> getCachedQueue(String playerId) async {
+    return (select(cachedQueue)
+      ..where((q) => q.playerId.equals(playerId))
+      ..orderBy([(q) => OrderingTerm.asc(q.position)]))
+      .get();
+  }
+
+  /// Clear queue for a player
+  Future<void> clearCachedQueue(String playerId) async {
+    await (delete(cachedQueue)..where((q) => q.playerId.equals(playerId))).go();
+  }
+
+  /// Clear all cached queues
+  Future<void> clearAllCachedQueues() async {
+    await delete(cachedQueue).go();
+  }
+
+  // ============================================
+  // Home Row Cache Operations
+  // ============================================
+
+  /// Save home row data
+  Future<void> saveHomeRowCache(String rowType, String itemsJson) async {
+    await into(homeRowCache).insertOnConflictUpdate(
+      HomeRowCacheCompanion(
+        rowType: Value(rowType),
+        itemsJson: Value(itemsJson),
+        lastUpdated: Value(DateTime.now()),
+      ),
+    );
+  }
+
+  /// Get cached home row data
+  Future<HomeRowCacheData?> getHomeRowCache(String rowType) async {
+    return (select(homeRowCache)..where((h) => h.rowType.equals(rowType)))
+        .getSingleOrNull();
+  }
+
+  /// Clear all home row cache
+  Future<void> clearHomeRowCache() async {
+    await delete(homeRowCache).go();
+  }
+
+  // ============================================
+  // Search History Operations
+  // ============================================
+
+  /// Save a search query to history (deduplicates and limits to 10)
+  Future<void> saveSearchQuery(String query) async {
+    final trimmedQuery = query.trim();
+    if (trimmedQuery.isEmpty) return;
+
+    await transaction(() async {
+      // Delete existing entry with same query (case-insensitive)
+      await (delete(searchHistory)
+            ..where((s) => s.query.lower().equals(trimmedQuery.toLowerCase())))
+          .go();
+
+      // Insert the new search
+      await into(searchHistory).insert(SearchHistoryCompanion.insert(
+        query: trimmedQuery,
+        searchedAt: DateTime.now(),
+      ));
+
+      // Keep only the 10 most recent searches
+      final allSearches = await (select(searchHistory)
+            ..orderBy([(s) => OrderingTerm.desc(s.searchedAt)]))
+          .get();
+
+      if (allSearches.length > 10) {
+        final toDelete = allSearches.skip(10).map((s) => s.id).toList();
+        await (delete(searchHistory)..where((s) => s.id.isIn(toDelete))).go();
+      }
+    });
+  }
+
+  /// Get recent search queries (up to 10, most recent first)
+  Future<List<String>> getRecentSearches() async {
+    final searches = await (select(searchHistory)
+          ..orderBy([(s) => OrderingTerm.desc(s.searchedAt)])
+          ..limit(10))
+        .get();
+    return searches.map((s) => s.query).toList();
+  }
+
+  /// Clear all search history
+  Future<void> clearSearchHistory() async {
+    await delete(searchHistory).go();
+  }
+}
@@ -0,0 +1,299 @@
+{
+  "@@locale": "de",
+
+  "appTitle": "Ensemble",
+  "connecting": "Verbinde...",
+  "connected": "Verbunden",
+  "disconnected": "Getrennt",
+
+  "serverAddress": "Serveradresse",
+  "serverAddressHint": "z.B. music.example.com oder 192.168.1.100",
+  "yourName": "Dein Name",
+  "yourFirstName": "Dein Vorname",
+  "portOptional": "Port (Optional)",
+  "portHint": "z.B. 8095 oder leer lassen",
+  "portDescription": "Leer lassen bei Reverse Proxy oder Standardports. 8095 eingeben bei Direktverbindung.",
+
+  "username": "Benutzername",
+  "password": "Passwort",
+  "detectAndConnect": "Erkennen & Verbinden",
+  "connect": "Verbinden",
+  "disconnect": "Trennen",
+
+  "authServerUrlOptional": "Auth-Server URL (Optional)",
+  "authServerUrlHint": "z.B. auth.example.com (wenn abweichend vom Server)",
+  "authServerUrlDescription": "Leer lassen, wenn Authentifizierung auf demselben Server",
+  "detectedAuthType": "Erkannt: {authType}",
+  "serverRequiresAuth": "Dieser Server erfordert Authentifizierung",
+
+  "tailscaleVpnConnection": "Tailscale VPN-Verbindung",
+  "unencryptedConnection": "Unverschlusselte Verbindung",
+  "usingHttpOverTailscale": "HTTP uber Tailscale (verschlusselter Tunnel)",
+  "httpsFailedUsingHttp": "HTTPS fehlgeschlagen, verwende HTTP",
+  "httpNotEncrypted": "HTTP-Verbindung - Daten sind nicht verschlusselt",
+
+  "pleaseEnterServerAddress": "Bitte gib deine Music Assistant Serveradresse ein",
+  "pleaseEnterName": "Bitte gib deinen Namen ein",
+  "pleaseEnterValidPort": "Bitte gib eine gultige Portnummer ein (1-65535)",
+  "pleaseEnterCredentials": "Bitte gib Benutzername und Passwort ein",
+  "authFailed": "Authentifizierung fehlgeschlagen. Bitte uberprufe deine Anmeldedaten.",
+  "maLoginFailed": "Music Assistant Anmeldung fehlgeschlagen. Bitte uberprufe deine Anmeldedaten.",
+  "connectionFailed": "Verbindung zum Server fehlgeschlagen. Bitte uberprufe die Adresse und versuche es erneut.",
+  "detectingAuth": "Erkenne Authentifizierung...",
+  "cannotDetermineAuth": "Authentifizierungsanforderungen konnten nicht ermittelt werden. Bitte uberprufe die Server-URL.",
+
+  "noAuthentication": "Keine Authentifizierung",
+  "httpBasicAuth": "HTTP Basic Auth",
+  "authelia": "Authelia",
+  "musicAssistantLogin": "Music Assistant Anmeldung",
+
+  "pressBackToMinimize": "Erneut drucken zum Minimieren",
+
+  "recentlyPlayed": "Zuletzt gespielt",
+  "discoverArtists": "Kunstler entdecken",
+  "discoverAlbums": "Alben entdecken",
+  "continueListening": "Weiterhoren",
+  "discoverAudiobooks": "Horbücher entdecken",
+  "discoverSeries": "Serien entdecken",
+  "favoriteAlbums": "Lieblingsalben",
+  "favoriteArtists": "Lieblingskünstler",
+  "favoriteTracks": "Lieblingssongs",
+
+  "searchMusic": "Musik suchen...",
+  "searchForContent": "Nach Künstlern, Alben oder Songs suchen",
+  "retry": "Wiederholen",
+  "all": "Alle",
+  "artists": "Künstler",
+  "albums": "Alben",
+  "tracks": "Songs",
+  "playlists": "Wiedergabelisten",
+  "audiobooks": "Hörbücher",
+  "music": "Musik",
+  "radio": "Radio",
+  "stations": "Sender",
+  "selectLibrary": "Bibliothek auswählen",
+  "noRadioStations": "Keine Radiosender",
+  "addRadioStationsHint": "Füge Radiosender in Music Assistant hinzu",
+  "searchFailed": "Suche fehlgeschlagen. Bitte überprüfe deine Verbindung.",
+
+  "queue": "Warteschlange",
+  "playerQueue": "{playerName} Warteschlange",
+  "noPlayerSelected": "Kein Player ausgewählt",
+  "undo": "Rückgängig",
+  "removedItem": "{itemName} entfernt",
+
+  "settings": "Einstellungen",
+  "debugLogs": "Debug-Protokolle",
+  "themeMode": "Design",
+  "light": "Hell",
+  "dark": "Dunkel",
+  "system": "System",
+  "pullToRefresh": "Ziehe zum Aktualisieren der Bibliothek",
+  "viewDebugLogs": "Debug-Protokolle anzeigen",
+
+  "viewAllPlayers": "Alle Player anzeigen",
+  "copyLogs": "Protokolle kopieren",
+  "clearLogs": "Protokolle löschen",
+  "copyList": "Liste kopieren",
+  "close": "Schließen",
+  "allPlayersCount": "Alle Player ({count})",
+  "errorLoadingPlayers": "Fehler beim Laden der Player: {error}",
+  "logsCopied": "Protokolle in Zwischenablage kopiert",
+  "logsCleared": "Protokolle gelöscht",
+  "playerListCopied": "Playerliste in Zwischenablage kopiert!",
+  "noLogsYet": "Noch keine Protokolle",
+  "infoPlus": "Info+",
+  "warnings": "Warnungen",
+  "errors": "Fehler",
+  "showingEntries": "Zeige {filtered} von {total} Einträgen",
+  "thisDevice": "Dieses Gerät",
+  "ghostPlayer": "Geist-Player (Duplikat)",
+  "unavailableCorrupt": "Nicht verfügbar/Beschädigt",
+  "playerId": "ID: {id}",
+  "playerInfo": "Verfügbar: {available} | Anbieter: {provider}",
+  "shareBugReport": "Fehlerbericht teilen",
+  "moreOptions": "Weitere Optionen",
+
+  "failedToUpdateFavorite": "Favorit konnte nicht aktualisiert werden: {error}",
+  "noPlayersAvailable": "Keine Player verfügbar",
+  "albumAddedToQueue": "Album zur Warteschlange hinzugefügt",
+  "tracksAddedToQueue": "Songs zur Warteschlange hinzugefügt",
+  "play": "Abspielen",
+  "noPlayersFound": "Keine Player gefunden",
+
+  "startingRadio": "Starte {name} Radio",
+  "failedToStartRadio": "Radio konnte nicht gestartet werden: {error}",
+  "startingRadioOnPlayer": "Starte {name} Radio auf {playerName}",
+  "addedRadioToQueue": "{name} Radio zur Warteschlange hinzugefügt",
+  "failedToAddToQueue": "Konnte nicht zur Warteschlange hinzufügen: {error}",
+  "radio": "Radio",
+  "inLibrary": "In Bibliothek",
+  "noAlbumsFound": "Keine Alben gefunden",
+
+  "playing": "Spiele {name}",
+  "playingTrack": "Spiele Song",
+  "nowPlaying": "Wird gespielt",
+
+  "markedAsFinished": "{name} als beendet markiert",
+  "failedToMarkFinished": "Konnte nicht als beendet markieren: {error}",
+  "markedAsUnplayed": "{name} als ungespielt markiert",
+  "failedToMarkUnplayed": "Konnte nicht als ungespielt markieren: {error}",
+  "failedToPlay": "Abspielen fehlgeschlagen: {error}",
+  "markAsFinished": "Als beendet markieren",
+  "markAsUnplayed": "Als ungespielt markieren",
+  "byAuthor": "Von {author}",
+
+  "audiobookCount": "{count} Hörbuch/Hörbücher",
+  "loading": "Laden...",
+  "bookCount": "{count} Buch/Bücher",
+  "books": "Bücher",
+
+  "noFavoriteAudiobooks": "Keine Lieblingshörbücher",
+  "tapHeartAudiobook": "Tippe auf das Herz bei einem Hörbuch, um es zu Favoriten hinzuzufügen",
+  "noAudiobooks": "Keine Hörbücher",
+  "addAudiobooksHint": "Füge Hörbücher zu deiner Bibliothek hinzu, um sie hier zu sehen",
+
+  "noFavoriteArtists": "Keine Lieblingskünstler",
+  "tapHeartArtist": "Tippe auf das Herz bei einem Künstler, um ihn zu Favoriten hinzuzufügen",
+  "noFavoriteAlbums": "Keine Lieblingsalben",
+  "tapHeartAlbum": "Tippe auf das Herz bei einem Album, um es zu Favoriten hinzuzufügen",
+  "noFavoritePlaylists": "Keine Lieblings-Wiedergabelisten",
+  "tapHeartPlaylist": "Tippe auf das Herz bei einer Wiedergabeliste, um sie zu Favoriten hinzuzufügen",
+  "noFavoriteTracks": "Keine Lieblingssongs",
+  "longPressTrackHint": "Halte einen Song gedrückt und tippe auf das Herz, um ihn zu Favoriten hinzuzufügen",
+  "loadSeries": "Serien laden",
+
+  "notConnected": "Nicht mit Music Assistant verbunden",
+  "notConnectedTitle": "Nicht verbunden",
+  "connectHint": "Verbinde dich mit deinem Music Assistant Server, um Musik zu hören",
+  "configureServer": "Server konfigurieren",
+
+  "noArtistsFound": "Keine Künstler gefunden",
+  "noTracksFound": "Keine Songs gefunden",
+  "noPlaylistsFound": "Keine Wiedergabelisten gefunden",
+  "queueIsEmpty": "Warteschlange ist leer",
+  "noResultsFound": "Keine Ergebnisse gefunden",
+  "refresh": "Aktualisieren",
+
+  "debugConsole": "Debug-Konsole",
+  "copy": "Kopieren",
+  "clear": "Löschen",
+  "noLogsToCopy": "Keine Protokolle zum Kopieren",
+  "noDebugLogsYet": "Noch keine Debug-Protokolle. Versuche Authentifizierung zu erkennen.",
+  "showDebug": "Debug anzeigen",
+  "hideDebug": "Debug ausblenden",
+
+  "chapters": "Kapitel",
+  "noChapters": "Keine Kapitel",
+  "noChapterInfo": "Dieses Hörbuch hat keine Kapitelinformationen",
+
+  "errorSeeking": "Fehler beim Spulen: {error}",
+  "error": "Fehler: {error}",
+
+  "home": "Start",
+  "library": "Bibliothek",
+
+  "homeScreen": "Startbildschirm",
+  "metadataApis": "Metadaten-APIs",
+  "theme": "Design",
+  "materialYou": "Material You",
+  "adaptiveTheme": "Adaptives Design",
+
+  "language": "Sprache",
+  "english": "Englisch",
+  "german": "Deutsch",
+  "spanish": "Spanisch",
+  "french": "Französisch",
+
+  "noTracksInPlaylist": "Keine Songs in Wiedergabeliste",
+  "sortAlphabetically": "Alphabetisch sortieren",
+  "sortByYear": "Nach Jahr sortieren",
+  "sortBySeriesOrder": "Nach Serienreihenfolge sortieren",
+  "listView": "Listenansicht",
+  "gridView": "Rasteransicht",
+  "noBooksInSeries": "Keine Bücher in dieser Serie gefunden",
+  "artist": "Künstler",
+  "showRecentlyPlayedAlbums": "Kürzlich gespielte Alben anzeigen",
+  "showRandomArtists": "Zufällige Künstler zum Entdecken anzeigen",
+  "showRandomAlbums": "Zufällige Alben zum Entdecken anzeigen",
+  "showAudiobooksInProgress": "Hörbücher in Bearbeitung anzeigen",
+  "showRandomAudiobooks": "Zufällige Hörbücher zum Entdecken anzeigen",
+  "showRandomSeries": "Zufällige Hörbuchserien zum Entdecken anzeigen",
+  "showFavoriteAlbums": "Lieblingsalben anzeigen",
+  "showFavoriteArtists": "Lieblingskünstler anzeigen",
+  "showFavoriteTracks": "Lieblingssongs anzeigen",
+  "extractColorsFromArtwork": "Farben aus Album- und Künstlercover extrahieren",
+  "chooseHomeScreenRows": "Wähle welche Zeilen auf dem Startbildschirm angezeigt werden",
+  "addedToFavorites": "Zu Favoriten hinzugefügt",
+  "removedFromFavorites": "Aus Favoriten entfernt",
+  "unknown": "Unbekannt",
+  "noUpcomingTracks": "Keine weiteren Songs",
+  "showAll": "Alle anzeigen",
+  "showFavoritesOnly": "Nur Favoriten anzeigen",
+  "changeView": "Ansicht ändern",
+  "authors": "Autoren",
+  "series": "Serien",
+  "shows": "Sendungen",
+  "podcasts": "Podcasts",
+  "podcastSupportComingSoon": "Podcast-Unterstützung kommt bald",
+  "playlist": "Wiedergabeliste",
+  "connectionError": "Verbindungsfehler",
+  "twoColumnGrid": "2-Spalten-Raster",
+  "threeColumnGrid": "3-Spalten-Raster",
+  "fromProviders": "Von Anbietern",
+
+  "resume": "Fortsetzen",
+  "about": "Über",
+  "inProgress": "In Bearbeitung",
+  "narratedBy": "Gesprochen von {narrators}",
+  "unknownNarrator": "Unbekannter Sprecher",
+  "unknownAuthor": "Unbekannter Autor",
+  "loadingChapters": "Lade Kapitel...",
+  "noChapterInfoAvailable": "Keine Kapitelinformationen verfügbar",
+  "percentComplete": "{percent}% abgeschlossen",
+  "theAudioDbApiKey": "TheAudioDB API-Schlüssel",
+  "theAudioDbApiKeyHint": "\"2\" für kostenlosen Zugang oder Premium-Schlüssel",
+  "audiobookLibraries": "Hörbuch-Bibliotheken",
+  "chooseAudiobookLibraries": "Wähle welche Audiobookshelf-Bibliotheken einbezogen werden",
+  "unknownLibrary": "Unbekannte Bibliothek",
+  "noSeriesFound": "Keine Serien gefunden",
+  "ensembleBugReport": "Ensemble Fehlerbericht",
+  "byOwner": "Von {owner}",
+  "noSeriesAvailable": "Keine Serien in deiner Hörbuch-Bibliothek verfügbar.\nZiehe zum Aktualisieren.",
+  "pullToLoadSeries": "Ziehe nach unten um Serien\nvon Music Assistant zu laden",
+
+  "search": "Suche",
+  "metadataApisDescription": "Künstlerbilder werden automatisch von Deezer abgerufen. Füge unten API-Schlüssel für Künstlerbiografien und Albenbeschreibungen hinzu.",
+  "lastFmApiKey": "Last.fm API-Schlüssel",
+  "lastFmApiKeyHint": "Kostenlosen Schlüssel auf last.fm/api holen",
+  "swipeToSwitchDevice": "Wischen um Gerät zu wechseln",
+  "chapterNumber": "Kapitel {number}",
+  "pcmAudio": "PCM-Audio",
+  "playOn": "Abspielen auf...",
+  "addAlbumToQueueOn": "Album zur Warteschlange hinzufügen auf...",
+  "addToQueueOn": "Zur Warteschlange hinzufügen auf...",
+  "startRadioOn": "{name} Radio starten auf...",
+  "book": "Buch",
+  "audiobookSingular": "Hörbuch",
+  "trackCount": "{count} {count, plural, =1{Song} other{Songs}}",
+  "materialYouDescription": "Systemfarben verwenden (Android 12+)",
+  "accentColor": "Akzentfarbe",
+  "players": "Geräte",
+  "preferLocalPlayer": "Lokales Gerät bevorzugen",
+  "preferLocalPlayerDescription": "Dieses Gerät immer zuerst auswählen, wenn verfügbar",
+  "smartSortPlayers": "Intelligente Sortierung",
+  "smartSortPlayersDescription": "Nach Status sortieren (spielt, an, aus) statt alphabetisch",
+  "playerStateUnavailable": "Nicht verfügbar",
+  "playerStateOff": "Aus",
+  "playerStateIdle": "Inaktiv",
+  "playerStateExternalSource": "Externe Quelle",
+  "playerSelected": "Ausgewählt",
+  "actionQueuedForSync": "Wird synchronisiert wenn online",
+  "pendingOfflineActions": "{count} ausstehende Synchronisierung",
+  "hintsAndTips": "Tipps & Hinweise",
+  "showHints": "Hinweise anzeigen",
+  "showHintsDescription": "Hilfreiche Tipps zum Entdecken von Funktionen anzeigen",
+  "pullToSelectPlayers": "Ziehen um Geräte auszuwählen",
+  "holdToSync": "Gedrückt halten zum Sync",
+  "swipeToAdjustVolume": "Wischen für Lautstärke"
+}
@@ -0,0 +1,495 @@
+{
+  "@@locale": "es",
+
+  "appTitle": "Ensemble",
+  "connecting": "Conectando...",
+  "connected": "Conectado",
+  "disconnected": "Desconectado",
+  "serverAddress": "Dirección del servidor",
+  "serverAddressHint": "ej., music.example.com o 192.168.1.100",
+  "yourName": "Tu nombre",
+  "yourFirstName": "Tu nombre de pila",
+  "portOptional": "Puerto (Opcional)",
+  "portHint": "ej., 8095 o dejar en blanco",
+  "portDescription": "Dejar en blanco para proxy inverso o puertos estándar. Introduce 8095 para conexión directa.",
+  "username": "Usuario",
+  "password": "Contraseña",
+  "detectAndConnect": "Detectar y conectar",
+  "connect": "Conectar",
+  "disconnect": "Desconectar",
+  "authServerUrlOptional": "URL del servidor de autenticación (Opcional)",
+  "authServerUrlHint": "ej., auth.example.com (si es diferente del servidor)",
+  "authServerUrlDescription": "Dejar vacío si la autenticación está en el mismo servidor",
+  "detectedAuthType": "Detectado: {authType}",
+  "@detectedAuthType": {
+    "placeholders": {
+      "authType": {
+        "type": "String"
+      }
+    }
+  },
+  "serverRequiresAuth": "Este servidor requiere autenticación",
+  "tailscaleVpnConnection": "Conexión VPN Tailscale",
+  "unencryptedConnection": "Conexión sin cifrar",
+  "usingHttpOverTailscale": "Usando HTTP sobre Tailscale (túnel cifrado)",
+  "httpsFailedUsingHttp": "HTTPS falló, usando HTTP como alternativa",
+  "httpNotEncrypted": "Conexión HTTP - los datos no están cifrados",
+  "pleaseEnterServerAddress": "Por favor, introduce la dirección de tu servidor Music Assistant",
+  "pleaseEnterName": "Por favor, introduce tu nombre",
+  "pleaseEnterValidPort": "Por favor, introduce un número de puerto válido (1-65535)",
+  "pleaseEnterCredentials": "Por favor, introduce usuario y contraseña",
+  "authFailed": "Autenticación fallida. Por favor, verifica tus credenciales.",
+  "maLoginFailed": "Inicio de sesión en Music Assistant fallido. Por favor, verifica tus credenciales.",
+  "connectionFailed": "No se pudo conectar al servidor. Por favor, verifica la dirección e inténtalo de nuevo.",
+  "detectingAuth": "Detectando autenticación...",
+  "cannotDetermineAuth": "No se pueden determinar los requisitos de autenticación. Por favor, verifica la URL del servidor.",
+  "noAuthentication": "Sin autenticación",
+  "httpBasicAuth": "Autenticación HTTP Basic",
+  "authelia": "Authelia",
+  "musicAssistantLogin": "Inicio de sesión de Music Assistant",
+  "pressBackToMinimize": "Presiona atrás de nuevo para minimizar",
+  "recentlyPlayed": "Reproducido recientemente",
+  "discoverArtists": "Descubrir artistas",
+  "discoverAlbums": "Descubrir álbumes",
+  "continueListening": "Continuar escuchando",
+  "discoverAudiobooks": "Descubrir audiolibros",
+  "discoverSeries": "Descubrir series",
+  "favoriteAlbums": "Álbumes favoritos",
+  "favoriteArtists": "Artistas favoritos",
+  "favoriteTracks": "Canciones favoritas",
+  "searchMusic": "Buscar música...",
+  "searchForContent": "Buscar artistas, álbumes o canciones",
+  "retry": "Reintentar",
+  "all": "Todo",
+  "artists": "Artistas",
+  "albums": "Álbumes",
+  "tracks": "Canciones",
+  "playlists": "Listas de reproducción",
+  "audiobooks": "Audiolibros",
+  "music": "Música",
+  "radio": "Radio",
+  "stations": "Emisoras",
+  "selectLibrary": "Seleccionar Biblioteca",
+  "noRadioStations": "No hay emisoras de radio",
+  "addRadioStationsHint": "Añade emisoras de radio en Music Assistant",
+  "searchFailed": "Búsqueda fallida. Por favor, verifica tu conexión.",
+  "queue": "Cola",
+  "playerQueue": "Cola de {playerName}",
+  "@playerQueue": {
+    "placeholders": {
+      "playerName": {
+        "type": "String"
+      }
+    }
+  },
+  "noPlayerSelected": "Ningún reproductor seleccionado",
+  "undo": "Deshacer",
+  "removedItem": "Eliminado {itemName}",
+  "@removedItem": {
+    "placeholders": {
+      "itemName": {
+        "type": "String"
+      }
+    }
+  },
+  "settings": "Ajustes",
+  "debugLogs": "Registros de depuración",
+  "themeMode": "Modo de tema",
+  "light": "Claro",
+  "dark": "Oscuro",
+  "system": "Sistema",
+  "pullToRefresh": "Desliza hacia abajo para actualizar la biblioteca y aplicar los cambios",
+  "viewDebugLogs": "Ver registros de depuración",
+  "viewAllPlayers": "Ver todos los reproductores",
+  "copyLogs": "Copiar registros",
+  "clearLogs": "Borrar registros",
+  "copyList": "Copiar lista",
+  "close": "Cerrar",
+  "allPlayersCount": "Todos los reproductores ({count})",
+  "@allPlayersCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "errorLoadingPlayers": "Error al cargar reproductores: {error}",
+  "@errorLoadingPlayers": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "logsCopied": "Registros copiados al portapapeles",
+  "logsCleared": "Registros borrados",
+  "playerListCopied": "Lista de reproductores copiada al portapapeles",
+  "noLogsYet": "Aún no hay registros",
+  "infoPlus": "Info+",
+  "warnings": "Advertencias",
+  "errors": "Errores",
+  "showingEntries": "Mostrando {filtered} de {total} entradas",
+  "@showingEntries": {
+    "placeholders": {
+      "filtered": {
+        "type": "int"
+      },
+      "total": {
+        "type": "int"
+      }
+    }
+  },
+  "thisDevice": "Este dispositivo",
+  "ghostPlayer": "Reproductor fantasma (duplicado)",
+  "unavailableCorrupt": "No disponible/Corrupto",
+  "playerId": "ID: {id}",
+  "@playerId": {
+    "placeholders": {
+      "id": {
+        "type": "String"
+      }
+    }
+  },
+  "playerInfo": "Disponible: {available} | Proveedor: {provider}",
+  "@playerInfo": {
+    "placeholders": {
+      "available": {
+        "type": "String"
+      },
+      "provider": {
+        "type": "String"
+      }
+    }
+  },
+  "shareBugReport": "Compartir informe de errores",
+  "moreOptions": "Más opciones",
+  "failedToUpdateFavorite": "Error al actualizar favorito: {error}",
+  "@failedToUpdateFavorite": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "noPlayersAvailable": "No hay reproductores disponibles",
+  "albumAddedToQueue": "Álbum añadido a la cola",
+  "tracksAddedToQueue": "Canciones añadidas a la cola",
+  "play": "Reproducir",
+  "noPlayersFound": "No se encontraron reproductores",
+  "startingRadio": "Iniciando radio de {name}",
+  "@startingRadio": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToStartRadio": "Error al iniciar radio: {error}",
+  "@failedToStartRadio": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "startingRadioOnPlayer": "Iniciando radio de {name} en {playerName}",
+  "@startingRadioOnPlayer": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      },
+      "playerName": {
+        "type": "String"
+      }
+    }
+  },
+  "addedRadioToQueue": "Radio de {name} añadida a la cola",
+  "@addedRadioToQueue": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToAddToQueue": "Error al añadir a la cola: {error}",
+  "@failedToAddToQueue": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "radio": "Radio",
+  "inLibrary": "En la biblioteca",
+  "noAlbumsFound": "No se encontraron álbumes",
+  "playing": "Reproduciendo {name}",
+  "@playing": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "playingTrack": "Reproduciendo canción",
+  "nowPlaying": "Reproduciendo ahora",
+  "markedAsFinished": "{name} marcado como terminado",
+  "@markedAsFinished": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToMarkFinished": "Error al marcar como terminado: {error}",
+  "@failedToMarkFinished": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "markedAsUnplayed": "{name} marcado como no reproducido",
+  "@markedAsUnplayed": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToMarkUnplayed": "Error al marcar como no reproducido: {error}",
+  "@failedToMarkUnplayed": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "failedToPlay": "Error al reproducir: {error}",
+  "@failedToPlay": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "markAsFinished": "Marcar como terminado",
+  "markAsUnplayed": "Marcar como no reproducido",
+  "byAuthor": "Por {author}",
+  "@byAuthor": {
+    "placeholders": {
+      "author": {
+        "type": "String"
+      }
+    }
+  },
+  "audiobookCount": "{count} audiolibro(s)",
+  "@audiobookCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "loading": "Cargando...",
+  "bookCount": "{count} libro(s)",
+  "@bookCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "books": "Libros",
+  "noFavoriteAudiobooks": "No hay audiolibros favoritos",
+  "tapHeartAudiobook": "Toca el corazón en un audiolibro para añadirlo a favoritos",
+  "noAudiobooks": "No hay audiolibros",
+  "addAudiobooksHint": "Añade audiolibros a tu biblioteca para verlos aquí",
+  "noFavoriteArtists": "No hay artistas favoritos",
+  "tapHeartArtist": "Toca el corazón en un artista para añadirlo a favoritos",
+  "noFavoriteAlbums": "No hay álbumes favoritos",
+  "tapHeartAlbum": "Toca el corazón en un álbum para añadirlo a favoritos",
+  "noFavoritePlaylists": "No hay listas de reproducción favoritas",
+  "tapHeartPlaylist": "Toca el corazón en una lista para añadirla a favoritos",
+  "noFavoriteTracks": "No hay canciones favoritas",
+  "longPressTrackHint": "Mantén presionada una canción y toca el corazón para añadirla a favoritos",
+  "loadSeries": "Cargar series",
+  "notConnected": "No conectado a Music Assistant",
+  "notConnectedTitle": "No conectado",
+  "connectHint": "Conéctate a tu servidor Music Assistant para empezar a escuchar",
+  "configureServer": "Configurar servidor",
+  "noArtistsFound": "No se encontraron artistas",
+  "noTracksFound": "No se encontraron canciones",
+  "noPlaylistsFound": "No se encontraron listas de reproducción",
+  "queueIsEmpty": "La cola está vacía",
+  "noResultsFound": "No se encontraron resultados",
+  "refresh": "Actualizar",
+  "debugConsole": "Consola de depuración",
+  "copy": "Copiar",
+  "clear": "Borrar",
+  "noLogsToCopy": "No hay registros para copiar",
+  "noDebugLogsYet": "Aún no hay registros de depuración. Intenta detectar autenticación.",
+  "showDebug": "Mostrar depuración",
+  "hideDebug": "Ocultar depuración",
+  "chapters": "Capítulos",
+  "noChapters": "Sin capítulos",
+  "noChapterInfo": "Este audiolibro no tiene información de capítulos",
+  "errorSeeking": "Error al buscar: {error}",
+  "@errorSeeking": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "error": "Error: {error}",
+  "@error": {
+    "placeholders": {
+      "error": {
+        "type": "String"
+      }
+    }
+  },
+  "home": "Inicio",
+  "library": "Biblioteca",
+  "homeScreen": "Pantalla de inicio",
+  "metadataApis": "APIs de metadatos",
+  "theme": "Tema",
+  "materialYou": "Material You",
+  "adaptiveTheme": "Tema adaptativo",
+  "language": "Idioma",
+  "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",
+  "sortBySeriesOrder": "Ordenar por orden de serie",
+  "listView": "Vista de lista",
+  "gridView": "Vista de cuadrícula",
+  "noBooksInSeries": "No se encontraron libros en esta serie",
+  "artist": "Artista",
+  "showRecentlyPlayedAlbums": "Mostrar álbumes reproducidos recientemente",
+  "showRandomArtists": "Mostrar artistas aleatorios para descubrir",
+  "showRandomAlbums": "Mostrar álbumes aleatorios para descubrir",
+  "showAudiobooksInProgress": "Mostrar audiolibros en progreso",
+  "showRandomAudiobooks": "Mostrar audiolibros aleatorios para descubrir",
+  "showRandomSeries": "Mostrar series de audiolibros aleatorias para descubrir",
+  "showFavoriteAlbums": "Mostrar una fila de tus álbumes favoritos",
+  "showFavoriteArtists": "Mostrar una fila de tus artistas favoritos",
+  "showFavoriteTracks": "Mostrar una fila de tus canciones favoritas",
+  "extractColorsFromArtwork": "Extraer colores de las portadas de álbumes y artistas",
+  "chooseHomeScreenRows": "Elige qué filas mostrar en la pantalla de inicio",
+  "addedToFavorites": "Añadido a favoritos",
+  "removedFromFavorites": "Eliminado de favoritos",
+  "unknown": "Desconocido",
+  "noUpcomingTracks": "No hay canciones próximas",
+  "showAll": "Mostrar todo",
+  "showFavoritesOnly": "Mostrar solo favoritos",
+  "changeView": "Cambiar vista",
+  "authors": "Autores",
+  "series": "Series",
+  "shows": "Programas",
+  "podcasts": "Podcasts",
+  "podcastSupportComingSoon": "Soporte de podcasts próximamente",
+  "playlist": "Lista de reproducción",
+  "connectionError": "Error de conexión",
+  "twoColumnGrid": "Cuadrícula de 2 columnas",
+  "threeColumnGrid": "Cuadrícula de 3 columnas",
+  "fromProviders": "De proveedores",
+  "resume": "Continuar",
+  "about": "Acerca de",
+  "inProgress": "En progreso",
+  "narratedBy": "Narrado por {narrators}",
+  "@narratedBy": {
+    "placeholders": {
+      "narrators": {
+        "type": "String"
+      }
+    }
+  },
+  "unknownNarrator": "Narrador desconocido",
+  "unknownAuthor": "Autor desconocido",
+  "loadingChapters": "Cargando capítulos...",
+  "noChapterInfoAvailable": "No hay información de capítulos disponible",
+  "percentComplete": "{percent}% completado",
+  "@percentComplete": {
+    "placeholders": {
+      "percent": {
+        "type": "int"
+      }
+    }
+  },
+  "theAudioDbApiKey": "Clave API de TheAudioDB",
+  "theAudioDbApiKeyHint": "Usa \"2\" para nivel gratuito o clave premium",
+  "audiobookLibraries": "Bibliotecas de audiolibros",
+  "chooseAudiobookLibraries": "Elige qué bibliotecas de Audiobookshelf incluir",
+  "unknownLibrary": "Biblioteca desconocida",
+  "noSeriesFound": "No se encontraron series",
+  "ensembleBugReport": "Informe de errores de Ensemble",
+  "byOwner": "Por {owner}",
+  "@byOwner": {
+    "placeholders": {
+      "owner": {
+        "type": "String"
+      }
+    }
+  },
+  "noSeriesAvailable": "No hay series disponibles en tu biblioteca de audiolibros.\nDesliza para actualizar.",
+  "pullToLoadSeries": "Desliza hacia abajo para cargar series\ndesde Music Assistant",
+  "search": "Buscar",
+  "metadataApisDescription": "Las imágenes de artistas se obtienen automáticamente de Deezer. Añade claves API a continuación para biografías de artistas y descripciones de álbumes.",
+  "lastFmApiKey": "Clave API de Last.fm",
+  "lastFmApiKeyHint": "Obtén una clave gratuita en last.fm/api",
+  "swipeToSwitchDevice": "Desliza para cambiar dispositivo",
+  "chapterNumber": "Capítulo {number}",
+  "@chapterNumber": {
+    "placeholders": {
+      "number": {
+        "type": "int"
+      }
+    }
+  },
+  "pcmAudio": "Audio PCM",
+  "playOn": "Reproducir en...",
+  "addAlbumToQueueOn": "Añadir álbum a la cola en...",
+  "addToQueueOn": "Añadir a la cola en...",
+  "startRadioOn": "Iniciar radio de {name} en...",
+  "@startRadioOn": {
+    "placeholders": {
+      "name": {
+        "type": "String"
+      }
+    }
+  },
+  "book": "libro",
+  "audiobookSingular": "audiolibro",
+  "trackCount": "{count} {count, plural, =1{canción} other{canciones}}",
+  "@trackCount": {
+    "placeholders": {
+      "count": {
+        "type": "int"
+      }
+    }
+  },
+  "materialYouDescription": "Usar colores del sistema (Android 12+)",
+  "accentColor": "Color de acento",
+  "players": "Dispositivos",
+  "preferLocalPlayer": "Preferir dispositivo local",
+  "preferLocalPlayerDescription": "Seleccionar siempre este dispositivo primero cuando esté disponible",
+  "smartSortPlayers": "Orden inteligente",
+  "smartSortPlayersDescription": "Ordenar por estado (reproduciendo, encendido, apagado) en lugar de alfabéticamente",
+  "playerStateUnavailable": "No disponible",
+  "playerStateOff": "Apagado",
+  "playerStateIdle": "Inactivo",
+  "playerStateExternalSource": "Fuente Externa",
+  "playerSelected": "Seleccionado",
+  "actionQueuedForSync": "Se sincronizará cuando esté en línea",
+  "pendingOfflineActions": "{count} sincronización pendiente",
+  "hintsAndTips": "Consejos y Sugerencias",
+  "showHints": "Mostrar Sugerencias",
+  "showHintsDescription": "Mostrar consejos útiles para descubrir funciones",
+  "pullToSelectPlayers": "Desliza para seleccionar dispositivos",
+  "holdToSync": "Mantén presionado para sync",
+  "swipeToAdjustVolume": "Desliza para ajustar volumen"
+}
@@ -1,13 +1,20 @@
 import 'dart:async';
+import 'dart:ui';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
 import 'package:audio_service/audio_service.dart';
+import 'package:flutter_localizations/flutter_localizations.dart';
+import 'l10n/app_localizations.dart';
+import 'providers/locale_provider.dart';
 import 'providers/music_assistant_provider.dart';
 import 'providers/navigation_provider.dart';
 import 'screens/home_screen.dart';
 import 'screens/login_screen.dart';
 import 'services/settings_service.dart';
+import 'services/database_service.dart';
+import 'services/profile_service.dart';
+import 'services/sync_service.dart';
 import 'services/audio/massiv_audio_handler.dart';
 import 'services/auth/auth_manager.dart';
 import 'services/debug_logger.dart';
@@ -27,6 +34,25 @@ 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');
+
+  // Migrate existing ownerName to profile (one-time for existing users)
+  await ProfileService.instance.migrateFromOwnerName();
+
+  // Migrate credentials to secure storage (one-time for existing users)
+  await SettingsService.migrateToSecureStorage();
+  _logger.log('🔐 Secure storage migration complete');
+
+  // Load library from cache for instant startup
+  await SyncService.instance.loadFromCache();
+  _logger.log('📦 Library cache loaded');
+
  // Create auth manager for streaming headers
  final authManager = AuthManager();

@@ -50,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,
-      systemNavigationBarColor: Color(0xFF1a1a1a),
-      systemNavigationBarIconBrightness: Brightness.light,
+      statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+      systemNavigationBarColor: isDark ? const Color(0xFF1a1a1a) : const Color(0xFFF5F5F5),
+      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 {
@@ -73,6 +124,7 @@ class MusicAssistantApp extends StatefulWidget {
 class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindingObserver {
  late MusicAssistantProvider _musicProvider;
  late ThemeProvider _themeProvider;
+  late LocaleProvider _localeProvider;
  final _hardwareVolumeService = HardwareVolumeService();
  StreamSubscription? _volumeUpSub;
  StreamSubscription? _volumeDownSub;
@@ -87,6 +139,7 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
    super.initState();
    _musicProvider = MusicAssistantProvider();
    _themeProvider = ThemeProvider();
+    _localeProvider = LocaleProvider();
    WidgetsBinding.instance.addObserver(this);
    _initHardwareVolumeControl();
    // Listen to player selection changes to toggle volume interception
@@ -153,11 +206,28 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
  @override
  Future<bool> didPopRoute() async {
    // Intercept back button at app level - runs BEFORE Navigator processes it
-    // If player is expanded, collapse it and consume the back gesture
+    // Priority order: device list > queue panel > expanded player > normal navigation
+
+    // Device list has highest priority - dismiss it first
+    if (GlobalPlayerOverlay.isPlayerRevealVisible) {
+      GlobalPlayerOverlay.dismissPlayerReveal();
+      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
    if (GlobalPlayerOverlay.isPlayerExpanded) {
      GlobalPlayerOverlay.collapsePlayer();
      return true; // We handled it, don't let Navigator process it
    }
+
    // Let Navigator handle the back gesture normally
    return super.didPopRoute();
  }
@@ -183,9 +253,10 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
      providers: [
        ChangeNotifierProvider.value(value: _musicProvider),
        ChangeNotifierProvider.value(value: _themeProvider),
+        ChangeNotifierProvider.value(value: _localeProvider),
      ],
-      child: Consumer<ThemeProvider>(
-        builder: (context, themeProvider, _) {
+      child: Consumer2<ThemeProvider, LocaleProvider>(
+        builder: (context, themeProvider, localeProvider, _) {
          return FutureBuilder<(ColorScheme, ColorScheme)?>(
            future: themeProvider.useMaterialTheme
                ? SystemThemeHelper.getSystemColorSchemes()
@@ -196,14 +267,21 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
              ColorScheme? darkColorScheme;

              if (themeProvider.useMaterialTheme && snapshot.hasData && snapshot.data != null) {
-                // Use system color schemes
+                // Use system color schemes, but override background to match app design
+                // Material You doesn't set background consistently, causing black screen issues
                final (light, dark) = snapshot.data!;
-                lightColorScheme = light;
-                darkColorScheme = dark;
+                lightColorScheme = light.copyWith(
+                  surface: light.surface,
+                  background: const Color(0xFFFAFAFA), // App's preferred light background
+                );
+                darkColorScheme = dark.copyWith(
+                  surface: const Color(0xFF2a2a2a), // App's preferred dark surface
+                  background: const Color(0xFF1a1a1a), // App's preferred dark background
+                );
              } else {
-                // Use brand color schemes
-                lightColorScheme = brandLightColorScheme;
-                darkColorScheme = brandDarkColorScheme;
+                // Use custom color from theme provider
+                lightColorScheme = generateLightColorScheme(themeProvider.customColor);
+                darkColorScheme = generateDarkColorScheme(themeProvider.customColor);
              }

              return SystemUIWrapper(
@@ -214,6 +292,38 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
                  navigatorKey: navigationProvider.navigatorKey,
                  title: 'Ensemble',
                  debugShowCheckedModeBanner: false,
+                  // Localization
+                  localizationsDelegates: const [
+                    S.delegate,
+                    GlobalMaterialLocalizations.delegate,
+                    GlobalWidgetsLocalizations.delegate,
+                    GlobalCupertinoLocalizations.delegate,
+                  ],
+                  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),
@@ -290,8 +400,8 @@ class _SystemUIWrapperState extends State<SystemUIWrapper> {
          statusBarColor: Colors.transparent,
          statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
          systemNavigationBarColor: isDark
-              ? widget.darkColorScheme.background
-              : widget.lightColorScheme.background,
+              ? widget.darkColorScheme.surface
+              : widget.lightColorScheme.surface,
          systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
        ),
      );
@@ -310,7 +420,16 @@ class _SystemUIWrapperState extends State<SystemUIWrapper> {
  }
 }

-/// Startup widget that checks if user is logged in and auto-connects
+/// Startup widget that checks if user is logged in and auto-connects.
+///
+/// CRITICAL: This widget is the single source of truth for the startup transition.
+/// It loads settings FIRST (before connection), then waits for the appropriate
+/// conditions before showing HomeScreen. This eliminates the race condition between
+/// AppStartup and GlobalPlayerOverlay that caused the home screen flash.
+///
+/// For first-time users: Holds dark screen until connected + player selected,
+/// so the welcome overlay can appear seamlessly.
+/// For returning users: Transitions as soon as connection is established.
 class AppStartup extends StatefulWidget {
  const AppStartup({super.key});

@@ -323,9 +442,32 @@ class _AppStartupState extends State<AppStartup> {
  String? _savedServerUrl;
  bool _connectionAttempted = false;

+  // Welcome system state - loaded FIRST before connection check
+  bool _settingsLoaded = false;
+  bool _hasCompletedOnboarding = true; // Default to true (no welcome needed)
+
  @override
  void initState() {
    super.initState();
+    _loadSettingsFirst();
+  }
+
+  /// Load settings BEFORE checking connection.
+  /// This ensures we know if this is a first-time user before transitioning.
+  Future<void> _loadSettingsFirst() async {
+    // Load onboarding state first - this is critical for determining
+    // when to transition to HomeScreen
+    _hasCompletedOnboarding = await SettingsService.getHasCompletedOnboarding();
+
+    if (!mounted) return;
+
+    setState(() {
+      _settingsLoaded = true;
+    });
+
+    _logger.log('🚀 AppStartup: Settings loaded, hasCompletedOnboarding=$_hasCompletedOnboarding');
+
+    // Now check connection
    _checkAndConnect();
  }

@@ -350,14 +492,30 @@ class _AppStartupState extends State<AppStartup> {
      // Just wait for it to complete or timeout
      _logger.log('🚀 AppStartup: Waiting for provider auto-connection to $serverUrl');

+      // For first-time users, we need to wait for both connection AND player selection
+      // so the welcome overlay can appear immediately without home screen flash.
+      // For returning users, just wait for connection.
+      final needsWelcome = !_hasCompletedOnboarding;
+
      // Give the provider time to connect (it restores credentials and connects in _initialize)
      // Check connection state periodically
      for (var i = 0; i < 20; i++) {
        await Future.delayed(const Duration(milliseconds: 250));
-        if (provider.isConnected) {
-          _logger.log('🚀 AppStartup: Connection established');
-          break;
+
+        if (needsWelcome) {
+          // First-time user: wait for connection + player selection
+          if (provider.isConnected && provider.selectedPlayer != null) {
+            _logger.log('🚀 AppStartup: First-time user ready (connected + player selected)');
+            break;
+          }
+        } else {
+          // Returning user: just wait for connection
+          if (provider.isConnected) {
+            _logger.log('🚀 AppStartup: Connection established');
+            break;
+          }
        }
+
        if (provider.connectionState == MAConnectionState.error) {
          _logger.log('🚀 AppStartup: Connection failed with error');
          break;
@@ -384,7 +542,8 @@ class _AppStartupState extends State<AppStartup> {
  @override
  Widget build(BuildContext context) {
    // Show loading while checking settings or connecting
-    if (!_connectionAttempted || _isConnecting) {
+    // CRITICAL: Don't transition until settings are loaded - this prevents the race
+    if (!_settingsLoaded || !_connectionAttempted || _isConnecting) {
      return Scaffold(
        backgroundColor: const Color(0xFF1a1a1a),
        body: Center(
@@ -4,6 +4,10 @@ enum MediaType {
  track,
  playlist,
  radio,
+  audiobook,
+  chapter,
+  podcast,
+  podcastEpisode,
 }

 class ProviderMapping {
@@ -12,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,
@@ -19,6 +27,7 @@ class ProviderMapping {
    required this.providerInstance,
    required this.available,
    this.audioFormat,
+    this.inLibrary = true,
  });

  factory ProviderMapping.fromJson(Map<String, dynamic> json) {
@@ -28,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,
    );
  }

@@ -38,6 +49,7 @@ class ProviderMapping {
      'provider_instance': providerInstance,
      'available': available,
      if (audioFormat != null) 'audio_format': audioFormat,
+      'in_library': inLibrary,
    };
  }
 }
@@ -106,7 +118,8 @@ class MediaItem {
      'media_type': mediaType.name,
      if (sortName != null) 'sort_name': sortName,
      if (uri != null) 'uri': uri,
-      if (providerMappings != null) 'provider_mappings': providerMappings,
+      if (providerMappings != null)
+        'provider_mappings': providerMappings!.map((m) => m.toJson()).toList(),
      if (metadata != null) 'metadata': metadata,
      if (favorite != null) 'favorite': favorite,
      if (position != null) 'position': position,
@@ -140,11 +153,15 @@ class Artist extends MediaItem {
      favorite: item.favorite,
    );
  }
+
+  @override
+  Map<String, dynamic> toJson() => super.toJson();
 }

 class Album extends MediaItem {
  final List<Artist>? artists;
  final String? albumType;
+  final int? year;

  Album({
    required super.itemId,
@@ -152,6 +169,7 @@ class Album extends MediaItem {
    required super.name,
    this.artists,
    this.albumType,
+    this.year,
    super.sortName,
    super.uri,
    super.providerMappings,
@@ -161,6 +179,15 @@ class Album extends MediaItem {

  factory Album.fromJson(Map<String, dynamic> json) {
    final item = MediaItem.fromJson(json);
+    // Parse year - can be int or null
+    int? year;
+    final yearValue = json['year'];
+    if (yearValue is int) {
+      year = yearValue;
+    } else if (yearValue is String) {
+      year = int.tryParse(yearValue);
+    }
+
    return Album(
      itemId: item.itemId,
      provider: item.provider,
@@ -169,6 +196,7 @@ class Album extends MediaItem {
          ?.map((e) => Artist.fromJson(e as Map<String, dynamic>))
          .toList(),
      albumType: json['album_type'] as String?,
+      year: year,
      sortName: item.sortName,
      uri: item.uri,
      providerMappings: item.providerMappings,
@@ -179,6 +207,28 @@ class Album extends MediaItem {

  String get artistsString =>
      artists?.map((a) => a.name).join(', ') ?? 'Unknown Artist';
+
+  /// Get album name with year appended (e.g., "Album Name (2023)")
+  String get nameWithYear {
+    return year != null ? '$name ($year)' : name;
+  }
+
+  /// Check if this album is in the user's library
+  bool get inLibrary {
+    if (provider == 'library') return true;
+    return providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
+
+  @override
+  Map<String, dynamic> toJson() {
+    final json = super.toJson();
+    if (artists != null) {
+      json['artists'] = artists!.map((a) => a.toJson()).toList();
+    }
+    if (albumType != null) json['album_type'] = albumType;
+    if (year != null) json['year'] = year;
+    return json;
+  }
 }

 class Track extends MediaItem {
@@ -224,6 +274,16 @@ class Track extends MediaItem {

  String get artistsString =>
      artists?.map((a) => a.name).join(', ') ?? 'Unknown Artist';
+
+  @override
+  Map<String, dynamic> toJson() {
+    final json = super.toJson();
+    if (artists != null) {
+      json['artists'] = artists!.map((a) => a.toJson()).toList();
+    }
+    if (album != null) json['album'] = album!.toJson();
+    return json;
+  }
 }

 class Playlist extends MediaItem {
@@ -262,3 +322,363 @@ class Playlist extends MediaItem {
    );
  }
 }
+
+class Chapter {
+  final int chapterNumber;
+  final int positionMs;
+  final String title;
+  final Duration? duration;
+
+  Chapter({
+    required this.chapterNumber,
+    required this.positionMs,
+    required this.title,
+    this.duration,
+  });
+
+  factory Chapter.fromJson(Map<String, dynamic> json) {
+    // MA API returns chapters with format:
+    // {position: 1, name: "Opening Credits", start: 0.0, end: 17.6}
+    // We need to handle both this format and potential others
+
+    // Get chapter number (MA uses 'position' for chapter number)
+    int chapterNum = 0;
+    if (json['position'] is int) {
+      chapterNum = json['position'] as int;
+    } else if (json['chapter_number'] is int) {
+      chapterNum = json['chapter_number'] as int;
+    } else if (json['chapter_id'] is int) {
+      chapterNum = json['chapter_id'] as int;
+    }
+
+    // Get position in milliseconds (MA uses 'start' in seconds)
+    int posMs = 0;
+    if (json['start'] != null) {
+      // MA provides start time in seconds (can be double)
+      posMs = ((json['start'] as num) * 1000).toInt();
+    } else if (json['position_ms'] != null) {
+      posMs = json['position_ms'] as int;
+    }
+
+    // Get title (MA uses 'name')
+    String title = json['name'] as String? ??
+                   json['title'] as String? ??
+                   'Chapter $chapterNum';
+
+    // Calculate duration from start/end if available
+    Duration? dur;
+    if (json['start'] != null && json['end'] != null) {
+      final startSec = (json['start'] as num).toDouble();
+      final endSec = (json['end'] as num).toDouble();
+      dur = Duration(milliseconds: ((endSec - startSec) * 1000).toInt());
+    } else if (json['duration'] != null) {
+      dur = Duration(seconds: (json['duration'] as num).toInt());
+    }
+
+    return Chapter(
+      chapterNumber: chapterNum,
+      positionMs: posMs,
+      title: title,
+      duration: dur,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'chapter_number': chapterNumber,
+      'position_ms': positionMs,
+      'title': title,
+      if (duration != null) 'duration': duration!.inSeconds,
+    };
+  }
+}
+
+class Audiobook extends MediaItem {
+  final List<Artist>? authors;
+  final List<Artist>? narrators;
+  final String? publisher;
+  final String? description;
+  final int? year;
+  final List<Chapter>? chapters;
+  final int? resumePositionMs;
+  final bool? fullyPlayed;
+  /// Browse order from API - used as fallback for series sequencing
+  final int? browseOrder;
+
+  Audiobook({
+    required super.itemId,
+    required super.provider,
+    required super.name,
+    this.authors,
+    this.narrators,
+    this.publisher,
+    this.description,
+    this.year,
+    this.chapters,
+    this.resumePositionMs,
+    this.fullyPlayed,
+    this.browseOrder,
+    super.sortName,
+    super.uri,
+    super.providerMappings,
+    super.metadata,
+    super.favorite,
+    super.duration,
+  }) : super(mediaType: MediaType.audiobook);
+
+  factory Audiobook.fromJson(Map<String, dynamic> json) {
+    final item = MediaItem.fromJson(json);
+
+    // Parse year
+    int? year;
+    final yearValue = json['year'];
+    if (yearValue is int) {
+      year = yearValue;
+    } else if (yearValue is String) {
+      year = int.tryParse(yearValue);
+    }
+
+    // Helper to parse authors/narrators that can be either strings or Artist objects
+    List<Artist>? parseArtistList(dynamic data) {
+      if (data == null) return null;
+      if (data is! List) return null;
+
+      return data.map((e) {
+        if (e is String) {
+          // MA returns just the name as a string
+          return Artist(
+            itemId: '',
+            provider: 'library',
+            name: e,
+          );
+        } else if (e is Map<String, dynamic>) {
+          // Full Artist object
+          return Artist.fromJson(e);
+        }
+        return Artist(itemId: '', provider: 'library', name: 'Unknown');
+      }).toList();
+    }
+
+    // Parse chapters - check top level first, then metadata
+    List<Chapter>? chapters;
+    final metadata = json['metadata'] as Map<String, dynamic>?;
+
+    dynamic chaptersData = json['chapters'];
+    if (chaptersData == null && metadata != null) {
+      chaptersData = metadata['chapters'];
+    }
+
+    if (chaptersData is List && chaptersData.isNotEmpty) {
+      chapters = chaptersData
+          .map((e) => Chapter.fromJson(e as Map<String, dynamic>))
+          .toList();
+    }
+
+    // Parse description - check top level first, then metadata
+    String? description = json['description'] as String?;
+    if (description == null && metadata != null) {
+      description = metadata['description'] as String?;
+    }
+
+    return Audiobook(
+      itemId: item.itemId,
+      provider: item.provider,
+      name: item.name,
+      authors: parseArtistList(json['authors']),
+      narrators: parseArtistList(json['narrators']),
+      publisher: json['publisher'] as String?,
+      description: description,
+      year: year,
+      chapters: chapters,
+      resumePositionMs: json['resume_position_ms'] as int?,
+      fullyPlayed: json['fully_played'] as bool?,
+      browseOrder: json['_browse_order'] as int?,
+      sortName: item.sortName,
+      uri: item.uri,
+      providerMappings: item.providerMappings,
+      metadata: item.metadata,
+      favorite: item.favorite,
+      duration: item.duration,
+    );
+  }
+
+  String get authorsString =>
+      authors?.map((a) => a.name).join(', ') ?? 'Unknown Author';
+
+  String get narratorsString =>
+      narrators?.map((n) => n.name).join(', ') ?? 'Unknown Narrator';
+
+  /// Get progress as a percentage (0.0 to 1.0)
+  double get progress {
+    if (fullyPlayed == true) return 1.0;
+    if (resumePositionMs == null || duration == null) return 0.0;
+    final totalMs = duration!.inMilliseconds;
+    if (totalMs == 0) return 0.0;
+    return (resumePositionMs! / totalMs).clamp(0.0, 1.0);
+  }
+
+  /// Get series sequence number from metadata (for sorting within a series)
+  /// Tries various metadata fields commonly used by audiobook providers
+  double? get seriesSequence {
+    // First try the parent's position field (used by MA browse results)
+    if (position != null) return position!.toDouble();
+
+    // Try extracting number from sort_name (e.g., "01 - Book Title" or "Book 1")
+    if (sortName != null && sortName!.isNotEmpty) {
+      // Try to extract leading number
+      final match = RegExp(r'^(\d+)').firstMatch(sortName!);
+      if (match != null) {
+        return double.tryParse(match.group(1)!);
+      }
+      // Try to extract "Book N" pattern
+      final bookMatch = RegExp(r'[Bb]ook\s*(\d+)').firstMatch(sortName!);
+      if (bookMatch != null) {
+        return double.tryParse(bookMatch.group(1)!);
+      }
+    }
+
+    // Try extracting from the name itself
+    final nameMatch = RegExp(r'^(\d+)').firstMatch(name);
+    if (nameMatch != null) {
+      return double.tryParse(nameMatch.group(1)!);
+    }
+    final bookNameMatch = RegExp(r'[Bb]ook\s*(\d+)').firstMatch(name);
+    if (bookNameMatch != null) {
+      return double.tryParse(bookNameMatch.group(1)!);
+    }
+
+    if (metadata == null) return null;
+
+    // Try common metadata fields for series sequence
+    final seq = metadata!['sequence'] ??
+                metadata!['series_sequence'] ??
+                metadata!['series_number'] ??
+                metadata!['position'] ??
+                metadata!['sort_order'] ??
+                metadata!['order'];
+
+    if (seq is num) return seq.toDouble();
+    if (seq is String) return double.tryParse(seq);
+
+    // Check if there's a series object with sequence
+    final series = metadata!['series'];
+    if (series is Map) {
+      final seriesSeq = series['sequence'] ?? series['number'] ?? series['order'];
+      if (seriesSeq is num) return seriesSeq.toDouble();
+      if (seriesSeq is String) return double.tryParse(seriesSeq);
+    }
+    if (series is List && series.isNotEmpty) {
+      final first = series.first;
+      if (first is Map) {
+        final seriesSeq = first['sequence'] ?? first['number'] ?? first['order'];
+        if (seriesSeq is num) return seriesSeq.toDouble();
+        if (seriesSeq is String) return double.tryParse(seriesSeq);
+      }
+    }
+
+    // Last resort: use browse order from API (preserves MA/Audiobookshelf order)
+    if (browseOrder != null) return browseOrder!.toDouble();
+
+    return null;
+  }
+
+  @override
+  Map<String, dynamic> toJson() {
+    final json = super.toJson();
+    if (authors != null) {
+      json['authors'] = authors!.map((a) => a.toJson()).toList();
+    }
+    if (narrators != null) {
+      json['narrators'] = narrators!.map((n) => n.toJson()).toList();
+    }
+    if (publisher != null) json['publisher'] = publisher;
+    if (description != null) json['description'] = description;
+    if (year != null) json['year'] = year;
+    if (chapters != null) {
+      json['chapters'] = chapters!.map((c) => c.toJson()).toList();
+    }
+    if (resumePositionMs != null) json['resume_position_ms'] = resumePositionMs;
+    if (fullyPlayed != null) json['fully_played'] = fullyPlayed;
+    if (browseOrder != null) json['_browse_order'] = browseOrder;
+    return json;
+  }
+}
+
+/// Represents a browseable folder in Music Assistant (providers, series, authors, etc.)
+class BrowseFolder {
+  final String path;
+  final String name;
+  final String? label;
+  final String? thumbnailUrl;
+  final bool canExpand;
+  final List<MediaItem>? items;
+
+  BrowseFolder({
+    required this.path,
+    required this.name,
+    this.label,
+    this.thumbnailUrl,
+    this.canExpand = true,
+    this.items,
+  });
+
+  factory BrowseFolder.fromJson(Map<String, dynamic> json) {
+    // MA returns either a BrowseFolder or a MediaItem
+    // BrowseFolder has 'path' and 'name', MediaItem has 'item_id' and 'media_type'
+    return BrowseFolder(
+      path: json['path'] as String? ?? json['uri'] as String? ?? '',
+      name: json['name'] as String? ?? json['label'] as String? ?? 'Unknown',
+      label: json['label'] as String?,
+      thumbnailUrl: _extractThumbnail(json),
+      canExpand: json['can_expand'] as bool? ?? true,
+    );
+  }
+
+  static String? _extractThumbnail(Map<String, dynamic> json) {
+    // Check for image in metadata
+    final metadata = json['metadata'] as Map<String, dynamic>?;
+    if (metadata != null) {
+      final images = metadata['images'] as List<dynamic>?;
+      if (images != null && images.isNotEmpty) {
+        final first = images.first as Map<String, dynamic>;
+        return first['path'] as String?;
+      }
+    }
+    // Check for direct thumbnail
+    return json['thumbnail'] as String? ?? json['image'] as String?;
+  }
+}
+
+/// Represents an audiobook series
+class AudiobookSeries {
+  final String id;
+  final String name;
+  final String? thumbnailUrl;
+  final List<Audiobook>? books;
+  final int? bookCount;
+
+  AudiobookSeries({
+    required this.id,
+    required this.name,
+    this.thumbnailUrl,
+    this.books,
+    this.bookCount,
+  });
+
+  factory AudiobookSeries.fromBrowseFolder(BrowseFolder folder) {
+    return AudiobookSeries(
+      id: folder.path,
+      name: folder.name,
+      thumbnailUrl: folder.thumbnailUrl,
+    );
+  }
+
+  factory AudiobookSeries.fromJson(Map<String, dynamic> json) {
+    return AudiobookSeries(
+      id: json['path'] as String? ?? json['id'] as String? ?? '',
+      name: json['name'] as String? ?? json['label'] as String? ?? 'Unknown Series',
+      thumbnailUrl: BrowseFolder._extractThumbnail(json),
+      bookCount: json['book_count'] as int?,
+    );
+  }
+}
@@ -12,6 +12,11 @@ class Player {
  final bool? volumeMuted;
  final double? elapsedTime; // Seconds elapsed in current track
  final double? elapsedTimeLastUpdated; // Unix timestamp when elapsed_time was last updated
+  final List<String>? groupMembers; // List of player IDs in sync group (includes self)
+  final String? syncedTo; // Player ID this player is synced to (null if leader or not synced)
+  final String? activeSource; // The currently active source for this player
+  final bool isExternalSource; // True when an external source (optical, Spotify, etc.) is active
+  final String? appId; // The app_id from MA - 'music_assistant' when MA is playing, else external source

  Player({
    required this.playerId,
@@ -25,15 +30,88 @@ class Player {
    this.volumeMuted,
    this.elapsedTime,
    this.elapsedTimeLastUpdated,
+    this.groupMembers,
+    this.syncedTo,
+    this.activeSource,
+    this.isExternalSource = false,
+    this.appId,
  });

+  /// Create a copy of this Player with some fields replaced
+  Player copyWith({
+    String? playerId,
+    String? name,
+    String? provider,
+    bool? available,
+    bool? powered,
+    String? state,
+    String? currentItemId,
+    int? volumeLevel,
+    bool? volumeMuted,
+    double? elapsedTime,
+    double? elapsedTimeLastUpdated,
+    List<String>? groupMembers,
+    String? syncedTo,
+    String? activeSource,
+    bool? isExternalSource,
+    String? appId,
+  }) {
+    return Player(
+      playerId: playerId ?? this.playerId,
+      name: name ?? this.name,
+      provider: provider ?? this.provider,
+      available: available ?? this.available,
+      powered: powered ?? this.powered,
+      state: state ?? this.state,
+      currentItemId: currentItemId ?? this.currentItemId,
+      volumeLevel: volumeLevel ?? this.volumeLevel,
+      volumeMuted: volumeMuted ?? this.volumeMuted,
+      elapsedTime: elapsedTime ?? this.elapsedTime,
+      elapsedTimeLastUpdated: elapsedTimeLastUpdated ?? this.elapsedTimeLastUpdated,
+      groupMembers: groupMembers ?? this.groupMembers,
+      syncedTo: syncedTo ?? this.syncedTo,
+      activeSource: activeSource ?? this.activeSource,
+      isExternalSource: isExternalSource ?? this.isExternalSource,
+      appId: appId ?? this.appId,
+    );
+  }
+
  // Derived properties
  bool get isPlaying => state == 'playing';
  bool get isMuted => volumeMuted ?? false;
  int get volume => volumeLevel ?? 0;

+  // Group properties
+  // A player is grouped if it's a leader with members OR a child synced to another
+  bool get isGrouped => (groupMembers != null && groupMembers!.length > 1) || syncedTo != null;
+  bool get isGroupLeader => groupMembers != null && groupMembers!.length > 1 && syncedTo == null;
+  bool get isGroupChild => syncedTo != null;
+
+  // A player is manually synced if it's synced TO another player (child of a sync group)
+  // This excludes pre-configured MA speaker groups which have groupMembers but no syncedTo
+  // Used for yellow border highlight - only shows for players the user manually synced
+  bool get isManuallySynced => syncedTo != null;
+
  // Track when this Player object was created (for local interpolation fallback)
  static final Map<String, double> _playerCreationTimes = {};
+  static const int _maxCreationTimesEntries = 50;
+
+  /// Clean up old creation time entries using LRU eviction
+  static void _cleanupCreationTimes() {
+    if (_playerCreationTimes.length <= _maxCreationTimesEntries) return;
+
+    // Sort by timestamp value (oldest first) for true LRU eviction
+    final sortedEntries = _playerCreationTimes.entries.toList()
+      ..sort((a, b) => a.value.compareTo(b.value));
+
+    // Remove oldest entries until we're at target size
+    final entriesToRemove = sortedEntries.take(
+      _playerCreationTimes.length - _maxCreationTimesEntries,
+    );
+    for (final entry in entriesToRemove) {
+      _playerCreationTimes.remove(entry.key);
+    }
+  }

  // Calculate current elapsed time (interpolated if playing)
  double get currentElapsedTime {
@@ -75,13 +153,8 @@ class Player {
    if (!_playerCreationTimes.containsKey(creationKey)) {
      // First time seeing this elapsed_time - record when we saw it
      _playerCreationTimes[creationKey] = now;
-      // Clean up old entries to prevent memory leak
-      if (_playerCreationTimes.length > 100) {
-        final keysToRemove = _playerCreationTimes.keys.take(50).toList();
-        for (final key in keysToRemove) {
-          _playerCreationTimes.remove(key);
-        }
-      }
+      // Clean up old entries to prevent memory leak (LRU eviction)
+      _cleanupCreationTimes();
    }

    final creationTime = _playerCreationTimes[creationKey]!;
@@ -135,6 +208,68 @@ class Player {
    elapsedTime ??= topLevelElapsedTime;
    elapsedTimeLastUpdated ??= topLevelLastUpdated;

+    // Parse group members - MA returns this as a list of player IDs
+    final groupMembersList = json['group_members'] as List<dynamic>?;
+    final groupMembers = groupMembersList?.map((e) => e.toString()).toList();
+
+    // Parse synced_to - the player ID this player is synced to
+    final syncedTo = json['synced_to'] as String?;
+
+    // Parse active_source - the currently active source for this player
+    final activeSource = json['active_source'] as String?;
+
+    // Detect external source (optical, Spotify, AirPlay, etc.)
+    // Primary indicator: app_id - if not 'music_assistant', it's an external source
+    // Secondary indicators: URI patterns and media_type
+    bool isExternalSource = false;
+
+    // Check app_id first - this is the most reliable indicator for DLNA players
+    // When MA is playing: app_id = 'music_assistant'
+    // When external source: app_id = 'http', 'spotify', etc.
+    final appId = json['app_id'] as String?;
+    if (appId != null && appId.isNotEmpty && appId != 'music_assistant') {
+      // app_id is set but not 'music_assistant' - external source is active
+      isExternalSource = true;
+    }
+
+    // Also check current_media for additional external source indicators
+    if (!isExternalSource && json.containsKey('current_media')) {
+      final currentMedia = json['current_media'] as Map<String, dynamic>?;
+      if (currentMedia != null) {
+        final uri = currentMedia['uri'] as String?;
+        final mediaType = currentMedia['media_type'] as String?;
+
+        // External source indicators:
+        // 1. URI is a simple identifier like 'optical', 'line_in', 'bluetooth', 'hdmi'
+        // 2. URI starts with external protocols: 'spotify://', 'airplay://', etc.
+        // 3. Media type is 'unknown' (MA doesn't recognize the source)
+        if (uri != null) {
+          final uriLower = uri.toLowerCase();
+          // Simple external source identifiers (no :// or /)
+          final isSimpleExternalId = !uri.contains('://') && !uri.contains('/') &&
+              (uriLower == 'optical' || uriLower == 'line_in' || uriLower == 'bluetooth' ||
+               uriLower == 'hdmi' || uriLower == 'tv' || uriLower == 'aux' ||
+               uriLower == 'coaxial' || uriLower == 'toslink');
+          // External streaming protocols
+          final isExternalProtocol = uriLower.startsWith('spotify://') ||
+              uriLower.startsWith('airplay://') ||
+              uriLower.startsWith('cast://') ||
+              uriLower.startsWith('bluetooth://');
+
+          isExternalSource = isSimpleExternalId || isExternalProtocol;
+        }
+
+        // Also check media_type - 'unknown' often indicates external source
+        if (!isExternalSource && mediaType == 'unknown') {
+          // If media_type is unknown and URI doesn't look like MA content, it's external
+          final uri = currentMedia['uri'] as String?;
+          if (uri != null && !uri.startsWith('library://') && !uri.contains('://track/')) {
+            isExternalSource = true;
+          }
+        }
+      }
+    }
+
    return Player(
      playerId: json['player_id'] as String,
      name: json['name'] as String,
@@ -147,6 +282,11 @@ class Player {
      volumeMuted: json['volume_muted'] as bool?,
      elapsedTime: elapsedTime,
      elapsedTimeLastUpdated: elapsedTimeLastUpdated,
+      groupMembers: groupMembers,
+      syncedTo: syncedTo,
+      activeSource: activeSource,
+      isExternalSource: isExternalSource,
+      appId: appId,
    );
  }

@@ -163,6 +303,11 @@ class Player {
      if (volumeMuted != null) 'volume_muted': volumeMuted,
      if (elapsedTime != null) 'elapsed_time': elapsedTime,
      if (elapsedTimeLastUpdated != null) 'elapsed_time_last_updated': elapsedTimeLastUpdated,
+      if (groupMembers != null) 'group_members': groupMembers,
+      if (syncedTo != null) 'synced_to': syncedTo,
+      if (activeSource != null) 'active_source': activeSource,
+      'is_external_source': isExternalSource,
+      if (appId != null) 'app_id': appId,
    };
  }
 }
@@ -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;
+}
@@ -1,239 +0,0 @@
-import 'dart:async';
-import 'package:flutter/foundation.dart';
-import '../services/music_assistant_api.dart';
-import '../services/settings_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
-/// Handles WebSocket connection, authentication, and reconnection
-class ConnectionProvider with ChangeNotifier {
-  MusicAssistantAPI? _api;
-  final AuthManager _authManager = AuthManager();
-  final DebugLogger _logger = DebugLogger();
-  final CacheService _cacheService = CacheService();
-
-  MAConnectionState _connectionState = MAConnectionState.disconnected;
-  String? _serverUrl;
-  String? _error;
-
-  // Callbacks for post-connection initialization
-  VoidCallback? onConnected;
-  VoidCallback? onAuthenticated;
-  VoidCallback? onDisconnected;
-
-  MAConnectionState get connectionState => _connectionState;
-  String? get serverUrl => _serverUrl;
-  String? get error => _error;
-  bool get isConnected => _connectionState == MAConnectionState.connected ||
-                          _connectionState == MAConnectionState.authenticated;
-
-  MusicAssistantAPI? get api => _api;
-  AuthManager get authManager => _authManager;
-  CacheService get cacheService => _cacheService;
-
-  ConnectionProvider() {
-    _initialize();
-  }
-
-  Future<void> _initialize() async {
-    _serverUrl = await SettingsService.getServerUrl();
-    if (_serverUrl != null && _serverUrl!.isNotEmpty) {
-      await _restoreAuthCredentials();
-      await connectToServer(_serverUrl!);
-    }
-  }
-
-  /// Restore auth credentials from persistent storage
-  Future<void> _restoreAuthCredentials() async {
-    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
-  Future<bool> handleMaAuthentication() 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
-  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');
-      } 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
-      await _api?.disconnect();
-
-      _api = MusicAssistantAPI(serverUrl, _authManager);
-
-      // Listen to connection state changes
-      _api!.connectionState.listen(
-        (state) async {
-          _connectionState = state;
-          notifyListeners();
-
-          if (state == MAConnectionState.connected) {
-            _logger.log('🔗 WebSocket connected to MA server');
-
-            if (_api!.authRequired && !_api!.isAuthenticated) {
-              _logger.log('🔐 MA auth required, attempting authentication...');
-              final authenticated = await handleMaAuthentication();
-              if (!authenticated) {
-                _logger.log('❌ MA authentication failed - stopping connection flow');
-                _error = 'Authentication required. Please log in again.';
-                notifyListeners();
-                return;
-              }
-              return;
-            }
-
-            // No auth required - notify connected
-            onConnected?.call();
-          } else if (state == MAConnectionState.authenticated) {
-            _logger.log('✅ MA authentication successful');
-            onAuthenticated?.call();
-          } else if (state == MAConnectionState.disconnected) {
-            _cacheService.clearAll();
-            onDisconnected?.call();
-          }
-        },
-        onError: (error) {
-          _logger.log('Connection state stream error: $error');
-          _connectionState = MAConnectionState.error;
-          notifyListeners();
-        },
-      );
-
-      await _api!.connect();
-      notifyListeners();
-    } catch (e) {
-      final errorInfo = ErrorHandler.handleError(e, context: 'Connect to server');
-      _error = errorInfo.userMessage;
-      _connectionState = MAConnectionState.error;
-      _logger.log('Connection error: ${errorInfo.technicalMessage}');
-      notifyListeners();
-      rethrow;
-    }
-  }
-
-  Future<void> disconnect() async {
-    await _api?.disconnect();
-    _connectionState = MAConnectionState.disconnected;
-    _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) {
-      _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() {
-    _api?.dispose();
-    super.dispose();
-  }
-}
@@ -1,383 +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 '../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();
-
-      final results = await Future.wait([
-        _api!.getArtists(limit: LibraryConstants.maxLibraryItems),
-        _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();
-
-      _artists = await _api!.getArtists(
-        limit: limit ?? LibraryConstants.maxLibraryItems,
-        offset: offset,
-        search: search,
-      );
-
-      _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();
-  }
-}
@@ -0,0 +1,44 @@
+import 'package:flutter/material.dart';
+import '../services/settings_service.dart';
+
+class LocaleProvider extends ChangeNotifier {
+  Locale? _locale; // null = system default
+
+  LocaleProvider() {
+    _loadLocale();
+  }
+
+  Locale? get locale => _locale;
+
+  Future<void> _loadLocale() async {
+    final savedLocale = await SettingsService.getLocale();
+    if (savedLocale != null) {
+      _locale = Locale(savedLocale);
+    }
+    notifyListeners();
+  }
+
+  Future<void> setLocale(Locale? locale) async {
+    _locale = locale;
+    await SettingsService.saveLocale(locale?.languageCode);
+    notifyListeners();
+  }
+
+  /// Returns the display name for a locale
+  static String getDisplayName(String? languageCode, BuildContext context) {
+    switch (languageCode) {
+      case 'en':
+        return 'English';
+      case 'de':
+        return 'Deutsch';
+      case 'es':
+        return 'Español';
+      case 'fr':
+        return 'Français';
+      case null:
+        return 'System';
+      default:
+        return languageCode;
+    }
+  }
+}
@@ -1,956 +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;
-        }
-
-        if (nameLower == 'this device' || player.playerId.startsWith('ma_')) {
-          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();
-
-          if (lastSelectedPlayerId != null) {
-            try {
-              playerToSelect = _availablePlayers.firstWhere(
-                (p) => p.playerId == lastSelectedPlayerId && p.available,
-              );
-            } catch (e) {}
-          }
-
-          if (playerToSelect == null && builtinPlayerId != null) {
-            try {
-              playerToSelect = _availablePlayers.firstWhere(
-                (p) => p.playerId == builtinPlayerId && p.available,
-              );
-            } catch (e) {}
-          }
-
-          if (playerToSelect == null) {
-            try {
-              playerToSelect = _availablePlayers.firstWhere(
-                (p) => p.state == 'playing' && p.available,
-              );
-            } catch (e) {}
-          }
-
-          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) async {
-    if (_api == null) return;
-    try {
-      await _api!.toggleShuffle(queueId);
-    } 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();
-  }
-}
@@ -8,17 +8,24 @@ import '../theme/palette_helper.dart';
 import '../theme/theme_provider.dart';
 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 {
  final Album album;
  final String? heroTagSuffix;
+  /// Initial image URL from the source (e.g., AlbumCard) for seamless hero animation
+  final String? initialImageUrl;

  const AlbumDetailsScreen({
-    super.key, 
+    super.key,
    required this.album,
    this.heroTagSuffix,
+    this.initialImageUrl,
  });

  @override
@@ -30,43 +37,51 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
  List<Track> _tracks = [];
  bool _isLoading = true;
  bool _isFavorite = false;
+  bool _isInLibrary = false;
  ColorScheme? _lightColorScheme;
  ColorScheme? _darkColorScheme;
  int? _expandedTrackIndex;
  bool _isDescriptionExpanded = false;
  String? _albumDescription;
-  
+  Album? _freshAlbum; // Full album data with image metadata
+
+  /// Get the best album data available (fresh with images, or widget.album as fallback)
+  Album get _displayAlbum => _freshAlbum ?? widget.album;
+
  String get _heroTagSuffix => widget.heroTagSuffix != null ? '_${widget.heroTagSuffix}' : '';

  @override
  void initState() {
    super.initState();
    _isFavorite = widget.album.favorite ?? false;
+    _isInLibrary = widget.album.inLibrary;
    _loadTracks();
    _loadAlbumDescription();
-    _refreshFavoriteStatus();

-    // CRITICAL FIX: Defer color extraction until after the transition completes
-    // This prevents expensive palette extraction during hero animation
-    // Wait for the first frame to be painted, then extract colors
+    // CRITICAL FIX: Defer both fresh data loading AND color extraction until
+    // after the hero animation completes. This prevents:
+    // 1. setState with new image URL during animation → grey icon flash
+    // 2. Expensive palette extraction blocking animation frames
    WidgetsBinding.instance.addPostFrameCallback((_) {
-      // Add small delay to ensure transition is complete
+      // 350ms matches FadeSlidePageRoute duration (300ms) + buffer
      Future.delayed(const Duration(milliseconds: 350), () {
        if (mounted) {
+          _loadFreshAlbumData();
          _extractColors();
        }
      });
    });
  }

-  Future<void> _refreshFavoriteStatus() async {
+  /// Load fresh album data from API to get full metadata including images
+  Future<void> _loadFreshAlbumData() async {
    final maProvider = context.read<MusicAssistantProvider>();
    if (maProvider.api == null) return;

    // Need a URI to fetch fresh album data
    final albumUri = widget.album.uri;
    if (albumUri == null || albumUri.isEmpty) {
-      _logger.log('Cannot refresh favorite status: album has no URI');
+      _logger.log('Cannot load fresh album: album has no URI');
      return;
    }

@@ -74,17 +89,20 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
      final freshAlbum = await maProvider.api!.getAlbumByUri(albumUri);
      if (freshAlbum != null && mounted) {
        setState(() {
+          _freshAlbum = freshAlbum;
          _isFavorite = freshAlbum.favorite ?? false;
        });
+        // Re-extract colors now that we have fresh album with images
+        _extractColors();
      }
    } catch (e) {
-      _logger.log('Error refreshing favorite status: $e');
+      _logger.log('Error loading fresh album data: $e');
    }
  }

  Future<void> _extractColors() async {
    final maProvider = context.read<MusicAssistantProvider>();
-    final imageUrl = maProvider.getImageUrl(widget.album, size: 512);
+    final imageUrl = maProvider.getImageUrl(_displayAlbum, size: 512);

    if (imageUrl == null) return;

@@ -106,10 +124,10 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick

  Future<void> _toggleFavorite() async {
    final maProvider = context.read<MusicAssistantProvider>();
-    if (maProvider.api == null) return;

    try {
      final newState = !_isFavorite;
+      bool success;

      if (newState) {
        // For adding: use the actual provider and itemId from provider_mappings
@@ -125,22 +143,24 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
              orElse: () => widget.album.providerMappings!.first,
            ),
          );
-          actualProvider = mapping.providerInstance;
+          // Use providerDomain (e.g., "spotify") not providerInstance (e.g., "spotify--xyz")
+          actualProvider = mapping.providerDomain;
          actualItemId = mapping.itemId;
        }

        _logger.log('Adding to favorites: provider=$actualProvider, itemId=$actualItemId');
-        await maProvider.api!.addToFavorites('album', actualItemId, actualProvider);
+        success = await maProvider.addToFavorites(
+          mediaType: 'album',
+          itemId: actualItemId,
+          provider: actualProvider,
+        );
      } else {
        // For removing: need the library_item_id (numeric)
-        // When provider is "library", itemId is the library ID as a string
-        // Otherwise, we need to find it from provider_mappings
        int? libraryItemId;

        if (widget.album.provider == 'library') {
          libraryItemId = int.tryParse(widget.album.itemId);
        } else if (widget.album.providerMappings != null) {
-          // Find the library mapping
          final libraryMapping = widget.album.providerMappings!.firstWhere(
            (m) => m.providerInstance == 'library',
            orElse: () => widget.album.providerMappings!.first,
@@ -155,33 +175,167 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
          throw Exception('Could not determine library ID for this album');
        }

-        _logger.log('Removing from favorites: libraryItemId=$libraryItemId');
-        await maProvider.api!.removeFromFavorites('album', libraryItemId);
+        success = await maProvider.removeFromFavorites(
+          mediaType: 'album',
+          libraryItemId: libraryItemId,
+        );
      }

-      setState(() {
-        _isFavorite = newState;
-      });
+      if (success) {
+        // Optimistically update UI regardless of online/offline state
+        setState(() {
+          _isFavorite = newState;
+        });

-      // Invalidate home cache so the home screen shows updated favorite status
-      maProvider.invalidateHomeCache();
+        // Invalidate home cache so the home screen shows updated favorite status
+        maProvider.invalidateHomeCache();

-      if (mounted) {
-        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(
-            content: Text(
-              _isFavorite ? 'Added to favorites' : 'Removed from favorites',
+        if (mounted) {
+          final isOffline = !maProvider.isConnected;
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(
+              content: Text(
+                isOffline
+                    ? S.of(context)!.actionQueuedForSync
+                    : (_isFavorite ? S.of(context)!.addedToFavorites : S.of(context)!.removedFromFavorites),
+              ),
+              duration: const Duration(seconds: 1),
            ),
-            duration: const Duration(seconds: 1),
-          ),
-        );
+          );
+        }
      }
    } catch (e) {
      _logger.log('Error toggling favorite: $e');
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
-            content: Text('Failed to update favorite: $e'),
+            content: Text(S.of(context)!.failedToUpdateFavorite(e.toString())),
+            duration: const Duration(seconds: 2),
+          ),
+        );
+      }
+    }
+  }
+
+  /// Toggle library status
+  Future<void> _toggleLibrary() async {
+    final maProvider = context.read<MusicAssistantProvider>();
+
+    try {
+      final newState = !_isInLibrary;
+
+      if (newState) {
+        // Add to library - MUST use non-library provider
+        String? actualProvider;
+        String? actualItemId;
+
+        if (widget.album.providerMappings != null && widget.album.providerMappings!.isNotEmpty) {
+          // For adding to library, we MUST use a non-library provider
+          final nonLibraryMapping = widget.album.providerMappings!.where(
+            (m) => m.providerInstance != 'library' && m.providerDomain != 'library',
+          ).firstOrNull;
+
+          if (nonLibraryMapping != null) {
+            actualProvider = nonLibraryMapping.providerDomain;
+            actualItemId = nonLibraryMapping.itemId;
+          }
+        }
+
+        // Fallback to item's own provider if no non-library mapping found
+        if (actualProvider == null || actualItemId == null) {
+          if (widget.album.provider != 'library') {
+            actualProvider = widget.album.provider;
+            actualItemId = widget.album.itemId;
+          } else {
+            // Item is library-only, can't add
+            _logger.log('Cannot add to library: album is library-only');
+            return;
+          }
+        }
+
+        // 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');
+        // 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;
+        if (widget.album.provider == 'library') {
+          libraryItemId = int.tryParse(widget.album.itemId);
+        } else if (widget.album.providerMappings != null) {
+          final libraryMapping = widget.album.providerMappings!.firstWhere(
+            (m) => m.providerInstance == 'library',
+            orElse: () => widget.album.providerMappings!.first,
+          );
+          if (libraryMapping.providerInstance == 'library') {
+            libraryItemId = int.tryParse(libraryMapping.itemId);
+          }
+        }
+
+        if (libraryItemId == null) {
+          _logger.log('Cannot remove from library: no library ID found');
+          return;
+        }
+
+        // OPTIMISTIC UPDATE: Update UI immediately
+        setState(() {
+          _isInLibrary = newState;
+        });
+
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(
+              content: Text(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');
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(
+            content: Text('Failed to update library: $e'),
            duration: const Duration(seconds: 2),
          ),
        );
@@ -194,11 +348,11 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick

    final track = _tracks[trackIndex];
    final maProvider = context.read<MusicAssistantProvider>();
-    if (maProvider.api == null) return;
-
    final currentFavorite = track.favorite ?? false;

    try {
+      bool success;
+
      if (currentFavorite) {
        // Remove from favorites - need library_item_id
        int? libraryItemId;
@@ -215,7 +369,12 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
        }

        if (libraryItemId != null) {
-          await maProvider.api!.removeFromFavorites('track', libraryItemId);
+          success = await maProvider.removeFromFavorites(
+            mediaType: 'track',
+            libraryItemId: libraryItemId,
+          );
+        } else {
+          success = false;
        }
      } else {
        // Add to favorites
@@ -230,44 +389,54 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
              orElse: () => track.providerMappings!.first,
            ),
          );
-          actualProvider = mapping.providerInstance;
+          // Use providerDomain (e.g., "spotify") not providerInstance (e.g., "spotify--xyz")
+          actualProvider = mapping.providerDomain;
          actualItemId = mapping.itemId;
        }

-        await maProvider.api!.addToFavorites('track', actualItemId, actualProvider);
+        success = await maProvider.addToFavorites(
+          mediaType: 'track',
+          itemId: actualItemId,
+          provider: actualProvider,
+        );
      }

-      // Update local state - create new track with toggled favorite
-      setState(() {
-        _tracks[trackIndex] = Track(
-          itemId: track.itemId,
-          provider: track.provider,
-          name: track.name,
-          uri: track.uri,
-          favorite: !currentFavorite,
-          artists: track.artists,
-          album: track.album,
-          duration: track.duration,
-          providerMappings: track.providerMappings,
-        );
-      });
+      if (success) {
+        // Optimistically update local state
+        setState(() {
+          _tracks[trackIndex] = Track(
+            itemId: track.itemId,
+            provider: track.provider,
+            name: track.name,
+            uri: track.uri,
+            favorite: !currentFavorite,
+            artists: track.artists,
+            album: track.album,
+            duration: track.duration,
+            providerMappings: track.providerMappings,
+          );
+        });

-      if (mounted) {
-        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(
-            content: Text(
-              !currentFavorite ? 'Added to favorites' : 'Removed from favorites',
+        if (mounted) {
+          final isOffline = !maProvider.isConnected;
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(
+              content: Text(
+                isOffline
+                    ? S.of(context)!.actionQueuedForSync
+                    : (!currentFavorite ? S.of(context)!.addedToFavorites : S.of(context)!.removedFromFavorites),
+              ),
+              duration: const Duration(seconds: 1),
            ),
-            duration: const Duration(seconds: 1),
-          ),
-        );
+          );
+        }
      }
    } catch (e) {
      _logger.log('Error toggling track favorite: $e');
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
-            content: Text('Failed to update favorite: $e'),
+            content: Text(S.of(context)!.failedToUpdateFavorite(e.toString())),
            duration: const Duration(seconds: 2),
          ),
        );
@@ -277,16 +446,46 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick

  Future<void> _loadTracks() async {
    final provider = context.read<MusicAssistantProvider>();
-    final tracks = await provider.getAlbumTracksWithCache(
-      widget.album.provider,
-      widget.album.itemId,
-    );
+    final cacheKey = '${widget.album.provider}_${widget.album.itemId}';

-    if (mounted) {
-      setState(() {
-        _tracks = tracks;
-        _isLoading = false;
-      });
+    // 1. Show cached data immediately (if available)
+    final cachedTracks = provider.getCachedAlbumTracks(cacheKey);
+    if (cachedTracks != null && cachedTracks.isNotEmpty) {
+      if (mounted) {
+        setState(() {
+          _tracks = cachedTracks;
+          _isLoading = false;
+        });
+      }
+    }
+
+    // 2. Fetch fresh data in background (silent refresh)
+    try {
+      final freshTracks = await provider.getAlbumTracksWithCache(
+        widget.album.provider,
+        widget.album.itemId,
+        forceRefresh: cachedTracks != null, // Force refresh if we had cache
+      );
+
+      // 3. Update if we got different data
+      if (mounted && freshTracks.isNotEmpty) {
+        final tracksChanged = _tracks.length != freshTracks.length ||
+            (_tracks.isNotEmpty && freshTracks.isNotEmpty &&
+             _tracks.first.itemId != freshTracks.first.itemId);
+        if (tracksChanged || _tracks.isEmpty) {
+          setState(() {
+            _tracks = freshTracks;
+            _isLoading = false;
+          });
+        }
+      }
+    } catch (e) {
+      _logger.log('⚠️ Background refresh failed: $e');
+    }
+
+    // Ensure loading is false even if everything failed
+    if (mounted && _isLoading) {
+      setState(() => _isLoading = false);
    }
  }

@@ -299,7 +498,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
      // Use the selected player
      final player = maProvider.selectedPlayer;
      if (player == null) {
-        _showError('No player selected');
+        _showError(S.of(context)!.noPlayerSelected);
        return;
      }

@@ -308,6 +507,9 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
      // Queue all tracks via Music Assistant
      await maProvider.playTracks(player.playerId, _tracks, startIndex: 0);
      _logger.log('Album queued on ${player.name}');
+
+      // Record to local recently played (per-profile)
+      RecentlyPlayedService.instance.recordAlbumPlayed(widget.album);
      // Stay on album page - mini player will appear
    } catch (e) {
      _logger.log('Error playing album: $e');
@@ -322,7 +524,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
      // Use the selected player
      final player = maProvider.selectedPlayer;
      if (player == null) {
-        _showError('No player selected');
+        _showError(S.of(context)!.noPlayerSelected);
        return;
      }

@@ -356,16 +558,16 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            Text(
-              'Add album to queue on...',
+              S.of(context)!.addAlbumToQueueOn,
              style: Theme.of(context).textTheme.titleLarge,
            ),
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            if (players.isEmpty)
-              const Padding(
-                padding: EdgeInsets.all(32.0),
-                child: Text('No players available'),
+              Padding(
+                padding: const EdgeInsets.all(32.0),
+                child: Text(S.of(context)!.noPlayersAvailable),
              )
            else
              Flexible(
@@ -393,9 +595,9 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                          _logger.log('Album added to queue on ${player.name}');
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
-                              const SnackBar(
-                                content: Text('Album added to queue'),
-                                duration: Duration(seconds: 1),
+                              SnackBar(
+                                content: Text(S.of(context)!.albumAddedToQueue),
+                                duration: const Duration(seconds: 1),
                              ),
                            );
                          }
@@ -436,16 +638,16 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            Text(
-              'Add to queue on...',
+              S.of(context)!.addToQueueOn,
              style: Theme.of(context).textTheme.titleLarge,
            ),
-            const SizedBox(height: 16),
+            Spacing.vGap16,
            if (players.isEmpty)
-              const Padding(
-                padding: EdgeInsets.all(32.0),
-                child: Text('No players available'),
+              Padding(
+                padding: const EdgeInsets.all(32.0),
+                child: Text(S.of(context)!.noPlayersAvailable),
              )
            else
              Flexible(
@@ -472,9 +674,9 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                          );
                          if (mounted) {
                            ScaffoldMessenger.of(context).showSnackBar(
-                              const SnackBar(
-                                content: Text('Tracks added to queue'),
-                                duration: Duration(seconds: 1),
+                              SnackBar(
+                                content: Text(S.of(context)!.tracksAddedToQueue),
+                                duration: const Duration(seconds: 1),
                              ),
                            );
                          }
@@ -487,7 +689,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                  },
                ),
              ),
-            const SizedBox(height: 16),
+            SizedBox(height: MediaQuery.of(context).padding.bottom + 16),
          ],
        ),
      ),
@@ -499,8 +701,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) {
-      final artist = widget.album.artists!.first;
+    if (_displayAlbum.artists != null && _displayAlbum.artists!.isNotEmpty) {
+      final artist = _displayAlbum.artists!.first;
      final maProvider = context.read<MusicAssistantProvider>();
      final imageUrl = maProvider.getImageUrl(artist, size: 256);
      Navigator.push(
@@ -590,9 +792,12 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
  Widget build(BuildContext context) {
    // CRITICAL FIX: Use select() instead of watch() to reduce rebuilds
    // Only rebuild when specific properties change, not on every provider update
-    final imageUrl = context.select<MusicAssistantProvider, String?>(
-      (provider) => provider.getImageUrl(widget.album, size: 512),
+    // Use _displayAlbum which has fresh data with images if available
+    final providerImageUrl = context.select<MusicAssistantProvider, String?>(
+      (provider) => provider.getImageUrl(_displayAlbum, size: 512),
    );
+    // Use initialImageUrl as fallback for seamless hero animation
+    final imageUrl = providerImageUrl ?? widget.initialImageUrl;
    final adaptiveTheme = context.select<ThemeProvider, bool>(
      (provider) => provider.adaptiveTheme,
    );
@@ -629,10 +834,16 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
      },
      child: Scaffold(
        backgroundColor: colorScheme.background,
-        body: CustomScrollView(
+        body: LayoutBuilder(
+          builder: (context, constraints) {
+            // Responsive cover size: 70% of screen width, clamped between 200-320
+            final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
+            final expandedHeight = coverSize + 70;
+
+            return CustomScrollView(
        slivers: [
          SliverAppBar(
-            expandedHeight: 350, // Increased height for bigger art
+            expandedHeight: expandedHeight,
            pinned: true,
            backgroundColor: colorScheme.background,
            leading: IconButton(
@@ -650,35 +861,50 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                  const SizedBox(height: 60),
                  GestureDetector(
                    onTap: () => _showFullscreenArt(imageUrl),
-                    child: Hero(
-                      tag: HeroTags.albumCover + (widget.album.uri ?? widget.album.itemId) + _heroTagSuffix,
-                      child: Container(
-                        width: 280, // Increased size
-                        height: 280,
-                        decoration: BoxDecoration(
-                          color: colorScheme.surfaceVariant,
-                          borderRadius: BorderRadius.circular(16), // Slightly more rounded
-                          boxShadow: [
-                            BoxShadow(
-                              color: Colors.black.withOpacity(0.3),
-                              blurRadius: 20,
-                              offset: const Offset(0, 10),
-                            ),
-                          ],
-                          image: imageUrl != null
-                              ? DecorationImage(
-                                  image: CachedNetworkImageProvider(imageUrl),
-                                  fit: BoxFit.cover,
-                                )
-                              : null,
+                    // Shadow container (outside Hero for correct clipping)
+                    child: Container(
+                      decoration: BoxDecoration(
+                        borderRadius: BorderRadius.circular(12),
+                        boxShadow: [
+                          BoxShadow(
+                            color: Colors.black.withOpacity(0.3),
+                            blurRadius: 20,
+                            offset: const Offset(0, 10),
+                          ),
+                        ],
+                      ),
+                      child: Hero(
+                        tag: HeroTags.albumCover + (widget.album.uri ?? widget.album.itemId) + _heroTagSuffix,
+                        // FIXED: Match source structure - ClipRRect(12) → Container → CachedNetworkImage
+                        child: ClipRRect(
+                          borderRadius: BorderRadius.circular(12),
+                          child: Container(
+                            width: coverSize,
+                            height: coverSize,
+                            color: colorScheme.surfaceVariant,
+                            child: imageUrl != null
+                                ? CachedNetworkImage(
+                                    imageUrl: imageUrl,
+                                    fit: BoxFit.cover,
+                                    // Match source memCacheWidth for smooth Hero
+                                    memCacheWidth: 256,
+                                    memCacheHeight: 256,
+                                    fadeInDuration: Duration.zero,
+                                    fadeOutDuration: Duration.zero,
+                                    placeholder: (_, __) => const SizedBox(),
+                                    errorWidget: (_, __, ___) => Icon(
+                                      Icons.album_rounded,
+                                      size: coverSize * 0.43,
+                                      color: colorScheme.onSurfaceVariant,
+                                    ),
+                                  )
+                                : Icon(
+                                    Icons.album_rounded,
+                                    size: coverSize * 0.43,
+                                    color: colorScheme.onSurfaceVariant,
+                                  ),
+                          ),
                        ),
-                        child: imageUrl == null
-                            ? Icon(
-                                Icons.album_rounded,
-                                size: 120,
-                                color: colorScheme.onSurfaceVariant,
-                              )
-                            : null,
                      ),
                    ),
                  ),
@@ -688,7 +914,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
          ),
          SliverToBoxAdapter(
            child: Padding(
-              padding: const EdgeInsets.all(24.0),
+              padding: const EdgeInsets.fromLTRB(24.0, 24.0, 24.0, 12.0),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
@@ -697,7 +923,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                    child: Material(
                      color: Colors.transparent,
                      child: Text(
-                        widget.album.name,
+                        widget.album.nameWithYear,
                        style: textTheme.headlineMedium?.copyWith(
                          color: colorScheme.onBackground,
                          fontWeight: FontWeight.bold,
@@ -705,7 +931,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(
@@ -716,7 +942,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),
                            ),
@@ -725,7 +951,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                      ),
                    ),
                  ),
-                  const SizedBox(height: 16),
+                  Spacing.vGap16,
                  // Album Description
                  if (_albumDescription != null && _albumDescription!.isNotEmpty) ...[
                    InkWell(
@@ -747,7 +973,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                        ),
                      ),
                    ),
-                    const SizedBox(height: 8),
+                    Spacing.vGap8,
                  ],
                  Row(
                    children: [
@@ -759,7 +985,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                          child: ElevatedButton.icon(
                            onPressed: _isLoading || _tracks.isEmpty ? null : _playAlbum,
                            icon: const Icon(Icons.play_arrow_rounded),
-                            label: const Text('Play'),
+                            label: Text(S.of(context)!.play),
                            style: ElevatedButton.styleFrom(
                              backgroundColor: colorScheme.primary,
                              foregroundColor: colorScheme.onPrimary,
@@ -818,7 +1044,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(
@@ -829,17 +1055,32 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                          ),
                        ),
                      ),
+
+                      const SizedBox(width: 12),
+
+                      // Library Button
+                      SizedBox(
+                        height: 50,
+                        width: 50,
+                        child: FilledButton.tonal(
+                          onPressed: _toggleLibrary,
+                          style: FilledButton.styleFrom(
+                            padding: EdgeInsets.zero,
+                            shape: RoundedRectangleBorder(
+                              borderRadius: BorderRadius.circular(12),
+                            ),
+                          ),
+                          child: Icon(
+                            _isInLibrary ? Icons.library_add_check : Icons.library_add,
+                            color: _isInLibrary
+                                ? colorScheme.primary
+                                : colorScheme.onSurfaceVariant,
+                          ),
+                        ),
+                      ),
                    ],
                  ),
                  const SizedBox(height: 24),
-                  Text(
-                    'Tracks',
-                    style: textTheme.titleLarge?.copyWith(
-                      color: colorScheme.onBackground,
-                      fontWeight: FontWeight.bold,
-                    ),
-                  ),
-                  const SizedBox(height: 12),
                ],
              ),
            ),
@@ -854,7 +1095,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
            SliverFillRemaining(
              child: Center(
                child: Text(
-                  'No tracks found',
+                  S.of(context)!.noTracksFound,
                  style: TextStyle(
                    color: colorScheme.onBackground.withOpacity(0.54),
                    fontSize: 16,
@@ -981,7 +1222,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(
@@ -1004,120 +1245,73 @@ 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
        ],
-      ),
+      );
+          },
+        ),
      ),
    );
  }

  void _showPlayAlbumFromHereMenu(BuildContext context, int startIndex) {
    final maProvider = context.read<MusicAssistantProvider>();
-    final players = maProvider.availablePlayers;

-    _showPlayOnSheet(
-      context,
-      players,
-      onPlayerSelected: (player) {
+    GlobalPlayerOverlay.hidePlayer();
+
+    showPlayerPickerSheet(
+      context: context,
+      title: S.of(context)!.playOn,
+      players: maProvider.availablePlayers,
+      selectedPlayer: maProvider.selectedPlayer,
+      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
-        maProvider.playTracks(
+        await maProvider.playTracks(
          player.playerId,
          _tracks,
          startIndex: startIndex,
        );
      },
-    );
+    ).whenComplete(() {
+      GlobalPlayerOverlay.showPlayer();
+    });
  }

  void _showPlayRadioMenu(BuildContext context, int trackIndex) {
    final maProvider = context.read<MusicAssistantProvider>();
-    final players = maProvider.availablePlayers;
    final track = _tracks[trackIndex];

-    _showPlayOnSheet(
-      context,
-      players,
-      onPlayerSelected: (player) {
+    GlobalPlayerOverlay.hidePlayer();
+
+    showPlayerPickerSheet(
+      context: context,
+      title: S.of(context)!.playOn,
+      players: maProvider.availablePlayers,
+      selectedPlayer: maProvider.selectedPlayer,
+      onPlayerSelected: (player) async {
        maProvider.selectPlayer(player);
-        maProvider.playRadio(player.playerId, track);
+        await maProvider.playRadio(player.playerId, track);
      },
-    );
+    ).whenComplete(() {
+      GlobalPlayerOverlay.showPlayer();
+    });
  }

  void _showPlayOnMenu(BuildContext context) {
    final maProvider = context.read<MusicAssistantProvider>();
-    final players = maProvider.availablePlayers;

-    _showPlayOnSheet(
-      context,
-      players,
-      onPlayerSelected: (player) {
-        maProvider.selectPlayer(player);
-        maProvider.playTracks(player.playerId, _tracks);
-      },
-    );
-  }
-
-  /// Shared "Play on..." bottom sheet with fixed height and scrollable list
-  void _showPlayOnSheet(
-    BuildContext context,
-    List players, {
-    required void Function(dynamic player) onPlayerSelected,
-  }) {
-    // Slide mini player down out of the way
    GlobalPlayerOverlay.hidePlayer();

-    final screenHeight = MediaQuery.of(context).size.height;
-    final bottomPadding = MediaQuery.of(context).padding.bottom;
-    final sheetHeight = (screenHeight * 0.45) + bottomPadding; // Fixed 45% + safe area
-
-    showModalBottomSheet(
+    showPlayerPickerSheet(
      context: context,
-      backgroundColor: Colors.transparent,
-      isScrollControlled: true,
-      builder: (context) => Container(
-        height: sheetHeight,
-        decoration: BoxDecoration(
-          color: Theme.of(context).colorScheme.surface,
-          borderRadius: const BorderRadius.vertical(top: Radius.circular(20)),
-        ),
-        child: Column(
-          children: [
-            const SizedBox(height: 16),
-            Text(
-              'Play on...',
-              style: Theme.of(context).textTheme.titleLarge,
-            ),
-            const SizedBox(height: 16),
-            Expanded(
-              child: players.isEmpty
-                  ? const Center(
-                      child: Text('No players available'),
-                    )
-                  : ListView.builder(
-                      padding: EdgeInsets.only(bottom: bottomPadding + 16),
-                      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: () {
-                            Navigator.pop(context);
-                            onPlayerSelected(player);
-                          },
-                        );
-                      },
-                    ),
-            ),
-          ],
-        ),
-      ),
+      title: S.of(context)!.playOn,
+      players: maProvider.availablePlayers,
+      selectedPlayer: maProvider.selectedPlayer,
+      onPlayerSelected: (player) async {
+        maProvider.selectPlayer(player);
+        await maProvider.playTracks(player.playerId, _tracks);
+      },
    ).whenComplete(() {
-      // Slide mini player back up when sheet is dismissed
      GlobalPlayerOverlay.showPlayer();
    });
  }
@@ -0,0 +1,558 @@
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+import 'package:cached_network_image/cached_network_image.dart';
+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 '../theme/palette_helper.dart';
+import '../theme/theme_provider.dart';
+import '../services/settings_service.dart';
+import '../services/metadata_service.dart';
+import '../services/debug_logger.dart';
+import '../utils/page_transitions.dart';
+import '../constants/hero_tags.dart';
+import '../l10n/app_localizations.dart';
+import 'audiobook_detail_screen.dart';
+
+class AudiobookAuthorScreen extends StatefulWidget {
+  final String authorName;
+  final List<Audiobook> audiobooks;
+  final String? heroTagSuffix;
+  final String? initialAuthorImageUrl;
+
+  const AudiobookAuthorScreen({
+    super.key,
+    required this.authorName,
+    required this.audiobooks,
+    this.heroTagSuffix,
+    this.initialAuthorImageUrl,
+  });
+
+  @override
+  State<AudiobookAuthorScreen> createState() => _AudiobookAuthorScreenState();
+}
+
+class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
+  final _logger = DebugLogger();
+  late List<Audiobook> _audiobooks;
+  ColorScheme? _lightColorScheme;
+  ColorScheme? _darkColorScheme;
+  String? _authorImageUrl;
+
+  // View preferences
+  String _sortOrder = 'alpha'; // 'alpha' or 'year'
+  String _viewMode = 'grid2'; // 'grid2', 'grid3', 'list'
+
+  String get _heroTagSuffix => widget.heroTagSuffix != null ? '_${widget.heroTagSuffix}' : '';
+
+  @override
+  void initState() {
+    super.initState();
+    _audiobooks = List.from(widget.audiobooks);
+    // Use initial image URL immediately for smooth hero animation
+    _authorImageUrl = widget.initialAuthorImageUrl;
+    _loadViewPreferences();
+    _sortAudiobooks();
+    _loadAuthorImage();
+  }
+
+  Future<void> _loadAuthorImage() async {
+    final imageUrl = await MetadataService.getAuthorImageUrl(widget.authorName);
+    if (mounted && imageUrl != null) {
+      setState(() {
+        _authorImageUrl = imageUrl;
+      });
+    }
+  }
+
+  Future<void> _loadViewPreferences() async {
+    final sortOrder = await SettingsService.getAuthorAudiobooksSortOrder();
+    final viewMode = await SettingsService.getAuthorAudiobooksViewMode();
+    if (mounted) {
+      setState(() {
+        _sortOrder = sortOrder;
+        _viewMode = viewMode;
+        _sortAudiobooks();
+      });
+    }
+  }
+
+  void _toggleSortOrder() {
+    final newOrder = _sortOrder == 'alpha' ? 'year' : 'alpha';
+    setState(() {
+      _sortOrder = newOrder;
+      _sortAudiobooks();
+    });
+    SettingsService.setAuthorAudiobooksSortOrder(newOrder);
+  }
+
+  void _cycleViewMode() {
+    String newMode;
+    switch (_viewMode) {
+      case 'grid2':
+        newMode = 'grid3';
+        break;
+      case 'grid3':
+        newMode = 'list';
+        break;
+      default:
+        newMode = 'grid2';
+    }
+    setState(() {
+      _viewMode = newMode;
+    });
+    SettingsService.setAuthorAudiobooksViewMode(newMode);
+  }
+
+  void _sortAudiobooks() {
+    if (_sortOrder == 'year') {
+      _audiobooks.sort((a, b) {
+        if (a.year == null && b.year == null) return a.name.compareTo(b.name);
+        if (a.year == null) return 1;
+        if (b.year == null) return -1;
+        return a.year!.compareTo(b.year!);
+      });
+    } else {
+      _audiobooks.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final adaptiveTheme = context.select<ThemeProvider, bool>(
+      (provider) => provider.adaptiveTheme,
+    );
+    final adaptiveLightScheme = context.select<ThemeProvider, ColorScheme?>(
+      (provider) => provider.adaptiveLightScheme,
+    );
+    final adaptiveDarkScheme = context.select<ThemeProvider, ColorScheme?>(
+      (provider) => provider.adaptiveDarkScheme,
+    );
+
+    final isDark = Theme.of(context).brightness == Brightness.dark;
+
+    ColorScheme? adaptiveScheme;
+    if (adaptiveTheme) {
+      adaptiveScheme = isDark
+        ? (_darkColorScheme ?? adaptiveDarkScheme)
+        : (_lightColorScheme ?? adaptiveLightScheme);
+    }
+    final colorScheme = adaptiveScheme ?? Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return PopScope(
+      canPop: true,
+      onPopInvokedWithResult: (didPop, result) {
+        if (didPop) {
+          clearAdaptiveColorsOnBack(context);
+        }
+      },
+      child: Scaffold(
+        backgroundColor: colorScheme.surface,
+        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: expandedHeight,
+              pinned: true,
+              backgroundColor: colorScheme.surface,
+              leading: IconButton(
+                icon: const Icon(Icons.arrow_back_rounded),
+                onPressed: () {
+                  clearAdaptiveColorsOnBack(context);
+                  Navigator.pop(context);
+                },
+                color: colorScheme.onSurface,
+              ),
+              flexibleSpace: FlexibleSpaceBar(
+                background: Column(
+                  mainAxisAlignment: MainAxisAlignment.center,
+                  children: [
+                    const SizedBox(height: 60),
+                    Hero(
+                      tag: HeroTags.authorImage + widget.authorName + _heroTagSuffix,
+                      child: Container(
+                        width: coverSize,
+                        height: coverSize,
+                        decoration: BoxDecoration(
+                          color: colorScheme.primaryContainer,
+                          shape: BoxShape.circle,
+                        ),
+                        child: Stack(
+                          alignment: Alignment.center,
+                          children: [
+                            // Icon always present underneath
+                            Icon(
+                              MdiIcons.accountOutline,
+                              size: coverSize * 0.5,
+                              color: colorScheme.onPrimaryContainer,
+                            ),
+                            // Image covers icon when loaded
+                            if (_authorImageUrl != null)
+                              SizedBox(
+                                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(),
+                                  ),
+                                ),
+                              ),
+                          ],
+                        ),
+                      ),
+                    ),
+                  ],
+                ),
+              ),
+            ),
+            SliverToBoxAdapter(
+              child: Padding(
+                padding: const EdgeInsets.all(24.0),
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  children: [
+                    Text(
+                      widget.authorName,
+                      style: textTheme.headlineMedium?.copyWith(
+                        color: colorScheme.onSurface,
+                        fontWeight: FontWeight.bold,
+                      ),
+                    ),
+                    const SizedBox(height: 8),
+                    Text(
+                      S.of(context)!.audiobookCount(_audiobooks.length),
+                      style: textTheme.bodyLarge?.copyWith(
+                        color: colorScheme.onSurface.withOpacity(0.7),
+                      ),
+                    ),
+                  ],
+                ),
+              ),
+            ),
+            // Audiobooks Section Header with controls
+            SliverToBoxAdapter(
+              child: Padding(
+                padding: const EdgeInsets.fromLTRB(24.0, 8.0, 12.0, 8.0),
+                child: Row(
+                  children: [
+                    Text(
+                      S.of(context)!.audiobooks,
+                      style: textTheme.titleLarge?.copyWith(
+                        color: colorScheme.onSurface,
+                        fontWeight: FontWeight.bold,
+                      ),
+                    ),
+                    const Spacer(),
+                    // Sort toggle
+                    IconButton(
+                      icon: Icon(
+                        _sortOrder == 'alpha' ? Icons.sort_by_alpha : Icons.calendar_today,
+                        color: colorScheme.primary,
+                        size: 20,
+                      ),
+                      tooltip: _sortOrder == 'alpha' ? S.of(context)!.sortByYear : S.of(context)!.sortAlphabetically,
+                      onPressed: _toggleSortOrder,
+                      visualDensity: VisualDensity.compact,
+                      padding: EdgeInsets.zero,
+                      constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                    ),
+                    // View mode toggle
+                    IconButton(
+                      icon: Icon(
+                        _viewMode == 'list'
+                            ? Icons.view_list
+                            : _viewMode == 'grid3'
+                                ? Icons.grid_view
+                                : Icons.grid_on,
+                        color: colorScheme.primary,
+                        size: 20,
+                      ),
+                      tooltip: _viewMode == 'grid2'
+                          ? S.of(context)!.threeColumnGrid
+                          : _viewMode == 'grid3'
+                              ? S.of(context)!.listView
+                              : S.of(context)!.twoColumnGrid,
+                      onPressed: _cycleViewMode,
+                      visualDensity: VisualDensity.compact,
+                      padding: EdgeInsets.zero,
+                      constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                    ),
+                  ],
+                ),
+              ),
+            ),
+            _buildAudiobookSliver(),
+            SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)),
+          ],
+            );
+          },
+        ),
+      ),
+    );
+  }
+
+  Widget _buildAudiobookSliver() {
+    if (_viewMode == 'list') {
+      return SliverPadding(
+        padding: const EdgeInsets.symmetric(horizontal: 12),
+        sliver: SliverList(
+          delegate: SliverChildBuilderDelegate(
+            (context, index) => _buildAudiobookListTile(_audiobooks[index]),
+            childCount: _audiobooks.length,
+          ),
+        ),
+      );
+    }
+
+    final crossAxisCount = _viewMode == 'grid3' ? 3 : 2;
+    final childAspectRatio = _viewMode == 'grid3' ? 0.65 : 0.70;
+
+    return SliverPadding(
+      padding: const EdgeInsets.symmetric(horizontal: 12),
+      sliver: SliverGrid(
+        gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
+          crossAxisCount: crossAxisCount,
+          childAspectRatio: childAspectRatio,
+          crossAxisSpacing: 12,
+          mainAxisSpacing: 12,
+        ),
+        delegate: SliverChildBuilderDelegate(
+          (context, index) => _buildAudiobookCard(_audiobooks[index]),
+          childCount: _audiobooks.length,
+        ),
+      ),
+    );
+  }
+
+  Widget _buildAudiobookCard(Audiobook book) {
+    final maProvider = context.read<MusicAssistantProvider>();
+    final imageUrl = maProvider.getImageUrl(book, size: 256);
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final heroSuffix = 'author${_heroTagSuffix}';
+
+    return InkWell(
+      onTap: () => _navigateToAudiobook(book, heroTagSuffix: heroSuffix, initialImageUrl: imageUrl),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          AspectRatio(
+            aspectRatio: 1.0,
+            child: Stack(
+              children: [
+                Hero(
+                  tag: HeroTags.audiobookCover + (book.uri ?? book.itemId) + '_$heroSuffix',
+                  child: ClipRRect(
+                    borderRadius: BorderRadius.circular(8),
+                    child: Container(
+                      color: colorScheme.surfaceContainerHighest,
+                      child: imageUrl != null
+                          ? CachedNetworkImage(
+                              imageUrl: imageUrl,
+                              fit: BoxFit.cover,
+                              width: double.infinity,
+                              height: double.infinity,
+                              fadeInDuration: Duration.zero,
+                              fadeOutDuration: Duration.zero,
+                              placeholder: (_, __) => Center(
+                                child: Icon(
+                                  MdiIcons.bookOutline,
+                                  size: 48,
+                                  color: colorScheme.onSurfaceVariant,
+                                ),
+                              ),
+                              errorWidget: (_, __, ___) => Center(
+                                child: Icon(
+                                  MdiIcons.bookOutline,
+                                  size: 48,
+                                  color: colorScheme.onSurfaceVariant,
+                                ),
+                              ),
+                            )
+                          : Center(
+                              child: Icon(
+                                MdiIcons.bookOutline,
+                                size: 48,
+                                color: colorScheme.onSurfaceVariant,
+                              ),
+                            ),
+                    ),
+                  ),
+                ),
+                // Progress indicator
+                if (book.progress > 0)
+                  Positioned(
+                    bottom: 0,
+                    left: 0,
+                    right: 0,
+                    child: LinearProgressIndicator(
+                      value: book.progress,
+                      backgroundColor: Colors.black54,
+                      valueColor: AlwaysStoppedAnimation<Color>(colorScheme.primary),
+                      minHeight: 3,
+                    ),
+                  ),
+              ],
+            ),
+          ),
+          const SizedBox(height: 8),
+          Hero(
+            tag: HeroTags.audiobookTitle + (book.uri ?? book.itemId) + '_$heroSuffix',
+            child: Material(
+              color: Colors.transparent,
+              child: Text(
+                book.name,
+                style: textTheme.titleSmall?.copyWith(
+                  color: colorScheme.onSurface,
+                  fontWeight: FontWeight.w500,
+                ),
+                maxLines: 2,
+                overflow: TextOverflow.ellipsis,
+              ),
+            ),
+          ),
+          if (book.narratorsString != S.of(context)!.unknownNarrator)
+            Text(
+              S.of(context)!.narratedBy(book.narratorsString),
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.onSurface.withOpacity(0.6),
+              ),
+              maxLines: 1,
+              overflow: TextOverflow.ellipsis,
+            ),
+        ],
+      ),
+    );
+  }
+
+  Widget _buildAudiobookListTile(Audiobook book) {
+    final maProvider = context.read<MusicAssistantProvider>();
+    final imageUrl = maProvider.getImageUrl(book, size: 128);
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final heroSuffix = 'author${_heroTagSuffix}';
+
+    return ListTile(
+      contentPadding: const EdgeInsets.symmetric(horizontal: 12, vertical: 4),
+      leading: Hero(
+        tag: HeroTags.audiobookCover + (book.uri ?? book.itemId) + '_$heroSuffix',
+        child: ClipRRect(
+          borderRadius: BorderRadius.circular(4),
+          child: Stack(
+            children: [
+              Container(
+                width: 56,
+                height: 56,
+                color: colorScheme.surfaceContainerHighest,
+                child: imageUrl != null
+                    ? CachedNetworkImage(
+                        imageUrl: imageUrl,
+                        fit: BoxFit.cover,
+                        fadeInDuration: Duration.zero,
+                        fadeOutDuration: Duration.zero,
+                        placeholder: (_, __) => Icon(
+                          MdiIcons.bookOutline,
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                        errorWidget: (_, __, ___) => Icon(
+                          MdiIcons.bookOutline,
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                      )
+                    : Icon(
+                        MdiIcons.bookOutline,
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+              ),
+              if (book.progress > 0)
+                Positioned(
+                  bottom: 0,
+                  left: 0,
+                  right: 0,
+                  child: LinearProgressIndicator(
+                    value: book.progress,
+                    backgroundColor: Colors.black54,
+                    valueColor: AlwaysStoppedAnimation<Color>(colorScheme.primary),
+                    minHeight: 2,
+                  ),
+                ),
+            ],
+          ),
+        ),
+      ),
+      title: Hero(
+        tag: HeroTags.audiobookTitle + (book.uri ?? book.itemId) + '_$heroSuffix',
+        child: Material(
+          color: Colors.transparent,
+          child: Text(
+            book.name,
+            style: textTheme.titleMedium?.copyWith(
+              color: colorScheme.onSurface,
+              fontWeight: FontWeight.w500,
+            ),
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+          ),
+        ),
+      ),
+      subtitle: Text(
+        book.narratorsString != S.of(context)!.unknownNarrator
+            ? S.of(context)!.narratedBy(book.narratorsString)
+            : book.duration != null
+                ? _formatDuration(book.duration!)
+                : '',
+        style: textTheme.bodySmall?.copyWith(
+          color: colorScheme.onSurface.withOpacity(0.7),
+        ),
+        maxLines: 1,
+        overflow: TextOverflow.ellipsis,
+      ),
+      trailing: book.progress > 0
+          ? Text(
+              '${(book.progress * 100).toInt()}%',
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.primary,
+              ),
+            )
+          : null,
+      onTap: () => _navigateToAudiobook(book, heroTagSuffix: heroSuffix, initialImageUrl: imageUrl),
+    );
+  }
+
+  void _navigateToAudiobook(Audiobook book, {String? heroTagSuffix, String? initialImageUrl}) {
+    Navigator.push(
+      context,
+      FadeSlidePageRoute(
+        child: AudiobookDetailScreen(
+          audiobook: book,
+          heroTagSuffix: heroTagSuffix,
+          initialImageUrl: initialImageUrl,
+        ),
+      ),
+    );
+  }
+
+  String _formatDuration(Duration duration) {
+    final hours = duration.inHours;
+    final minutes = duration.inMinutes % 60;
+    if (hours > 0) {
+      return '${hours}h ${minutes}m';
+    }
+    return '${minutes}m';
+  }
+}
@@ -0,0 +1,853 @@
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+import 'package:cached_network_image/cached_network_image.dart';
+import 'package:material_design_icons_flutter/material_design_icons_flutter.dart';
+import 'package:palette_generator/palette_generator.dart';
+import '../models/media_item.dart';
+import '../providers/music_assistant_provider.dart';
+import '../widgets/global_player_overlay.dart' show BottomSpacing;
+import '../services/settings_service.dart';
+import '../services/debug_logger.dart';
+import '../utils/page_transitions.dart';
+import '../constants/hero_tags.dart';
+import 'audiobook_detail_screen.dart';
+import '../l10n/app_localizations.dart';
+
+class AudiobookSeriesScreen extends StatefulWidget {
+  final AudiobookSeries series;
+  final String? heroTag;
+  /// Pre-loaded cover URLs from the library screen for smooth Hero animation
+  final List<String>? initialCovers;
+
+  const AudiobookSeriesScreen({
+    super.key,
+    required this.series,
+    this.heroTag,
+    this.initialCovers,
+  });
+
+  @override
+  State<AudiobookSeriesScreen> createState() => _AudiobookSeriesScreenState();
+}
+
+class _AudiobookSeriesScreenState extends State<AudiobookSeriesScreen> {
+  final _logger = DebugLogger();
+  List<Audiobook> _audiobooks = [];
+  bool _isLoading = true;
+  String? _error;
+
+  // View preferences
+  String _sortOrder = 'series'; // 'series' (by series number) or 'alpha'
+  String _viewMode = 'grid2'; // 'grid2', 'grid3', 'list'
+
+  // Extracted colors from book covers
+  List<Color> _extractedColors = [];
+
+  // Cover URLs - start with initial covers, update when books load
+  List<String> _coverUrls = [];
+
+  @override
+  void initState() {
+    super.initState();
+    // Use initial covers immediately for smooth Hero animation
+    if (widget.initialCovers != null && widget.initialCovers!.isNotEmpty) {
+      _coverUrls = List.from(widget.initialCovers!);
+      // Start color extraction from initial covers
+      _extractColorsFromUrls(widget.initialCovers!);
+    }
+    _loadViewPreferences();
+    // Defer loading until after first frame to ensure UI renders first
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (mounted) {
+        _loadSeriesBooks();
+      }
+    });
+  }
+
+  /// Extract colors from cover URLs (used for initial covers)
+  Future<void> _extractColorsFromUrls(List<String> coverUrls) async {
+    final extractedColors = <Color>[];
+
+    for (final url in coverUrls.take(4)) {
+      try {
+        final palette = await PaletteGenerator.fromImageProvider(
+          CachedNetworkImageProvider(url),
+          maximumColorCount: 8,
+        );
+
+        if (palette.darkMutedColor != null) {
+          extractedColors.add(palette.darkMutedColor!.color);
+        }
+        if (palette.mutedColor != null) {
+          extractedColors.add(palette.mutedColor!.color);
+        }
+        if (palette.darkVibrantColor != null) {
+          extractedColors.add(palette.darkVibrantColor!.color);
+        }
+        if (palette.dominantColor != null) {
+          final hsl = HSLColor.fromColor(palette.dominantColor!.color);
+          extractedColors.add(hsl.withLightness((hsl.lightness * 0.4).clamp(0.1, 0.3)).toColor());
+        }
+      } catch (e) {
+        _logger.log('📚 Error extracting colors: $e');
+      }
+    }
+
+    if (extractedColors.isNotEmpty && mounted) {
+      setState(() {
+        _extractedColors = extractedColors;
+      });
+    }
+  }
+
+  Future<void> _loadViewPreferences() async {
+    final sortOrder = await SettingsService.getSeriesAudiobooksSortOrder();
+    final viewMode = await SettingsService.getSeriesAudiobooksViewMode();
+    if (mounted) {
+      setState(() {
+        _sortOrder = sortOrder;
+        _viewMode = viewMode;
+      });
+    }
+  }
+
+  void _toggleSortOrder() {
+    final newOrder = _sortOrder == 'series' ? 'alpha' : 'series';
+    setState(() {
+      _sortOrder = newOrder;
+      _sortAudiobooks();
+    });
+    SettingsService.setSeriesAudiobooksSortOrder(newOrder);
+  }
+
+  void _cycleViewMode() {
+    String newMode;
+    switch (_viewMode) {
+      case 'grid2':
+        newMode = 'grid3';
+        break;
+      case 'grid3':
+        newMode = 'list';
+        break;
+      default:
+        newMode = 'grid2';
+    }
+    setState(() {
+      _viewMode = newMode;
+    });
+    SettingsService.setSeriesAudiobooksViewMode(newMode);
+  }
+
+  void _sortAudiobooks() {
+    if (_sortOrder == 'series') {
+      // Sort by series number (sequence), falling back to name for books without sequence
+      _audiobooks.sort((a, b) {
+        final seqA = a.seriesSequence;
+        final seqB = b.seriesSequence;
+        if (seqA == null && seqB == null) return a.name.compareTo(b.name);
+        if (seqA == null) return 1; // Books without sequence go to end
+        if (seqB == null) return -1;
+        return seqA.compareTo(seqB);
+      });
+    } else {
+      // Sort alphabetically
+      _audiobooks.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));
+    }
+  }
+
+  Future<void> _loadSeriesBooks() async {
+    _logger.log('📚 SeriesScreen _loadSeriesBooks START');
+    try {
+      setState(() {
+        _isLoading = true;
+        _error = null;
+      });
+      _logger.log('📚 SeriesScreen setState done, getting provider...');
+
+      final maProvider = context.read<MusicAssistantProvider>();
+      _logger.log('📚 SeriesScreen got provider, api=${maProvider.api != null}');
+
+      if (maProvider.api == null) {
+        setState(() {
+          _error = S.of(context)!.notConnected;
+          _isLoading = false;
+        });
+        return;
+      }
+
+      _logger.log('📚 SeriesScreen calling getSeriesAudiobooks: path=${widget.series.id}');
+      final books = await maProvider.api!.getSeriesAudiobooks(widget.series.id);
+      _logger.log('📚 SeriesScreen got ${books.length} books');
+
+      // Debug: Log sequence data for each book
+      for (final book in books) {
+        _logger.log('📚 Book: "${book.name}" | position=${book.position} | browseOrder=${book.browseOrder} | sortName=${book.sortName} | seq=${book.seriesSequence} | metadata.series=${book.metadata?['series']}');
+      }
+
+      if (mounted) {
+        // Update cover URLs from loaded books
+        final newCovers = <String>[];
+        for (final book in books.take(9)) {
+          final imageUrl = maProvider.getImageUrl(book);
+          if (imageUrl != null) {
+            newCovers.add(imageUrl);
+          }
+        }
+
+        setState(() {
+          _audiobooks = books;
+          _sortAudiobooks(); // Sort inside setState so UI updates
+          // Update covers if we got new ones (may have more than initial)
+          if (newCovers.isNotEmpty) {
+            _coverUrls = newCovers;
+          }
+          _isLoading = false;
+        });
+        // Debug: Log sorted order
+        _logger.log('📚 Sorted order ($_sortOrder):');
+        for (final book in _audiobooks) {
+          _logger.log('  - ${book.seriesSequence ?? "null"}: ${book.name}');
+        }
+
+        // Extract colors from book covers asynchronously
+        _extractCoverColors(maProvider);
+      }
+    } catch (e, stack) {
+      _logger.log('📚 SeriesScreen error: $e');
+      _logger.log('📚 SeriesScreen stack: $stack');
+      if (mounted) {
+        setState(() {
+          _error = 'Failed to load books: $e';
+          _isLoading = false;
+        });
+      }
+    }
+  }
+
+  /// Extract colors from book covers for empty grid cells
+  Future<void> _extractCoverColors(MusicAssistantProvider maProvider) async {
+    final extractedColors = <Color>[];
+
+    // Extract colors from first few book covers
+    for (final book in _audiobooks.take(4)) {
+      final imageUrl = maProvider.getImageUrl(book);
+      if (imageUrl == null) continue;
+
+      try {
+        final palette = await PaletteGenerator.fromImageProvider(
+          CachedNetworkImageProvider(imageUrl),
+          maximumColorCount: 8,
+        );
+
+        // Get dark muted colors for grid squares
+        if (palette.darkMutedColor != null) {
+          extractedColors.add(palette.darkMutedColor!.color);
+        }
+        if (palette.mutedColor != null) {
+          extractedColors.add(palette.mutedColor!.color);
+        }
+        if (palette.darkVibrantColor != null) {
+          extractedColors.add(palette.darkVibrantColor!.color);
+        }
+        if (palette.dominantColor != null) {
+          // Darken the dominant color for better appearance
+          final hsl = HSLColor.fromColor(palette.dominantColor!.color);
+          extractedColors.add(hsl.withLightness((hsl.lightness * 0.4).clamp(0.1, 0.3)).toColor());
+        }
+      } catch (e) {
+        _logger.log('📚 Error extracting colors: $e');
+      }
+    }
+
+    if (extractedColors.isNotEmpty && mounted) {
+      setState(() {
+        _extractedColors = extractedColors;
+      });
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final maProvider = context.watch<MusicAssistantProvider>();
+    final l10n = S.of(context)!;
+
+    return Scaffold(
+      backgroundColor: colorScheme.surface,
+      body: LayoutBuilder(
+        builder: (context, constraints) {
+          // Responsive cover size: 70% of screen width, clamped between 200-320
+          final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
+          final expandedHeight = coverSize + 70;
+
+          return CustomScrollView(
+        slivers: [
+          // App bar with series cover collage (matches audiobook detail screen)
+          SliverAppBar(
+            expandedHeight: expandedHeight,
+            pinned: true,
+            backgroundColor: colorScheme.surface,
+            leading: IconButton(
+              icon: const Icon(Icons.arrow_back_rounded),
+              onPressed: () => Navigator.pop(context),
+              color: colorScheme.onSurface,
+            ),
+            flexibleSpace: FlexibleSpaceBar(
+              background: Column(
+                mainAxisAlignment: MainAxisAlignment.center,
+                children: [
+                  const SizedBox(height: 60),
+                  // Series cover collage - responsive size
+                  Hero(
+                    tag: widget.heroTag ?? 'series_cover_${widget.series.id}',
+                    child: Container(
+                      width: coverSize,
+                      height: coverSize,
+                      decoration: BoxDecoration(
+                        color: colorScheme.surfaceContainerHighest,
+                        borderRadius: BorderRadius.circular(12),
+                        boxShadow: [
+                          BoxShadow(
+                            color: Colors.black.withOpacity(0.2),
+                            blurRadius: 10,
+                            offset: const Offset(0, 4),
+                          ),
+                        ],
+                      ),
+                      child: ClipRRect(
+                        borderRadius: BorderRadius.circular(12),
+                        child: _buildSeriesCover(colorScheme, maProvider),
+                      ),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ),
+
+          // Title and count
+          SliverToBoxAdapter(
+            child: Padding(
+              padding: const EdgeInsets.all(24.0),
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Text(
+                    widget.series.name,
+                    style: textTheme.headlineMedium?.copyWith(
+                      color: colorScheme.onSurface,
+                      fontWeight: FontWeight.bold,
+                    ),
+                  ),
+                  const SizedBox(height: 8),
+                  Text(
+                    _isLoading
+                        ? l10n.loading
+                        : l10n.bookCount(_audiobooks.length),
+                    style: textTheme.bodyLarge?.copyWith(
+                      color: colorScheme.onSurface.withOpacity(0.7),
+                    ),
+                  ),
+                ],
+              ),
+            ),
+          ),
+
+          // Books section header with controls
+          SliverToBoxAdapter(
+            child: Padding(
+              padding: const EdgeInsets.fromLTRB(24.0, 8.0, 12.0, 8.0),
+              child: Row(
+                children: [
+                  Text(
+                    l10n.books,
+                    style: textTheme.titleLarge?.copyWith(
+                      color: colorScheme.onSurface,
+                      fontWeight: FontWeight.bold,
+                    ),
+                  ),
+                  const Spacer(),
+                  // Sort toggle
+                  IconButton(
+                    icon: Icon(
+                      _sortOrder == 'series' ? Icons.format_list_numbered : Icons.sort_by_alpha,
+                      color: colorScheme.primary,
+                      size: 20,
+                    ),
+                    tooltip: _sortOrder == 'series' ? S.of(context)!.sortAlphabetically : S.of(context)!.sortBySeriesOrder,
+                    onPressed: _toggleSortOrder,
+                    visualDensity: VisualDensity.compact,
+                    padding: EdgeInsets.zero,
+                    constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                  ),
+                  // View mode toggle
+                  IconButton(
+                    icon: Icon(
+                      _viewMode == 'list'
+                          ? Icons.view_list
+                          : _viewMode == 'grid3'
+                              ? Icons.grid_view
+                              : Icons.grid_on,
+                      color: colorScheme.primary,
+                      size: 20,
+                    ),
+                    tooltip: _viewMode == 'grid2'
+                        ? S.of(context)!.threeColumnGrid
+                        : _viewMode == 'grid3'
+                            ? S.of(context)!.listView
+                            : S.of(context)!.twoColumnGrid,
+                    onPressed: _cycleViewMode,
+                    visualDensity: VisualDensity.compact,
+                    padding: EdgeInsets.zero,
+                    constraints: const BoxConstraints(minWidth: 36, minHeight: 36),
+                  ),
+                ],
+              ),
+            ),
+          ),
+
+          // Content
+          if (_isLoading)
+            const SliverFillRemaining(
+              child: Center(child: CircularProgressIndicator()),
+            )
+          else if (_error != null)
+            SliverFillRemaining(
+              child: Center(
+                child: Column(
+                  mainAxisAlignment: MainAxisAlignment.center,
+                  children: [
+                    Icon(Icons.error_outline, size: 48, color: colorScheme.error),
+                    const SizedBox(height: 16),
+                    Text(_error!, style: TextStyle(color: colorScheme.error)),
+                    const SizedBox(height: 16),
+                    ElevatedButton(
+                      onPressed: _loadSeriesBooks,
+                      child: Text(l10n.retry),
+                    ),
+                  ],
+                ),
+              ),
+            )
+          else if (_audiobooks.isEmpty)
+            SliverFillRemaining(
+              child: Center(
+                child: Column(
+                  mainAxisAlignment: MainAxisAlignment.center,
+                  children: [
+                    Icon(Icons.library_books_outlined,
+                        size: 48, color: colorScheme.onSurfaceVariant),
+                    const SizedBox(height: 16),
+                    Text(
+                      S.of(context)!.noBooksInSeries,
+                      style: TextStyle(color: colorScheme.onSurfaceVariant),
+                    ),
+                  ],
+                ),
+              ),
+            )
+          else
+            _buildAudiobookSliver(maProvider),
+
+          // Bottom padding for mini player
+          SliverToBoxAdapter(
+            child: SizedBox(height: BottomSpacing.withMiniPlayer),
+          ),
+        ],
+      );
+        },
+      ),
+    );
+  }
+
+  // Dark pastel colors for empty cells - muted and book-like
+  static const _emptyColors = [
+    Color(0xFF2D3436), // Dark slate
+    Color(0xFF34495E), // Dark blue-grey
+    Color(0xFF4A3728), // Dark brown
+    Color(0xFF2C3E50), // Midnight blue
+    Color(0xFF3D3D3D), // Charcoal
+    Color(0xFF4A4458), // Dark purple-grey
+    Color(0xFF3E4A47), // Dark teal-grey
+    Color(0xFF4A3F35), // Dark warm grey
+  ];
+
+  Widget _buildSeriesCover(ColorScheme colorScheme, MusicAssistantProvider maProvider) {
+    // Use _coverUrls which may have initial covers or loaded covers
+    // Only show placeholder if we truly have no covers
+    if (_coverUrls.isEmpty) {
+      return Container(
+        color: colorScheme.surfaceContainerHighest,
+        child: Center(
+          child: Icon(
+            Icons.collections_bookmark_rounded,
+            size: 64,
+            color: colorScheme.onSurfaceVariant.withOpacity(0.5),
+          ),
+        ),
+      );
+    }
+
+    final covers = _coverUrls;
+
+    // Dynamic grid size based on number of covers (matches library screen)
+    // 1 cover = 1x1, 2-4 covers = 2x2, 5+ covers = 3x3
+    int gridSize;
+    if (covers.length == 1) {
+      gridSize = 1;
+    } else if (covers.length <= 4) {
+      gridSize = 2;
+    } else {
+      gridSize = 3;
+    }
+
+    // Use series ID to pick consistent colors and nested grid patterns
+    final colorSeed = widget.series.id.hashCode;
+
+    // Pad covers to fill grid
+    final displayCovers = List<String?>.filled(gridSize * gridSize, null);
+    for (var i = 0; i < covers.length && i < displayCovers.length; i++) {
+      displayCovers[i] = covers[i];
+    }
+
+    // Build grid using Column/Row for proper sizing (no scrolling issues)
+    return Column(
+      children: List.generate(gridSize, (row) {
+        return Expanded(
+          child: Row(
+            children: List.generate(gridSize, (col) {
+              final index = row * gridSize + col;
+              final coverUrl = displayCovers[index];
+
+              return Expanded(
+                child: coverUrl != null
+                      ? CachedNetworkImage(
+                          imageUrl: coverUrl,
+                          fit: BoxFit.cover,
+                          fadeInDuration: Duration.zero,
+                          fadeOutDuration: Duration.zero,
+                          placeholder: (_, __) => Container(
+                            color: colorScheme.surfaceContainerHighest,
+                          ),
+                          errorWidget: (_, __, ___) => Container(
+                            color: colorScheme.surfaceContainerHighest,
+                            child: Icon(
+                              Icons.book,
+                              color: colorScheme.onSurfaceVariant.withOpacity(0.3),
+                              size: 20,
+                            ),
+                          ),
+                        )
+                      : _buildEmptyCell(colorSeed, index),
+              );
+            }),
+          ),
+        );
+      }),
+    );
+  }
+
+  /// Builds an empty cell with either a solid color or a nested grid
+  /// The pattern is deterministic based on series ID and cell index
+  Widget _buildEmptyCell(int colorSeed, int cellIndex) {
+    // Use extracted colors if available, otherwise fall back to static palette
+    final baseColors = _extractedColors.isNotEmpty ? _extractedColors : _emptyColors;
+    // Tone down colors - reduce saturation and darken
+    final colors = baseColors.map((c) {
+      final hsl = HSLColor.fromColor(c);
+      return hsl
+          .withSaturation((hsl.saturation * 0.5).clamp(0.05, 0.25))
+          .withLightness((hsl.lightness * 0.7).clamp(0.08, 0.20))
+          .toColor();
+    }).toList();
+
+    // Use combined seed for deterministic but varied patterns
+    final seed = colorSeed + cellIndex * 17; // Prime multiplier for better distribution
+
+    // Determine nested grid size: 1 (solid), 2 (2x2), or 3 (3x3)
+    // Distribution: ~50% solid, ~30% 2x2, ~20% 3x3
+    final sizeRoll = seed.abs() % 100;
+    int nestedSize;
+    if (sizeRoll < 50) {
+      nestedSize = 1; // Solid color
+    } else if (sizeRoll < 80) {
+      nestedSize = 2; // 2x2 grid
+    } else {
+      nestedSize = 3; // 3x3 grid
+    }
+
+    if (nestedSize == 1) {
+      // Solid color
+      final colorIndex = seed.abs() % colors.length;
+      return Container(color: colors[colorIndex]);
+    }
+
+    // Build nested grid (no margins - seamless)
+    return Column(
+      children: List.generate(nestedSize, (row) {
+        return Expanded(
+          child: Row(
+            children: List.generate(nestedSize, (col) {
+              final nestedIndex = row * nestedSize + col;
+              // Use different seed for each nested cell
+              final nestedSeed = seed + nestedIndex * 7;
+              final colorIndex = nestedSeed.abs() % colors.length;
+              return Expanded(
+                child: Container(color: colors[colorIndex]),
+              );
+            }),
+          ),
+        );
+      }),
+    );
+  }
+
+  Widget _buildAudiobookSliver(MusicAssistantProvider maProvider) {
+    if (_viewMode == 'list') {
+      return SliverPadding(
+        padding: const EdgeInsets.symmetric(horizontal: 12),
+        sliver: SliverList(
+          delegate: SliverChildBuilderDelegate(
+            (context, index) => _buildAudiobookListTile(_audiobooks[index], maProvider),
+            childCount: _audiobooks.length,
+          ),
+        ),
+      );
+    }
+
+    final crossAxisCount = _viewMode == 'grid3' ? 3 : 2;
+    final childAspectRatio = _viewMode == 'grid3' ? 0.65 : 0.70;
+
+    return SliverPadding(
+      padding: const EdgeInsets.symmetric(horizontal: 12),
+      sliver: SliverGrid(
+        gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
+          crossAxisCount: crossAxisCount,
+          childAspectRatio: childAspectRatio,
+          crossAxisSpacing: 12,
+          mainAxisSpacing: 12,
+        ),
+        delegate: SliverChildBuilderDelegate(
+          (context, index) => _buildAudiobookCard(_audiobooks[index], maProvider),
+          childCount: _audiobooks.length,
+        ),
+      ),
+    );
+  }
+
+  Widget _buildAudiobookCard(Audiobook book, MusicAssistantProvider maProvider) {
+    final imageUrl = maProvider.getImageUrl(book, size: 256);
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final heroSuffix = 'series_${widget.series.id}';
+
+    return InkWell(
+      onTap: () => _navigateToAudiobook(book, heroTagSuffix: heroSuffix, initialImageUrl: imageUrl),
+      child: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          AspectRatio(
+            aspectRatio: 1.0,
+            child: Stack(
+              children: [
+                Hero(
+                  tag: HeroTags.audiobookCover + (book.uri ?? book.itemId) + '_$heroSuffix',
+                  child: ClipRRect(
+                    borderRadius: BorderRadius.circular(8),
+                    child: Container(
+                      color: colorScheme.surfaceContainerHighest,
+                      child: imageUrl != null
+                          ? CachedNetworkImage(
+                              imageUrl: imageUrl,
+                              fit: BoxFit.cover,
+                              width: double.infinity,
+                              height: double.infinity,
+                              fadeInDuration: Duration.zero,
+                              fadeOutDuration: Duration.zero,
+                              placeholder: (_, __) => Center(
+                                child: Icon(
+                                  MdiIcons.bookOutline,
+                                  size: 48,
+                                  color: colorScheme.onSurfaceVariant,
+                                ),
+                              ),
+                              errorWidget: (_, __, ___) => Center(
+                                child: Icon(
+                                  MdiIcons.bookOutline,
+                                  size: 48,
+                                  color: colorScheme.onSurfaceVariant,
+                                ),
+                              ),
+                            )
+                          : Center(
+                              child: Icon(
+                                MdiIcons.bookOutline,
+                                size: 48,
+                                color: colorScheme.onSurfaceVariant,
+                              ),
+                            ),
+                    ),
+                  ),
+                ),
+                // Progress indicator
+                if (book.progress > 0)
+                  Positioned(
+                    bottom: 0,
+                    left: 0,
+                    right: 0,
+                    child: LinearProgressIndicator(
+                      value: book.progress,
+                      backgroundColor: Colors.black54,
+                      valueColor: AlwaysStoppedAnimation<Color>(colorScheme.primary),
+                      minHeight: 3,
+                    ),
+                  ),
+              ],
+            ),
+          ),
+          const SizedBox(height: 8),
+          Hero(
+            tag: HeroTags.audiobookTitle + (book.uri ?? book.itemId) + '_$heroSuffix',
+            child: Material(
+              color: Colors.transparent,
+              child: Text(
+                book.name,
+                style: textTheme.titleSmall?.copyWith(
+                  color: colorScheme.onSurface,
+                  fontWeight: FontWeight.w500,
+                ),
+                maxLines: 2,
+                overflow: TextOverflow.ellipsis,
+              ),
+            ),
+          ),
+          if (book.authorsString.isNotEmpty && book.authorsString != S.of(context)!.unknownAuthor)
+            Text(
+              book.authorsString,
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.onSurface.withOpacity(0.6),
+              ),
+              maxLines: 1,
+              overflow: TextOverflow.ellipsis,
+            ),
+        ],
+      ),
+    );
+  }
+
+  Widget _buildAudiobookListTile(Audiobook book, MusicAssistantProvider maProvider) {
+    final imageUrl = maProvider.getImageUrl(book, size: 128);
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final heroSuffix = 'series_${widget.series.id}';
+
+    return ListTile(
+      contentPadding: const EdgeInsets.symmetric(horizontal: 12, vertical: 4),
+      leading: Hero(
+        tag: HeroTags.audiobookCover + (book.uri ?? book.itemId) + '_$heroSuffix',
+        child: ClipRRect(
+          borderRadius: BorderRadius.circular(4),
+          child: Stack(
+            children: [
+              Container(
+                width: 56,
+                height: 56,
+                color: colorScheme.surfaceContainerHighest,
+                child: imageUrl != null
+                    ? CachedNetworkImage(
+                        imageUrl: imageUrl,
+                        fit: BoxFit.cover,
+                        fadeInDuration: Duration.zero,
+                        fadeOutDuration: Duration.zero,
+                        placeholder: (_, __) => Icon(
+                          MdiIcons.bookOutline,
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                        errorWidget: (_, __, ___) => Icon(
+                          MdiIcons.bookOutline,
+                          color: colorScheme.onSurfaceVariant,
+                        ),
+                      )
+                    : Icon(
+                        MdiIcons.bookOutline,
+                        color: colorScheme.onSurfaceVariant,
+                      ),
+              ),
+              if (book.progress > 0)
+                Positioned(
+                  bottom: 0,
+                  left: 0,
+                  right: 0,
+                  child: LinearProgressIndicator(
+                    value: book.progress,
+                    backgroundColor: Colors.black54,
+                    valueColor: AlwaysStoppedAnimation<Color>(colorScheme.primary),
+                    minHeight: 2,
+                  ),
+                ),
+            ],
+          ),
+        ),
+      ),
+      title: Hero(
+        tag: HeroTags.audiobookTitle + (book.uri ?? book.itemId) + '_$heroSuffix',
+        child: Material(
+          color: Colors.transparent,
+          child: Text(
+            book.name,
+            style: textTheme.titleMedium?.copyWith(
+              color: colorScheme.onSurface,
+              fontWeight: FontWeight.w500,
+            ),
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+          ),
+        ),
+      ),
+      subtitle: Text(
+        book.authorsString.isNotEmpty && book.authorsString != S.of(context)!.unknownAuthor
+            ? book.authorsString
+            : book.duration != null
+                ? _formatDuration(book.duration!)
+                : '',
+        style: textTheme.bodySmall?.copyWith(
+          color: colorScheme.onSurface.withOpacity(0.7),
+        ),
+        maxLines: 1,
+        overflow: TextOverflow.ellipsis,
+      ),
+      trailing: book.progress > 0
+          ? Text(
+              '${(book.progress * 100).toInt()}%',
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.primary,
+              ),
+            )
+          : null,
+      onTap: () => _navigateToAudiobook(book, heroTagSuffix: heroSuffix, initialImageUrl: imageUrl),
+    );
+  }
+
+  void _navigateToAudiobook(Audiobook book, {String? heroTagSuffix, String? initialImageUrl}) {
+    Navigator.push(
+      context,
+      FadeSlidePageRoute(
+        child: AudiobookDetailScreen(
+          audiobook: book,
+          heroTagSuffix: heroTagSuffix,
+          initialImageUrl: initialImageUrl,
+        ),
+      ),
+    );
+  }
+
+  String _formatDuration(Duration duration) {
+    final hours = duration.inHours;
+    final minutes = duration.inMinutes % 60;
+    if (hours > 0) {
+      return '${hours}h ${minutes}m';
+    }
+    return '${minutes}m';
+  }
+}
@@ -5,6 +5,7 @@ import 'package:share_plus/share_plus.dart';
 import '../services/debug_logger.dart';
 import '../providers/music_assistant_provider.dart';
 import '../widgets/global_player_overlay.dart';
+import '../l10n/app_localizations.dart';

 class DebugLogScreen extends StatefulWidget {
  const DebugLogScreen({super.key});
@@ -42,10 +43,10 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
  void _copyLogs() {
    Clipboard.setData(ClipboardData(text: _logger.getAllLogs()));
    ScaffoldMessenger.of(context).showSnackBar(
-      const SnackBar(
-        content: Text('Logs copied to clipboard'),
+      SnackBar(
+        content: Text(S.of(context)!.logsCopied),
        backgroundColor: Colors.green,
-        duration: Duration(seconds: 2),
+        duration: const Duration(seconds: 2),
      ),
    );
  }
@@ -58,7 +59,7 @@ class _DebugLogScreenState extends State<DebugLogScreen> {

      await Share.share(
        report,
-        subject: 'Ensemble Bug Report',
+        subject: S.of(context)!.ensembleBugReport,
      );
    } finally {
      if (mounted) {
@@ -72,9 +73,9 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
      _logger.clear();
    });
    ScaffoldMessenger.of(context).showSnackBar(
-      const SnackBar(
-        content: Text('Logs cleared'),
-        duration: Duration(seconds: 1),
+      SnackBar(
+        content: Text(S.of(context)!.logsCleared),
+        duration: const Duration(seconds: 1),
      ),
    );
  }
@@ -93,7 +94,7 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
        builder: (context) => AlertDialog(
          backgroundColor: const Color(0xFF2a2a2a),
          title: Text(
-            'All Players (${allPlayers.length})',
+            S.of(context)!.allPlayersCount(allPlayers.length),
            style: const TextStyle(color: Colors.white),
          ),
          content: SizedBox(
@@ -153,27 +154,27 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
                      crossAxisAlignment: CrossAxisAlignment.start,
                      children: [
                        Text(
-                          'ID: ${player.playerId}',
+                          S.of(context)!.playerId(player.playerId),
                          style: const TextStyle(color: Colors.white70, fontSize: 11),
                        ),
                        Text(
-                          'Available: ${player.available} | Provider: ${player.provider}',
+                          S.of(context)!.playerInfo(player.available.toString(), player.provider ?? 'unknown'),
                          style: const TextStyle(color: Colors.white70, fontSize: 11),
                        ),
                        if (isCurrentPlayer)
-                          const Text(
-                            '← This device',
-                            style: TextStyle(color: Colors.green, fontSize: 11, fontWeight: FontWeight.bold),
+                          Text(
+                            S.of(context)!.thisDevice,
+                            style: const TextStyle(color: Colors.green, fontSize: 11, fontWeight: FontWeight.bold),
                          ),
                        if (isGhost && !isCorrupt)
-                          const Text(
-                            '⚠️ Ghost player (duplicate)',
-                            style: TextStyle(color: Colors.red, fontSize: 11),
+                          Text(
+                            S.of(context)!.ghostPlayer,
+                            style: const TextStyle(color: Colors.red, fontSize: 11),
                          ),
                        if (isCorrupt)
-                          const Text(
-                            '⚠️ Unavailable/Corrupt',
-                            style: TextStyle(color: Colors.orange, fontSize: 11),
+                          Text(
+                            S.of(context)!.unavailableCorrupt,
+                            style: const TextStyle(color: Colors.orange, fontSize: 11),
                          ),
                      ],
                    ),
@@ -195,15 +196,15 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
                if (context.mounted) {
                  Navigator.pop(context);
                  ScaffoldMessenger.of(context).showSnackBar(
-                    const SnackBar(content: Text('Player list copied to clipboard!')),
+                    SnackBar(content: Text(S.of(context)!.playerListCopied)),
                  );
                }
              },
-              child: const Text('Copy List'),
+              child: Text(S.of(context)!.copyList),
            ),
            TextButton(
              onPressed: () => Navigator.pop(context),
-              child: const Text('Close'),
+              child: Text(S.of(context)!.close),
            ),
          ],
        ),
@@ -211,7 +212,7 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
    } catch (e) {
      if (mounted) {
        ScaffoldMessenger.of(context).showSnackBar(
-          SnackBar(content: Text('Error loading players: $e')),
+          SnackBar(content: Text(S.of(context)!.errorLoadingPlayers(e.toString()))),
        );
      }
    }
@@ -229,9 +230,9 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
          onPressed: () => Navigator.pop(context),
          color: Colors.white,
        ),
-        title: const Text(
-          'Debug Logs',
-          style: TextStyle(
+        title: Text(
+          S.of(context)!.debugLogs,
+          style: const TextStyle(
            color: Colors.white,
            fontSize: 20,
            fontWeight: FontWeight.w300,
@@ -256,11 +257,11 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
                  icon: const Icon(Icons.share_rounded),
                  onPressed: _shareBugReport,
                  color: Colors.white,
-                  tooltip: 'Share bug report',
+                  tooltip: S.of(context)!.shareBugReport,
                ),
          PopupMenuButton<String>(
            icon: const Icon(Icons.more_vert, color: Colors.white),
-            tooltip: 'More options',
+            tooltip: S.of(context)!.moreOptions,
            onSelected: (value) async {
              switch (value) {
                case 'show_players':
@@ -275,27 +276,27 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
              }
            },
            itemBuilder: (context) => [
-              const PopupMenuItem(
+              PopupMenuItem(
                value: 'show_players',
                child: ListTile(
-                  leading: Icon(Icons.speaker_group_rounded),
-                  title: Text('View All Players'),
+                  leading: const Icon(Icons.speaker_group_rounded),
+                  title: Text(S.of(context)!.viewAllPlayers),
                  dense: true,
                ),
              ),
-              const PopupMenuItem(
+              PopupMenuItem(
                value: 'copy_logs',
                child: ListTile(
-                  leading: Icon(Icons.copy_rounded),
-                  title: Text('Copy Logs'),
+                  leading: const Icon(Icons.copy_rounded),
+                  title: Text(S.of(context)!.copyLogs),
                  dense: true,
                ),
              ),
-              const PopupMenuItem(
+              PopupMenuItem(
                value: 'clear_logs',
                child: ListTile(
-                  leading: Icon(Icons.delete_rounded),
-                  title: Text('Clear Logs'),
+                  leading: const Icon(Icons.delete_rounded),
+                  title: Text(S.of(context)!.clearLogs),
                  dense: true,
                ),
              ),
@@ -317,20 +318,20 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
                  scrollDirection: Axis.horizontal,
                  child: Row(
                    children: [
-                      _buildFilterChip('All', LogLevel.debug),
+                      _buildFilterChip(S.of(context)!.all, LogLevel.debug),
                      const SizedBox(width: 8),
-                      _buildFilterChip('Info+', LogLevel.info),
+                      _buildFilterChip(S.of(context)!.infoPlus, LogLevel.info),
                      const SizedBox(width: 8),
-                      _buildFilterChip('Warnings', LogLevel.warning),
+                      _buildFilterChip(S.of(context)!.warnings, LogLevel.warning),
                      const SizedBox(width: 8),
-                      _buildFilterChip('Errors', LogLevel.error),
+                      _buildFilterChip(S.of(context)!.errors, LogLevel.error),
                    ],
                  ),
                ),
                const SizedBox(height: 8),
                // Stats
                Text(
-                  'Showing ${_filteredEntries.length} of ${_logger.entries.length} entries',
+                  S.of(context)!.showingEntries(_filteredEntries.length, _logger.entries.length),
                  style: const TextStyle(color: Colors.white54, fontSize: 11),
                ),
              ],
@@ -338,10 +339,10 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
          ),
          Expanded(
            child: _filteredEntries.isEmpty
-                ? const Center(
+                ? Center(
                    child: Text(
-                      'No logs yet',
-                      style: TextStyle(
+                      S.of(context)!.noLogsYet,
+                      style: const TextStyle(
                        color: Colors.white54,
                        fontSize: 16,
                      ),
@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
+import '../l10n/app_localizations.dart';
 import '../providers/navigation_provider.dart';
 import '../widgets/global_player_overlay.dart';
 import 'new_home_screen.dart';
@@ -39,7 +40,7 @@ class _HomeScreenState extends State<HomeScreen> {
    ScaffoldMessenger.of(context).clearSnackBars();
    ScaffoldMessenger.of(context).showSnackBar(
      SnackBar(
-        content: const Text('Press back again to minimize'),
+        content: Text(S.of(context)!.pressBackToMinimize),
        duration: const Duration(seconds: 2),
        behavior: SnackBarBehavior.floating,
        margin: const EdgeInsets.only(bottom: 80, left: 16, right: 16),
@@ -61,6 +62,18 @@ class _HomeScreenState extends State<HomeScreen> {
          onPopInvokedWithResult: (didPop, result) {
            if (didPop) return;

+            // If player reveal (device list) is visible, dismiss it first (with animation)
+            if (GlobalPlayerOverlay.isPlayerRevealVisible) {
+              GlobalPlayerOverlay.dismissPlayerReveal();
+              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,6 +4,7 @@ import '../providers/music_assistant_provider.dart';
 import '../models/media_item.dart';
 import '../widgets/album_card.dart';
 import '../widgets/common/empty_state.dart';
+import '../l10n/app_localizations.dart';

 class LibraryAlbumsScreen extends StatelessWidget {
  const LibraryAlbumsScreen({super.key});
@@ -25,7 +26,7 @@ class LibraryAlbumsScreen extends StatelessWidget {
          color: colorScheme.onBackground,
        ),
        title: Text(
-          'Albums',
+          S.of(context)!.albums,
          style: textTheme.headlineSmall?.copyWith(
            color: colorScheme.onBackground,
            fontWeight: FontWeight.w300,
@@ -46,7 +47,9 @@ class LibraryAlbumsScreen extends StatelessWidget {
  Widget _buildAlbumsList(BuildContext context, List<Album> albums, bool isLoading) {
    final colorScheme = Theme.of(context).colorScheme;

-    if (isLoading) {
+    // Show cached data immediately if available, even while loading
+    // Only show spinner if we have no data at all AND we're loading
+    if (albums.isEmpty && isLoading) {
      return Center(
        child: CircularProgressIndicator(color: colorScheme.primary),
      );
@@ -54,13 +57,14 @@ class LibraryAlbumsScreen extends StatelessWidget {

    if (albums.isEmpty) {
      return EmptyState.albums(
+        context: context,
        onRefresh: () => context.read<MusicAssistantProvider>().loadLibrary(),
      );
    }

    return RefreshIndicator(
      color: colorScheme.primary,
-      backgroundColor: colorScheme.surface,
+      backgroundColor: colorScheme.background,
      onRefresh: () async {
        await context.read<MusicAssistantProvider>().loadLibrary();
      },
@@ -6,6 +6,7 @@ import '../utils/page_transitions.dart';
 import '../widgets/common/empty_state.dart';
 import '../widgets/artist_avatar.dart';
 import 'artist_details_screen.dart';
+import '../l10n/app_localizations.dart';

 class LibraryArtistsScreen extends StatelessWidget {
  const LibraryArtistsScreen({super.key});
@@ -27,7 +28,7 @@ class LibraryArtistsScreen extends StatelessWidget {
          color: colorScheme.onBackground,
        ),
        title: Text(
-          'Artists',
+          S.of(context)!.artists,
          style: textTheme.headlineSmall?.copyWith(
            color: colorScheme.onBackground,
            fontWeight: FontWeight.w300,
@@ -48,7 +49,9 @@ class LibraryArtistsScreen extends StatelessWidget {
  Widget _buildArtistsList(BuildContext context, List<Artist> artists, bool isLoading) {
    final colorScheme = Theme.of(context).colorScheme;

-    if (isLoading) {
+    // Show cached data immediately if available, even while loading
+    // Only show spinner if we have no data at all AND we're loading
+    if (artists.isEmpty && isLoading) {
      return Center(
        child: CircularProgressIndicator(color: colorScheme.primary),
      );
@@ -56,13 +59,14 @@ class LibraryArtistsScreen extends StatelessWidget {

    if (artists.isEmpty) {
      return EmptyState.artists(
+        context: context,
        onRefresh: () => context.read<MusicAssistantProvider>().loadLibrary(),
      );
    }

    return RefreshIndicator(
      color: colorScheme.primary,
-      backgroundColor: colorScheme.surface,
+      backgroundColor: colorScheme.background,
      onRefresh: () async {
        await context.read<MusicAssistantProvider>().loadLibrary();
      },
@@ -4,7 +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});
@@ -29,17 +34,11 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
    });

    final maProvider = context.read<MusicAssistantProvider>();
-    if (maProvider.api != null) {
-      final playlists = await maProvider.api!.getPlaylists(limit: 100);
-      setState(() {
-        _playlists = playlists;
-        _isLoading = false;
-      });
-    } else {
-      setState(() {
-        _isLoading = false;
-      });
-    }
+    final playlists = await maProvider.getPlaylists(limit: 100);
+    setState(() {
+      _playlists = playlists;
+      _isLoading = false;
+    });
  }

  @override
@@ -59,7 +58,7 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
          color: colorScheme.onBackground,
        ),
        title: Text(
-          'Playlists',
+          S.of(context)!.playlists,
          style: textTheme.headlineSmall?.copyWith(
            color: colorScheme.onBackground,
            fontWeight: FontWeight.w300,
@@ -74,19 +73,21 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
  Widget _buildPlaylistsList(BuildContext context, MusicAssistantProvider provider) {
    final colorScheme = Theme.of(context).colorScheme;

-    if (_isLoading) {
+    // Show cached data immediately if available, even while loading
+    // Only show spinner if we have no data at all AND we're loading
+    if (_playlists.isEmpty && _isLoading) {
      return Center(
        child: CircularProgressIndicator(color: colorScheme.primary),
      );
    }

    if (_playlists.isEmpty) {
-      return EmptyState.playlists(onRefresh: _loadPlaylists);
+      return EmptyState.playlists(context: context, onRefresh: _loadPlaylists);
    }

    return RefreshIndicator(
      color: colorScheme.primary,
-      backgroundColor: colorScheme.surface,
+      backgroundColor: colorScheme.background,
      onRefresh: _loadPlaylists,
      child: ListView.builder(
        itemCount: _playlists.length,
@@ -107,39 +108,60 @@ 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(
-          width: 48,
-          height: 48,
-          decoration: BoxDecoration(
-            color: colorScheme.surfaceVariant,
+        leading: Hero(
+          tag: HeroTags.playlistCover + (playlist.uri ?? playlist.itemId) + heroSuffix,
+          child: ClipRRect(
            borderRadius: BorderRadius.circular(8),
-            image: imageUrl != null
-                ? DecorationImage(
-                    image: CachedNetworkImageProvider(imageUrl),
-                    fit: BoxFit.cover,
-                  )
-                : null,
+            child: Container(
+              width: 48,
+              height: 48,
+              color: colorScheme.surfaceContainerHighest,
+              child: imageUrl != 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(
-          playlist.name,
-          style: textTheme.titleMedium?.copyWith(
-            color: colorScheme.onSurface,
-            fontWeight: FontWeight.w500,
+        title: Hero(
+          tag: HeroTags.playlistTitle + (playlist.uri ?? playlist.itemId) + heroSuffix,
+          child: Material(
+            color: Colors.transparent,
+            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
-              ? '${playlist.trackCount} tracks'
-              : playlist.owner ?? 'Playlist',
+              ? '${playlist.trackCount} ${S.of(context)!.tracks}'
+              : playlist.owner ?? S.of(context)!.playlist,
          style: textTheme.bodySmall?.copyWith(
            color: colorScheme.onSurface.withOpacity(0.7),
          ),
@@ -147,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(
-              builder: (context) => PlaylistDetailsScreen(
+            FadeSlidePageRoute(
+              child: PlaylistDetailsScreen(
                playlist: playlist,
-                provider: playlist.provider,
-                itemId: playlist.itemId,
+                heroTagSuffix: 'playlists',
+                initialImageUrl: imageUrl,
              ),
            ),
          );
@@ -4,6 +4,7 @@ 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 '../l10n/app_localizations.dart';

 class LibraryTracksScreen extends StatelessWidget {
  const LibraryTracksScreen({super.key});
@@ -25,7 +26,7 @@ class LibraryTracksScreen extends StatelessWidget {
          color: colorScheme.onBackground,
        ),
        title: Text(
-          'Tracks',
+          S.of(context)!.tracks,
          style: textTheme.headlineSmall?.copyWith(
            color: colorScheme.onBackground,
            fontWeight: FontWeight.w300,
@@ -41,14 +42,16 @@ class LibraryTracksScreen extends StatelessWidget {
      BuildContext context, MusicAssistantProvider provider) {
    final colorScheme = Theme.of(context).colorScheme;

-    if (provider.isLoading) {
+    // Show cached data immediately if available, even while loading
+    // Only show spinner if we have no data at all AND we're loading
+    if (provider.tracks.isEmpty && provider.isLoading) {
      return Center(
        child: CircularProgressIndicator(color: colorScheme.primary),
      );
    }

    if (provider.tracks.isEmpty) {
-      return EmptyState.tracks(onRefresh: provider.loadLibrary);
+      return EmptyState.tracks(context: context, onRefresh: provider.loadLibrary);
    }

    return ListView.builder(
@@ -129,7 +132,7 @@ class LibraryTracksScreen extends StatelessWidget {

    if (maProvider.selectedPlayer == null) {
      ScaffoldMessenger.of(context).showSnackBar(
-        const SnackBar(content: Text('No player selected')),
+        SnackBar(content: Text(S.of(context)!.noPlayerSelected)),
      );
      return;
    }
@@ -2,9 +2,12 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import '../providers/music_assistant_provider.dart';
 import '../services/settings_service.dart';
+import '../services/database_service.dart';
+import '../services/profile_service.dart';
 import '../services/auth/auth_strategy.dart';
 import '../services/debug_logger.dart';
 import '../widgets/debug/debug_console.dart';
+import '../l10n/app_localizations.dart';
 import 'home_screen.dart';

 class LoginScreen extends StatefulWidget {
@@ -30,6 +33,8 @@ class _LoginScreenState extends State<LoginScreen> {
  String? _error;
  bool _showDebug = false;
  List<String> _debugLogs = [];
+  String? _resolvedServerUrl; // The actual URL after fallback (e.g., HTTP if HTTPS failed)
+  bool _usedHttpFallback = false; // True if HTTPS failed and we fell back to HTTP

  @override
  void initState() {
@@ -94,10 +99,27 @@ class _LoginScreenState extends State<LoginScreen> {
      return 'http://$url';
    }

+    // Tailscale URLs (*.ts.net) - default to http:// since VPN tunnel is already encrypted
+    if (url.endsWith('.ts.net') || url.contains('.ts.net:')) {
+      return 'http://$url';
+    }
+
    // For domain names, default to https://
    return 'https://$url';
  }

+  /// Check if the URL is using HTTP (for security warning display)
+  bool _isHttpConnection(String url) {
+    final normalized = _normalizeServerUrl(url);
+    return normalized.startsWith('http://') && !normalized.startsWith('https://');
+  }
+
+  /// Check if the URL is a Tailscale URL (safe for HTTP)
+  bool _isTailscaleUrl(String url) {
+    final normalized = url.trim().toLowerCase();
+    return normalized.contains('.ts.net');
+  }
+
  String _buildServerUrl() {
    // Normalize the base URL
    var url = _normalizeServerUrl(_serverUrlController.text.trim());
@@ -137,7 +159,7 @@ class _LoginScreenState extends State<LoginScreen> {
  Future<void> _detectAuthRequirements() async {
    if (_serverUrlController.text.trim().isEmpty) {
      setState(() {
-        _error = 'Please enter your Music Assistant server address';
+        _error = S.of(context)!.pleaseEnterServerAddress;
      });
      return;
    }
@@ -147,6 +169,8 @@ class _LoginScreenState extends State<LoginScreen> {
      _error = null;
      _detectedAuthStrategy = null;
      _detectedAuthType = null;
+      _resolvedServerUrl = null;
+      _usedHttpFallback = false;
      _debugLogs.clear();
    });

@@ -160,11 +184,18 @@ class _LoginScreenState extends State<LoginScreen> {
      // Auto-detect authentication requirements
      final strategy = await provider.authManager.detectAuthStrategy(serverUrl);

+      // Check if auth manager used a different URL (e.g., HTTP fallback)
+      final resolvedUrl = provider.authManager.lastSuccessfulUrl;
+      if (resolvedUrl != null && resolvedUrl != serverUrl) {
+        _addDebugLog('URL resolved via fallback: $resolvedUrl');
+        _usedHttpFallback = serverUrl.startsWith('https://') && resolvedUrl.startsWith('http://');
+      }
+
      _addDebugLog('Detection complete. Strategy: ${strategy?.name ?? 'null'}');

      if (strategy == null) {
        setState(() {
-          _error = 'Cannot determine authentication requirements. Please check server URL.';
+          _error = S.of(context)!.cannotDetermineAuth;
          _isDetectingAuth = false;
        });
        return;
@@ -173,6 +204,7 @@ class _LoginScreenState extends State<LoginScreen> {
      setState(() {
        _detectedAuthStrategy = strategy;
        _detectedAuthType = _getAuthTypeName(strategy.name);
+        _resolvedServerUrl = resolvedUrl;
        _isDetectingAuth = false;
      });

@@ -199,13 +231,13 @@ class _LoginScreenState extends State<LoginScreen> {
  String _getAuthTypeName(String strategyName) {
    switch (strategyName) {
      case 'none':
-        return 'No Authentication';
+        return S.of(context)!.noAuthentication;
      case 'basic':
-        return 'HTTP Basic Auth';
+        return S.of(context)!.httpBasicAuth;
      case 'authelia':
-        return 'Authelia';
+        return S.of(context)!.authelia;
      case 'music_assistant':
-        return 'Music Assistant Login';
+        return S.of(context)!.musicAssistantLogin;
      default:
        return 'Unknown';
    }
@@ -229,7 +261,7 @@ class _LoginScreenState extends State<LoginScreen> {
  Future<void> _connect() async {
    if (_serverUrlController.text.trim().isEmpty) {
      setState(() {
-        _error = 'Please enter your Music Assistant server address';
+        _error = S.of(context)!.pleaseEnterServerAddress;
      });
      return;
    }
@@ -239,7 +271,7 @@ class _LoginScreenState extends State<LoginScreen> {
    final isMaAuth = _detectedAuthStrategy?.name == 'music_assistant';
    if (!isMaAuth && _ownerNameController.text.trim().isEmpty) {
      setState(() {
-        _error = 'Please enter your name';
+        _error = S.of(context)!.pleaseEnterName;
      });
      return;
    }
@@ -250,7 +282,9 @@ class _LoginScreenState extends State<LoginScreen> {
    });

    try {
-      final serverUrl = _buildServerUrl();
+      // Use the resolved URL if available (e.g., from HTTP fallback), otherwise build it
+      final serverUrl = _resolvedServerUrl ?? _buildServerUrl();
+      _addDebugLog('Using server URL for connection: $serverUrl');
      final port = _portController.text.trim();

      // Validate port (if provided)
@@ -259,7 +293,7 @@ class _LoginScreenState extends State<LoginScreen> {
        portNum = int.tryParse(port);
        if (portNum == null || portNum < 1 || portNum > 65535) {
          setState(() {
-            _error = 'Please enter a valid port number (1-65535)';
+            _error = S.of(context)!.pleaseEnterValidPort;
            _isConnecting = false;
          });
          return;
@@ -269,7 +303,13 @@ class _LoginScreenState extends State<LoginScreen> {
      // Save owner name (if provided) and port to settings
      // For MA auth, the owner name will be set from user profile after login
      if (!isMaAuth && _ownerNameController.text.trim().isNotEmpty) {
-        await SettingsService.setOwnerName(_ownerNameController.text.trim());
+        final ownerName = _ownerNameController.text.trim();
+        await SettingsService.setOwnerName(ownerName);
+
+        // Create/activate profile in local database for manual name entry
+        if (DatabaseService.instance.isInitialized) {
+          await ProfileService.instance.onManualNameEntered(ownerName);
+        }
      }
      await SettingsService.setWebSocketPort(portNum);

@@ -285,7 +325,7 @@ class _LoginScreenState extends State<LoginScreen> {

        if (username.isEmpty || password.isEmpty) {
          setState(() {
-            _error = 'Please enter username and password';
+            _error = S.of(context)!.pleaseEnterCredentials;
            _isConnecting = false;
          });
          return;
@@ -311,7 +351,7 @@ class _LoginScreenState extends State<LoginScreen> {

        if (!success) {
          setState(() {
-            _error = 'Authentication failed. Please check your credentials.';
+            _error = S.of(context)!.authFailed;
            _isConnecting = false;
          });
          return;
@@ -345,7 +385,7 @@ class _LoginScreenState extends State<LoginScreen> {

        if (username.isEmpty || password.isEmpty) {
          setState(() {
-            _error = 'Please enter username and password';
+            _error = S.of(context)!.pleaseEnterCredentials;
            _isConnecting = false;
          });
          return;
@@ -369,7 +409,7 @@ class _LoginScreenState extends State<LoginScreen> {

          if (accessToken == null) {
            setState(() {
-              _error = 'Music Assistant login failed. Please check your credentials.';
+              _error = S.of(context)!.maLoginFailed;
              _isConnecting = false;
            });
            return;
@@ -403,6 +443,18 @@ class _LoginScreenState extends State<LoginScreen> {
      }

      if (provider.isConnected) {
+        // For first-time users, wait for player selection so the welcome
+        // overlay can appear immediately without home screen flash.
+        // This matches the logic in AppStartup._checkAndConnect().
+        final hasCompletedOnboarding = await SettingsService.getHasCompletedOnboarding();
+        if (!hasCompletedOnboarding) {
+          // First-time user: wait for connection + player selection
+          for (int i = 0; i < 20; i++) {
+            await Future.delayed(const Duration(milliseconds: 250));
+            if (provider.selectedPlayer != null) break;
+          }
+        }
+
        // Navigate to home screen
        if (mounted) {
          // Ensure keyboard is closed before navigating
@@ -413,7 +465,7 @@ class _LoginScreenState extends State<LoginScreen> {
        }
      } else {
        setState(() {
-          _error = 'Could not connect to server. Please check the address and try again.';
+          _error = S.of(context)!.connectionFailed;
          _isConnecting = false;
        });
      }
@@ -461,7 +513,7 @@ class _LoginScreenState extends State<LoginScreen> {

              // Server URL
              Text(
-                'Server Address',
+                S.of(context)!.serverAddress,
                style: textTheme.titleMedium?.copyWith(
                  color: colorScheme.onBackground,
                  fontWeight: FontWeight.w500,
@@ -473,7 +525,7 @@ class _LoginScreenState extends State<LoginScreen> {
                controller: _serverUrlController,
                style: TextStyle(color: colorScheme.onSurface),
                decoration: InputDecoration(
-                  hintText: 'e.g., music.example.com or 192.168.1.100',
+                  hintText: S.of(context)!.serverAddressHint,
                  hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                  filled: true,
                  fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -500,7 +552,7 @@ class _LoginScreenState extends State<LoginScreen> {
              if (_detectedAuthStrategy != null &&
                  _detectedAuthStrategy!.name != 'music_assistant') ...[
                Text(
-                  'Your Name',
+                  S.of(context)!.yourName,
                  style: textTheme.titleMedium?.copyWith(
                    color: colorScheme.onBackground,
                    fontWeight: FontWeight.w500,
@@ -512,7 +564,7 @@ class _LoginScreenState extends State<LoginScreen> {
                  controller: _ownerNameController,
                  style: TextStyle(color: colorScheme.onSurface),
                  decoration: InputDecoration(
-                    hintText: 'Your first name',
+                    hintText: S.of(context)!.yourFirstName,
                    hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                    filled: true,
                    fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -535,7 +587,7 @@ class _LoginScreenState extends State<LoginScreen> {

              // Port
              Text(
-                'Port (Optional)',
+                S.of(context)!.portOptional,
                style: textTheme.titleMedium?.copyWith(
                  color: colorScheme.onBackground,
                  fontWeight: FontWeight.w500,
@@ -543,7 +595,7 @@ class _LoginScreenState extends State<LoginScreen> {
              ),
              const SizedBox(height: 8),
              Text(
-                'Leave blank for reverse proxy or standard ports. Enter 8095 for direct connection.',
+                S.of(context)!.portDescription,
                style: TextStyle(
                  color: colorScheme.onBackground.withOpacity(0.6),
                  fontSize: 12,
@@ -555,7 +607,7 @@ class _LoginScreenState extends State<LoginScreen> {
                controller: _portController,
                style: TextStyle(color: colorScheme.onSurface),
                decoration: InputDecoration(
-                  hintText: 'e.g., 8095 or leave blank',
+                  hintText: S.of(context)!.portHint,
                  hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                  filled: true,
                  fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -600,7 +652,7 @@ class _LoginScreenState extends State<LoginScreen> {
                          crossAxisAlignment: CrossAxisAlignment.start,
                          children: [
                            Text(
-                              'Detected: $_detectedAuthType',
+                              S.of(context)!.detectedAuthType(_detectedAuthType!),
                              style: TextStyle(
                                color: needsAuth
                                    ? colorScheme.onPrimaryContainer
@@ -613,7 +665,7 @@ class _LoginScreenState extends State<LoginScreen> {
                              Padding(
                                padding: const EdgeInsets.only(top: 4),
                                child: Text(
-                                  'This server requires authentication',
+                                  S.of(context)!.serverRequiresAuth,
                                  style: TextStyle(
                                    color: colorScheme.onPrimaryContainer.withOpacity(0.7),
                                    fontSize: 12,
@@ -627,12 +679,77 @@ class _LoginScreenState extends State<LoginScreen> {
                  ),
                ),

+              // HTTP connection info banner
+              if (_resolvedServerUrl != null && _isHttpConnection(_resolvedServerUrl!))
+                Container(
+                  padding: const EdgeInsets.all(16),
+                  margin: const EdgeInsets.only(bottom: 24),
+                  decoration: BoxDecoration(
+                    color: _isTailscaleUrl(_serverUrlController.text)
+                        ? colorScheme.secondaryContainer.withOpacity(0.3)
+                        : colorScheme.errorContainer.withOpacity(0.3),
+                    borderRadius: BorderRadius.circular(12),
+                    border: _isTailscaleUrl(_serverUrlController.text)
+                        ? null
+                        : Border.all(color: colorScheme.error.withOpacity(0.3)),
+                  ),
+                  child: Row(
+                    children: [
+                      Icon(
+                        _isTailscaleUrl(_serverUrlController.text)
+                            ? Icons.vpn_lock_rounded
+                            : Icons.warning_amber_rounded,
+                        color: _isTailscaleUrl(_serverUrlController.text)
+                            ? colorScheme.secondary
+                            : colorScheme.error,
+                        size: 24,
+                      ),
+                      const SizedBox(width: 12),
+                      Expanded(
+                        child: Column(
+                          crossAxisAlignment: CrossAxisAlignment.start,
+                          children: [
+                            Text(
+                              _isTailscaleUrl(_serverUrlController.text)
+                                  ? S.of(context)!.tailscaleVpnConnection
+                                  : S.of(context)!.unencryptedConnection,
+                              style: TextStyle(
+                                color: _isTailscaleUrl(_serverUrlController.text)
+                                    ? colorScheme.onSecondaryContainer
+                                    : colorScheme.onErrorContainer,
+                                fontSize: 14,
+                                fontWeight: FontWeight.w600,
+                              ),
+                            ),
+                            Padding(
+                              padding: const EdgeInsets.only(top: 4),
+                              child: Text(
+                                _isTailscaleUrl(_serverUrlController.text)
+                                    ? S.of(context)!.usingHttpOverTailscale
+                                    : _usedHttpFallback
+                                        ? S.of(context)!.httpsFailedUsingHttp
+                                        : S.of(context)!.httpNotEncrypted,
+                                style: TextStyle(
+                                  color: (_isTailscaleUrl(_serverUrlController.text)
+                                      ? colorScheme.onSecondaryContainer
+                                      : colorScheme.onErrorContainer).withOpacity(0.7),
+                                  fontSize: 12,
+                                ),
+                              ),
+                            ),
+                          ],
+                        ),
+                      ),
+                    ],
+                  ),
+                ),
+
              // Authentication fields (shown only if auth required)
              if (needsAuth) ...[
                // Auth Server URL (only for Authelia)
                if (_detectedAuthStrategy?.name == 'authelia') ...[
                  Text(
-                    'Auth Server URL (Optional)',
+                    S.of(context)!.authServerUrlOptional,
                    style: textTheme.titleMedium?.copyWith(
                      color: colorScheme.onBackground,
                      fontWeight: FontWeight.w500,
@@ -640,7 +757,7 @@ class _LoginScreenState extends State<LoginScreen> {
                  ),
                  const SizedBox(height: 8),
                  Text(
-                    'Leave empty if authentication is on the same server',
+                    S.of(context)!.authServerUrlDescription,
                    style: TextStyle(
                      color: colorScheme.onBackground.withOpacity(0.6),
                      fontSize: 12,
@@ -652,7 +769,7 @@ class _LoginScreenState extends State<LoginScreen> {
                    controller: _authServerUrlController,
                    style: TextStyle(color: colorScheme.onSurface),
                    decoration: InputDecoration(
-                      hintText: 'e.g., auth.example.com (if different from server)',
+                      hintText: S.of(context)!.authServerUrlHint,
                      hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                      filled: true,
                      fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -673,7 +790,7 @@ class _LoginScreenState extends State<LoginScreen> {
                ],

                Text(
-                  'Username',
+                  S.of(context)!.username,
                  style: textTheme.titleMedium?.copyWith(
                    color: colorScheme.onBackground,
                    fontWeight: FontWeight.w500,
@@ -686,7 +803,7 @@ class _LoginScreenState extends State<LoginScreen> {
                  focusNode: _usernameFocusNode,
                  style: TextStyle(color: colorScheme.onSurface),
                  decoration: InputDecoration(
-                    hintText: 'Username',
+                    hintText: S.of(context)!.username,
                    hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                    filled: true,
                    fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -706,7 +823,7 @@ class _LoginScreenState extends State<LoginScreen> {
                const SizedBox(height: 16),

                Text(
-                  'Password',
+                  S.of(context)!.password,
                  style: textTheme.titleMedium?.copyWith(
                    color: colorScheme.onBackground,
                    fontWeight: FontWeight.w500,
@@ -718,7 +835,7 @@ class _LoginScreenState extends State<LoginScreen> {
                  controller: _passwordController,
                  style: TextStyle(color: colorScheme.onSurface),
                  decoration: InputDecoration(
-                    hintText: 'Password',
+                    hintText: S.of(context)!.password,
                    hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                    filled: true,
                    fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -808,9 +925,9 @@ class _LoginScreenState extends State<LoginScreen> {
                            ),
                          ),
                          const SizedBox(width: 12),
-                          const Text(
-                            'Detecting authentication...',
-                            style: TextStyle(
+                          Text(
+                            S.of(context)!.detectingAuth,
+                            style: const TextStyle(
                              fontSize: 16,
                              fontWeight: FontWeight.bold,
                            ),
@@ -827,7 +944,7 @@ class _LoginScreenState extends State<LoginScreen> {
                            ),
                          )
                        : Text(
-                            _detectedAuthStrategy == null ? 'Detect & Connect' : 'Connect',
+                            _detectedAuthStrategy == null ? S.of(context)!.detectAndConnect : S.of(context)!.connect,
                            style: const TextStyle(
                              fontSize: 16,
                              fontWeight: FontWeight.bold,
@@ -1,14 +1,21 @@
 import 'package:flutter/material.dart';
 import 'package:flutter/scheduler.dart';
 import 'package:provider/provider.dart';
+import '../l10n/app_localizations.dart';
 import '../providers/music_assistant_provider.dart';
 import '../services/settings_service.dart';
 import '../services/debug_logger.dart';
+import '../services/sync_service.dart';
 import '../widgets/global_player_overlay.dart';
 import '../widgets/player_selector.dart';
 import '../widgets/album_row.dart';
 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';
@@ -31,27 +38,102 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
  bool _showFavoriteAlbums = false;
  bool _showFavoriteArtists = false;
  bool _showFavoriteTracks = false;
-  // Random order for favorites (generated once per session)
-  late List<int> _favoritesOrder;
+  bool _showFavoritePlaylists = false;
+  bool _showFavoriteRadioStations = false;
+  bool _showFavoritePodcasts = false;
+  // Audiobook rows (default off)
+  bool _showContinueListeningAudiobooks = false;
+  bool _showDiscoverAudiobooks = false;
+  bool _showDiscoverSeries = false;
+  // Row order (loaded from settings)
+  List<String> _homeRowOrder = List.from(SettingsService.defaultHomeRowOrder);

  @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);
-    // Generate random order for favorites rows (0, 1, 2 shuffled)
-    _favoritesOrder = [0, 1, 2]..shuffle();
    _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)
@@ -67,6 +149,13 @@ 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();
+    final rowOrder = await SettingsService.getHomeRowOrder();
    if (mounted) {
      setState(() {
        _showRecentAlbums = showRecent;
@@ -75,6 +164,13 @@ 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;
+        _homeRowOrder = rowOrder;
      });
    }
  }
@@ -84,6 +180,9 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
    final provider = context.read<MusicAssistantProvider>();
    provider.invalidateHomeCache();

+    // Force full library sync from MA API
+    await provider.forceLibrarySync();
+
    // Reload settings in case they changed
    await _loadSettings();

@@ -127,6 +226,28 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
        titleSpacing: 0,
        centerTitle: false,
        actions: [
+          // Sync indicator - shows when library is syncing in background
+          ListenableBuilder(
+            listenable: SyncService.instance,
+            builder: (context, _) {
+              if (!SyncService.instance.isSyncing) {
+                return const SizedBox.shrink();
+              }
+              return Padding(
+                padding: const EdgeInsets.only(right: 8.0),
+                child: SizedBox(
+                  width: 20,
+                  height: 20,
+                  child: CircularProgressIndicator(
+                    strokeWidth: 2,
+                    valueColor: AlwaysStoppedAnimation<Color>(
+                      Theme.of(context).colorScheme.primary.withOpacity(0.7),
+                    ),
+                  ),
+                ),
+              );
+            },
+          ),
          const PlayerSelector(),
        ],
      ),
@@ -135,19 +256,63 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
          selector: (_, p) => p.isConnected,
          builder: (context, isConnected, child) {
            final maProvider = context.read<MusicAssistantProvider>();
-            return !isConnected
-                ? DisconnectedState.full(
-                    onSettings: () => Navigator.push(
-                      context,
-                      MaterialPageRoute(builder: (context) => const SettingsScreen()),
+            final syncService = SyncService.instance;
+
+            // Show cached data even when not connected (if we have cache)
+            // Only show disconnected state if we have no cached data at all
+            if (!isConnected && !syncService.hasCache) {
+              return DisconnectedState.full(
+                context: context,
+                onSettings: () => Navigator.push(
+                  context,
+                  MaterialPageRoute(builder: (context) => const SettingsScreen()),
+                ),
+              );
+            }
+
+            return Stack(
+              children: [
+                // Main content
+                RefreshIndicator(
+                  onRefresh: _onRefresh,
+                  color: colorScheme.primary,
+                  backgroundColor: colorScheme.background,
+                  child: _buildConnectedView(context, maProvider),
+                ),
+                // Connecting banner overlay (doesn't affect layout)
+                // Hide when we have cached players - UI is functional during background reconnect
+                if (!isConnected && syncService.hasCache && !maProvider.hasCachedPlayers)
+                  Positioned(
+                    top: 0,
+                    left: 0,
+                    right: 0,
+                    child: Container(
+                      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 6),
+                      color: colorScheme.primaryContainer.withOpacity(0.9),
+                      child: Row(
+                        mainAxisAlignment: MainAxisAlignment.center,
+                        children: [
+                          SizedBox(
+                            width: 12,
+                            height: 12,
+                            child: CircularProgressIndicator(
+                              strokeWidth: 2,
+                              color: colorScheme.primary,
+                            ),
+                          ),
+                          const SizedBox(width: 8),
+                          Text(
+                            S.of(context)!.connecting,
+                            style: Theme.of(context).textTheme.bodySmall?.copyWith(
+                              color: colorScheme.onPrimaryContainer,
+                            ),
+                          ),
+                        ],
+                      ),
                    ),
-                  )
-                : RefreshIndicator(
-                    onRefresh: _onRefresh,
-                    color: colorScheme.primary,
-                    backgroundColor: colorScheme.surface,
-                    child: _buildConnectedView(context, maProvider),
-                  );
+                  ),
+              ],
+            );
          },
        ),
      ),
@@ -155,18 +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 includes its title, artwork, and info
+        // Each row is always 1/3 of screen height
+        // 1 row = 1/3, 2 rows = 2/3, 3 rows = full screen, 4+ rows scroll
        final availableHeight = constraints.maxHeight - BottomSpacing.withMiniPlayer;
-        final rowHeight = availableHeight / 3;

-        // Build favorites rows in random order
-        final favoritesWidgets = _buildFavoritesRows(provider, rowHeight);
+        // 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>(
@@ -192,37 +389,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
              child: Column(
                key: _refreshKey,
                crossAxisAlignment: CrossAxisAlignment.start,
-                children: [
-                  // Recently played albums (optional)
-                  if (_showRecentAlbums)
-                    AlbumRow(
-                      key: const ValueKey('recent-albums'),
-                      title: 'Recently Played',
-                      loadAlbums: () => provider.getRecentAlbumsWithCache(),
-                      rowHeight: rowHeight,
-                    ),
-
-                  // Discover Artists (optional)
-                  if (_showDiscoverArtists)
-                    ArtistRow(
-                      key: const ValueKey('discover-artists'),
-                      title: 'Discover Artists',
-                      loadArtists: () => provider.getDiscoverArtistsWithCache(),
-                      rowHeight: rowHeight,
-                    ),
-
-                  // Discover Albums (optional)
-                  if (_showDiscoverAlbums)
-                    AlbumRow(
-                      key: const ValueKey('discover-albums'),
-                      title: 'Discover Albums',
-                      loadAlbums: () => provider.getDiscoverAlbumsWithCache(),
-                      rowHeight: rowHeight,
-                    ),
-
-                  // Favorites rows in random order
-                  ...favoritesWidgets,
-                ],
+                children: _buildOrderedRows(provider, rowHeight),
              ),
            ),
          ),
@@ -231,51 +398,135 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
    );
  }

-  /// Build favorites rows in random order (order set once per session)
-  List<Widget> _buildFavoritesRows(MusicAssistantProvider provider, double rowHeight) {
-    // Create list of enabled favorites with their order index
-    final enabledFavorites = <MapEntry<int, Widget>>[];
+  /// Build rows in the user's configured order
+  List<Widget> _buildOrderedRows(MusicAssistantProvider provider, double rowHeight) {
+    final rows = <Widget>[];

-    if (_showFavoriteAlbums) {
-      enabledFavorites.add(MapEntry(
-        _favoritesOrder[0],
-        AlbumRow(
+    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);
+      }
+    }
+
+    return rows;
+  }
+
+  /// Build a single row widget by ID, returns null if row is disabled
+  Widget? _buildRowWidget(String rowId, MusicAssistantProvider provider, double rowHeight) {
+    switch (rowId) {
+      case 'recent-albums':
+        if (!_showRecentAlbums) return null;
+        return AlbumRow(
+          key: const ValueKey('recent-albums'),
+          title: S.of(context)!.recentlyPlayed,
+          loadAlbums: () => provider.getRecentAlbumsWithCache(),
+          getCachedAlbums: () => provider.getCachedRecentAlbums(),
+          rowHeight: rowHeight,
+        );
+      case 'discover-artists':
+        if (!_showDiscoverArtists) return null;
+        return ArtistRow(
+          key: const ValueKey('discover-artists'),
+          title: S.of(context)!.discoverArtists,
+          loadArtists: () => provider.getDiscoverArtistsWithCache(),
+          getCachedArtists: () => provider.getCachedDiscoverArtists(),
+          rowHeight: rowHeight,
+        );
+      case 'discover-albums':
+        if (!_showDiscoverAlbums) return null;
+        return AlbumRow(
+          key: const ValueKey('discover-albums'),
+          title: S.of(context)!.discoverAlbums,
+          loadAlbums: () => provider.getDiscoverAlbumsWithCache(),
+          getCachedAlbums: () => provider.getCachedDiscoverAlbums(),
+          rowHeight: rowHeight,
+        );
+      case 'continue-listening':
+        if (!_showContinueListeningAudiobooks) return null;
+        return AudiobookRow(
+          key: const ValueKey('continue-listening'),
+          title: S.of(context)!.continueListening,
+          loadAudiobooks: () => provider.getInProgressAudiobooksWithCache(),
+          getCachedAudiobooks: () => provider.getCachedInProgressAudiobooks(),
+          rowHeight: rowHeight,
+        );
+      case 'discover-audiobooks':
+        if (!_showDiscoverAudiobooks) return null;
+        return AudiobookRow(
+          key: const ValueKey('discover-audiobooks'),
+          title: S.of(context)!.discoverAudiobooks,
+          loadAudiobooks: () => provider.getDiscoverAudiobooksWithCache(),
+          getCachedAudiobooks: () => provider.getCachedDiscoverAudiobooks(),
+          rowHeight: rowHeight,
+        );
+      case 'discover-series':
+        if (!_showDiscoverSeries) return null;
+        return SeriesRow(
+          key: const ValueKey('discover-series'),
+          title: S.of(context)!.discoverSeries,
+          loadSeries: () => provider.getDiscoverSeriesWithCache(),
+          getCachedSeries: () => provider.getCachedDiscoverSeries(),
+          rowHeight: rowHeight,
+        );
+      case 'favorite-albums':
+        if (!_showFavoriteAlbums) return null;
+        return AlbumRow(
          key: const ValueKey('favorite-albums'),
-          title: 'Favorite Albums',
+          title: S.of(context)!.favoriteAlbums,
          loadAlbums: () => provider.getFavoriteAlbums(),
          rowHeight: rowHeight,
-        ),
-      ));
-    }
-
-    if (_showFavoriteArtists) {
-      enabledFavorites.add(MapEntry(
-        _favoritesOrder[1],
-        ArtistRow(
+        );
+      case 'favorite-artists':
+        if (!_showFavoriteArtists) return null;
+        return ArtistRow(
          key: const ValueKey('favorite-artists'),
-          title: 'Favorite Artists',
+          title: S.of(context)!.favoriteArtists,
          loadArtists: () => provider.getFavoriteArtists(),
          rowHeight: rowHeight,
-        ),
-      ));
-    }
-
-    if (_showFavoriteTracks) {
-      enabledFavorites.add(MapEntry(
-        _favoritesOrder[2],
-        TrackRow(
+        );
+      case 'favorite-tracks':
+        if (!_showFavoriteTracks) return null;
+        return TrackRow(
          key: const ValueKey('favorite-tracks'),
-          title: 'Favorite Tracks',
+          title: S.of(context)!.favoriteTracks,
          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;
    }
-
-    // Sort by the random order index
-    enabledFavorites.sort((a, b) => a.key.compareTo(b.key));
-
-    return enabledFavorites.map((e) => e.value).toList();
  }
 }

@@ -0,0 +1,929 @@
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+import 'package:cached_network_image/cached_network_image.dart';
+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 '../constants/hero_tags.dart';
+import '../l10n/app_localizations.dart';
+
+class PodcastDetailScreen extends StatefulWidget {
+  final MediaItem podcast;
+  final String? heroTagSuffix;
+  final String? initialImageUrl;
+
+  const PodcastDetailScreen({
+    super.key,
+    required this.podcast,
+    this.heroTagSuffix,
+    this.initialImageUrl,
+  });
+
+  @override
+  State<PodcastDetailScreen> createState() => _PodcastDetailScreenState();
+}
+
+class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
+  final _logger = DebugLogger();
+  ColorScheme? _lightColorScheme;
+  ColorScheme? _darkColorScheme;
+  List<MediaItem> _episodes = [];
+  bool _isLoadingEpisodes = false;
+  bool _isDescriptionExpanded = false;
+  bool _isInLibrary = false;
+  String? _expandedEpisodeId; // Track which episode is expanded for actions
+
+  String get _heroTagSuffix => widget.heroTagSuffix != null ? '_${widget.heroTagSuffix}' : '';
+
+  @override
+  void initState() {
+    super.initState();
+    _isInLibrary = _checkIfInLibrary(widget.podcast);
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      Future.delayed(const Duration(milliseconds: 350), () {
+        if (mounted) {
+          _extractColors();
+        }
+      });
+      _loadEpisodes();
+    });
+  }
+
+  /// Check if podcast is in library
+  bool _checkIfInLibrary(MediaItem podcast) {
+    if (podcast.provider == 'library') return true;
+    return podcast.providerMappings?.any((m) => m.providerInstance == 'library') ?? false;
+  }
+
+  /// Toggle library status
+  Future<void> _toggleLibrary() async {
+    final maProvider = context.read<MusicAssistantProvider>();
+
+    try {
+      final newState = !_isInLibrary;
+
+      if (newState) {
+        // Add to library - MUST use non-library provider
+        String? actualProvider;
+        String? actualItemId;
+
+        if (widget.podcast.providerMappings != null && widget.podcast.providerMappings!.isNotEmpty) {
+          // For adding to library, we MUST use a non-library provider
+          final nonLibraryMapping = widget.podcast.providerMappings!.where(
+            (m) => m.providerInstance != 'library' && m.providerDomain != 'library',
+          ).firstOrNull;
+
+          if (nonLibraryMapping != null) {
+            actualProvider = nonLibraryMapping.providerDomain;
+            actualItemId = nonLibraryMapping.itemId;
+          }
+        }
+
+        // Fallback to item's own provider if no non-library mapping found
+        if (actualProvider == null || actualItemId == null) {
+          if (widget.podcast.provider != 'library') {
+            actualProvider = widget.podcast.provider;
+            actualItemId = widget.podcast.itemId;
+          } else {
+            // Item is library-only, can't add
+            _logger.log('Cannot add to library: podcast is library-only');
+            return;
+          }
+        }
+
+        // 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');
+        // 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;
+        if (widget.podcast.provider == 'library') {
+          libraryItemId = int.tryParse(widget.podcast.itemId);
+        } else if (widget.podcast.providerMappings != null) {
+          final libraryMapping = widget.podcast.providerMappings!.firstWhere(
+            (m) => m.providerInstance == 'library',
+            orElse: () => widget.podcast.providerMappings!.first,
+          );
+          if (libraryMapping.providerInstance == 'library') {
+            libraryItemId = int.tryParse(libraryMapping.itemId);
+          }
+        }
+
+        if (libraryItemId == null) {
+          _logger.log('Cannot remove from library: no library ID found');
+          return;
+        }
+
+        // OPTIMISTIC UPDATE: Update UI immediately
+        setState(() {
+          _isInLibrary = newState;
+        });
+
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(
+              content: Text(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');
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(
+            content: Text('Failed to update library: $e'),
+            duration: const Duration(seconds: 2),
+          ),
+        );
+      }
+    }
+  }
+
+  Future<void> _extractColors() async {
+    final maProvider = context.read<MusicAssistantProvider>();
+    // Use initialImageUrl first for consistency with hero animation
+    final imageUrl = widget.initialImageUrl ?? maProvider.getPodcastImageUrl(widget.podcast);
+
+    if (imageUrl != null) {
+      try {
+        final colorSchemes = await PaletteHelper.extractColorSchemes(
+          CachedNetworkImageProvider(imageUrl),
+        );
+        if (mounted && colorSchemes != null) {
+          setState(() {
+            _lightColorScheme = colorSchemes.$1;
+            _darkColorScheme = colorSchemes.$2;
+          });
+        }
+      } catch (e) {
+        _logger.log('🎙️ Error extracting colors: $e');
+      }
+    }
+  }
+
+  Future<void> _loadEpisodes() async {
+    if (_isLoadingEpisodes) return;
+
+    setState(() {
+      _isLoadingEpisodes = true;
+    });
+
+    try {
+      final maProvider = context.read<MusicAssistantProvider>();
+      if (maProvider.api != null) {
+        List<MediaItem> episodes = [];
+
+        // 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}');
+          // Debug: Log first episode metadata to see available fields
+          if (episodes.isNotEmpty) {
+            final first = episodes.first;
+            _logger.log('🎙️ First episode metadata keys: ${first.metadata?.keys.toList()}');
+            _logger.log('🎙️ First episode metadata: ${first.metadata}');
+          }
+          setState(() {
+            _episodes = episodes;
+          });
+        }
+      }
+    } catch (e) {
+      _logger.log('🎙️ Error loading episodes: $e');
+    } finally {
+      if (mounted) {
+        setState(() {
+          _isLoadingEpisodes = false;
+        });
+      }
+    }
+  }
+
+  void _playEpisode(MediaItem episode) async {
+    final maProvider = context.read<MusicAssistantProvider>();
+    final selectedPlayer = maProvider.selectedPlayer;
+
+    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(
+            SnackBar(
+              content: Text('Playing: ${episode.name}'),
+              duration: const Duration(seconds: 1),
+            ),
+          );
+        }
+      } catch (e) {
+        _logger.log('🎙️ Error playing episode: $e');
+        if (mounted) {
+          ScaffoldMessenger.of(context).showSnackBar(
+            SnackBar(content: Text('Failed to play episode: $e')),
+          );
+        }
+      }
+    } else {
+      _showPlayOnMenu(context, episode);
+    }
+  }
+
+  void _showPlayOnMenu(BuildContext context, MediaItem episode) {
+    final maProvider = context.read<MusicAssistantProvider>();
+
+    GlobalPlayerOverlay.hidePlayer();
+
+    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) {
+    if (duration == null || duration == Duration.zero) return '';
+    final hours = duration.inHours;
+    final minutes = duration.inMinutes.remainder(60);
+
+    if (hours > 0) {
+      return '${hours}h ${minutes}m';
+    }
+    return '${minutes} min';
+  }
+
+  /// Format release date from episode metadata
+  /// Tries various common field names for publication date
+  String? _formatReleaseDate(Map<String, dynamic>? metadata) {
+    if (metadata == null) return null;
+
+    // Try various common field names for publication date
+    dynamic dateValue = metadata['published'] ??
+        metadata['pub_date'] ??
+        metadata['release_date'] ??
+        metadata['aired'] ??
+        metadata['timestamp'];
+
+    if (dateValue == null) return null;
+
+    try {
+      DateTime? date;
+      if (dateValue is String) {
+        date = DateTime.tryParse(dateValue);
+      } else if (dateValue is int) {
+        // Unix timestamp
+        date = DateTime.fromMillisecondsSinceEpoch(dateValue * 1000);
+      }
+
+      if (date != null) {
+        // Format as "Jan 15, 2024"
+        final months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+        return '${months[date.month - 1]} ${date.day}, ${date.year}';
+      }
+    } catch (e) {
+      _logger.log('🎙️ Error parsing release date: $e');
+    }
+
+    return null;
+  }
+
+  /// Add episode to queue on current player
+  Future<void> _addToQueue(MediaItem episode) async {
+    final maProvider = context.read<MusicAssistantProvider>();
+    final selectedPlayer = maProvider.selectedPlayer;
+
+    if (selectedPlayer == null) {
+      ScaffoldMessenger.of(context).showSnackBar(
+        SnackBar(content: Text(S.of(context)!.noPlayerSelected)),
+      );
+      return;
+    }
+
+    try {
+      // Convert MediaItem to Track for queue addition
+      final track = Track(
+        itemId: episode.itemId,
+        provider: episode.provider,
+        name: episode.name,
+        uri: episode.uri,
+        duration: episode.duration,
+        metadata: episode.metadata,
+      );
+      await maProvider.addTrackToQueue(selectedPlayer.playerId, track);
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(
+            content: Text(S.of(context)!.addedToQueue),
+            duration: const Duration(seconds: 1),
+          ),
+        );
+      }
+    } catch (e) {
+      _logger.log('🎙️ Error adding episode to queue: $e');
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(content: Text(S.of(context)!.failedToAddToQueue(e.toString()))),
+        );
+      }
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // CRITICAL FIX: Use select() instead of watch() to prevent rebuilds during Hero animation
+    // watch() rebuilds on ANY provider change (library updates, etc.) causing animation jank
+    // select() only rebuilds when the specific podcast image URL changes
+    final providerImageUrl = context.select<MusicAssistantProvider, String?>(
+      (provider) => provider.getPodcastImageUrl(widget.podcast),
+    );
+    // Use initialImageUrl for seamless hero animation (same URL as source)
+    final imageUrl = widget.initialImageUrl ?? providerImageUrl;
+
+    final adaptiveTheme = context.select<ThemeProvider, bool>(
+      (provider) => provider.adaptiveTheme,
+    );
+    final adaptiveLightScheme = context.select<ThemeProvider, ColorScheme?>(
+      (provider) => provider.adaptiveLightScheme,
+    );
+    final adaptiveDarkScheme = context.select<ThemeProvider, ColorScheme?>(
+      (provider) => provider.adaptiveDarkScheme,
+    );
+
+    final isDark = Theme.of(context).brightness == Brightness.dark;
+
+    ColorScheme? adaptiveScheme;
+    if (adaptiveTheme) {
+      adaptiveScheme = isDark
+          ? (_darkColorScheme ?? adaptiveDarkScheme)
+          : (_lightColorScheme ?? adaptiveLightScheme);
+    }
+    final colorScheme = adaptiveScheme ?? Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    final description = widget.podcast.metadata?['description'] as String?;
+    final author = widget.podcast.metadata?['author'] as String?;
+
+    return PopScope(
+      canPop: true,
+      onPopInvokedWithResult: (didPop, result) {
+        if (didPop) {
+          clearAdaptiveColorsOnBack(context);
+        }
+      },
+      child: Scaffold(
+        backgroundColor: colorScheme.surface,
+        body: LayoutBuilder(
+          builder: (context, constraints) {
+            final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
+            final expandedHeight = coverSize + 70;
+
+            return CustomScrollView(
+              slivers: [
+                SliverAppBar(
+                  expandedHeight: expandedHeight,
+                  pinned: true,
+                  backgroundColor: colorScheme.surface,
+                  leading: IconButton(
+                    icon: const Icon(Icons.arrow_back_rounded),
+                    onPressed: () {
+                      clearAdaptiveColorsOnBack(context);
+                      Navigator.pop(context);
+                    },
+                    color: colorScheme.onSurface,
+                  ),
+                  flexibleSpace: FlexibleSpaceBar(
+                    background: Column(
+                      mainAxisAlignment: MainAxisAlignment.center,
+                      children: [
+                        const SizedBox(height: 60),
+                        Hero(
+                          tag: HeroTags.podcastCover + (widget.podcast.uri ?? widget.podcast.itemId) + _heroTagSuffix,
+                          // Match audiobook pattern: ClipRRect + CachedNetworkImage for smooth hero
+                          child: ClipRRect(
+                            borderRadius: BorderRadius.circular(16),
+                            child: Container(
+                              width: coverSize,
+                              height: coverSize,
+                              color: colorScheme.surfaceContainerHighest,
+                              child: imageUrl != null
+                                  ? CachedNetworkImage(
+                                      imageUrl: imageUrl,
+                                      fit: BoxFit.cover,
+                                      // Match source memCacheWidth for smooth Hero animation
+                                      memCacheWidth: 256,
+                                      memCacheHeight: 256,
+                                      fadeInDuration: Duration.zero,
+                                      fadeOutDuration: Duration.zero,
+                                      placeholder: (_, __) => Center(
+                                        child: Icon(
+                                          MdiIcons.podcast,
+                                          size: coverSize * 0.43,
+                                          color: colorScheme.onSurfaceVariant,
+                                        ),
+                                      ),
+                                      errorWidget: (_, __, ___) => Center(
+                                        child: Icon(
+                                          MdiIcons.podcast,
+                                          size: coverSize * 0.43,
+                                          color: colorScheme.onSurfaceVariant,
+                                        ),
+                                      ),
+                                    )
+                                  : Center(
+                                      child: Icon(
+                                        MdiIcons.podcast,
+                                        size: coverSize * 0.43,
+                                        color: colorScheme.onSurfaceVariant,
+                                      ),
+                                    ),
+                            ),
+                          ),
+                        ),
+                      ],
+                    ),
+                  ),
+                ),
+                SliverToBoxAdapter(
+                  child: Padding(
+                    padding: const EdgeInsets.all(16),
+                    child: Column(
+                      crossAxisAlignment: CrossAxisAlignment.center,
+                      children: [
+                        // Podcast title
+                        Text(
+                          widget.podcast.name,
+                          style: textTheme.headlineSmall?.copyWith(
+                            fontWeight: FontWeight.bold,
+                            color: colorScheme.onSurface,
+                          ),
+                          textAlign: TextAlign.center,
+                        ),
+                        if (author != null) ...[
+                          const SizedBox(height: 4),
+                          Text(
+                            author,
+                            style: textTheme.bodyLarge?.copyWith(
+                              color: colorScheme.onSurface.withOpacity(0.7),
+                            ),
+                            textAlign: TextAlign.center,
+                          ),
+                        ],
+                        const SizedBox(height: 16),
+
+                        // Action buttons row
+                        Padding(
+                          padding: const EdgeInsets.symmetric(horizontal: 16),
+                          child: Row(
+                            children: [
+                              // Main Play Latest Episode Button
+                              Expanded(
+                                flex: 2,
+                                child: SizedBox(
+                                  height: 50,
+                                  child: ElevatedButton.icon(
+                                    onPressed: _isLoadingEpisodes || _episodes.isEmpty
+                                        ? null
+                                        : () => _playEpisode(_episodes.first),
+                                    icon: const Icon(Icons.play_arrow_rounded),
+                                    label: Text(S.of(context)!.play),
+                                    style: ElevatedButton.styleFrom(
+                                      backgroundColor: colorScheme.primary,
+                                      foregroundColor: colorScheme.onPrimary,
+                                      disabledBackgroundColor: colorScheme.primary.withOpacity(0.38),
+                                      disabledForegroundColor: colorScheme.onPrimary.withOpacity(0.38),
+                                      shape: RoundedRectangleBorder(
+                                        borderRadius: BorderRadius.circular(12),
+                                      ),
+                                    ),
+                                  ),
+                                ),
+                              ),
+                              const SizedBox(width: 12),
+                              // "Play on..." Button
+                              SizedBox(
+                                height: 50,
+                                width: 50,
+                                child: FilledButton.tonal(
+                                  onPressed: _isLoadingEpisodes || _episodes.isEmpty
+                                      ? null
+                                      : () => _showPlayOnMenu(context, _episodes.first),
+                                  style: FilledButton.styleFrom(
+                                    padding: EdgeInsets.zero,
+                                    shape: RoundedRectangleBorder(
+                                      borderRadius: BorderRadius.circular(12),
+                                    ),
+                                  ),
+                                  child: const Icon(Icons.speaker_group_outlined),
+                                ),
+                              ),
+                              const SizedBox(width: 12),
+                              // Library button
+                              SizedBox(
+                                height: 50,
+                                width: 50,
+                                child: FilledButton.tonal(
+                                  onPressed: _toggleLibrary,
+                                  style: FilledButton.styleFrom(
+                                    padding: EdgeInsets.zero,
+                                    shape: RoundedRectangleBorder(
+                                      borderRadius: BorderRadius.circular(12),
+                                    ),
+                                  ),
+                                  child: Icon(
+                                    _isInLibrary ? Icons.library_add_check : Icons.library_add,
+                                    color: _isInLibrary
+                                        ? colorScheme.primary
+                                        : colorScheme.onSurfaceVariant,
+                                  ),
+                                ),
+                              ),
+                            ],
+                          ),
+                        ),
+                        const SizedBox(height: 16),
+
+                        // Description
+                        if (description != null && description.isNotEmpty) ...[
+                          GestureDetector(
+                            onTap: () {
+                              setState(() {
+                                _isDescriptionExpanded = !_isDescriptionExpanded;
+                              });
+                            },
+                            child: AnimatedCrossFade(
+                              firstChild: Text(
+                                description,
+                                maxLines: 3,
+                                overflow: TextOverflow.ellipsis,
+                                style: textTheme.bodyMedium?.copyWith(
+                                  color: colorScheme.onSurface.withOpacity(0.7),
+                                ),
+                              ),
+                              secondChild: Text(
+                                description,
+                                style: textTheme.bodyMedium?.copyWith(
+                                  color: colorScheme.onSurface.withOpacity(0.7),
+                                ),
+                              ),
+                              crossFadeState: _isDescriptionExpanded
+                                  ? CrossFadeState.showSecond
+                                  : CrossFadeState.showFirst,
+                              duration: const Duration(milliseconds: 200),
+                            ),
+                          ),
+                          const SizedBox(height: 16),
+                        ],
+
+                        // Episodes header
+                        Row(
+                          children: [
+                            Text(
+                              S.of(context)!.episodes,
+                              style: textTheme.titleLarge?.copyWith(
+                                fontWeight: FontWeight.bold,
+                                color: colorScheme.onSurface,
+                              ),
+                            ),
+                            const SizedBox(width: 8),
+                            if (_episodes.isNotEmpty)
+                              Text(
+                                '(${_episodes.length})',
+                                style: textTheme.bodyLarge?.copyWith(
+                                  color: colorScheme.onSurface.withOpacity(0.5),
+                                ),
+                              ),
+                          ],
+                        ),
+                      ],
+                    ),
+                  ),
+                ),
+
+                // Episodes list
+                if (_isLoadingEpisodes)
+                  SliverToBoxAdapter(
+                    child: Center(
+                      child: Padding(
+                        padding: const EdgeInsets.all(32),
+                        child: CircularProgressIndicator(color: colorScheme.primary),
+                      ),
+                    ),
+                  )
+                else if (_episodes.isEmpty)
+                  SliverToBoxAdapter(
+                    child: Center(
+                      child: Padding(
+                        padding: const EdgeInsets.all(32),
+                        child: Column(
+                          children: [
+                            Icon(
+                              MdiIcons.microphoneOff,
+                              size: 48,
+                              color: colorScheme.onSurface.withOpacity(0.3),
+                            ),
+                            const SizedBox(height: 16),
+                            Text(
+                              'No episodes found',
+                              style: textTheme.bodyLarge?.copyWith(
+                                color: colorScheme.onSurface.withOpacity(0.5),
+                              ),
+                            ),
+                          ],
+                        ),
+                      ),
+                    ),
+                  )
+                else
+                  SliverList(
+                    delegate: SliverChildBuilderDelegate(
+                      (context, index) {
+                        final episode = _episodes[index];
+                        final episodeDescription = episode.metadata?['description'] as String?;
+                        final duration = episode.duration;
+                        final episodeId = episode.uri ?? episode.itemId;
+                        final isExpanded = _expandedEpisodeId == episodeId;
+                        final episodeImageUrl = context.read<MusicAssistantProvider>().getImageUrl(episode, size: 256);
+
+                        // Try to get release date from metadata
+                        final releaseDate = _formatReleaseDate(episode.metadata);
+
+                        return Column(
+                          children: [
+                            InkWell(
+                              onTap: () => _playEpisode(episode),
+                              onLongPress: () {
+                                setState(() {
+                                  _expandedEpisodeId = isExpanded ? null : episodeId;
+                                });
+                              },
+                              child: Padding(
+                                padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
+                                child: Row(
+                                  crossAxisAlignment: CrossAxisAlignment.start,
+                                  children: [
+                                    // Episode cover (bigger than before)
+                                    ClipRRect(
+                                      borderRadius: BorderRadius.circular(8),
+                                      child: Container(
+                                        width: 72,
+                                        height: 72,
+                                        color: colorScheme.surfaceContainerHighest,
+                                        child: episodeImageUrl != null
+                                            ? CachedNetworkImage(
+                                                imageUrl: episodeImageUrl,
+                                                fit: BoxFit.cover,
+                                                fadeInDuration: Duration.zero,
+                                                fadeOutDuration: Duration.zero,
+                                                placeholder: (_, __) => Icon(
+                                                  MdiIcons.podcast,
+                                                  size: 32,
+                                                  color: colorScheme.onSurfaceVariant,
+                                                ),
+                                                errorWidget: (_, __, ___) => Icon(
+                                                  MdiIcons.podcast,
+                                                  size: 32,
+                                                  color: colorScheme.onSurfaceVariant,
+                                                ),
+                                              )
+                                            : Icon(
+                                                MdiIcons.podcast,
+                                                size: 32,
+                                                color: colorScheme.onSurfaceVariant,
+                                              ),
+                                      ),
+                                    ),
+                                    const SizedBox(width: 12),
+                                    // Episode info
+                                    Expanded(
+                                      child: Column(
+                                        crossAxisAlignment: CrossAxisAlignment.start,
+                                        children: [
+                                          Text(
+                                            episode.name,
+                                            style: textTheme.titleSmall?.copyWith(
+                                              fontWeight: FontWeight.w500,
+                                            ),
+                                            maxLines: 2,
+                                            overflow: TextOverflow.ellipsis,
+                                          ),
+                                          if (episodeDescription != null && episodeDescription.isNotEmpty) ...[
+                                            const SizedBox(height: 4),
+                                            Text(
+                                              episodeDescription,
+                                              maxLines: isExpanded ? 100 : 2,
+                                              overflow: TextOverflow.ellipsis,
+                                              style: textTheme.bodySmall?.copyWith(
+                                                color: colorScheme.onSurface.withOpacity(0.6),
+                                              ),
+                                            ),
+                                          ],
+                                          const SizedBox(height: 6),
+                                          // Duration and release date row
+                                          Row(
+                                            children: [
+                                              if (duration != null && duration > Duration.zero) ...[
+                                                Icon(
+                                                  Icons.access_time,
+                                                  size: 14,
+                                                  color: colorScheme.onSurface.withOpacity(0.5),
+                                                ),
+                                                const SizedBox(width: 4),
+                                                Text(
+                                                  _formatDuration(duration),
+                                                  style: textTheme.bodySmall?.copyWith(
+                                                    color: colorScheme.onSurface.withOpacity(0.5),
+                                                  ),
+                                                ),
+                                              ],
+                                              if (duration != null && duration > Duration.zero && releaseDate != null)
+                                                Padding(
+                                                  padding: const EdgeInsets.symmetric(horizontal: 8),
+                                                  child: Text(
+                                                    '•',
+                                                    style: textTheme.bodySmall?.copyWith(
+                                                      color: colorScheme.onSurface.withOpacity(0.5),
+                                                    ),
+                                                  ),
+                                                ),
+                                              if (releaseDate != null)
+                                                Text(
+                                                  releaseDate,
+                                                  style: textTheme.bodySmall?.copyWith(
+                                                    color: colorScheme.onSurface.withOpacity(0.5),
+                                                  ),
+                                                ),
+                                            ],
+                                          ),
+                                        ],
+                                      ),
+                                    ),
+                                  ],
+                                ),
+                              ),
+                            ),
+                            // Expanded action buttons (matching album track style)
+                            AnimatedCrossFade(
+                              firstChild: const SizedBox.shrink(),
+                              secondChild: Padding(
+                                padding: const EdgeInsets.only(left: 100, right: 16, bottom: 12),
+                                child: Row(
+                                  children: [
+                                    // Play button
+                                    SizedBox(
+                                      height: 44,
+                                      width: 44,
+                                      child: FilledButton.tonal(
+                                        onPressed: () => _playEpisode(episode),
+                                        style: FilledButton.styleFrom(
+                                          padding: EdgeInsets.zero,
+                                          shape: RoundedRectangleBorder(
+                                            borderRadius: BorderRadius.circular(12),
+                                          ),
+                                        ),
+                                        child: const Icon(Icons.play_arrow, size: 20),
+                                      ),
+                                    ),
+                                    const SizedBox(width: 10),
+                                    // Play on... button
+                                    SizedBox(
+                                      height: 44,
+                                      width: 44,
+                                      child: FilledButton.tonal(
+                                        onPressed: () => _showPlayOnMenu(context, episode),
+                                        style: FilledButton.styleFrom(
+                                          padding: EdgeInsets.zero,
+                                          shape: RoundedRectangleBorder(
+                                            borderRadius: BorderRadius.circular(12),
+                                          ),
+                                        ),
+                                        child: const Icon(Icons.speaker_group_outlined, size: 20),
+                                      ),
+                                    ),
+                                    const SizedBox(width: 10),
+                                    // Add to queue button
+                                    SizedBox(
+                                      height: 44,
+                                      width: 44,
+                                      child: FilledButton.tonal(
+                                        onPressed: () => _addToQueue(episode),
+                                        style: FilledButton.styleFrom(
+                                          padding: EdgeInsets.zero,
+                                          shape: RoundedRectangleBorder(
+                                            borderRadius: BorderRadius.circular(12),
+                                          ),
+                                        ),
+                                        child: const Icon(Icons.playlist_add, size: 20),
+                                      ),
+                                    ),
+                                  ],
+                                ),
+                              ),
+                              crossFadeState: isExpanded
+                                  ? CrossFadeState.showSecond
+                                  : CrossFadeState.showFirst,
+                              duration: const Duration(milliseconds: 200),
+                            ),
+                          ],
+                        );
+                      },
+                      childCount: _episodes.length,
+                    ),
+                  ),
+
+                // Bottom padding for mini player
+                SliverToBoxAdapter(
+                  child: SizedBox(height: BottomSpacing.withMiniPlayer),
+                ),
+              ],
+            );
+          },
+        ),
+      ),
+    );
+  }
+}
@@ -4,6 +4,8 @@ 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 {
  const QueueScreen({super.key});
@@ -51,7 +53,7 @@ class _QueueScreenState extends State<QueueScreen> {
        if (mounted) {
          setState(() {
            _isLoading = false;
-            _error = 'No player selected';
+            _error = S.of(context)!.noPlayerSelected;
          });
        }
      }
@@ -66,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>();
@@ -77,7 +141,7 @@ class _QueueScreenState extends State<QueueScreen> {
        backgroundColor: Colors.transparent,
        elevation: 0,
        title: Text(
-          player != null ? '${player.name} Queue' : 'Queue',
+          player != null ? S.of(context)!.playerQueue(player.name) : S.of(context)!.queue,
          style: const TextStyle(
            color: Colors.white,
            fontSize: 20,
@@ -86,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,
@@ -116,7 +185,7 @@ class _QueueScreenState extends State<QueueScreen> {
            const SizedBox(height: 16),
            ElevatedButton(
              onPressed: _loadQueue,
-              child: const Text('Retry'),
+              child: Text(S.of(context)!.retry),
            ),
          ],
        ),
@@ -131,7 +200,7 @@ class _QueueScreenState extends State<QueueScreen> {
            Icon(Icons.speaker_group, size: 64, color: Colors.grey[700]),
            const SizedBox(height: 16),
            Text(
-              'No player selected',
+              S.of(context)!.noPlayerSelected,
              style: TextStyle(color: Colors.grey[600], fontSize: 18),
            ),
          ],
@@ -140,7 +209,7 @@ class _QueueScreenState extends State<QueueScreen> {
    }

    if (_queue == null || _queue!.items.isEmpty) {
-      return EmptyState.queue();
+      return EmptyState.queue(context: context);
    }

    // Filter to show only current and upcoming items (not history)
@@ -148,9 +217,9 @@ class _QueueScreenState extends State<QueueScreen> {
    final upcomingItems = _queue!.items.sublist(currentIndex);

    if (upcomingItems.isEmpty) {
-      return const EmptyState(
+      return EmptyState(
        icon: Icons.queue_music,
-        message: 'No upcoming tracks',
+        message: S.of(context)!.noUpcomingTracks,
      );
    }

@@ -220,9 +289,9 @@ class _QueueScreenState extends State<QueueScreen> {

        ScaffoldMessenger.of(context).showSnackBar(
          SnackBar(
-            content: Text('Removed ${item.track.name}'),
+            content: Text(S.of(context)!.removedItem(item.track.name)),
            action: SnackBarAction(
-              label: 'Undo',
+              label: S.of(context)!.undo,
              onPressed: () {
                setState(() {
                  _queue!.items.insert(index, item);
@@ -1,9 +1,12 @@
 import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
+import '../l10n/app_localizations.dart';
+import '../providers/locale_provider.dart';
 import '../providers/music_assistant_provider.dart';
 import '../services/music_assistant_api.dart';
 import '../services/settings_service.dart';
 import '../theme/theme_provider.dart';
+import '../theme/app_theme.dart';
 import '../widgets/global_player_overlay.dart';
 import 'debug_log_screen.dart';
 import 'login_screen.dart';
@@ -26,6 +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);
+  // Player settings
+  bool _preferLocalPlayer = false;
+  bool _smartSortPlayers = false;
+  bool _volumePrecisionMode = true;
+  // Hint settings
+  bool _showHints = true;

  @override
  void initState() {
@@ -51,6 +69,26 @@ 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();
+    final showDiscAudiobooks = await SettingsService.getShowDiscoverAudiobooks();
+    final showDiscSeries = await SettingsService.getShowDiscoverSeries();
+
+    // Load home row order
+    final rowOrder = await SettingsService.getHomeRowOrder();
+
+    // 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();
+
    if (mounted) {
      setState(() {
        _showRecentAlbums = showRecent;
@@ -59,6 +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;
+        _preferLocalPlayer = preferLocal;
+        _smartSortPlayers = smartSort;
+        _volumePrecisionMode = volumePrecision;
+        _showHints = showHints;
      });
    }
  }
@@ -70,6 +119,127 @@ class _SettingsScreenState extends State<SettingsScreen> {
    super.dispose();
  }

+  // Helper to get row display info
+  Map<String, String> _getRowInfo(String rowId) {
+    final s = S.of(context)!;
+    switch (rowId) {
+      case 'recent-albums':
+        return {'title': s.recentlyPlayed, 'subtitle': s.showRecentlyPlayedAlbums};
+      case 'discover-artists':
+        return {'title': s.discoverArtists, 'subtitle': s.showRandomArtists};
+      case 'discover-albums':
+        return {'title': s.discoverAlbums, 'subtitle': s.showRandomAlbums};
+      case 'continue-listening':
+        return {'title': s.continueListening, 'subtitle': s.showAudiobooksInProgress};
+      case 'discover-audiobooks':
+        return {'title': s.discoverAudiobooks, 'subtitle': s.showRandomAudiobooks};
+      case 'discover-series':
+        return {'title': s.discoverSeries, 'subtitle': s.showRandomSeries};
+      case 'favorite-albums':
+        return {'title': s.favoriteAlbums, 'subtitle': s.showFavoriteAlbums};
+      case 'favorite-artists':
+        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': ''};
+    }
+  }
+
+  // Helper to get row enabled state
+  bool _getRowEnabled(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;
+    }
+  }
+
+  // Helper to set row enabled state
+  void _setRowEnabled(String rowId, bool value) {
+    setState(() {
+      switch (rowId) {
+        case 'recent-albums':
+          _showRecentAlbums = value;
+          SettingsService.setShowRecentAlbums(value);
+          break;
+        case 'discover-artists':
+          _showDiscoverArtists = value;
+          SettingsService.setShowDiscoverArtists(value);
+          break;
+        case 'discover-albums':
+          _showDiscoverAlbums = value;
+          SettingsService.setShowDiscoverAlbums(value);
+          break;
+        case 'continue-listening':
+          _showContinueListeningAudiobooks = value;
+          SettingsService.setShowContinueListeningAudiobooks(value);
+          break;
+        case 'discover-audiobooks':
+          _showDiscoverAudiobooks = value;
+          SettingsService.setShowDiscoverAudiobooks(value);
+          break;
+        case 'discover-series':
+          _showDiscoverSeries = value;
+          SettingsService.setShowDiscoverSeries(value);
+          break;
+        case 'favorite-albums':
+          _showFavoriteAlbums = value;
+          SettingsService.setShowFavoriteAlbums(value);
+          break;
+        case 'favorite-artists':
+          _showFavoriteArtists = value;
+          SettingsService.setShowFavoriteArtists(value);
+          break;
+        case 'favorite-tracks':
+          _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;
+      }
+    });
+  }
+
  Future<void> _disconnect() async {
    final provider = context.read<MusicAssistantProvider>();
    await provider.disconnect();
@@ -103,7 +273,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
          color: colorScheme.onBackground,
        ),
        title: Text(
-          'Settings',
+          S.of(context)!.settings,
          style: textTheme.titleLarge?.copyWith(
            color: colorScheme.onBackground,
            fontWeight: FontWeight.w300,
@@ -122,7 +292,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
              );
            },
            color: colorScheme.onBackground,
-            tooltip: 'Debug Logs',
+            tooltip: S.of(context)!.debugLogs,
          ),
        ],
      ),
@@ -132,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(
-                'assets/images/ensemble_icon_transparent.png',
-                width: MediaQuery.of(context).size.width * 0.5,
-                fit: BoxFit.contain,
-              ),
+              child: Theme.of(context).brightness == Brightness.light
+                  ? ColorFiltered(
+                      colorFilter: const ColorFilter.mode(
+                        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
@@ -178,9 +361,9 @@ class _SettingsScreenState extends State<SettingsScreen> {
              child: FilledButton.tonalIcon(
                onPressed: _disconnect,
                icon: const Icon(Icons.logout_rounded),
-                label: const Text(
-                  'Disconnect',
-                  style: TextStyle(
+                label: Text(
+                  S.of(context)!.disconnect,
+                  style: const TextStyle(
                    fontSize: 16,
                    fontWeight: FontWeight.w500,
                  ),
@@ -199,7 +382,7 @@ class _SettingsScreenState extends State<SettingsScreen> {

            // Theme section
            Text(
-              'Theme',
+              S.of(context)!.theme,
              style: textTheme.titleMedium?.copyWith(
                color: colorScheme.onBackground,
                fontWeight: FontWeight.bold,
@@ -210,14 +393,14 @@ class _SettingsScreenState extends State<SettingsScreen> {
            Container(
              padding: const EdgeInsets.all(16),
              decoration: BoxDecoration(
-                color: colorScheme.surfaceVariant.withOpacity(0.3),
-                borderRadius: BorderRadius.circular(12),
+                color: colorScheme.surfaceVariant.withOpacity(0.5),
+                borderRadius: BorderRadius.circular(8),
              ),
              child: Column(
                crossAxisAlignment: CrossAxisAlignment.start,
                children: [
                  Text(
-                    'Theme Mode',
+                    S.of(context)!.themeMode,
                    style: textTheme.bodySmall?.copyWith(
                      color: colorScheme.onSurfaceVariant,
                    ),
@@ -228,21 +411,21 @@ class _SettingsScreenState extends State<SettingsScreen> {
                      return SizedBox(
                        width: double.infinity,
                        child: SegmentedButton<ThemeMode>(
-                          segments: const [
+                          segments: [
                            ButtonSegment<ThemeMode>(
                              value: ThemeMode.light,
-                              label: Text('Light'),
-                              icon: Icon(Icons.light_mode_rounded),
+                              label: Text(S.of(context)!.light),
+                              icon: const Icon(Icons.light_mode_rounded),
                            ),
                            ButtonSegment<ThemeMode>(
                              value: ThemeMode.dark,
-                              label: Text('Dark'),
-                              icon: Icon(Icons.dark_mode_rounded),
+                              label: Text(S.of(context)!.dark),
+                              icon: const Icon(Icons.dark_mode_rounded),
                            ),
                            ButtonSegment<ThemeMode>(
                              value: ThemeMode.system,
-                              label: Text('System'),
-                              icon: Icon(Icons.auto_mode_rounded),
+                              label: Text(S.of(context)!.system),
+                              icon: const Icon(Icons.auto_mode_rounded),
                            ),
                          ],
                          selected: {themeProvider.themeMode},
@@ -254,7 +437,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
                              if (states.contains(WidgetState.selected)) {
                                return colorScheme.primaryContainer;
                              }
-                              return colorScheme.surfaceVariant.withOpacity(0.3);
+                              return colorScheme.surfaceVariant.withOpacity(0.5);
                            }),
                            foregroundColor: WidgetStateProperty.resolveWith((states) {
                              if (states.contains(WidgetState.selected)) {
@@ -263,6 +446,9 @@ class _SettingsScreenState extends State<SettingsScreen> {
                              return colorScheme.onSurfaceVariant;
                            }),
                            side: WidgetStateProperty.all(BorderSide.none),
+                            shape: WidgetStateProperty.all(
+                              RoundedRectangleBorder(borderRadius: BorderRadius.circular(8)),
+                            ),
                          ),
                        ),
                      );
@@ -274,6 +460,67 @@ class _SettingsScreenState extends State<SettingsScreen> {

            const SizedBox(height: 16),

+            // Accent color picker
+            Consumer<ThemeProvider>(
+              builder: (context, themeProvider, _) {
+                final isDisabled = themeProvider.useMaterialTheme;
+                return Container(
+                  padding: const EdgeInsets.all(16),
+                  decoration: BoxDecoration(
+                    color: colorScheme.surfaceVariant.withOpacity(0.3),
+                    borderRadius: BorderRadius.circular(12),
+                  ),
+                  child: Column(
+                    crossAxisAlignment: CrossAxisAlignment.start,
+                    children: [
+                      Text(
+                        S.of(context)!.accentColor,
+                        style: TextStyle(
+                          color: isDisabled
+                              ? colorScheme.onSurface.withOpacity(0.4)
+                              : colorScheme.onSurface,
+                          fontWeight: FontWeight.w500,
+                        ),
+                      ),
+                      const SizedBox(height: 12),
+                      Row(
+                        mainAxisAlignment: MainAxisAlignment.spaceEvenly,
+                        children: accentColorOptions.map((color) {
+                          final isSelected = themeProvider.customColor.value == color.value;
+                          return GestureDetector(
+                            onTap: isDisabled ? null : () {
+                              themeProvider.setCustomColor(color);
+                            },
+                            child: AnimatedContainer(
+                              duration: const Duration(milliseconds: 200),
+                              curve: Curves.easeInOut,
+                              width: 40,
+                              height: 40,
+                              decoration: BoxDecoration(
+                                color: isDisabled ? color.withOpacity(0.3) : color,
+                                shape: BoxShape.circle,
+                                border: isSelected && !isDisabled
+                                    ? Border.all(color: colorScheme.onSurface, width: 3)
+                                    : null,
+                                boxShadow: isSelected && !isDisabled
+                                    ? [BoxShadow(color: color.withOpacity(0.5), blurRadius: 8, spreadRadius: 2)]
+                                    : null,
+                              ),
+                              child: isSelected && !isDisabled
+                                  ? Icon(Icons.check, color: Colors.white, size: 20)
+                                  : null,
+                            ),
+                          );
+                        }).toList(),
+                      ),
+                    ],
+                  ),
+                );
+              },
+            ),
+
+            const SizedBox(height: 16),
+
            Consumer<ThemeProvider>(
              builder: (context, themeProvider, _) {
                return Container(
@@ -284,11 +531,11 @@ class _SettingsScreenState extends State<SettingsScreen> {
                  ),
                  child: SwitchListTile(
                    title: Text(
-                      'Material You',
+                      S.of(context)!.materialYou,
                      style: TextStyle(color: colorScheme.onSurface),
                    ),
                    subtitle: Text(
-                      'Use system colors (Android 12+)',
+                      S.of(context)!.materialYouDescription,
                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
                    ),
                    value: themeProvider.useMaterialTheme,
@@ -314,11 +561,11 @@ class _SettingsScreenState extends State<SettingsScreen> {
                  ),
                  child: SwitchListTile(
                    title: Text(
-                      'Adaptive Theme',
+                      S.of(context)!.adaptiveTheme,
                      style: TextStyle(color: colorScheme.onSurface),
                    ),
                    subtitle: Text(
-                      'Extract colors from album and artist artwork',
+                      S.of(context)!.extractColorsFromArtwork,
                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
                    ),
                    value: themeProvider.adaptiveTheme,
@@ -334,9 +581,201 @@ class _SettingsScreenState extends State<SettingsScreen> {

            const SizedBox(height: 32),

-            // Home Screen section
+            // Language section
            Text(
-              'Home Screen',
+              S.of(context)!.language,
+              style: textTheme.titleMedium?.copyWith(
+                color: colorScheme.onBackground,
+                fontWeight: FontWeight.bold,
+              ),
+            ),
+            const SizedBox(height: 16),
+
+            Consumer<LocaleProvider>(
+              builder: (context, localeProvider, _) {
+                String getLanguageName(String? code) {
+                  switch (code) {
+                    case 'en':
+                      return 'English';
+                    case 'de':
+                      return 'Deutsch';
+                    case 'es':
+                      return 'Español';
+                    default:
+                      return S.of(context)!.system;
+                  }
+                }
+
+                return ListTile(
+                  contentPadding: const EdgeInsets.symmetric(horizontal: 16, vertical: 4),
+                  shape: RoundedRectangleBorder(borderRadius: BorderRadius.circular(8)),
+                  tileColor: colorScheme.surfaceVariant.withOpacity(0.5),
+                  leading: Icon(Icons.language_rounded, color: colorScheme.onSurfaceVariant),
+                  title: Text(S.of(context)!.language),
+                  subtitle: Text(
+                    getLanguageName(localeProvider.locale?.languageCode),
+                    style: TextStyle(color: colorScheme.primary),
+                  ),
+                  trailing: Icon(Icons.chevron_right, color: colorScheme.onSurfaceVariant),
+                  onTap: () {
+                    showDialog(
+                      context: context,
+                      builder: (dialogContext) {
+                        return AlertDialog(
+                          title: Text(S.of(context)!.language),
+                          content: Column(
+                            mainAxisSize: MainAxisSize.min,
+                            children: [
+                              RadioListTile<String?>(
+                                title: Text(S.of(context)!.system),
+                                subtitle: Text(S.of(context)!.auto),
+                                value: null,
+                                groupValue: localeProvider.locale?.languageCode,
+                                onChanged: (value) {
+                                  localeProvider.setLocale(null);
+                                  Navigator.pop(dialogContext);
+                                },
+                              ),
+                              RadioListTile<String?>(
+                                title: Text(S.of(context)!.english),
+                                value: 'en',
+                                groupValue: localeProvider.locale?.languageCode,
+                                onChanged: (value) {
+                                  localeProvider.setLocale(const Locale('en'));
+                                  Navigator.pop(dialogContext);
+                                },
+                              ),
+                              RadioListTile<String?>(
+                                title: Text(S.of(context)!.german),
+                                value: 'de',
+                                groupValue: localeProvider.locale?.languageCode,
+                                onChanged: (value) {
+                                  localeProvider.setLocale(const Locale('de'));
+                                  Navigator.pop(dialogContext);
+                                },
+                              ),
+                              RadioListTile<String?>(
+                                title: Text(S.of(context)!.spanish),
+                                value: 'es',
+                                groupValue: localeProvider.locale?.languageCode,
+                                onChanged: (value) {
+                                  localeProvider.setLocale(const Locale('es'));
+                                  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);
+                                },
+                              ),
+                            ],
+                          ),
+                        );
+                      },
+                    );
+                  },
+                );
+              },
+            ),
+
+            const SizedBox(height: 32),
+
+            // Player section
+            Text(
+              S.of(context)!.players,
+              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(
+                  S.of(context)!.preferLocalPlayer,
+                  style: TextStyle(color: colorScheme.onSurface),
+                ),
+                subtitle: Text(
+                  S.of(context)!.preferLocalPlayerDescription,
+                  style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                ),
+                value: _preferLocalPlayer,
+                onChanged: (value) {
+                  setState(() => _preferLocalPlayer = value);
+                  SettingsService.setPreferLocalPlayer(value);
+                },
+                activeColor: colorScheme.primary,
+                contentPadding: EdgeInsets.zero,
+              ),
+            ),
+
+            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(
+                  S.of(context)!.smartSortPlayers,
+                  style: TextStyle(color: colorScheme.onSurface),
+                ),
+                subtitle: Text(
+                  S.of(context)!.smartSortPlayersDescription,
+                  style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                ),
+                value: _smartSortPlayers,
+                onChanged: (value) {
+                  setState(() => _smartSortPlayers = value);
+                  SettingsService.setSmartSortPlayers(value);
+                },
+                activeColor: colorScheme.primary,
+                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),
+
+            // Hints & Tips section
+            Text(
+              S.of(context)!.hintsAndTips,
              style: textTheme.titleMedium?.copyWith(
                color: colorScheme.onBackground,
                fontWeight: FontWeight.bold,
@@ -344,159 +783,124 @@ class _SettingsScreenState extends State<SettingsScreen> {
            ),
            const SizedBox(height: 8),
            Text(
-              'Choose which rows to display on the home screen',
+              S.of(context)!.showHintsDescription,
              style: textTheme.bodySmall?.copyWith(
                color: colorScheme.onBackground.withOpacity(0.6),
              ),
            ),
            const SizedBox(height: 16),

-            // Main rows section
            Container(
              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
              decoration: BoxDecoration(
                color: colorScheme.surfaceVariant.withOpacity(0.3),
                borderRadius: BorderRadius.circular(12),
              ),
-              child: Column(
-                children: [
-                  SwitchListTile(
-                    title: Text(
-                      'Recently Played',
-                      style: TextStyle(color: colorScheme.onSurface),
-                    ),
-                    subtitle: Text(
-                      'Show recently played albums',
-                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
-                    ),
-                    value: _showRecentAlbums,
-                    onChanged: (value) {
-                      setState(() => _showRecentAlbums = value);
-                      SettingsService.setShowRecentAlbums(value);
-                    },
-                    activeColor: colorScheme.primary,
-                    contentPadding: EdgeInsets.zero,
-                  ),
-                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
-                  SwitchListTile(
-                    title: Text(
-                      'Discover Artists',
-                      style: TextStyle(color: colorScheme.onSurface),
-                    ),
-                    subtitle: Text(
-                      'Show random artists to discover',
-                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
-                    ),
-                    value: _showDiscoverArtists,
-                    onChanged: (value) {
-                      setState(() => _showDiscoverArtists = value);
-                      SettingsService.setShowDiscoverArtists(value);
-                    },
-                    activeColor: colorScheme.primary,
-                    contentPadding: EdgeInsets.zero,
-                  ),
-                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
-                  SwitchListTile(
-                    title: Text(
-                      'Discover Albums',
-                      style: TextStyle(color: colorScheme.onSurface),
-                    ),
-                    subtitle: Text(
-                      'Show random albums to discover',
-                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
-                    ),
-                    value: _showDiscoverAlbums,
-                    onChanged: (value) {
-                      setState(() => _showDiscoverAlbums = value);
-                      SettingsService.setShowDiscoverAlbums(value);
-                    },
-                    activeColor: colorScheme.primary,
-                    contentPadding: EdgeInsets.zero,
-                  ),
-                ],
+              child: SwitchListTile(
+                title: Text(
+                  S.of(context)!.showHints,
+                  style: TextStyle(color: colorScheme.onSurface),
+                ),
+                value: _showHints,
+                onChanged: (value) {
+                  setState(() => _showHints = value);
+                  SettingsService.setShowHints(value);
+                },
+                activeColor: colorScheme.primary,
+                contentPadding: EdgeInsets.zero,
              ),
            ),

-            const SizedBox(height: 16),
+            const SizedBox(height: 32),

+            // Home Screen section
            Text(
-              'Favorites',
-              style: textTheme.bodySmall?.copyWith(
-                color: colorScheme.onBackground.withOpacity(0.6),
+              S.of(context)!.homeScreen,
+              style: textTheme.titleMedium?.copyWith(
+                color: colorScheme.onBackground,
+                fontWeight: FontWeight.bold,
              ),
            ),
            const SizedBox(height: 8),
+            Text(
+              S.of(context)!.chooseHomeScreenRows,
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.onBackground.withOpacity(0.6),
+              ),
+            ),
+            const SizedBox(height: 16),

-            // Favorites rows section
+            // Reorderable home rows list
            Container(
-              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
              decoration: BoxDecoration(
                color: colorScheme.surfaceVariant.withOpacity(0.3),
                borderRadius: BorderRadius.circular(12),
              ),
-              child: Column(
-                children: [
-                  SwitchListTile(
-                    title: Text(
-                      'Favorite Albums',
-                      style: TextStyle(color: colorScheme.onSurface),
+              clipBehavior: Clip.antiAlias,
+              child: ReorderableListView.builder(
+                shrinkWrap: true,
+                physics: const NeverScrollableScrollPhysics(),
+                buildDefaultDragHandles: false,
+                itemCount: _homeRowOrder.length,
+                onReorder: (oldIndex, newIndex) {
+                  setState(() {
+                    if (newIndex > oldIndex) newIndex--;
+                    final item = _homeRowOrder.removeAt(oldIndex);
+                    _homeRowOrder.insert(newIndex, item);
+                  });
+                  SettingsService.setHomeRowOrder(_homeRowOrder);
+                },
+                itemBuilder: (context, index) {
+                  final rowId = _homeRowOrder[index];
+                  final rowInfo = _getRowInfo(rowId);
+                  final isEnabled = _getRowEnabled(rowId);
+
+                  return Container(
+                    key: ValueKey(rowId),
+                    decoration: BoxDecoration(
+                      border: index < _homeRowOrder.length - 1
+                          ? Border(bottom: BorderSide(color: colorScheme.outline.withOpacity(0.2)))
+                          : null,
                    ),
-                    subtitle: Text(
-                      'Show a row of your favorite albums',
-                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    child: Row(
+                      children: [
+                        ReorderableDragStartListener(
+                          index: index,
+                          child: Padding(
+                            padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 16),
+                            child: Icon(
+                              Icons.drag_handle,
+                              color: colorScheme.onSurface.withOpacity(0.5),
+                            ),
+                          ),
+                        ),
+                        Expanded(
+                          child: SwitchListTile(
+                            title: Text(
+                              rowInfo['title']!,
+                              style: TextStyle(color: colorScheme.onSurface),
+                            ),
+                            subtitle: Text(
+                              rowInfo['subtitle']!,
+                              style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                            ),
+                            value: isEnabled,
+                            onChanged: (value) => _setRowEnabled(rowId, value),
+                            activeColor: colorScheme.primary,
+                            contentPadding: const EdgeInsets.only(right: 8),
+                          ),
+                        ),
+                      ],
                    ),
-                    value: _showFavoriteAlbums,
-                    onChanged: (value) {
-                      setState(() => _showFavoriteAlbums = value);
-                      SettingsService.setShowFavoriteAlbums(value);
-                    },
-                    activeColor: colorScheme.primary,
-                    contentPadding: EdgeInsets.zero,
-                  ),
-                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
-                  SwitchListTile(
-                    title: Text(
-                      'Favorite Artists',
-                      style: TextStyle(color: colorScheme.onSurface),
-                    ),
-                    subtitle: Text(
-                      'Show a row of your favorite artists',
-                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
-                    ),
-                    value: _showFavoriteArtists,
-                    onChanged: (value) {
-                      setState(() => _showFavoriteArtists = value);
-                      SettingsService.setShowFavoriteArtists(value);
-                    },
-                    activeColor: colorScheme.primary,
-                    contentPadding: EdgeInsets.zero,
-                  ),
-                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
-                  SwitchListTile(
-                    title: Text(
-                      'Favorite Tracks',
-                      style: TextStyle(color: colorScheme.onSurface),
-                    ),
-                    subtitle: Text(
-                      'Show a row of your favorite tracks',
-                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
-                    ),
-                    value: _showFavoriteTracks,
-                    onChanged: (value) {
-                      setState(() => _showFavoriteTracks = value);
-                      SettingsService.setShowFavoriteTracks(value);
-                    },
-                    activeColor: colorScheme.primary,
-                    contentPadding: EdgeInsets.zero,
-                  ),
-                ],
+                  );
+                },
              ),
            ),

            const SizedBox(height: 32),

            Text(
-              'Metadata APIs (Optional)',
+              S.of(context)!.metadataApis,
              style: textTheme.titleMedium?.copyWith(
                color: colorScheme.onBackground,
                fontWeight: FontWeight.bold,
@@ -504,7 +908,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
            ),
            const SizedBox(height: 8),
            Text(
-              'Artist images are automatically fetched from Deezer. Add API keys below for artist biographies and album descriptions.',
+              S.of(context)!.metadataApisDescription,
              style: textTheme.bodySmall?.copyWith(
                color: colorScheme.onBackground.withOpacity(0.6),
              ),
@@ -515,8 +919,8 @@ class _SettingsScreenState extends State<SettingsScreen> {
              controller: _lastFmApiKeyController,
              style: TextStyle(color: colorScheme.onSurface),
              decoration: InputDecoration(
-                labelText: 'Last.fm API Key',
-                hintText: 'Get free key at last.fm/api',
+                labelText: S.of(context)!.lastFmApiKey,
+                hintText: S.of(context)!.lastFmApiKeyHint,
                hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                filled: true,
                fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -552,8 +956,8 @@ class _SettingsScreenState extends State<SettingsScreen> {
              controller: _audioDbApiKeyController,
              style: TextStyle(color: colorScheme.onSurface),
              decoration: InputDecoration(
-                labelText: 'TheAudioDB API Key',
-                hintText: 'Use "2" for free tier or premium key',
+                labelText: S.of(context)!.theAudioDbApiKey,
+                hintText: S.of(context)!.theAudioDbApiKeyHint,
                hintStyle: TextStyle(color: colorScheme.onSurface.withOpacity(0.38)),
                filled: true,
                fillColor: colorScheme.surfaceVariant.withOpacity(0.3),
@@ -598,7 +1002,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
                  );
                },
                icon: const Icon(Icons.bug_report_rounded),
-                label: const Text('View Debug Logs'),
+                label: Text(S.of(context)!.viewDebugLogs),
                style: FilledButton.styleFrom(
                  backgroundColor: colorScheme.surfaceVariant.withOpacity(0.5),
                  foregroundColor: colorScheme.onSurfaceVariant,
@@ -647,17 +1051,19 @@ class _SettingsScreenState extends State<SettingsScreen> {
  }

  String _getStatusText(MAConnectionState state) {
+    final s = S.of(context)!;
    switch (state) {
      case MAConnectionState.connected:
      case MAConnectionState.authenticated:
-        return 'Connected';
+        return s.connected;
      case MAConnectionState.connecting:
      case MAConnectionState.authenticating:
-        return 'Connecting...';
+        return s.connecting;
      case MAConnectionState.error:
-        return 'Connection Error';
+        return s.connectionError;
      case MAConnectionState.disconnected:
-        return 'Disconnected';
+        return s.disconnected;
    }
  }
+
 }
@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'package:audio_service/audio_service.dart';
 import 'package:audio_session/audio_session.dart';
 import 'package:just_audio/just_audio.dart';
@@ -11,6 +12,12 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
  final AuthManager authManager;
  final _logger = DebugLogger();

+  // Stream subscriptions for proper cleanup
+  StreamSubscription? _interruptionSubscription;
+  StreamSubscription? _becomingNoisySubscription;
+  StreamSubscription? _playbackEventSubscription;
+  StreamSubscription? _currentIndexSubscription;
+
  // Track current metadata separately from what's in the notification
  // This allows us to update the notification when metadata arrives late
  MediaItem? _currentMediaItem;
@@ -42,7 +49,7 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
    await session.configure(const AudioSessionConfiguration.music());

    // Handle audio interruptions
-    session.interruptionEventStream.listen((event) {
+    _interruptionSubscription = session.interruptionEventStream.listen((event) {
      if (event.begin) {
        switch (event.type) {
          case AudioInterruptionType.duck:
@@ -68,15 +75,15 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
    });

    // Handle becoming noisy (headphones unplugged)
-    session.becomingNoisyEventStream.listen((_) {
+    _becomingNoisySubscription = session.becomingNoisyEventStream.listen((_) {
      pause();
    });

    // Broadcast playback state changes
-    _player.playbackEventStream.listen(_broadcastState);
+    _playbackEventSubscription = _player.playbackEventStream.listen(_broadcastState);

    // Broadcast current media item changes
-    _player.currentIndexStream.listen((_) {
+    _currentIndexSubscription = _player.currentIndexStream.listen((_) {
      if (_currentMediaItem != null) {
        mediaItem.add(_currentMediaItem);
      }
@@ -293,4 +300,13 @@ class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
  Stream<Duration?> get durationStream => _player.durationStream;

  MediaItem? get currentMediaItem => _currentMediaItem;
+
+  /// Dispose of resources and cancel all subscriptions
+  Future<void> dispose() async {
+    await _interruptionSubscription?.cancel();
+    await _becomingNoisySubscription?.cancel();
+    await _playbackEventSubscription?.cancel();
+    await _currentIndexSubscription?.cancel();
+    await _player.dispose();
+  }
 }
@@ -1,4 +1,5 @@
 import 'dart:convert';
+import 'dart:io';
 import 'package:http/http.dart' as http;
 import 'auth_strategy.dart';
 import 'no_auth_strategy.dart';
@@ -31,11 +32,42 @@ class AuthManager {

  /// Auto-detect authentication requirements for a server
  /// Returns null if server is unreachable or auth method unknown
+  /// Also returns the final URL used (in case of HTTP fallback) via the callback
+  String? _lastSuccessfulUrl;
+  String? get lastSuccessfulUrl => _lastSuccessfulUrl;
+
  Future<AuthStrategy?> detectAuthStrategy(String serverUrl) async {
    _logger.log('🔍 Auto-detecting auth strategy for $serverUrl');
+    _lastSuccessfulUrl = null;

    // Normalize URL
-    var baseUrl = serverUrl;
+    var baseUrl = _normalizeUrl(serverUrl);
+    _logger.log('Normalized URL: $baseUrl');
+
+    // Try detection with the initial URL
+    var result = await _tryDetectAuth(baseUrl);
+
+    // If HTTPS failed and we haven't tried HTTP yet, try HTTP fallback
+    if (result == null && baseUrl.startsWith('https://')) {
+      final httpUrl = baseUrl.replaceFirst('https://', 'http://');
+      _logger.log('🔄 HTTPS failed, trying HTTP fallback: $httpUrl');
+      result = await _tryDetectAuth(httpUrl);
+      if (result != null) {
+        baseUrl = httpUrl;
+      }
+    }
+
+    if (result != null) {
+      _lastSuccessfulUrl = baseUrl;
+      _logger.log('✅ Auth detection successful with URL: $baseUrl');
+    }
+
+    return result;
+  }
+
+  /// Normalize a server URL with appropriate protocol
+  String _normalizeUrl(String url) {
+    var baseUrl = url;
    if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
      // Use http for local IPs, https for domains
      if (baseUrl.startsWith('192.') ||
@@ -44,13 +76,39 @@ class AuthManager {
          baseUrl == 'localhost' ||
          baseUrl.startsWith('127.')) {
        baseUrl = 'http://$baseUrl';
+      } else if (baseUrl.endsWith('.ts.net') || baseUrl.contains('.ts.net:')) {
+        // Tailscale URLs - default to http:// since VPN tunnel is already encrypted
+        baseUrl = 'http://$baseUrl';
+        _logger.log('🔗 Detected Tailscale URL, using HTTP');
      } else {
        baseUrl = 'https://$baseUrl';
      }
    }
+    return baseUrl;
+  }

+  /// Check if a hostname is a local/private IP address
+  bool _isLocalIpAddress(String host) {
+    return host.startsWith('192.168.') ||
+        host.startsWith('10.') ||
+        host.startsWith('172.16.') ||
+        host.startsWith('172.17.') ||
+        host.startsWith('172.18.') ||
+        host.startsWith('172.19.') ||
+        host.startsWith('172.2') ||
+        host.startsWith('172.30.') ||
+        host.startsWith('172.31.') ||
+        host == 'localhost' ||
+        host.startsWith('127.') ||
+        host.endsWith('.local') ||
+        host.endsWith('.ts.net');
+  }
+
+  /// Try to detect auth strategy for a given URL
+  /// Returns the strategy if successful, null if connection failed
+  Future<AuthStrategy?> _tryDetectAuth(String baseUrl) async {
    // First, check if this is a Music Assistant server with native auth
-    _logger.log('Checking for Music Assistant native auth...');
+    _logger.log('Checking for Music Assistant native auth at $baseUrl...');
    final maAuthResult = await _checkMusicAssistantAuth(baseUrl);
    if (maAuthResult != null) {
      if (maAuthResult == 'required') {
@@ -124,7 +182,7 @@ class AuthManager {
      }
    } catch (e) {
      _logger.log('✗ Auth detection error: $e');
-      return null; // Return null instead of rethrow to show generic error
+      return null; // Return null to trigger fallback
    }

    _logger.log('⚠️ Could not determine auth method');
@@ -136,24 +194,61 @@ class AuthManager {
  Future<String?> _checkMusicAssistantAuth(String baseUrl) async {
    try {
      final uri = Uri.parse(baseUrl);
+      // Use the port from URL if specified, otherwise use default ports (80/443)
+      // Don't default to 8095 here - that's only for direct connections without reverse proxy
      final apiUrl = Uri(
        scheme: uri.scheme,
        host: uri.host,
-        port: uri.hasPort ? uri.port : (uri.scheme == 'https' ? null : 8095),
+        port: uri.hasPort ? uri.port : null,
        path: '/api',
      );

      _logger.log('Checking MA API at: $apiUrl');

-      // Try to get server info - this tells us if auth is required
-      // Note: The command is just 'info', not 'server/info'
-      final response = await http.post(
-        apiUrl,
-        headers: {'Content-Type': 'application/json'},
-        body: jsonEncode({
-          'command': 'info',
-        }),
-      ).timeout(const Duration(seconds: 5));
+      // Use IOClient to control redirect behavior for local IPs
+      final isLocalIp = _isLocalIpAddress(uri.host);
+      http.Response response;
+
+      if (isLocalIp) {
+        // For local IPs, don't follow redirects - handle them explicitly
+        final client = HttpClient();
+        try {
+          final request = await client.postUrl(apiUrl);
+          request.followRedirects = false;
+          request.headers.set('Content-Type', 'application/json');
+          request.write(jsonEncode({'command': 'info'}));
+          final ioResponse = await request.close().timeout(const Duration(seconds: 5));
+
+          // Check for redirect to HTTPS
+          if (ioResponse.statusCode == 308 || ioResponse.statusCode == 301 || ioResponse.statusCode == 302) {
+            final location = ioResponse.headers.value('location');
+            _logger.log('Local IP redirects to: $location');
+            if (location != null && location.startsWith('https://')) {
+              _logger.log('⚠️ Server redirects HTTP to HTTPS - this may cause certificate issues for local IP');
+              // Don't follow the redirect - it will likely fail with cert error
+              // Instead, return null to trigger fallback logic
+              client.close();
+              return null;
+            }
+          }
+
+          final body = await ioResponse.transform(utf8.decoder).join();
+          response = http.Response(body, ioResponse.statusCode);
+          client.close();
+        } catch (e) {
+          client.close();
+          rethrow;
+        }
+      } else {
+        // For non-local URLs, use standard http.post which follows redirects
+        response = await http.post(
+          apiUrl,
+          headers: {'Content-Type': 'application/json'},
+          body: jsonEncode({
+            'command': 'info',
+          }),
+        ).timeout(const Duration(seconds: 5));
+      }

      _logger.log('MA API response: ${response.statusCode}');
      _logger.log('MA API body: ${response.body}');
@@ -213,21 +308,47 @@ class AuthManager {
  /// Test if server is accessible without authentication
  Future<bool> _canConnectWithoutAuth(String serverUrl) async {
    try {
-      // Test root endpoint - Music Assistant doesn't have /api/info
-      final testUrl = serverUrl;
-      _logger.log('No-auth test URL: $testUrl');
+      final uri = Uri.parse(serverUrl);
+      _logger.log('No-auth test URL: $serverUrl');

-      final response = await http.get(
-        Uri.parse(testUrl),
-        // Don't follow redirects - we want to see if server requires auth
-      ).timeout(const Duration(seconds: 10));
+      final isLocalIp = _isLocalIpAddress(uri.host);
+      int statusCode;

-      _logger.log('No-auth status: ${response.statusCode}');
+      if (isLocalIp) {
+        // For local IPs, don't follow redirects to avoid HTTPS cert issues
+        final client = HttpClient();
+        try {
+          final request = await client.getUrl(uri);
+          request.followRedirects = false;
+          final response = await request.close().timeout(const Duration(seconds: 10));
+          statusCode = response.statusCode;
+
+          // Check for redirect to HTTPS
+          if (statusCode == 308 || statusCode == 301 || statusCode == 302) {
+            final location = response.headers.value('location');
+            if (location != null && location.startsWith('https://')) {
+              _logger.log('⚠️ Local IP redirects to HTTPS: $location');
+              client.close();
+              return false; // Can't connect - would need HTTPS which has cert issues
+            }
+          }
+          client.close();
+        } catch (e) {
+          client.close();
+          rethrow;
+        }
+      } else {
+        // For non-local URLs, use standard http.get
+        final response = await http.get(uri).timeout(const Duration(seconds: 10));
+        statusCode = response.statusCode;
+      }
+
+      _logger.log('No-auth status: $statusCode');

      // 200 = no auth required
-      // 302/307 = redirect (probably to auth)
+      // 302/307/308 = redirect (probably to auth or HTTPS)
      // 401 = auth required
-      if (response.statusCode == 200) {
+      if (statusCode == 200) {
        return true;
      }

@@ -1,19 +1,34 @@
+import 'dart:convert';
 import '../models/media_item.dart';
+import '../models/player.dart';
 import '../services/debug_logger.dart';
+import '../services/database_service.dart';
 import '../constants/timings.dart';

 /// Centralized cache service for all app data caching
 /// This is a non-notifying service - it just stores and retrieves cached data
 class CacheService {
  final DebugLogger _logger = DebugLogger();
+  bool _homeRowsLoaded = false;
+
+  // Cache size limits to prevent unbounded memory growth
+  static const int _maxDetailCacheSize = 50; // Max albums/playlists/artists cached
+  static const int _maxSearchCacheSize = 20; // Max search queries cached
+  static const int _maxPlayerTrackCacheSize = 30; // Max player track associations

  // Home screen row caching
  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 = {};
@@ -28,10 +43,13 @@ class CacheService {
  final Map<String, DateTime> _searchCacheTime = {};

  // Player list caching
+  List<Player>? _cachedPlayers;
+  Player? _cachedSelectedPlayer;
  DateTime? _playersLastFetched;

  // Player track cache (for smooth swipe transitions)
  final Map<String, Track?> _playerTrackCache = {};
+  final Map<String, DateTime> _playerTrackCacheTime = {};

  // ============================================================================
  // HOME SCREEN ROW CACHING
@@ -54,6 +72,8 @@ class CacheService {
    _cachedRecentAlbums = albums;
    _recentAlbumsLastFetched = DateTime.now();
    _logger.log('✅ Cached ${albums.length} recent albums');
+    // Persist to database for instant load on next launch
+    _persistHomeRowToDatabase('recent_albums', albums.map((a) => a.toJson()).toList());
  }

  /// Check if discover artists cache is valid
@@ -73,6 +93,8 @@ class CacheService {
    _cachedDiscoverArtists = artists;
    _discoverArtistsLastFetched = DateTime.now();
    _logger.log('✅ Cached ${artists.length} discover artists');
+    // Persist to database for instant load on next launch
+    _persistHomeRowToDatabase('discover_artists', artists.map((a) => a.toJson()).toList());
  }

  /// Check if discover albums cache is valid
@@ -92,6 +114,76 @@ class CacheService {
    _cachedDiscoverAlbums = albums;
    _discoverAlbumsLastFetched = DateTime.now();
    _logger.log('✅ Cached ${albums.length} discover albums');
+    // Persist to database for instant load on next launch
+    _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)
@@ -99,9 +191,42 @@ class CacheService {
    _recentAlbumsLastFetched = null;
    _discoverArtistsLastFetched = null;
    _discoverAlbumsLastFetched = null;
+    _inProgressAudiobooksLastFetched = null;
+    _discoverAudiobooksLastFetched = null;
+    _discoverSeriesLastFetched = null;
    _logger.log('🗑️ Home screen cache invalidated');
  }

+  /// Invalidate home album caches (call when albums are added/removed from library)
+  void invalidateHomeAlbumCaches() {
+    _cachedRecentAlbums = null;
+    _recentAlbumsLastFetched = null;
+    _cachedDiscoverAlbums = null;
+    _discoverAlbumsLastFetched = null;
+    _logger.log('🗑️ Home album caches invalidated');
+  }
+
+  /// Invalidate home artist caches (call when artists are added/removed from library)
+  void invalidateHomeArtistCaches() {
+    _cachedDiscoverArtists = null;
+    _discoverArtistsLastFetched = null;
+    _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
  // ============================================================================
@@ -123,15 +248,23 @@ class CacheService {
  void setCachedAlbumTracks(String cacheKey, List<Track> tracks) {
    _albumTracksCache[cacheKey] = tracks;
    _albumTracksCacheTime[cacheKey] = DateTime.now();
+    _evictOldestEntries(_albumTracksCache, _albumTracksCacheTime, _maxDetailCacheSize);
    _logger.log('✅ Cached ${tracks.length} tracks for album $cacheKey');
  }

-  /// Invalidate album tracks cache
+  /// Invalidate album tracks cache for a specific album
  void invalidateAlbumTracksCache(String albumId) {
    _albumTracksCache.remove(albumId);
    _albumTracksCacheTime.remove(albumId);
  }

+  /// Invalidate all album tracks caches (call when tracks are added/removed from library)
+  void invalidateAllAlbumTracksCaches() {
+    _albumTracksCache.clear();
+    _albumTracksCacheTime.clear();
+    _logger.log('🗑️ All album tracks caches invalidated');
+  }
+
  /// Check if playlist tracks cache is valid
  bool isPlaylistTracksCacheValid(String cacheKey, {bool forceRefresh = false}) {
    if (forceRefresh) return false;
@@ -149,15 +282,23 @@ class CacheService {
  void setCachedPlaylistTracks(String cacheKey, List<Track> tracks) {
    _playlistTracksCache[cacheKey] = tracks;
    _playlistTracksCacheTime[cacheKey] = DateTime.now();
+    _evictOldestEntries(_playlistTracksCache, _playlistTracksCacheTime, _maxDetailCacheSize);
    _logger.log('✅ Cached ${tracks.length} tracks for playlist $cacheKey');
  }

-  /// Invalidate playlist tracks cache
+  /// Invalidate playlist tracks cache for a specific playlist
  void invalidatePlaylistTracksCache(String playlistId) {
    _playlistTracksCache.remove(playlistId);
    _playlistTracksCacheTime.remove(playlistId);
  }

+  /// Invalidate all playlist tracks caches (call when tracks are added/removed from library)
+  void invalidateAllPlaylistTracksCaches() {
+    _playlistTracksCache.clear();
+    _playlistTracksCacheTime.clear();
+    _logger.log('🗑️ All playlist tracks caches invalidated');
+  }
+
  /// Check if artist albums cache is valid
  bool isArtistAlbumsCacheValid(String cacheKey, {bool forceRefresh = false}) {
    if (forceRefresh) return false;
@@ -175,9 +316,17 @@ class CacheService {
  void setCachedArtistAlbums(String cacheKey, List<Album> albums) {
    _artistAlbumsCache[cacheKey] = albums;
    _artistAlbumsCacheTime[cacheKey] = DateTime.now();
+    _evictOldestEntries(_artistAlbumsCache, _artistAlbumsCacheTime, _maxDetailCacheSize);
    _logger.log('✅ Cached ${albums.length} albums for artist $cacheKey');
  }

+  /// Invalidate all artist albums caches (call when albums are added/removed from library)
+  void invalidateArtistAlbumsCache() {
+    _artistAlbumsCache.clear();
+    _artistAlbumsCacheTime.clear();
+    _logger.log('🗑️ Artist albums cache invalidated');
+  }
+
  // ============================================================================
  // SEARCH CACHING
  // ============================================================================
@@ -199,9 +348,17 @@ class CacheService {
  void setCachedSearchResults(String cacheKey, Map<String, List<MediaItem>> results) {
    _searchCache[cacheKey] = results;
    _searchCacheTime[cacheKey] = DateTime.now();
+    _evictOldestEntries(_searchCache, _searchCacheTime, _maxSearchCacheSize);
    _logger.log('✅ Cached search results for "$cacheKey"');
  }

+  /// Invalidate all search cache (call when library items change)
+  void invalidateSearchCache() {
+    _searchCache.clear();
+    _searchCacheTime.clear();
+    _logger.log('🗑️ Search cache invalidated');
+  }
+
  // ============================================================================
  // PLAYER CACHING
  // ============================================================================
@@ -219,12 +376,43 @@ class CacheService {
    _playersLastFetched = DateTime.now();
  }

+  /// Get cached players list
+  List<Player>? getCachedPlayers() => _cachedPlayers;
+
+  /// Set cached players list
+  void setCachedPlayers(List<Player> players) {
+    _cachedPlayers = players;
+    _playersLastFetched = DateTime.now();
+  }
+
+  /// Get cached selected player
+  Player? getCachedSelectedPlayer() => _cachedSelectedPlayer;
+
+  /// Set cached selected player
+  void setCachedSelectedPlayer(Player? player) {
+    _cachedSelectedPlayer = player;
+  }
+
+  /// Check if we have cached players (for instant UI display on app resume)
+  bool get hasCachedPlayers => _cachedPlayers != null && _cachedPlayers!.isNotEmpty;
+
  /// Get cached track for a player (used for smooth swipe transitions)
  Track? getCachedTrackForPlayer(String playerId) => _playerTrackCache[playerId];

+  /// Get all player IDs that have cached tracks
+  Iterable<String> getAllCachedPlayerIds() => _playerTrackCache.keys;
+
  /// Set cached track for a player
  void setCachedTrackForPlayer(String playerId, Track? track) {
    _playerTrackCache[playerId] = track;
+    _playerTrackCacheTime[playerId] = DateTime.now();
+    _evictOldestEntries(_playerTrackCache, _playerTrackCacheTime, _maxPlayerTrackCacheSize);
+  }
+
+  /// Clear cached track for a player (e.g., when external source is active)
+  void clearCachedTrackForPlayer(String playerId) {
+    _playerTrackCache.remove(playerId);
+    _playerTrackCacheTime.remove(playerId);
  }

  // ============================================================================
@@ -242,6 +430,7 @@ class CacheService {
    _searchCache.clear();
    _searchCacheTime.clear();
    _playerTrackCache.clear();
+    _playerTrackCacheTime.clear();
    _logger.log('🗑️ All detail caches cleared');
  }

@@ -249,6 +438,112 @@ class CacheService {
  void clearAll() {
    invalidateHomeCache();
    clearAllDetailCaches();
+    _cachedPlayers = null;
+    _cachedSelectedPlayer = null;
    _playersLastFetched = null;
  }
+
+  // ============================================================================
+  // DATABASE PERSISTENCE FOR HOME ROWS
+  // ============================================================================
+
+  /// Load home row data from database for instant display on startup
+  Future<void> loadHomeRowsFromDatabase() async {
+    if (_homeRowsLoaded) return;
+    _homeRowsLoaded = true;
+
+    try {
+      if (!DatabaseService.instance.isInitialized) return;
+
+      // Load recent albums
+      final recentData = await DatabaseService.instance.getHomeRowCache('recent_albums');
+      if (recentData != null) {
+        try {
+          final items = (jsonDecode(recentData.itemsJson) as List)
+              .map((json) => Album.fromJson(json as Map<String, dynamic>))
+              .toList();
+          _cachedRecentAlbums = items;
+          _recentAlbumsLastFetched = recentData.lastUpdated;
+          _logger.log('📦 Loaded ${items.length} recent albums from database');
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse recent albums: $e');
+        }
+      }
+
+      // Load discover artists
+      final artistsData = await DatabaseService.instance.getHomeRowCache('discover_artists');
+      if (artistsData != null) {
+        try {
+          final items = (jsonDecode(artistsData.itemsJson) as List)
+              .map((json) => Artist.fromJson(json as Map<String, dynamic>))
+              .toList();
+          _cachedDiscoverArtists = items;
+          _discoverArtistsLastFetched = artistsData.lastUpdated;
+          _logger.log('📦 Loaded ${items.length} discover artists from database');
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse discover artists: $e');
+        }
+      }
+
+      // Load discover albums
+      final albumsData = await DatabaseService.instance.getHomeRowCache('discover_albums');
+      if (albumsData != null) {
+        try {
+          final items = (jsonDecode(albumsData.itemsJson) as List)
+              .map((json) => Album.fromJson(json as Map<String, dynamic>))
+              .toList();
+          _cachedDiscoverAlbums = items;
+          _discoverAlbumsLastFetched = albumsData.lastUpdated;
+          _logger.log('📦 Loaded ${items.length} discover albums from database');
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse discover albums: $e');
+        }
+      }
+    } catch (e) {
+      _logger.log('⚠️ Error loading home rows from database: $e');
+    }
+  }
+
+  /// Persist home row data to database (fire-and-forget)
+  void _persistHomeRowToDatabase(String rowType, List<Map<String, dynamic>> items) {
+    () async {
+      try {
+        if (!DatabaseService.instance.isInitialized) return;
+        await DatabaseService.instance.saveHomeRowCache(rowType, jsonEncode(items));
+        _logger.log('💾 Persisted $rowType to database');
+      } catch (e) {
+        _logger.log('⚠️ Failed to persist $rowType: $e');
+      }
+    }();
+  }
+
+  // ============================================================================
+  // LRU CACHE EVICTION
+  // ============================================================================
+
+  /// Evict oldest entries from cache maps to enforce size limit (LRU eviction)
+  /// Uses the timestamp map to determine which entries are oldest
+  void _evictOldestEntries<K, V>(
+    Map<K, V> cache,
+    Map<K, DateTime> cacheTime,
+    int maxSize,
+  ) {
+    if (cache.length <= maxSize) return;
+
+    // Sort keys by timestamp (oldest first)
+    final sortedKeys = cacheTime.keys.toList()
+      ..sort((a, b) => (cacheTime[a] ?? DateTime.now())
+          .compareTo(cacheTime[b] ?? DateTime.now()));
+
+    // Remove oldest entries until we're at maxSize
+    final keysToRemove = sortedKeys.take(cache.length - maxSize);
+    for (final key in keysToRemove) {
+      cache.remove(key);
+      cacheTime.remove(key);
+    }
+
+    if (keysToRemove.isNotEmpty) {
+      _logger.log('🗑️ LRU evicted ${keysToRemove.length} cache entries');
+    }
+  }
 }
@@ -0,0 +1,340 @@
+import 'dart:convert';
+import '../database/database.dart';
+import 'debug_logger.dart';
+
+/// Singleton service for database access throughout the app
+class DatabaseService {
+  static DatabaseService? _instance;
+  static AppDatabase? _database;
+  static final _logger = DebugLogger();
+
+  DatabaseService._();
+
+  /// Get the singleton instance
+  static DatabaseService get instance {
+    _instance ??= DatabaseService._();
+    return _instance!;
+  }
+
+  /// Get the database instance
+  AppDatabase get db {
+    if (_database == null) {
+      throw StateError('Database not initialized. Call initialize() first.');
+    }
+    return _database!;
+  }
+
+  /// Check if database is initialized
+  bool get isInitialized => _database != null;
+
+  /// Initialize the database
+  Future<void> initialize() async {
+    if (_database != null) {
+      _logger.log('Database already initialized');
+      return;
+    }
+
+    _logger.log('Initializing database...');
+    _database = AppDatabase();
+    _logger.log('Database initialized successfully');
+  }
+
+  /// Close the database (for cleanup)
+  Future<void> close() async {
+    await _database?.close();
+    _database = null;
+    _logger.log('Database closed');
+  }
+
+  // ============================================
+  // Profile Convenience Methods
+  // ============================================
+
+  /// Get the currently active profile
+  Future<Profile?> getActiveProfile() => db.getActiveProfile();
+
+  /// Set the active profile (creates if doesn't exist)
+  Future<Profile> setActiveProfile({
+    required String username,
+    String? displayName,
+    required String source,
+  }) {
+    _logger.log('Setting active profile: $username (source: $source)');
+    return db.setActiveProfile(
+      username: username,
+      displayName: displayName,
+      source: source,
+    );
+  }
+
+  /// Get all profiles
+  Future<List<Profile>> getAllProfiles() => db.getAllProfiles();
+
+  // ============================================
+  // Recently Played Convenience Methods
+  // ============================================
+
+  /// Add an item to recently played
+  Future<void> addRecentlyPlayed({
+    required String mediaId,
+    required String mediaType,
+    required String name,
+    String? artistName,
+    String? imageUrl,
+    Map<String, dynamic>? metadata,
+  }) {
+    _logger.log('Adding to recently played: $name ($mediaType)');
+    return db.addRecentlyPlayed(
+      mediaId: mediaId,
+      mediaType: mediaType,
+      name: name,
+      artistName: artistName,
+      imageUrl: imageUrl,
+      metadata: metadata != null ? jsonEncode(metadata) : null,
+    );
+  }
+
+  /// Get recently played items
+  Future<List<RecentlyPlayedData>> getRecentlyPlayed({int limit = 20}) {
+    return db.getRecentlyPlayed(limit: limit);
+  }
+
+  /// Clear recently played for current profile
+  Future<void> clearRecentlyPlayed() => db.clearRecentlyPlayed();
+
+  // ============================================
+  // Library Cache Convenience Methods
+  // ============================================
+
+  /// 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,
+    );
+  }
+
+  /// Get cached items with JSON deserialization
+  Future<List<Map<String, dynamic>>> getCachedItems(String itemType) async {
+    final items = await db.getCachedItems(itemType);
+    return items.map((item) {
+      try {
+        return jsonDecode(item.data) as Map<String, dynamic>;
+      } catch (e) {
+        _logger.log('Error decoding cached item: $e');
+        return <String, dynamic>{};
+      }
+    }).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);
+    if (item == null) return null;
+    try {
+      return jsonDecode(item.data) as Map<String, dynamic>;
+    } catch (e) {
+      _logger.log('Error decoding cached item: $e');
+      return null;
+    }
+  }
+
+  /// Check if sync is needed
+  Future<bool> needsSync(String syncType, {Duration maxAge = const Duration(minutes: 5)}) {
+    return db.needsSync(syncType, maxAge);
+  }
+
+  /// Update sync timestamp
+  Future<void> updateSyncMetadata(String syncType, int itemCount) {
+    return db.updateSyncMetadata(syncType, itemCount);
+  }
+
+  /// Clear all cached data (useful for logout)
+  Future<void> clearAllCache() => db.clearAllCache();
+
+  /// Clear cached items of a specific type (e.g., 'album', 'artist')
+  /// Used before re-syncing to remove stale items
+  Future<void> clearCacheForType(String itemType) => db.clearCache(itemType);
+
+  /// Mark a specific cached item as deleted
+  /// Used when removing items from library for immediate database update
+  Future<void> markCachedItemDeleted(String itemType, String itemId) {
+    return db.markItemsDeleted(itemType, [itemId]);
+  }
+
+  // ============================================
+  // Player Cache Convenience Methods
+  // ============================================
+
+  /// Save playback state for instant resume
+  Future<void> savePlaybackState({
+    String? playerId,
+    String? playerName,
+    String? currentTrackJson,
+    double positionSeconds = 0.0,
+    bool isPlaying = false,
+  }) {
+    return db.savePlaybackState(
+      playerId: playerId,
+      playerName: playerName,
+      currentTrackJson: currentTrackJson,
+      positionSeconds: positionSeconds,
+      isPlaying: isPlaying,
+    );
+  }
+
+  /// Get saved playback state
+  Future<PlaybackStateData?> getPlaybackState() => db.getPlaybackState();
+
+  /// Cache a player with optional track info
+  Future<void> cachePlayer({
+    required String playerId,
+    required String playerJson,
+    String? currentTrackJson,
+  }) {
+    return db.cachePlayer(
+      playerId: playerId,
+      playerJson: playerJson,
+      currentTrackJson: currentTrackJson,
+    );
+  }
+
+  /// Cache multiple players at once
+  Future<void> cachePlayers(List<Map<String, dynamic>> players) {
+    return db.cachePlayers(players);
+  }
+
+  /// Get all cached players
+  Future<List<CachedPlayer>> getCachedPlayers() => db.getCachedPlayers();
+
+  /// Update cached track for a player
+  Future<void> updateCachedPlayerTrack(String playerId, String? trackJson) {
+    return db.updateCachedPlayerTrack(playerId, trackJson);
+  }
+
+  /// Clear all cached players
+  Future<void> clearCachedPlayers() => db.clearCachedPlayers();
+
+  /// Save queue for a player
+  Future<void> saveQueue(String playerId, List<String> itemJsonList) {
+    return db.saveQueue(playerId, itemJsonList);
+  }
+
+  /// Get cached queue for a player
+  Future<List<CachedQueueData>> getCachedQueue(String playerId) {
+    return db.getCachedQueue(playerId);
+  }
+
+  /// Clear queue for a player
+  Future<void> clearCachedQueue(String playerId) => db.clearCachedQueue(playerId);
+
+  // ============================================
+  // Home Row Cache Convenience Methods
+  // ============================================
+
+  /// Save home row data (recent albums, discover artists, etc.)
+  Future<void> saveHomeRowCache(String rowType, String itemsJson) {
+    return db.saveHomeRowCache(rowType, itemsJson);
+  }
+
+  /// Get cached home row data
+  Future<HomeRowCacheData?> getHomeRowCache(String rowType) {
+    return db.getHomeRowCache(rowType);
+  }
+
+  /// Clear all home row cache
+  Future<void> clearHomeRowCache() => db.clearHomeRowCache();
+
+  // ============================================
+  // Search History Convenience Methods
+  // ============================================
+
+  /// Save a search query to history
+  Future<void> saveSearchQuery(String query) => db.saveSearchQuery(query);
+
+  /// Get recent search queries (up to 10)
+  Future<List<String>> getRecentSearches() => db.getRecentSearches();
+
+  /// Clear all search history
+  Future<void> clearSearchHistory() => db.clearSearchHistory();
+
+  // ============================================
+  // Cast-to-Sendspin Mapping Methods
+  // ============================================
+
+  static const String _sendspinMappingType = 'cast_sendspin_mapping';
+
+  /// Save a Cast UUID to Sendspin ID mapping
+  Future<void> saveCastToSendspinMapping(String castId, String sendspinId) {
+    _logger.log('💾 Persisting Cast->Sendspin mapping: $castId -> $sendspinId');
+    return db.cacheItem(
+      itemType: _sendspinMappingType,
+      itemId: castId,
+      data: jsonEncode({'sendspinId': sendspinId}),
+    );
+  }
+
+  /// Get persisted Sendspin ID for a Cast UUID
+  Future<String?> getSendspinIdForCast(String castId) async {
+    final item = await db.getCachedItem(_sendspinMappingType, castId);
+    if (item == null) return null;
+    try {
+      final data = jsonDecode(item.data) as Map<String, dynamic>;
+      return data['sendspinId'] as String?;
+    } catch (e) {
+      _logger.log('Error decoding Sendspin mapping: $e');
+      return null;
+    }
+  }
+
+  /// Load all persisted Cast-to-Sendspin mappings
+  Future<Map<String, String>> getAllCastToSendspinMappings() async {
+    final items = await db.getCachedItems(_sendspinMappingType);
+    final mappings = <String, String>{};
+    for (final item in items) {
+      try {
+        final data = jsonDecode(item.data) as Map<String, dynamic>;
+        final sendspinId = data['sendspinId'] as String?;
+        if (sendspinId != null) {
+          // The itemId is the Cast UUID
+          mappings[item.itemId] = sendspinId;
+        }
+      } catch (e) {
+        _logger.log('Error decoding Sendspin mapping: $e');
+      }
+    }
+    _logger.log('📦 Loaded ${mappings.length} Cast->Sendspin mappings from database');
+    return mappings;
+  }
+}
@@ -1,36 +1,99 @@
+import 'dart:io';
+import 'dart:ui' as ui;
+import 'package:device_info_plus/device_info_plus.dart';
 import 'package:shared_preferences/shared_preferences.dart';
-import 'package:uuid/uuid.dart';
 import 'debug_logger.dart';
+import 'settings_service.dart';

-/// Service to generate unique per-installation player IDs
-/// Simplified to match KMP client pattern: single storage key, lazy generation
-/// This prevents the critical bug where multiple devices of the same model
-/// would share the same player ID and trigger playback on all devices
+/// Service to generate unique per-device player IDs
+/// Uses stable device identifiers (ANDROID_ID) combined with MA username
+/// to create persistent player IDs that survive storage wipes and support
+/// multiple devices per account
 class DeviceIdService {
  static const String _keyLocalPlayerId = 'local_player_id';
  static final _logger = DebugLogger();
-  static const _uuid = Uuid();

-  /// Get or generate a unique player ID for this installation
-  /// ID is generated once and persisted across app restarts
-  /// Format: ensemble_<uuid>
-  ///
-  /// This matches the KMP client pattern: generate on first access, store once
-  static Future<String> getOrCreateDevicePlayerId() async {
-    final prefs = await SharedPreferences.getInstance();
+  // Cache stable device ID to avoid repeated platform calls
+  static String? _cachedStableDeviceId;

-    // Single source of truth - no complex migration logic
-    final existingId = prefs.getString(_keyLocalPlayerId);
-    if (existingId != null && existingId.startsWith('ensemble_')) {
-      _logger.log('Using existing player ID: $existingId');
-      return existingId;
+  /// Get stable device identifier that persists across storage wipes
+  /// - Android: Uses ANDROID_ID (persists until factory reset)
+  /// - iOS: Uses identifierForVendor (persists until app reinstall)
+  static Future<String> _getStableDeviceId() async {
+    if (_cachedStableDeviceId != null) {
+      return _cachedStableDeviceId!;
    }

-    // Generate new ID on first access
-    final playerId = 'ensemble_${_uuid.v4()}';
-    await prefs.setString(_keyLocalPlayerId, playerId);
-    _logger.log('Generated new player ID: $playerId');
-    return playerId;
+    final deviceInfo = DeviceInfoPlugin();
+
+    if (Platform.isAndroid) {
+      final android = await deviceInfo.androidInfo;
+      // ANDROID_ID is unique per device+user combo, persists across storage wipes
+      // Only resets on factory reset
+      _cachedStableDeviceId = android.id;
+    } else if (Platform.isIOS) {
+      final ios = await deviceInfo.iosInfo;
+      // identifierForVendor persists across app updates but resets on reinstall
+      _cachedStableDeviceId = ios.identifierForVendor ?? 'unknown_ios';
+    } else {
+      // Fallback for other platforms (web, desktop)
+      _cachedStableDeviceId = 'unknown_platform';
+    }
+
+    return _cachedStableDeviceId!;
+  }
+
+  /// Detect if device is a tablet based on screen size
+  /// Uses the standard 600dp threshold (shortest side >= 600 = tablet)
+  static bool get isTablet {
+    try {
+      final view = ui.PlatformDispatcher.instance.views.first;
+      final size = view.physicalSize / view.devicePixelRatio;
+      return size.shortestSide >= 600;
+    } catch (e) {
+      _logger.log('Failed to detect device type: $e');
+      return false; // Default to phone if detection fails
+    }
+  }
+
+  /// Get or generate a unique player ID for this device
+  /// Format: ensemble_{username}_{deviceId} or ensemble_{deviceId}
+  ///
+  /// Key behaviors:
+  /// - Uses stable device ID that survives storage wipes
+  /// - Includes MA username to support multiple devices per account
+  /// - Regenerates if username changes (user logged in with different account)
+  static Future<String> getOrCreateDevicePlayerId() async {
+    final prefs = await SharedPreferences.getInstance();
+    final stableDeviceId = await _getStableDeviceId();
+    final maUsername = await SettingsService.getUsername();
+
+    // Generate expected ID based on current username and device
+    // Use shorter device ID suffix (first 8 chars) to keep ID reasonable length
+    final deviceIdSuffix = stableDeviceId.length > 8
+        ? stableDeviceId.substring(0, 8)
+        : stableDeviceId;
+
+    final expectedId = maUsername != null && maUsername.isNotEmpty
+        ? 'ensemble_${maUsername}_$deviceIdSuffix'
+        : 'ensemble_$deviceIdSuffix';
+
+    // Check if we already have the correct ID
+    final existingId = prefs.getString(_keyLocalPlayerId);
+    if (existingId == expectedId) {
+      _logger.log('Using existing player ID: $expectedId');
+      return expectedId;
+    }
+
+    // ID needs to be updated (first login, username changed, or migration)
+    if (existingId != null) {
+      _logger.log('Updating player ID from $existingId to $expectedId');
+    } else {
+      _logger.log('Generated new player ID: $expectedId');
+    }
+
+    await prefs.setString(_keyLocalPlayerId, expectedId);
+    return expectedId;
  }

  /// Adopt an existing player ID (used when claiming a ghost player)
@@ -45,4 +108,12 @@ class DeviceIdService {
    final prefs = await SharedPreferences.getInstance();
    return prefs.getString(_keyLocalPlayerId) == null;
  }
+
+  /// Force regeneration of player ID on next call
+  /// Useful after login/logout to ensure ID matches current user
+  static Future<void> invalidateCachedId() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_keyLocalPlayerId);
+    _logger.log('Invalidated cached player ID');
+  }
 }
@@ -71,6 +71,18 @@ class ErrorHandler {
      );
    }

+    // Unavailable content errors - these won't resolve with retry
+    if (errorStr.contains('no playable') ||
+        errorStr.contains('lack available providers') ||
+        errorStr.contains('no available providers')) {
+      return ErrorInfo(
+        type: ErrorType.playback,
+        userMessage: 'These tracks are unavailable. The music provider may not have them available for streaming.',
+        technicalMessage: error.toString(),
+        canRetry: false,
+      );
+    }
+
    // Playback errors
    if (errorStr.contains('queue') ||
        errorStr.contains('player') ||
@@ -82,5 +82,9 @@ class HardwareVolumeService {
    } catch (e) {
      _logger.error('Failed to stop volume button listening', context: 'VolumeService', error: e);
    }
+
+    // Close StreamControllers to prevent memory leaks
+    await _volumeUpController.close();
+    await _volumeDownController.close();
  }
 }
@@ -254,6 +254,9 @@ class MetadataService {
  // Cache for album images
  static final Map<String, String?> _albumImageCache = {};

+  // Cache for author images (audiobooks)
+  static final Map<String, String?> _authorImageCache = {};
+
  /// Fetches album cover URL from Deezer (free, no API key required)
  /// Returns the image URL if found, null otherwise
  static Future<String?> getAlbumImageUrl(String albumName, String? artistName) async {
@@ -323,10 +326,425 @@ class MetadataService {
    return null;
  }

+  /// Generate name variations for fuzzy matching
+  /// Returns a list of name variations to try, in priority order
+  static List<String> _generateNameVariations(String authorName) {
+    final variations = <String>[];
+    final original = authorName.trim();
+
+    // Always try original first
+    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"
+      }
+    }
+
+    // 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 {
+      // Step 1: Search for author to get ASIN
+      final searchUri = Uri.https('api.audnex.us', '/authors', {'name': name});
+      final searchResponse = await http.get(searchUri).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]+'), '');
+
+          for (final result in searchData) {
+            final resultName = (result['name'] as String?)?.toLowerCase().replaceAll(RegExp(r'[.\s]+'), '');
+            final asin = result['asin'] as String?;
+            if (asin != null) {
+              if (resultName == nameLower) {
+                bestAsin = asin;
+                break; // Exact match found
+              }
+              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 for "$name": $e', context: 'Metadata');
+    }
+    return null;
+  }
+
+  /// Try to fetch author image from Open Library
+  static Future<String?> _tryOpenLibrary(String name) async {
+    try {
+      final uri = Uri.https('openlibrary.org', '/search/authors.json', {
+        'q': name,
+        '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 authorKey = authors[0]['key'] as String?;
+          if (authorKey != null) {
+            final olid = authorKey.replaceAll('/authors/', '');
+            final imageUrl = 'https://covers.openlibrary.org/a/olid/$olid-L.jpg';
+
+            // Verify image exists - Open Library returns 302 redirects for valid images
+            try {
+              final check = await http.head(Uri.parse(imageUrl)).timeout(const Duration(seconds: 3));
+              // Accept 200 (direct), 301/302 (redirect to archive.org), or 307/308 (temporary redirect)
+              if (check.statusCode == 200 || check.statusCode == 301 ||
+                  check.statusCode == 302 || check.statusCode == 307 || check.statusCode == 308) {
+                return imageUrl;
+              }
+            } catch (_) {}
+          }
+        }
+      }
+    } 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('Wikidata author image error for "$name": $e', context: 'Metadata');
+    }
+    return null;
+  }
+
+  /// Try to fetch author image from Wikipedia
+  static Future<String?> _tryWikipedia(String name) async {
+    try {
+      // Search for author - "writer author" suffix helps find the right page
+      final searchUri = Uri.https('en.wikipedia.org', '/w/api.php', {
+        'action': 'query',
+        'list': 'search',
+        'srsearch': '$name writer author',
+        '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 results = searchData['query']?['search'] as List?;
+        if (results != null && results.isNotEmpty) {
+          final pageTitle = results[0]['title'] as String?;
+          if (pageTitle != null) {
+            // Get page image
+            final imageUri = Uri.https('en.wikipedia.org', '/w/api.php', {
+              'action': 'query',
+              'titles': pageTitle,
+              'prop': 'pageimages',
+              'pithumbsize': '500',
+              'format': 'json',
+            });
+            final imageResponse = await http.get(imageUri).timeout(const Duration(seconds: 5));
+
+            if (imageResponse.statusCode == 200) {
+              final imageData = json.decode(imageResponse.body);
+              final pages = imageData['query']?['pages'] as Map<String, dynamic>?;
+              if (pages != null && pages.isNotEmpty) {
+                final page = pages.values.first as Map<String, dynamic>?;
+                final thumbnail = page?['thumbnail'] as Map<String, dynamic>?;
+                final imageUrl = thumbnail?['source'] as String?;
+                if (imageUrl != null && imageUrl.isNotEmpty) {
+                  return imageUrl;
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (e) {
+      _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
+    _authorImageCache[cacheKey] = null;
+    return null;
+  }
+
  /// Clears the metadata cache
  static void clearCache() {
    _cache.clear();
    _artistImageCache.clear();
    _albumImageCache.clear();
+    _authorImageCache.clear();
  }
 }
@@ -0,0 +1,138 @@
+import 'dart:convert';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'debug_logger.dart';
+
+/// Represents a queued action that will be executed when connection is restored
+class QueuedAction {
+  final String type;
+  final Map<String, dynamic> params;
+  final DateTime queuedAt;
+
+  QueuedAction({
+    required this.type,
+    required this.params,
+    required this.queuedAt,
+  });
+
+  Map<String, dynamic> toJson() => {
+    'type': type,
+    'params': params,
+    'queuedAt': queuedAt.toIso8601String(),
+  };
+
+  factory QueuedAction.fromJson(Map<String, dynamic> json) => QueuedAction(
+    type: json['type'] as String,
+    params: json['params'] as Map<String, dynamic>,
+    queuedAt: DateTime.parse(json['queuedAt'] as String),
+  );
+}
+
+/// Service for queuing actions when offline and executing them when back online
+class OfflineActionQueue {
+  static OfflineActionQueue? _instance;
+  static OfflineActionQueue get instance => _instance ??= OfflineActionQueue._();
+
+  OfflineActionQueue._();
+
+  final _logger = DebugLogger();
+  static const _prefsKey = 'offline_action_queue';
+
+  List<QueuedAction> _queue = [];
+  bool _isProcessing = false;
+
+  /// Get the current queue (for display)
+  List<QueuedAction> get queue => List.unmodifiable(_queue);
+
+  /// Check if there are pending actions
+  bool get hasPendingActions => _queue.isNotEmpty;
+
+  /// Number of pending actions
+  int get pendingCount => _queue.length;
+
+  /// Initialize and load persisted queue
+  Future<void> initialize() async {
+    try {
+      final prefs = await SharedPreferences.getInstance();
+      final queueJson = prefs.getString(_prefsKey);
+      if (queueJson != null) {
+        final List<dynamic> decoded = jsonDecode(queueJson);
+        _queue = decoded.map((j) => QueuedAction.fromJson(j as Map<String, dynamic>)).toList();
+        _logger.log('📋 Loaded ${_queue.length} offline actions from storage');
+      }
+    } catch (e) {
+      _logger.log('⚠️ Error loading offline action queue: $e');
+    }
+  }
+
+  /// Queue an action for later execution
+  Future<void> queueAction(String type, Map<String, dynamic> params) async {
+    final action = QueuedAction(
+      type: type,
+      params: params,
+      queuedAt: DateTime.now(),
+    );
+    _queue.add(action);
+    await _persistQueue();
+    _logger.log('📋 Queued offline action: $type');
+  }
+
+  /// Process all queued actions (call when connection is restored)
+  Future<void> processQueue(Future<bool> Function(QueuedAction action) executor) async {
+    if (_isProcessing || _queue.isEmpty) return;
+
+    _isProcessing = true;
+    _logger.log('🔄 Processing ${_queue.length} offline actions...');
+
+    final processed = <QueuedAction>[];
+
+    for (final action in _queue) {
+      try {
+        final success = await executor(action);
+        if (success) {
+          processed.add(action);
+          _logger.log('✅ Processed offline action: ${action.type}');
+        } else {
+          _logger.log('⚠️ Failed to process offline action: ${action.type}');
+        }
+      } catch (e) {
+        _logger.log('❌ Error processing offline action: $e');
+      }
+    }
+
+    // Remove processed actions
+    _queue.removeWhere((a) => processed.contains(a));
+    await _persistQueue();
+
+    _isProcessing = false;
+    _logger.log('📋 ${processed.length} actions processed, ${_queue.length} remaining');
+  }
+
+  /// Clear all queued actions
+  Future<void> clearQueue() async {
+    _queue.clear();
+    await _persistQueue();
+    _logger.log('🗑️ Offline action queue cleared');
+  }
+
+  /// Persist queue to storage
+  Future<void> _persistQueue() async {
+    try {
+      final prefs = await SharedPreferences.getInstance();
+      if (_queue.isEmpty) {
+        await prefs.remove(_prefsKey);
+      } else {
+        final queueJson = jsonEncode(_queue.map((a) => a.toJson()).toList());
+        await prefs.setString(_prefsKey, queueJson);
+      }
+    } catch (e) {
+      _logger.log('⚠️ Error persisting offline action queue: $e');
+    }
+  }
+}
+
+/// Action types for offline queuing
+class OfflineActionTypes {
+  static const String toggleFavorite = 'toggle_favorite';
+  static const String addToPlaylist = 'add_to_playlist';
+  static const String removeFromPlaylist = 'remove_from_playlist';
+}
@@ -0,0 +1,691 @@
+import 'dart:async';
+import 'dart:typed_data';
+import 'package:flutter/foundation.dart' show unawaited;
+import 'package:flutter_pcm_sound/flutter_pcm_sound.dart' as pcm;
+import 'debug_logger.dart';
+
+/// Callback type for elapsed time updates
+typedef ElapsedTimeCallback = void Function(Duration elapsed);
+
+/// Audio format configuration matching Sendspin protocol
+class PcmAudioFormat {
+  final int sampleRate;
+  final int channels;
+  final int bitDepth;
+
+  const PcmAudioFormat({
+    this.sampleRate = 48000,
+    this.channels = 2,
+    this.bitDepth = 16,
+  });
+
+  /// Default Sendspin format: 48kHz, stereo, 16-bit PCM
+  static const sendspin = PcmAudioFormat();
+}
+
+/// Player state for PCM audio
+enum PcmPlayerState {
+  idle,
+  initializing,
+  ready,
+  playing,
+  pausing,   // Transitional state: pause requested, waiting for completion
+  paused,
+  resuming,  // Transitional state: resume requested, re-initializing
+  stopping,  // Transitional state: stop requested, cleaning up
+  error,
+}
+
+/// Error types for PCM player operations
+enum PcmPlayerError {
+  initializationFailed,
+  feedFailed,
+  pauseFailed,
+  resumeFailed,
+  streamError,
+  releaseTimeout,
+}
+
+/// Callback type for error events
+typedef PcmErrorCallback = void Function(PcmPlayerError error, String message);
+
+/// Service to play raw PCM audio data from Sendspin WebSocket stream
+/// Uses flutter_pcm_sound plugin for low-level PCM playback
+///
+/// State Machine:
+/// - idle → initializing → ready → playing ↔ paused
+/// - Any state can transition to error
+/// - Transitional states (pausing, resuming, stopping) block operations
+class PcmAudioPlayer {
+  final _logger = DebugLogger();
+
+  PcmPlayerState _state = PcmPlayerState.idle;
+  PcmAudioFormat _format = PcmAudioFormat.sendspin;
+
+  StreamSubscription<Uint8List>? _audioSubscription;
+
+  // Audio buffer for smooth playback
+  final List<Uint8List> _audioBuffer = [];
+  bool _isFeeding = false;
+  bool _isStarted = false;
+  bool _isAutoRecovering = false;  // Tracks auto-recovery from setup errors
+  Completer<void>? _feedCompleter;  // Tracks when current feed operation completes
+
+  // Error callback for operation failures
+  PcmErrorCallback? onError;
+
+  // Maximum chunks to feed at once to keep native buffer small (~200ms)
+  // Each chunk is ~25ms of audio, so 8 chunks = ~200ms
+  // Reduced from 12 (300ms) to 8 for faster pause response
+  static const int _maxChunksPerFeed = 8;
+
+  // Feed threshold - lower = faster pause but more risk of underruns
+  // Reduced from 8000 to 5000 frames (~104ms vs ~166ms) for faster response
+  static const int _feedThreshold = 5000;
+
+  // Maximum buffer size to prevent memory overflow (~10 seconds of audio)
+  // At 48kHz stereo 16-bit: 192KB/sec, so ~2MB for 10 seconds
+  // Each chunk is ~4KB, so max ~500 chunks
+  static const int _maxBufferChunks = 500;
+
+  // Stats
+  int _framesPlayed = 0;
+  int _bytesPlayed = 0;
+
+  // Elapsed time tracking for notification sync
+  Timer? _elapsedTimeTimer;
+  final _elapsedTimeController = StreamController<Duration>.broadcast();
+  ElapsedTimeCallback? onElapsedTimeUpdate;
+
+  // Track offset for pause/resume (preserves position across pause cycles)
+  int _bytesPlayedAtLastPause = 0;
+  DateTime? _playbackStartTime;
+
+  PcmPlayerState get state => _state;
+  bool get isPlaying => _state == PcmPlayerState.playing;
+  bool get isPaused => _state == PcmPlayerState.paused;
+  bool get isReady => _state == PcmPlayerState.ready || _state == PcmPlayerState.playing || _state == PcmPlayerState.paused;
+  int get framesPlayed => _framesPlayed;
+  int get bytesPlayed => _bytesPlayed;
+
+  /// Check if player is in a transitional state (operation in progress)
+  bool get isTransitioning => _state == PcmPlayerState.pausing ||
+                               _state == PcmPlayerState.resuming ||
+                               _state == PcmPlayerState.stopping;
+
+  /// Check if feeding should be blocked
+  bool get _shouldBlockFeeding => isTransitioning || _state == PcmPlayerState.paused;
+
+  /// Stream of elapsed time updates (emits every 500ms when playing)
+  Stream<Duration> get elapsedTimeStream => _elapsedTimeController.stream;
+
+  /// Calculate elapsed playback time from bytes played
+  /// For 48kHz stereo 16-bit: 4 bytes per frame, 48000 frames per second
+  Duration get elapsedTime {
+    // Bytes per frame = channels * (bitDepth / 8) = 2 * 2 = 4
+    final bytesPerFrame = _format.channels * (_format.bitDepth ~/ 8);
+    final framesFromBytes = _bytesPlayed / bytesPerFrame;
+    final elapsedSeconds = framesFromBytes / _format.sampleRate;
+    return Duration(milliseconds: (elapsedSeconds * 1000).round());
+  }
+
+  /// Get elapsed time in seconds (for convenience)
+  double get elapsedTimeSeconds {
+    final bytesPerFrame = _format.channels * (_format.bitDepth ~/ 8);
+    final framesFromBytes = _bytesPlayed / bytesPerFrame;
+    return framesFromBytes / _format.sampleRate;
+  }
+
+  /// Initialize the PCM player with the given format
+  Future<bool> initialize({PcmAudioFormat? format}) async {
+    if (_state == PcmPlayerState.initializing) return false;
+
+    _format = format ?? PcmAudioFormat.sendspin;
+    _state = PcmPlayerState.initializing;
+
+    try {
+      _logger.log('PcmAudioPlayer: Initializing (${_format.sampleRate}Hz, ${_format.channels}ch, ${_format.bitDepth}bit)');
+
+      // Setup flutter_pcm_sound with Sendspin audio format
+      await pcm.FlutterPcmSound.setup(
+        sampleRate: _format.sampleRate,
+        channelCount: _format.channels,
+      );
+
+      // Set feed threshold - request more data when buffer has fewer frames
+      // Lower threshold = lower latency but more risk of underruns
+      // Using _feedThreshold (5000 frames = ~104ms) for faster pause response
+      await pcm.FlutterPcmSound.setFeedThreshold(_feedThreshold);
+
+      // Set up feed callback for when buffer needs more data
+      pcm.FlutterPcmSound.setFeedCallback(_onFeedRequested);
+
+      // Set log level for debugging
+      await pcm.FlutterPcmSound.setLogLevel(pcm.LogLevel.standard);
+
+      _state = PcmPlayerState.ready;
+      _logger.log('PcmAudioPlayer: Initialized successfully');
+      return true;
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Initialization failed: $e');
+      _state = PcmPlayerState.error;
+      return false;
+    }
+  }
+
+  /// Callback when flutter_pcm_sound needs more audio data
+  void _onFeedRequested(int remainingFrames) {
+    // This is called from native when buffer is getting low
+    // Block feeding during pause, transitional states, or when not playing
+    if (_state != PcmPlayerState.playing) return;
+    if (_shouldBlockFeeding) return;
+    if (_audioBuffer.isEmpty || _isFeeding) return;
+
+    _feedNextChunk();
+  }
+
+  /// Connect to a Sendspin audio data stream and start playback
+  Future<bool> connectToStream(Stream<Uint8List> audioStream) async {
+    if (_state == PcmPlayerState.error || _state == PcmPlayerState.idle) {
+      _logger.log('PcmAudioPlayer: Cannot connect - player not initialized');
+      return false;
+    }
+
+    // Cancel any existing subscription
+    await _audioSubscription?.cancel();
+
+    _logger.log('PcmAudioPlayer: Connecting to audio stream');
+
+    // Subscribe to the audio stream
+    _audioSubscription = audioStream.listen(
+      _onAudioData,
+      onError: _onStreamError,
+      onDone: _onStreamDone,
+    );
+
+    return true;
+  }
+
+  /// Safely add audio data to buffer with overflow protection
+  void _addToBuffer(Uint8List audioData) {
+    // If buffer is full, drop oldest chunks to make room
+    while (_audioBuffer.length >= _maxBufferChunks) {
+      _audioBuffer.removeAt(0);
+      _logger.log('⚠️ PcmAudioPlayer: Buffer overflow - dropping oldest chunk');
+    }
+    _audioBuffer.add(audioData);
+  }
+
+  /// Handle incoming audio data from the stream
+  void _onAudioData(Uint8List audioData) {
+    // Ignore data if in error state
+    if (_state == PcmPlayerState.error) return;
+
+    // Handle audio arriving during paused/transitional states
+    // This can happen when audio frames arrive before stream/start message (race condition)
+    // We need to auto-recover in this case
+    if (_shouldBlockFeeding) {
+      // If we're paused and audio is arriving, this is likely a new stream
+      // starting before the stream/start message. Queue for auto-recovery.
+      if (_state == PcmPlayerState.paused && !_isAutoRecovering) {
+        _logger.log('PcmAudioPlayer: Audio arriving while paused - initiating auto-recovery');
+        _isAutoRecovering = true;
+        _addToBuffer(audioData);
+
+        // Trigger async recovery
+        _autoRecoverFromPause();
+        return;
+      }
+
+      // If already recovering or in transitional state, buffer the data
+      if (_isAutoRecovering) {
+        _addToBuffer(audioData);
+        return;
+      }
+
+      // For other blocking states (pausing, stopping, resuming), ignore
+      return;
+    }
+
+    // Add to buffer with overflow protection
+    _addToBuffer(audioData);
+
+    // Start playback if not already started
+    if (!_isStarted && _state == PcmPlayerState.ready) {
+      _startPlayback();
+    }
+
+    // Feed data if not currently feeding
+    if (!_isFeeding && _isStarted) {
+      _feedNextChunk();
+    }
+  }
+
+  /// Auto-recover from paused state when audio arrives unexpectedly
+  Future<void> _autoRecoverFromPause() async {
+    _logger.log('PcmAudioPlayer: Auto-recovering from pause');
+
+    try {
+      // Re-initialize the native player
+      await pcm.FlutterPcmSound.setup(
+        sampleRate: _format.sampleRate,
+        channelCount: _format.channels,
+      );
+      await pcm.FlutterPcmSound.setFeedThreshold(_feedThreshold);
+      pcm.FlutterPcmSound.setFeedCallback(_onFeedRequested);
+      await pcm.FlutterPcmSound.start();
+
+      _isStarted = true;
+      _state = PcmPlayerState.playing;
+      _startElapsedTimeTimer();
+      _logger.log('PcmAudioPlayer: Auto-recovery from pause successful');
+
+      // Start feeding buffered data
+      _isAutoRecovering = false;
+      if (_audioBuffer.isNotEmpty && !_isFeeding) {
+        _feedNextChunk();
+      }
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Auto-recovery from pause failed: $e');
+      _isAutoRecovering = false;
+      _state = PcmPlayerState.error;
+      _emitError(PcmPlayerError.resumeFailed, e.toString());
+    }
+  }
+
+  /// Start audio playback
+  Future<void> _startPlayback() async {
+    if (_isStarted) return;
+
+    try {
+      await pcm.FlutterPcmSound.start();
+      _isStarted = true;
+      _state = PcmPlayerState.playing;
+      _playbackStartTime = DateTime.now();
+      _startElapsedTimeTimer();
+      _logger.log('PcmAudioPlayer: Started playback');
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Error starting playback: $e');
+      _state = PcmPlayerState.error;
+    }
+  }
+
+  /// Start the elapsed time update timer
+  void _startElapsedTimeTimer() {
+    _elapsedTimeTimer?.cancel();
+    _elapsedTimeTimer = Timer.periodic(
+      const Duration(milliseconds: 500),
+      (_) => _emitElapsedTime(),
+    );
+    // Emit immediately
+    _emitElapsedTime();
+  }
+
+  /// Stop the elapsed time update timer
+  void _stopElapsedTimeTimer() {
+    _elapsedTimeTimer?.cancel();
+    _elapsedTimeTimer = null;
+  }
+
+  /// Emit the current elapsed time to listeners
+  void _emitElapsedTime() {
+    if (_state != PcmPlayerState.playing) return;
+
+    final elapsed = elapsedTime;
+    if (!_elapsedTimeController.isClosed) {
+      _elapsedTimeController.add(elapsed);
+    }
+    onElapsedTimeUpdate?.call(elapsed);
+  }
+
+  /// Feed the next chunk of audio data to the player
+  /// CRITICAL: Only feeds limited chunks to keep native buffer small (~200ms)
+  /// This enables faster pause response by minimizing buffered audio
+  Future<void> _feedNextChunk() async {
+    if (_isFeeding || _audioBuffer.isEmpty || _shouldBlockFeeding) return;
+
+    _isFeeding = true;
+    _feedCompleter = Completer<void>();
+
+    try {
+      int chunksProcessed = 0;
+
+      // CRITICAL: Only feed limited chunks to keep native buffer small
+      // This is the key to fast pause - we drain ~200ms instead of 5-8 seconds
+      while (_audioBuffer.isNotEmpty &&
+             chunksProcessed < _maxChunksPerFeed &&
+             _state == PcmPlayerState.playing &&
+             !_shouldBlockFeeding) {
+        final chunk = _audioBuffer.removeAt(0);
+
+        // Convert Uint8List (raw bytes) to Int16 samples
+        // Sendspin sends 16-bit little-endian PCM
+        final samples = _bytesToInt16List(chunk);
+
+        // Check state again before the async feed call
+        if (samples.isNotEmpty && !_shouldBlockFeeding) {
+          try {
+            await pcm.FlutterPcmSound.feed(pcm.PcmArrayInt16.fromList(samples));
+          } catch (feedError) {
+            // Auto-recover from "must call setup first" error
+            // This happens when audio frames arrive before stream/start message
+            if (feedError.toString().contains('must call setup first') && !_isAutoRecovering) {
+              _logger.log('PcmAudioPlayer: Auto-recovering from setup error');
+              _isAutoRecovering = true;
+
+              try {
+                // Re-initialize the native player
+                await pcm.FlutterPcmSound.setup(
+                  sampleRate: _format.sampleRate,
+                  channelCount: _format.channels,
+                );
+                await pcm.FlutterPcmSound.setFeedThreshold(_feedThreshold);
+                pcm.FlutterPcmSound.setFeedCallback(_onFeedRequested);
+                await pcm.FlutterPcmSound.start();
+                _isStarted = true;
+                _state = PcmPlayerState.playing;
+                _startElapsedTimeTimer();
+                _logger.log('PcmAudioPlayer: Auto-recovery successful');
+
+                // Retry the feed with the current chunk
+                await pcm.FlutterPcmSound.feed(pcm.PcmArrayInt16.fromList(samples));
+              } catch (recoveryError) {
+                _logger.log('PcmAudioPlayer: Auto-recovery failed: $recoveryError');
+                _isAutoRecovering = false;
+                rethrow;
+              }
+              _isAutoRecovering = false;
+            } else {
+              rethrow;
+            }
+          }
+
+          // Don't update stats if we got paused during the feed
+          if (!_shouldBlockFeeding) {
+            _framesPlayed++;
+            _bytesPlayed += chunk.length;
+            chunksProcessed++;
+
+            // Log periodically
+            if (_framesPlayed % 100 == 0) {
+              _logger.log('PcmAudioPlayer: Played $_framesPlayed frames (${(_bytesPlayed / 1024).toStringAsFixed(1)} KB)');
+            }
+          }
+        }
+
+        // Yield to event loop mid-feed to allow UI to respond
+        if (chunksProcessed % 4 == 0) {
+          await Future.delayed(Duration.zero);
+        }
+      }
+    } catch (e) {
+      // Don't log errors during pause/transition - expected when player is released
+      if (!_shouldBlockFeeding) {
+        _logger.log('PcmAudioPlayer: Error feeding audio: $e');
+        _emitError(PcmPlayerError.feedFailed, e.toString());
+      }
+    }
+
+    _isFeeding = false;
+    _feedCompleter?.complete();
+    _feedCompleter = null;
+  }
+
+  /// Emit an error to the callback
+  void _emitError(PcmPlayerError error, String message) {
+    _logger.log('PcmAudioPlayer: Error - $error: $message');
+    onError?.call(error, message);
+  }
+
+  /// Convert raw bytes (Uint8List) to Int16 samples
+  /// Assumes little-endian 16-bit PCM
+  List<int> _bytesToInt16List(Uint8List bytes) {
+    if (bytes.length < 2) return [];
+
+    final byteData = ByteData.sublistView(bytes);
+    final samples = <int>[];
+
+    for (int i = 0; i < bytes.length - 1; i += 2) {
+      samples.add(byteData.getInt16(i, Endian.little));
+    }
+
+    return samples;
+  }
+
+  /// Handle stream errors - notify listeners and pause playback
+  void _onStreamError(dynamic error) {
+    _logger.log('PcmAudioPlayer: Stream error: $error');
+    _emitError(PcmPlayerError.streamError, error.toString());
+
+    // Pause on stream error to prevent playback of corrupted/incomplete audio
+    if (_state == PcmPlayerState.playing) {
+      _logger.log('PcmAudioPlayer: Pausing due to stream error');
+      pause();
+    }
+  }
+
+  /// Handle stream completion
+  void _onStreamDone() {
+    _logger.log('PcmAudioPlayer: Audio stream ended');
+    // Don't stop immediately - let buffered audio finish
+  }
+
+  /// Start playback (if paused or ready)
+  /// Returns true if playback started successfully
+  Future<bool> play() async {
+    if (_state == PcmPlayerState.error) return false;
+    if (isTransitioning) {
+      _logger.log('PcmAudioPlayer: Cannot play - operation in progress (state: $_state)');
+      return false;
+    }
+
+    if (_state == PcmPlayerState.paused) {
+      // Resume from pause - need to re-initialize since we released on pause
+      _logger.log('PcmAudioPlayer: Resuming from pause at ${elapsedTime.inSeconds}s');
+      _state = PcmPlayerState.resuming;
+
+      // Re-initialize the PCM player (it was released on pause)
+      try {
+        await pcm.FlutterPcmSound.setup(
+          sampleRate: _format.sampleRate,
+          channelCount: _format.channels,
+        );
+        await pcm.FlutterPcmSound.setFeedThreshold(_feedThreshold);
+        pcm.FlutterPcmSound.setFeedCallback(_onFeedRequested);
+        await pcm.FlutterPcmSound.start();
+        _isStarted = true;
+      } catch (e) {
+        _logger.log('PcmAudioPlayer: Error re-initializing on resume: $e');
+        _emitError(PcmPlayerError.resumeFailed, e.toString());
+        _state = PcmPlayerState.error;
+        return false;
+      }
+
+      _state = PcmPlayerState.playing;
+      _startElapsedTimeTimer();
+
+      // Resume feeding - new audio will come from stream
+      if (!_isFeeding && _audioBuffer.isNotEmpty) {
+        _feedNextChunk();
+      }
+
+      _logger.log('PcmAudioPlayer: Resumed playback');
+      return true;
+    } else if (_state == PcmPlayerState.ready) {
+      await _startPlayback();
+      _logger.log('PcmAudioPlayer: Started playback');
+
+      // Start feeding
+      if (!_isFeeding && _audioBuffer.isNotEmpty) {
+        _feedNextChunk();
+      }
+      return true;
+    }
+
+    return false;
+  }
+
+  /// Pause playback - stops feeding and releases player for instant stop
+  /// Position is preserved via _bytesPlayed tracking
+  /// Uses release() to clear native buffer for instant audio stop
+  /// Returns true if pause was successful
+  Future<bool> pause() async {
+    if (_state != PcmPlayerState.playing) {
+      _logger.log('PcmAudioPlayer: Cannot pause - not playing (state: $_state)');
+      return false;
+    }
+
+    _logger.log('PcmAudioPlayer: Pause requested');
+
+    // Set pausing state FIRST to stop feed loop from starting new feeds
+    _state = PcmPlayerState.pausing;
+
+    // Clear our buffer - no more data will be fed
+    _audioBuffer.clear();
+
+    // Clear feed callback to prevent native from triggering more feeds
+    pcm.FlutterPcmSound.setFeedCallback(null);
+
+    // Mark as not feeding
+    _isFeeding = false;
+
+    // Save position and stop timer
+    _bytesPlayedAtLastPause = _bytesPlayed;
+    _stopElapsedTimeTimer();
+
+    // Schedule release() to clear native buffer - use Future.delayed to yield control
+    // This allows UI to update before the potentially blocking release() call
+    unawaited(Future.delayed(Duration.zero, () async {
+      try {
+        await pcm.FlutterPcmSound.release().timeout(
+          const Duration(milliseconds: 500),
+          onTimeout: () {
+            _logger.log('PcmAudioPlayer: Release timed out');
+            _emitError(PcmPlayerError.releaseTimeout, 'release() timed out');
+          },
+        );
+        _isStarted = false;
+        _logger.log('PcmAudioPlayer: Player released for instant stop');
+      } catch (e) {
+        _logger.log('PcmAudioPlayer: Release error (expected if already released): $e');
+      }
+    }));
+
+    // Transition to paused state
+    _state = PcmPlayerState.paused;
+    _logger.log('PcmAudioPlayer: Paused playback at ${elapsedTime.inSeconds}s');
+    return true;
+  }
+
+  /// Stop playback (clears buffer and resets position)
+  /// Returns true if stop was successful
+  Future<bool> stop() async {
+    if (_state == PcmPlayerState.idle) return true;
+
+    _logger.log('PcmAudioPlayer: Stop requested');
+
+    // Set stopping state to block any in-flight feed operations
+    _state = PcmPlayerState.stopping;
+    _isStarted = false;
+    _stopElapsedTimeTimer();
+
+    // Clear the feed callback to prevent native code from triggering new feeds
+    pcm.FlutterPcmSound.setFeedCallback(null);
+
+    // Wait for any in-progress feed operation to complete (with timeout)
+    final completer = _feedCompleter;
+    if (completer != null && !completer.isCompleted) {
+      await completer.future.timeout(
+        const Duration(milliseconds: 500),
+        onTimeout: () {
+          _logger.log('PcmAudioPlayer: Feed wait timed out on stop');
+        },
+      );
+    }
+
+    _audioBuffer.clear();
+    _isFeeding = false;
+
+    try {
+      await pcm.FlutterPcmSound.release();
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Error releasing: $e');
+    }
+
+    _state = PcmPlayerState.ready;
+    _framesPlayed = 0;
+    _bytesPlayed = 0;
+    _bytesPlayedAtLastPause = 0;
+    _playbackStartTime = null;
+    _logger.log('PcmAudioPlayer: Stopped playback');
+
+    // Re-initialize for next playback
+    await initialize(format: _format);
+    return true;
+  }
+
+  /// Reset position to zero (for new track) without stopping playback
+  void resetPosition() {
+    _framesPlayed = 0;
+    _bytesPlayed = 0;
+    _bytesPlayedAtLastPause = 0;
+    _playbackStartTime = DateTime.now();
+    _logger.log('PcmAudioPlayer: Position reset to 0');
+    _emitElapsedTime();
+  }
+
+  /// Disconnect from audio stream
+  Future<void> disconnect() async {
+    await _audioSubscription?.cancel();
+    _audioSubscription = null;
+    await stop();
+    _logger.log('PcmAudioPlayer: Disconnected from stream');
+  }
+
+  /// Release all resources
+  Future<void> dispose() async {
+    _logger.log('PcmAudioPlayer: Disposing...');
+
+    // Set stopping state to block any feed operations
+    _state = PcmPlayerState.stopping;
+    _isStarted = false;
+    _stopElapsedTimeTimer();
+
+    // Clear the feed callback first
+    pcm.FlutterPcmSound.setFeedCallback(null);
+
+    // Wait for any in-progress feed operation
+    final completer = _feedCompleter;
+    if (completer != null && !completer.isCompleted) {
+      await completer.future.timeout(
+        const Duration(milliseconds: 500),
+        onTimeout: () {
+          _logger.log('PcmAudioPlayer: Feed wait timed out on dispose');
+        },
+      );
+    }
+
+    _isFeeding = false;
+    await _audioSubscription?.cancel();
+    _audioSubscription = null;
+    _audioBuffer.clear();
+
+    try {
+      await pcm.FlutterPcmSound.release().timeout(
+        const Duration(milliseconds: 500),
+        onTimeout: () {
+          _logger.log('PcmAudioPlayer: Release timed out on dispose');
+        },
+      );
+    } catch (e) {
+      _logger.log('PcmAudioPlayer: Error releasing: $e');
+    }
+
+    if (!_elapsedTimeController.isClosed) {
+      await _elapsedTimeController.close();
+    }
+
+    _state = PcmPlayerState.idle;
+    _logger.log('PcmAudioPlayer: Disposed');
+  }
+}
@@ -24,6 +24,10 @@ class PositionTracker {
  double _anchorPosition = 0.0;  // Position in seconds at anchor time
  DateTime _anchorTime = DateTime.now();  // When we set the anchor

+  // Maximum time to interpolate from a stale anchor before capping
+  // After this, we stop adding time to prevent indefinite drift
+  static const Duration _maxAnchorAge = Duration(seconds: 30);
+
  // Interpolation timer
  Timer? _interpolationTimer;

@@ -43,7 +47,13 @@ class PositionTracker {
    }

    final now = DateTime.now();
-    final elapsed = now.difference(_anchorTime).inMilliseconds / 1000.0;
+    final anchorAge = now.difference(_anchorTime);
+
+    // Cap interpolation at max anchor age to prevent indefinite drift
+    // If anchor is stale, return last known position (anchor + max age)
+    final elapsed = anchorAge > _maxAnchorAge
+        ? _maxAnchorAge.inMilliseconds / 1000.0
+        : anchorAge.inMilliseconds / 1000.0;
    final interpolated = _anchorPosition + elapsed;

    // Cap at duration to prevent overflow
@@ -61,7 +71,12 @@ class PositionTracker {
    }

    final now = DateTime.now();
-    final elapsed = now.difference(_anchorTime).inMilliseconds / 1000.0;
+    final anchorAge = now.difference(_anchorTime);
+
+    // Cap interpolation at max anchor age to prevent indefinite drift
+    final elapsed = anchorAge > _maxAnchorAge
+        ? _maxAnchorAge.inMilliseconds / 1000.0
+        : anchorAge.inMilliseconds / 1000.0;
    final interpolated = _anchorPosition + elapsed;

    // Cap at duration
@@ -0,0 +1,110 @@
+import 'database_service.dart';
+import 'settings_service.dart';
+import 'debug_logger.dart';
+import '../database/database.dart';
+
+/// Service for managing user profiles
+/// Profiles are auto-created from MA authentication or manual name entry
+class ProfileService {
+  static ProfileService? _instance;
+  static final _logger = DebugLogger();
+
+  ProfileService._();
+
+  /// Get the singleton instance
+  static ProfileService get instance {
+    _instance ??= ProfileService._();
+    return _instance!;
+  }
+
+  DatabaseService get _db => DatabaseService.instance;
+
+  /// Get the currently active profile
+  Future<Profile?> getActiveProfile() async {
+    if (!_db.isInitialized) return null;
+    return _db.getActiveProfile();
+  }
+
+  /// Get the active profile's username/name
+  Future<String?> getActiveProfileName() async {
+    final profile = await getActiveProfile();
+    return profile?.displayName ?? profile?.username;
+  }
+
+  /// Called after successful MA authentication
+  /// Creates or activates profile based on MA user info
+  Future<Profile> onMaAuthenticated({
+    required String username,
+    String? displayName,
+  }) async {
+    _logger.log('MA authenticated: username=$username, displayName=$displayName');
+
+    final profile = await _db.setActiveProfile(
+      username: username,
+      displayName: displayName,
+      source: 'ma_auth',
+    );
+
+    _logger.log('Profile activated: ${profile.username} (${profile.displayName})');
+    return profile;
+  }
+
+  /// Called when user manually enters their name (no MA auth)
+  /// Creates or activates profile based on entered name
+  Future<Profile> onManualNameEntered(String name) async {
+    _logger.log('Manual name entered: $name');
+
+    // Use name as both username and display name for manual profiles
+    final profile = await _db.setActiveProfile(
+      username: name.toLowerCase().replaceAll(' ', '_'),
+      displayName: name,
+      source: 'manual',
+    );
+
+    _logger.log('Profile activated: ${profile.username} (${profile.displayName})');
+    return profile;
+  }
+
+  /// Migrate existing ownerName to profile (one-time migration)
+  Future<void> migrateFromOwnerName() async {
+    if (!_db.isInitialized) return;
+
+    // Check if we already have any profiles
+    final profiles = await _db.getAllProfiles();
+    if (profiles.isNotEmpty) {
+      _logger.log('Migration skipped - profiles already exist');
+      return;
+    }
+
+    // Check for existing ownerName in settings
+    final ownerName = await SettingsService.getOwnerName();
+    if (ownerName == null || ownerName.isEmpty) {
+      _logger.log('Migration skipped - no ownerName to migrate');
+      return;
+    }
+
+    _logger.log('Migrating ownerName "$ownerName" to profile...');
+
+    // Create profile from ownerName
+    // We don't know if it was MA auth or manual, so default to manual
+    await _db.setActiveProfile(
+      username: ownerName.toLowerCase().replaceAll(' ', '_'),
+      displayName: ownerName,
+      source: 'migrated',
+    );
+
+    _logger.log('Migration complete');
+  }
+
+  /// Get all profiles (for potential profile switcher UI)
+  Future<List<Profile>> getAllProfiles() async {
+    if (!_db.isInitialized) return [];
+    return _db.getAllProfiles();
+  }
+
+  /// Check if any profile exists
+  Future<bool> hasAnyProfile() async {
+    final profiles = await getAllProfiles();
+    return profiles.isNotEmpty;
+  }
+}
@@ -0,0 +1,259 @@
+import 'dart:convert';
+import 'database_service.dart';
+import 'debug_logger.dart';
+import '../database/database.dart';
+import '../models/media_item.dart';
+
+/// Service for tracking recently played items locally, per-profile
+/// This supplements MA's server-side tracking with instant local data
+class RecentlyPlayedService {
+  static RecentlyPlayedService? _instance;
+  static final _logger = DebugLogger();
+
+  RecentlyPlayedService._();
+
+  /// Get the singleton instance
+  static RecentlyPlayedService get instance {
+    _instance ??= RecentlyPlayedService._();
+    return _instance!;
+  }
+
+  DatabaseService get _db => DatabaseService.instance;
+
+  /// Record an album being played
+  Future<void> recordAlbumPlayed(Album album) async {
+    if (!_db.isInitialized) return;
+
+    try {
+      // Store images metadata for instant artwork display
+      final images = album.metadata?['images'];
+      await _db.addRecentlyPlayed(
+        mediaId: album.itemId,
+        mediaType: 'album',
+        name: album.name,
+        artistName: album.artistsString,
+        metadata: {
+          'provider': album.provider,
+          'uri': album.uri,
+          if (images != null) 'images': images,
+        },
+      );
+      _logger.log('📝 Recorded album play: ${album.name}');
+    } catch (e) {
+      _logger.log('⚠️ Failed to record album play: $e');
+    }
+  }
+
+  /// Record an artist being played (e.g., artist radio)
+  Future<void> recordArtistPlayed(Artist artist) async {
+    if (!_db.isInitialized) return;
+
+    try {
+      await _db.addRecentlyPlayed(
+        mediaId: artist.itemId,
+        mediaType: 'artist',
+        name: artist.name,
+        metadata: {
+          'provider': artist.provider,
+          'uri': artist.uri,
+        },
+      );
+      _logger.log('📝 Recorded artist play: ${artist.name}');
+    } catch (e) {
+      _logger.log('⚠️ Failed to record artist play: $e');
+    }
+  }
+
+  /// Record a track being played
+  Future<void> recordTrackPlayed(Track track) async {
+    if (!_db.isInitialized) return;
+
+    try {
+      await _db.addRecentlyPlayed(
+        mediaId: track.itemId,
+        mediaType: 'track',
+        name: track.name,
+        artistName: track.artistsString,
+        metadata: {
+          'provider': track.provider,
+          'uri': track.uri,
+          'albumName': track.album?.name,
+        },
+      );
+      _logger.log('📝 Recorded track play: ${track.name}');
+    } catch (e) {
+      _logger.log('⚠️ Failed to record track play: $e');
+    }
+  }
+
+  /// Record a playlist being played
+  Future<void> recordPlaylistPlayed(Playlist playlist) async {
+    if (!_db.isInitialized) return;
+
+    try {
+      await _db.addRecentlyPlayed(
+        mediaId: playlist.itemId,
+        mediaType: 'playlist',
+        name: playlist.name,
+        metadata: {
+          'provider': playlist.provider,
+          'uri': playlist.uri,
+        },
+      );
+      _logger.log('📝 Recorded playlist play: ${playlist.name}');
+    } catch (e) {
+      _logger.log('⚠️ Failed to record playlist play: $e');
+    }
+  }
+
+  /// Record an audiobook being played
+  Future<void> recordAudiobookPlayed(Audiobook audiobook) async {
+    if (!_db.isInitialized) return;
+
+    try {
+      await _db.addRecentlyPlayed(
+        mediaId: audiobook.itemId,
+        mediaType: 'audiobook',
+        name: audiobook.name,
+        artistName: audiobook.authorsString,
+        metadata: {
+          'provider': audiobook.provider,
+          'uri': audiobook.uri,
+          'narrators': audiobook.narratorsString,
+          'duration': audiobook.duration?.inSeconds,
+          'resumePositionMs': audiobook.resumePositionMs,
+        },
+      );
+      _logger.log('📝 Recorded audiobook play: ${audiobook.name}');
+    } catch (e) {
+      _logger.log('⚠️ Failed to record audiobook play: $e');
+    }
+  }
+
+  /// Get recently played albums for the current profile
+  /// Returns Album objects reconstructed from local data
+  Future<List<Album>> getRecentAlbums({int limit = 20}) async {
+    if (!_db.isInitialized) return [];
+
+    try {
+      final items = await _db.getRecentlyPlayed(limit: limit * 2); // Get more to filter
+
+      // Filter for albums and convert to Album objects
+      final albums = <Album>[];
+      final seenIds = <String>{};
+
+      for (final item in items) {
+        if (item.mediaType != 'album') continue;
+        if (seenIds.contains(item.mediaId)) continue;
+        seenIds.add(item.mediaId);
+
+        Map<String, dynamic>? metadata;
+        if (item.metadata != null) {
+          try {
+            metadata = jsonDecode(item.metadata!) as Map<String, dynamic>;
+          } catch (e) {
+            // Corrupted metadata JSON - log and continue with null metadata
+            _logger.log('⚠️ Error parsing album metadata for ${item.mediaId}: $e');
+          }
+        }
+
+        // Build metadata with images if available (for instant artwork display)
+        Map<String, dynamic>? albumMetadata;
+        if (metadata?['images'] != null) {
+          albumMetadata = {'images': metadata!['images']};
+        }
+
+        albums.add(Album(
+          itemId: item.mediaId,
+          provider: metadata?['provider'] ?? 'library',
+          name: item.name,
+          uri: metadata?['uri'],
+          // Create minimal artist info from stored name
+          artists: item.artistName != null
+              ? [Artist(itemId: '', provider: '', name: item.artistName!)]
+              : null,
+          metadata: albumMetadata,
+        ));
+
+        if (albums.length >= limit) break;
+      }
+
+      return albums;
+    } catch (e) {
+      _logger.log('⚠️ Failed to get recent albums: $e');
+      return [];
+    }
+  }
+
+  /// Get recently played audiobooks for the current profile
+  /// Returns Audiobook objects reconstructed from local data
+  Future<List<Audiobook>> getRecentAudiobooks({int limit = 20}) async {
+    if (!_db.isInitialized) return [];
+
+    try {
+      final items = await _db.getRecentlyPlayed(limit: limit * 2); // Get more to filter
+
+      // Filter for audiobooks and convert to Audiobook objects
+      final audiobooks = <Audiobook>[];
+      final seenIds = <String>{};
+
+      for (final item in items) {
+        if (item.mediaType != 'audiobook') continue;
+        if (seenIds.contains(item.mediaId)) continue;
+        seenIds.add(item.mediaId);
+
+        Map<String, dynamic>? metadata;
+        if (item.metadata != null) {
+          try {
+            metadata = jsonDecode(item.metadata!) as Map<String, dynamic>;
+          } catch (e) {
+            // Corrupted metadata JSON - log and continue with null metadata
+            _logger.log('⚠️ Error parsing audiobook metadata for ${item.mediaId}: $e');
+          }
+        }
+
+        audiobooks.add(Audiobook(
+          itemId: item.mediaId,
+          provider: metadata?['provider'] ?? 'library',
+          name: item.name,
+          uri: metadata?['uri'],
+          // Create minimal author info from stored name
+          authors: item.artistName != null
+              ? [Artist(itemId: '', provider: '', name: item.artistName!)]
+              : null,
+          duration: metadata?['duration'] != null
+              ? Duration(seconds: metadata!['duration'] as int)
+              : null,
+          resumePositionMs: metadata?['resumePositionMs'] as int?,
+        ));
+
+        if (audiobooks.length >= limit) break;
+      }
+
+      return audiobooks;
+    } catch (e) {
+      _logger.log('⚠️ Failed to get recent audiobooks: $e');
+      return [];
+    }
+  }
+
+  /// Get all recently played items for the current profile
+  Future<List<RecentlyPlayedData>> getRecentlyPlayed({int limit = 20}) async {
+    if (!_db.isInitialized) return [];
+    return _db.getRecentlyPlayed(limit: limit);
+  }
+
+  /// Check if we have local recently played data
+  Future<bool> hasLocalData() async {
+    if (!_db.isInitialized) return false;
+    final items = await _db.getRecentlyPlayed(limit: 1);
+    return items.isNotEmpty;
+  }
+
+  /// Clear recently played for current profile
+  Future<void> clear() async {
+    if (!_db.isInitialized) return;
+    await _db.clearRecentlyPlayed();
+    _logger.log('🗑️ Cleared recently played');
+  }
+}
@@ -0,0 +1,211 @@
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+import 'dart:convert';
+
+/// Service for securely storing sensitive data like passwords and tokens.
+/// Uses platform-specific secure storage (Keychain on iOS, EncryptedSharedPreferences on Android).
+class SecureStorageService {
+  static const _storage = FlutterSecureStorage(
+    aOptions: AndroidOptions(
+      encryptedSharedPreferences: true,
+    ),
+  );
+
+  // Keys for secure storage
+  static const String _keyAuthToken = 'secure_auth_token';
+  static const String _keyMaAuthToken = 'secure_ma_auth_token';
+  static const String _keyAuthCredentials = 'secure_auth_credentials';
+  static const String _keyPassword = 'secure_password';
+  static const String _keyAbsApiToken = 'secure_abs_api_token';
+
+  // Auth Token (for stream requests)
+  static Future<String?> getAuthToken() async {
+    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 {
+    if (token == null || token.isEmpty) {
+      await _storage.delete(key: _keyAuthToken);
+    } else {
+      await _storage.write(key: _keyAuthToken, value: token);
+    }
+  }
+
+  // Music Assistant Native Auth Token (long-lived token)
+  static Future<String?> getMaAuthToken() async {
+    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 {
+    if (token == null || token.isEmpty) {
+      await _storage.delete(key: _keyMaAuthToken);
+    } else {
+      await _storage.write(key: _keyMaAuthToken, value: token);
+    }
+  }
+
+  static Future<void> clearMaAuthToken() async {
+    await _storage.delete(key: _keyMaAuthToken);
+  }
+
+  // Auth Credentials (serialized auth strategy credentials)
+  static Future<Map<String, dynamic>?> getAuthCredentials() async {
+    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>;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  static Future<void> setAuthCredentials(Map<String, dynamic> credentials) async {
+    await _storage.write(key: _keyAuthCredentials, value: jsonEncode(credentials));
+  }
+
+  static Future<void> clearAuthCredentials() async {
+    await _storage.delete(key: _keyAuthCredentials);
+  }
+
+  // Password
+  static Future<String?> getPassword() async {
+    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 {
+    if (password == null || password.isEmpty) {
+      await _storage.delete(key: _keyPassword);
+    } else {
+      await _storage.write(key: _keyPassword, value: password);
+    }
+  }
+
+  // Audiobookshelf API Token
+  static Future<String?> getAbsApiToken() async {
+    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 {
+    if (token == null || token.isEmpty) {
+      await _storage.delete(key: _keyAbsApiToken);
+    } else {
+      await _storage.write(key: _keyAbsApiToken, value: token);
+    }
+  }
+
+  /// Clear all secure storage (used during logout)
+  static Future<void> clearAll() async {
+    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) {
+      await setAuthToken(authToken);
+      await prefs.remove('auth_token');
+    }
+
+    // Migrate MA auth token
+    final maAuthToken = prefs.getString('ma_auth_token');
+    if (maAuthToken != null && maAuthToken.isNotEmpty) {
+      await setMaAuthToken(maAuthToken);
+      await prefs.remove('ma_auth_token');
+    }
+
+    // Migrate auth credentials
+    final authCredentials = prefs.getString('auth_credentials');
+    if (authCredentials != null && authCredentials.isNotEmpty) {
+      try {
+        final decoded = jsonDecode(authCredentials) as Map<String, dynamic>;
+        await setAuthCredentials(decoded);
+        await prefs.remove('auth_credentials');
+      } catch (_) {
+        // Invalid JSON, just remove it
+        await prefs.remove('auth_credentials');
+      }
+    }
+
+    // Migrate password
+    final password = prefs.getString('password');
+    if (password != null && password.isNotEmpty) {
+      await setPassword(password);
+      await prefs.remove('password');
+    }
+
+    // Migrate ABS API token
+    final absApiToken = prefs.getString('abs_api_token');
+    if (absApiToken != null && absApiToken.isNotEmpty) {
+      await setAbsApiToken(absApiToken);
+      await prefs.remove('abs_api_token');
+    }
+
+    // Mark migration as completed to skip on future runs
+    await prefs.setBool(_keyMigrationCompleted, true);
+  }
+}
@@ -0,0 +1,692 @@
+import 'dart:async';
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+import 'package:web_socket_channel/web_socket_channel.dart';
+import 'package:web_socket_channel/io.dart';
+import 'debug_logger.dart';
+import 'settings_service.dart';
+import 'device_id_service.dart';
+
+/// Connection state for Sendspin player
+enum SendspinConnectionState {
+  disconnected,
+  connecting,
+  connected,
+  error,
+}
+
+/// Callback types for Sendspin events
+typedef SendspinPlayCallback = void Function(String streamUrl, Map<String, dynamic> trackInfo);
+typedef SendspinPauseCallback = void Function();
+typedef SendspinStopCallback = void Function();
+typedef SendspinSeekCallback = void Function(int positionSeconds);
+typedef SendspinVolumeCallback = void Function(int volumeLevel);
+typedef SendspinAudioDataCallback = void Function(Uint8List audioData);
+typedef SendspinStreamStartCallback = void Function(Map<String, dynamic>? trackInfo);
+typedef SendspinStreamEndCallback = void Function();
+
+/// Service to manage Sendspin WebSocket connection for local playback
+/// Sendspin is the replacement for builtin_player in MA 2.7.0b20+
+///
+/// Connection strategy (smart fallback for external access):
+/// 1. If server is HTTPS, try external wss://{server}/sendspin first
+/// 2. Fall back to local_ws_url from API (ws://local-ip:8927/sendspin)
+/// 3. WebRTC fallback as last resort (requires TURN servers)
+class SendspinService {
+  final String serverUrl;
+  final _logger = DebugLogger();
+
+  WebSocketChannel? _channel;
+  Timer? _heartbeatTimer;
+  Timer? _reconnectTimer;
+
+  // Connection state
+  SendspinConnectionState _state = SendspinConnectionState.disconnected;
+  SendspinConnectionState get state => _state;
+
+  final _stateController = StreamController<SendspinConnectionState>.broadcast();
+  Stream<SendspinConnectionState> get stateStream => _stateController.stream;
+
+  // Player info
+  String? _playerId;
+  String? _playerName;
+  String? _connectedUrl;
+
+  String? get playerId => _playerId;
+  String? get playerName => _playerName;
+
+  // Event callbacks
+  SendspinPlayCallback? onPlay;
+  SendspinPauseCallback? onPause;
+  SendspinStopCallback? onStop;
+  SendspinSeekCallback? onSeek;
+  SendspinVolumeCallback? onVolume;
+  SendspinAudioDataCallback? onAudioData;
+  SendspinStreamStartCallback? onStreamStart;
+  SendspinStreamEndCallback? onStreamEnd;
+
+  // Audio data stream for raw PCM frames
+  final _audioDataController = StreamController<Uint8List>.broadcast();
+  Stream<Uint8List> get audioDataStream => _audioDataController.stream;
+
+  // Track audio streaming state
+  bool _isStreamingAudio = false;
+  int _audioFramesReceived = 0;
+
+  // Player state for reporting to server
+  bool _isPowered = true;
+  bool _isPlaying = false;
+  bool _isPaused = false;
+  int _position = 0;
+  int _volume = 100;
+  bool _isMuted = false;
+
+  bool _isDisposed = false;
+
+  // Auth token for proxy authentication (MA 2.7.1+)
+  String? _authToken;
+
+  // Connection deduplication guard - prevents multiple concurrent auth attempts
+  Completer<bool>? _connectionInProgress;
+
+  SendspinService(this.serverUrl);
+
+  /// Set the MA auth token for proxy authentication
+  void setAuthToken(String? token) {
+    _authToken = token;
+  }
+
+  /// Initialize and connect to Sendspin server
+  /// Uses persistent player ID and username-based naming
+  Future<bool> connect() async {
+    if (_isDisposed) return false;
+    if (_state == SendspinConnectionState.connected) return true;
+
+    // Deduplicate concurrent connection attempts
+    if (_connectionInProgress != null) {
+      _logger.log('Sendspin: Connection already in progress, waiting...');
+      return _connectionInProgress!.future;
+    }
+    _connectionInProgress = Completer<bool>();
+
+    _updateState(SendspinConnectionState.connecting);
+
+    try {
+      // Get persistent player ID and name
+      _playerId = await DeviceIdService.getOrCreateDevicePlayerId();
+      _playerName = await SettingsService.getLocalPlayerName();
+
+      _logger.log('Sendspin: Connecting as "$_playerName" (ID: $_playerId)');
+
+      // Try connection strategies in order
+      bool connected = false;
+
+      // Strategy 1: If server is HTTPS, try external wss:// first
+      // Use proxy auth for MA 2.7.1+ - the proxy requires authentication before hello
+      if (_isHttpsServer()) {
+        final externalUrl = _buildExternalSendspinUrl();
+        _logger.log('Sendspin: Trying external URL: $externalUrl');
+        connected = await _tryConnect(externalUrl, timeout: const Duration(seconds: 5), useProxyAuth: true);
+      }
+
+      // Note: Local network connections (ws://ip:8927/sendspin) are handled
+      // by the provider calling connectWithUrl() directly, not by this method.
+
+      if (!connected) {
+        _logger.log('Sendspin: External proxy connection failed');
+        _updateState(SendspinConnectionState.error);
+        _connectionInProgress?.complete(false);
+        _connectionInProgress = null;
+        return false;
+      }
+
+      _connectionInProgress?.complete(true);
+      _connectionInProgress = null;
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection error: $e');
+      _updateState(SendspinConnectionState.error);
+      _connectionInProgress?.complete(false);
+      _connectionInProgress = null;
+      return false;
+    }
+  }
+
+  /// Connect with a specific WebSocket URL (called by provider with local_ws_url)
+  Future<bool> connectWithUrl(String wsUrl) async {
+    if (_isDisposed) return false;
+    if (_state == SendspinConnectionState.connected) return true;
+
+    // Deduplicate concurrent connection attempts
+    if (_connectionInProgress != null) {
+      _logger.log('Sendspin: Connection already in progress, waiting...');
+      return _connectionInProgress!.future;
+    }
+    _connectionInProgress = Completer<bool>();
+
+    _updateState(SendspinConnectionState.connecting);
+
+    try {
+      _playerId = await DeviceIdService.getOrCreateDevicePlayerId();
+      _playerName = await SettingsService.getLocalPlayerName();
+
+      _logger.log('Sendspin: Connecting with URL: $wsUrl');
+
+      final connected = await _tryConnect(wsUrl, timeout: const Duration(seconds: 5));
+
+      if (!connected) {
+        _updateState(SendspinConnectionState.error);
+        _connectionInProgress?.complete(false);
+        _connectionInProgress = null;
+        return false;
+      }
+
+      _connectionInProgress?.complete(true);
+      _connectionInProgress = null;
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection error: $e');
+      _updateState(SendspinConnectionState.error);
+      _connectionInProgress?.complete(false);
+      _connectionInProgress = null;
+      return false;
+    }
+  }
+
+  /// Attempt to connect to a specific WebSocket URL
+  /// If useProxyAuth is true and we have an auth token, authenticate first (for MA 2.7.1+ proxy)
+  Future<bool> _tryConnect(String url, {Duration timeout = const Duration(seconds: 5), bool useProxyAuth = false}) async {
+    try {
+      // Connect to the base URL without query params - we send player info in hello message
+      _logger.log('Sendspin: Connecting to $url${useProxyAuth ? ' (with proxy auth)' : ''}');
+
+      // Create WebSocket connection
+      final webSocket = await WebSocket.connect(url).timeout(timeout);
+
+      _channel = IOWebSocketChannel(webSocket);
+      _connectedUrl = url;
+
+      // Set up message listener BEFORE sending hello
+      _channel!.stream.listen(
+        _handleMessage,
+        onError: _handleError,
+        onDone: _handleDone,
+      );
+
+      // If using proxy auth (MA 2.7.1+), authenticate first
+      if (useProxyAuth && _authToken != null) {
+        _logger.log('Sendspin: Sending proxy auth with token');
+        _sendMessage({
+          'type': 'auth',
+          'token': _authToken,
+        }, allowDuringHandshake: true);
+
+        // Wait for auth_ok response
+        final authOk = await _waitForAuth().timeout(
+          const Duration(seconds: 5),
+          onTimeout: () => false,
+        );
+
+        if (!authOk) {
+          _logger.log('Sendspin: Proxy authentication failed or timed out');
+          await _channel?.sink.close();
+          _channel = null;
+          return false;
+        }
+        _logger.log('Sendspin: Proxy auth successful, proceeding with hello');
+      }
+
+      // Send client/hello message immediately after connecting
+      // This is required by the Sendspin protocol - server waits for this
+      // Message format follows aiosendspin protocol spec
+      _logger.log('Sendspin: Sending client/hello with player_id=$_playerId');
+      _sendMessage({
+        'type': 'client/hello',
+        'payload': {
+          'client_id': _playerId,
+          'name': _playerName,
+          'version': 1,  // Protocol version (integer)
+          'supported_roles': ['player@v1'],
+          'player_support': {
+            'supported_formats': [
+              {
+                'codec': 'pcm',
+                'channels': 2,
+                'sample_rate': 48000,
+                'bit_depth': 16,
+              },
+            ],
+            'buffer_capacity': 1048576,  // 1MB buffer
+            'supported_commands': ['volume', 'mute'],
+          },
+        },
+      }, allowDuringHandshake: true);
+
+      // Wait for server acknowledgment (server sends welcome/registered after hello)
+      final ackReceived = await _waitForAck().timeout(
+        const Duration(seconds: 5),
+        onTimeout: () => false,
+      );
+
+      if (!ackReceived) {
+        _logger.log('Sendspin: No acknowledgment from server after hello');
+        await _channel?.sink.close();
+        _channel = null;
+        return false;
+      }
+
+      _logger.log('Sendspin: Connected and registered successfully');
+      _updateState(SendspinConnectionState.connected);
+      _startHeartbeat();
+
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection attempt failed: $e');
+      return false;
+    }
+  }
+
+  /// Wait for server acknowledgment after connection
+  Completer<bool>? _ackCompleter;
+  Completer<bool>? _authCompleter;
+
+  Future<bool> _waitForAck() async {
+    _ackCompleter = Completer<bool>();
+    return _ackCompleter!.future;
+  }
+
+  Future<bool> _waitForAuth() async {
+    _authCompleter = Completer<bool>();
+    return _authCompleter!.future;
+  }
+
+  /// Handle incoming WebSocket messages
+  /// WebSocket can send text frames (JSON control messages) or binary frames (PCM audio data)
+  void _handleMessage(dynamic message) {
+    // Check if this is binary audio data (Uint8List) or text (String)
+    if (message is List<int>) {
+      _handleBinaryAudioData(Uint8List.fromList(message));
+      return;
+    }
+
+    // Handle text messages (JSON)
+    if (message is! String) {
+      _logger.log('Sendspin: Unexpected message type: ${message.runtimeType}');
+      return;
+    }
+
+    try {
+      final data = jsonDecode(message) as Map<String, dynamic>;
+      final type = data['type'] as String?;
+
+      _logger.log('Sendspin: Received message type: $type');
+
+      switch (type) {
+        case 'server/hello':
+          // Server acknowledged our client/hello - we're registered!
+          _logger.log('Sendspin: Received server/hello - connection successful');
+          final payload = data['payload'] as Map<String, dynamic>?;
+          if (payload != null) {
+            _logger.log('Sendspin: Server name: ${payload['name']}, version: ${payload['version']}');
+            _logger.log('Sendspin: Active roles: ${payload['active_roles']}');
+          }
+          if (_ackCompleter != null && !_ackCompleter!.isCompleted) {
+            _ackCompleter!.complete(true);
+          }
+          // Send initial client/state immediately after handshake (required by spec)
+          // Note: These must use allowDuringHandshake since state is still 'connecting'
+          _sendInitialState();
+          // Also send initial time sync
+          _sendClientTime(allowDuringHandshake: true);
+          break;
+
+        case 'server/time':
+          // Server responded to our time sync - can be used to calculate clock offset
+          // For now, just log it (proper sync would use Kalman filter)
+          _logger.log('Sendspin: Received server/time response');
+          break;
+
+        case 'group/update':
+          // Group state update - store for reference but no response needed
+          _logger.log('Sendspin: Received group/update');
+          final groupPayload = data['payload'] as Map<String, dynamic>?;
+          if (groupPayload != null) {
+            _logger.log('Sendspin: Group state: ${groupPayload['playback_state']}');
+          }
+          break;
+
+        case 'stream/start':
+          // Server is starting to send audio data
+          _logger.log('Sendspin: Audio stream starting');
+          _isStreamingAudio = true;
+          _audioFramesReceived = 0;
+          _isPlaying = true;
+          _isPaused = false;
+          // Notify provider to start PCM player and foreground service
+          final streamPayload = data['payload'] as Map<String, dynamic>?;
+          onStreamStart?.call(streamPayload);
+          break;
+
+        case 'stream/end':
+          // Server finished sending audio data
+          _logger.log('Sendspin: Audio stream ended (received $_audioFramesReceived frames)');
+          _isStreamingAudio = false;
+          _isPlaying = false;
+          // Notify provider to stop PCM player
+          onStreamEnd?.call();
+          break;
+
+        case 'auth_ok':
+          // Proxy authentication successful (MA 2.7.1+)
+          _logger.log('Sendspin: Proxy authentication successful');
+          if (_authCompleter != null && !_authCompleter!.isCompleted) {
+            _authCompleter!.complete(true);
+          }
+          break;
+
+        case 'ack':
+        case 'connected':
+        case 'registered':
+          // Legacy/fallback acknowledgment types
+          if (_ackCompleter != null && !_ackCompleter!.isCompleted) {
+            _ackCompleter!.complete(true);
+          }
+          break;
+
+        case 'play':
+          // Server wants us to play audio (URL-based, not raw PCM)
+          final streamUrl = data['url'] as String?;
+          final trackInfo = data['track'] as Map<String, dynamic>? ?? {};
+          if (streamUrl != null && onPlay != null) {
+            _isPlaying = true;
+            _isPaused = false;
+            onPlay!(streamUrl, trackInfo);
+          }
+          break;
+
+        case 'pause':
+          _isPaused = true;
+          _isPlaying = false;
+          onPause?.call();
+          break;
+
+        case 'stop':
+          _isPlaying = false;
+          _isPaused = false;
+          _isStreamingAudio = false;
+          onStop?.call();
+          break;
+
+        case 'seek':
+          final position = data['position'] as int?;
+          if (position != null) {
+            _position = position;
+            onSeek?.call(position);
+          }
+          break;
+
+        case 'volume':
+          final level = data['level'] as int?;
+          if (level != null) {
+            _volume = level;
+            onVolume?.call(level);
+          }
+          break;
+
+        case 'ping':
+          // Respond to server ping
+          _sendMessage({'type': 'pong'});
+          break;
+
+        case 'error':
+          final errorMsg = data['message'] as String?;
+          _logger.log('Sendspin: Server error: $errorMsg');
+          break;
+
+        default:
+          _logger.log('Sendspin: Unknown message type: $type');
+      }
+    } catch (e) {
+      _logger.log('Sendspin: Error handling JSON message: $e');
+    }
+  }
+
+  /// Handle binary audio data (PCM frames from server)
+  /// Sendspin binary frame format:
+  /// - Byte 0: message type (uint8) - Type 4 = audio data
+  /// - Bytes 1-8: timestamp (int64 microseconds, little-endian) for synchronization
+  /// - Bytes 9+: actual PCM audio data (16-bit stereo 48kHz)
+  void _handleBinaryAudioData(Uint8List frame) {
+    // Minimum frame size: 1 (type) + 8 (timestamp) + 2 (at least one sample)
+    if (frame.length < 11) {
+      _logger.log('Sendspin: Binary frame too short: ${frame.length} bytes');
+      return;
+    }
+
+    // Parse header
+    final messageType = frame[0];
+
+    // Type 4 = audio data, other types may be used for other purposes
+    if (messageType != 4) {
+      _logger.log('Sendspin: Unexpected binary message type: $messageType');
+      return;
+    }
+
+    // Extract timestamp (bytes 1-8, little-endian int64)
+    final timestampBytes = ByteData.sublistView(frame, 1, 9);
+    final timestamp = timestampBytes.getInt64(0, Endian.little);
+
+    // Extract actual PCM audio data (everything after the 9-byte header)
+    final audioData = Uint8List.sublistView(frame, 9);
+
+    _audioFramesReceived++;
+
+    // Log periodically to avoid spam
+    if (_audioFramesReceived == 1) {
+      _logger.log('Sendspin: Receiving audio data (first frame: ${frame.length} bytes, audio: ${audioData.length} bytes, ts: $timestamp)');
+    } else if (_audioFramesReceived % 100 == 0) {
+      _logger.log('Sendspin: Received $_audioFramesReceived audio frames');
+    }
+
+    // Emit only the PCM audio data (without header) to stream for consumers
+    if (!_audioDataController.isClosed) {
+      _audioDataController.add(audioData);
+    }
+
+    // Call callback if registered
+    onAudioData?.call(audioData);
+  }
+
+  /// Handle WebSocket errors
+  void _handleError(dynamic error) {
+    _logger.log('Sendspin: WebSocket error: $error');
+    _updateState(SendspinConnectionState.error);
+    _scheduleReconnect();
+  }
+
+  /// Handle WebSocket close
+  void _handleDone() {
+    _logger.log('Sendspin: WebSocket closed');
+    _updateState(SendspinConnectionState.disconnected);
+    _scheduleReconnect();
+  }
+
+  /// Send a JSON message to the server
+  /// allowDuringHandshake: set to true to send messages before connection is established (e.g., hello)
+  void _sendMessage(Map<String, dynamic> message, {bool allowDuringHandshake = false}) {
+    if (_channel == null) return;
+
+    // During handshake, we need to send hello even though state is still 'connecting'
+    if (!allowDuringHandshake && _state != SendspinConnectionState.connected) return;
+
+    try {
+      final json = jsonEncode(message);
+      _logger.log('Sendspin: Sending message: ${message['type']}');
+      _channel!.sink.add(json);
+    } catch (e) {
+      _logger.log('Sendspin: Error sending message: $e');
+    }
+  }
+
+  /// Report current player state to server
+  /// Uses Sendspin protocol 'client/state' message format
+  void reportState({
+    bool? powered,
+    bool? playing,
+    bool? paused,
+    int? position,
+    int? volume,
+    bool? muted,
+  }) {
+    if (powered != null) _isPowered = powered;
+    if (playing != null) _isPlaying = playing;
+    if (paused != null) _isPaused = paused;
+    if (position != null) _position = position;
+    if (volume != null) _volume = volume;
+    if (muted != null) _isMuted = muted;
+
+    // Determine player state for Sendspin protocol
+    // Valid values: 'synchronized', 'error', 'external_source'
+    // When connected, we're always synchronized (ready to receive audio)
+    const playerState = 'synchronized';
+
+    _sendMessage({
+      'type': 'client/state',
+      'payload': {
+        'player': {
+          'state': playerState,
+          'volume': _volume,
+          'muted': _isMuted,
+        },
+      },
+    });
+  }
+
+  /// Check if server URL is HTTPS
+  bool _isHttpsServer() {
+    return serverUrl.startsWith('https://') ||
+           serverUrl.startsWith('wss://') ||
+           (!serverUrl.contains('://') && !serverUrl.contains(':'));
+  }
+
+  /// Build external Sendspin WebSocket URL from server URL
+  String _buildExternalSendspinUrl() {
+    var url = serverUrl;
+
+    // Convert HTTP(S) to WS(S)
+    if (url.startsWith('https://')) {
+      url = 'wss://${url.substring(8)}';
+    } else if (url.startsWith('http://')) {
+      url = 'ws://${url.substring(7)}';
+    } else if (!url.startsWith('ws://') && !url.startsWith('wss://')) {
+      url = 'wss://$url';
+    }
+
+    // Remove trailing slash and add /sendspin path
+    url = url.replaceAll(RegExp(r'/+$'), '');
+
+    // Remove any existing path and add /sendspin
+    final uri = Uri.parse(url);
+    return Uri(
+      scheme: uri.scheme,
+      host: uri.host,
+      port: uri.hasPort ? uri.port : null,
+      path: '/sendspin',
+    ).toString();
+  }
+
+  /// Start heartbeat timer using Sendspin's client/time for clock synchronization
+  void _startHeartbeat() {
+    _stopHeartbeat();
+    _heartbeatTimer = Timer.periodic(const Duration(seconds: 30), (_) {
+      _sendClientTime();
+    });
+  }
+
+  /// Send client/time message for clock synchronization (Sendspin protocol)
+  void _sendClientTime({bool allowDuringHandshake = false}) {
+    final timestampMicroseconds = DateTime.now().microsecondsSinceEpoch;
+    _sendMessage({
+      'type': 'client/time',
+      'payload': {
+        'client_transmitted': timestampMicroseconds,
+      },
+    }, allowDuringHandshake: allowDuringHandshake);
+  }
+
+  /// Send initial client/state immediately after handshake (required by Sendspin spec)
+  /// Must use allowDuringHandshake since state is still 'connecting' at this point
+  void _sendInitialState() {
+    _logger.log('Sendspin: Sending initial client/state');
+    _sendMessage({
+      'type': 'client/state',
+      'payload': {
+        'player': {
+          'state': 'synchronized',
+          'volume': _volume,
+          'muted': _isMuted,
+        },
+      },
+    }, allowDuringHandshake: true);
+  }
+
+  /// Stop heartbeat timer
+  void _stopHeartbeat() {
+    _heartbeatTimer?.cancel();
+    _heartbeatTimer = null;
+  }
+
+  /// Schedule reconnection attempt
+  void _scheduleReconnect() {
+    if (_isDisposed) return;
+
+    _reconnectTimer?.cancel();
+    _reconnectTimer = Timer(const Duration(seconds: 5), () {
+      if (!_isDisposed && _state != SendspinConnectionState.connected) {
+        _logger.log('Sendspin: Attempting reconnection...');
+        if (_connectedUrl != null) {
+          connectWithUrl(_connectedUrl!);
+        }
+      }
+    });
+  }
+
+  /// Update connection state
+  void _updateState(SendspinConnectionState newState) {
+    if (_state != newState) {
+      _state = newState;
+      _stateController.add(newState);
+    }
+  }
+
+  /// Disconnect from server using Sendspin's client/goodbye message
+  Future<void> disconnect() async {
+    _stopHeartbeat();
+    _reconnectTimer?.cancel();
+
+    if (_channel != null) {
+      // Send graceful goodbye per Sendspin protocol
+      _sendMessage({
+        'type': 'client/goodbye',
+        'payload': {
+          'reason': 'user_request',
+        },
+      });
+      await _channel!.sink.close();
+      _channel = null;
+    }
+
+    _updateState(SendspinConnectionState.disconnected);
+  }
+
+  /// Dispose the service
+  void dispose() {
+    _isDisposed = true;
+    _stopHeartbeat();
+    _reconnectTimer?.cancel();
+    _channel?.sink.close();
+    _stateController.close();
+    _audioDataController.close();
+  }
+}
--- a/Show More
+++ b/Show More