Bump version to 2.7.0-beta+30 for release

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.github/workflows/build-apk.yml

@@ -4,10 +4,13 @@ on:
   push:
     branches:
       - main
+      - master
       - 'claude/**'
+      - 'feature/**'
   pull_request:
     branches:
       - main
+      - master
   workflow_dispatch:
 
 jobs:
@@ -34,21 +37,40 @@ jobs:
 
       - 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
-        
+
       - name: Analyze code
         run: flutter analyze
         continue-on-error: true
 
+      - name: Setup signing keystore
+        run: |
+          # Decode keystore from secret (persistent key for consistent signatures)
+          echo "${{ secrets.KEYSTORE_BASE64 }}" | base64 -d > android/app/upload-keystore.jks
+
+          # Create key.properties file
+          cat > android/key.properties << EOF
+          storePassword=${{ secrets.KEYSTORE_PASSWORD }}
+          keyPassword=${{ secrets.KEY_PASSWORD }}
+          keyAlias=${{ secrets.KEY_ALIAS }}
+          storeFile=upload-keystore.jks
+          EOF
+
       - name: Build APK
         run: flutter build apk --release
 
       - name: Upload APK artifact
         uses: actions/upload-artifact@v4
         with:
-          name: amass-apk
+          name: ensemble-apk
           path: build/app/outputs/flutter-apk/app-release.apk
           retention-days: 30
 

ARCHITECTURE.md

@@ -1,429 +0,0 @@
-# Music Assistant Mobile - Architecture Documentation
-
-## Overview
-
-Music Assistant Mobile is a Flutter application that connects to a [Music Assistant](https://music-assistant.io/) server to browse and control music playback across various devices and players.
-
-## Architecture Pattern
-
-The app follows the **Provider pattern** for state management with a **layered architecture**:
-
-```
-┌─────────────────────────────────────┐
-│         Presentation Layer          │
-│    (Screens, Widgets, UI Logic)     │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│         State Management            │
-│    (Providers - Business Logic)     │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│         Service Layer               │
-│  (API, Auth, Audio, Settings, etc)  │
-└──────────────┬──────────────────────┘
-               │
-┌──────────────┴──────────────────────┐
-│         Data Layer                  │
-│      (Models, DTOs)                 │
-└─────────────────────────────────────┘
-```
-
-## Key Components
-
-### 1. Providers (`lib/providers/`)
-
-**MusicAssistantProvider** - Central state manager
-- Manages WebSocket connection to Music Assistant server
-- Handles authentication and auto-login
-- Maintains library state (artists, albums, tracks)
-- Manages player selection and playback state
-- Implements player list caching (5-minute cache)
-- Polls selected player state every 2 seconds
-
-**MusicPlayerProvider** - Local audio playback (deprecated)
-- Legacy local playback using just_audio
-- Being phased out in favor of server-side playback control
-
-### 2. Services (`lib/services/`)
-
-**MusicAssistantAPI** - WebSocket API client
-- Connects to Music Assistant server via WebSocket
-- Implements JSON-RPC message protocol
-- Handles server info, events, and command responses
-- Provides methods for:
-  - Library browsing (artists, albums, tracks, playlists)
-  - Search functionality
-  - Player control and queue management
-  - Built-in player registration
-  - Stream URL generation
-
-**AuthService** - Authentication management
-- Handles Authelia authentication (separate auth domain)
-- Stores and retrieves session cookies
-- Auto-login with saved credentials
-
-**SettingsService** - Persistent settings
-- Uses `shared_preferences` for local storage
-- Stores:
-  - Server URL and WebSocket port
-  - Username and password (encrypted)
-  - Built-in player ID
-  - Authentication token
-
-**AudioPlayerService** - Local audio playback
-- Wraps `just_audio` for audio playback
-- Handles play, pause, stop, seek operations
-- Currently used for built-in player mode
-
-**BuiltinPlayerService** - Server push events
-- Listens to built-in player events from server
-- Handles QUEUE_ITEMS, PLAY_MEDIA, STOP, etc.
-- Coordinates with AudioPlayerService
-
-**DebugLogger** - Logging utility
-- Prints timestamped debug logs
-- Helps troubleshooting and development
-
-### 3. Models (`lib/models/`)
-
-**MediaItem** - Base class for media entities
-- `Artist` - Artist metadata
-- `Album` - Album metadata with artists
-- `Track` - Track metadata with artists and album
-- All include provider mappings and metadata
-
-**Player** - Music Assistant player
-- Player ID, name, state (idle/playing/paused)
-- Availability and power status
-- Derived `isPlaying` getter
-
-**PlayerQueue** - Player queue state
-- List of `QueueItem`
-- Current index/item
-- Player ID
-
-**QueueItem** - Item in player queue
-- Queue item ID
-- Track metadata
-- Stream details (sample rate, bit depth, content type)
-
-**BuiltinPlayerEvent** - Server push events
-- Event type (QUEUE_ITEMS, PLAY_MEDIA, etc.)
-- Event data payload
-
-### 4. Screens (`lib/screens/`)
-
-**Navigation Flow:**
-```
-MainLayout (Bottom Navigation)
-├── NewHomeScreen
-│   ├── LibraryStats
-│   ├── AlbumRow (Recent, Random, All)
-│   └── SearchScreen (via app bar)
-├── NewLibraryScreen
-│   ├── LibraryArtistsScreen (with pull-to-refresh)
-│   ├── LibraryAlbumsScreen (with pull-to-refresh)
-│   └── LibraryTracksScreen
-└── SettingsScreen
-```
-
-**Detail Screens:**
-- `ArtistDetailsScreen` - Artist albums
-- `AlbumDetailsScreen` - Album tracks with play button
-- `PlayerScreen` - Full player view
-- `QueueScreen` - Queue management (reorder, remove)
-- `SearchScreen` - Global search (artists, albums, tracks)
-
-### 5. Widgets (`lib/widgets/`)
-
-**Reusable Components:**
-- `MiniPlayer` - Bottom now playing bar
-- `PlayerSelector` - Device/player picker
-- `AlbumRow` - Horizontal scrolling album list
-- `LibraryStats` - Library statistics card
-- `PlayerControls` - Playback controls (deprecated)
-
-## Data Flow
-
-### Player Selection & Control
-
-```
-User selects player → PlayerSelector widget
-                    ↓
-        MusicAssistantProvider.selectPlayer()
-                    ↓
-        Starts player state polling (every 2s)
-                    ↓
-        Fetches queue via getQueue()
-                    ↓
-        Updates currentTrack
-                    ↓
-        MiniPlayer displays track info
-```
-
-### Music Playback
-
-```
-User plays album → AlbumDetailsScreen._playAlbum()
-                ↓
-        MusicAssistantProvider.playTracks()
-                ↓
-        API: player_queues/play_media
-                ↓
-        Server queues tracks on selected player
-                ↓
-        Player state polling updates UI
-```
-
-### Library Loading
-
-```
-App connects → MusicAssistantProvider._initialize()
-             ↓
-         connectToServer()
-             ↓
-         WebSocket connection established
-             ↓
-         loadLibrary() (auto-triggered)
-             ↓
-         Fetches artists, albums, tracks (limit: 100 each)
-             ↓
-         notifyListeners() → UI updates
-```
-
-## API Integration
-
-### WebSocket Commands
-
-The app uses Music Assistant's WebSocket JSON-RPC API:
-
-**Library:**
-- `music/artists/library_items` - Get artists
-- `music/albums/library_items` - Get albums
-- `music/tracks/library_items` - Get tracks
-- `music/search` - Search all media types
-
-**Playback Control:**
-- `player_queues/play_media` - Queue and play tracks
-- `player_command/play` - Resume playback
-- `player_command/pause` - Pause playback
-- `player_command/next` - Next track
-- `player_command/previous` - Previous track
-
-**Queue Management:**
-- `player_queues/items` - Get queue items (returns List, not object)
-
-**Players:**
-- `players/all` - Get all available players
-
-**Built-in Player:**
-- `builtin_player/register` - Register device as player
-- `builtin_player/update_state` - Update player state
-
-### Event Subscriptions
-
-The WebSocket connection receives real-time events:
-- `player_updated` - Player state changed
-- `queue_updated` - Queue modified
-- `queue_items_updated` - Queue items changed
-- `media_item_played` - Track started playing
-- `builtin_player` - Built-in player event (QUEUE_ITEMS, PLAY_MEDIA, etc.)
-
-## Performance Optimizations
-
-### 1. Player List Caching
-- Cache player list for 5 minutes
-- Reduces API calls on player selector opens
-- Force refresh available via `refreshPlayers()`
-
-### 2. Debounced Search
-- 500ms debounce on search input
-- Prevents excessive API calls while typing
-
-### 3. Pagination
-- Library loads with limit (default: 100)
-- Can be extended for infinite scroll
-
-### 4. Image Loading
-- NetworkImage with error handling
-- Fallback to icon on load failure
-- Size parameter for different image resolutions
-
-## State Management Pattern
-
-```dart
-// Provider pattern example
-class MusicAssistantProvider with ChangeNotifier {
-  List<Album> _albums = [];
-
-  List<Album> get albums => _albums;
-
-  Future<void> loadAlbums() async {
-    _albums = await _api.getAlbums();
-    notifyListeners(); // Triggers UI rebuild
-  }
-}
-
-// Widget consumption
-class AlbumList extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    final provider = context.watch<MusicAssistantProvider>();
-    return ListView(
-      children: provider.albums.map((album) => AlbumTile(album)).toList(),
-    );
-  }
-}
-```
-
-## Authentication Flow
-
-### Authelia Integration
-
-Music Assistant Mobile supports Authelia authentication on separate domains:
-
-```
-1. User enters credentials in SettingsScreen
-           ↓
-2. AuthService.login(serverUrl, username, password)
-           ↓
-3. POST to auth.serverscloud.org
-           ↓
-4. Extract authelia_session cookie
-           ↓
-5. Store cookie in SettingsService
-           ↓
-6. Include cookie in WebSocket handshake
-           ↓
-7. WebSocket: headers['Cookie'] = 'authelia_session=...'
-```
-
-### Auto-Login
-
-On app startup:
-1. Check for saved credentials
-2. If found, attempt silent login
-3. On success, connect to Music Assistant server
-4. On failure, user can re-enter credentials
-
-## Error Handling
-
-### API Errors
-- Try-catch blocks around all API calls
-- Errors logged via DebugLogger
-- UI shows error states (empty states, snackbars)
-
-### WebSocket Reconnection
-- Auto-reconnect on disconnect (3-second delay)
-- Connection state tracked via Stream
-- UI reflects connection status
-
-### Queue Parsing Errors
-- Defensive parsing with try-catch per item
-- Failed items skipped, parsing continues
-- Debug logging for troubleshooting
-
-## Testing Strategy
-
-### Unit Tests (TODO)
-- API service methods
-- Model parsing (fromJson/toJson)
-- State management logic
-
-### Widget Tests (TODO)
-- Screen rendering
-- User interactions
-- Navigation flows
-
-### Integration Tests (TODO)
-- End-to-end user flows
-- WebSocket communication
-- Authentication
-
-## Future Enhancements
-
-### Planned Features
-1. **Playlists** - Browse and play playlists
-2. **Favorites** - Mark/unmark favorites, filter by favorites
-3. **Lyrics** - Display lyrics for current track
-4. **Sleep Timer** - Auto-stop playback
-5. **Crossfade** - Smooth transitions between tracks
-6. **Equalizer** - Audio customization
-7. **Offline Mode** - Cached playback
-8. **Android Auto / CarPlay** - In-car integration
-
-### Technical Improvements
-1. **Retry Logic** - Exponential backoff for failed requests
-2. **Better Error Messages** - User-friendly error descriptions
-3. **Loading States** - Skeleton screens, shimmer effects
-4. **Infinite Scroll** - Lazy load library items
-5. **Image Caching** - Reduce network usage
-6. **WebSocket Reconnection** - Smarter reconnection strategy
-
-## Development Guidelines
-
-### Code Style
-- Follow [Effective Dart](https://dart.dev/guides/language/effective-dart)
-- Use meaningful variable names
-- Add comments for complex logic
-- Keep functions small and focused
-
-### File Organization
-```
-lib/
-├── main.dart                 # App entry point
-├── models/                   # Data models
-├── providers/                # State management
-├── screens/                  # Full-screen views
-├── widgets/                  # Reusable components
-└── services/                 # Business logic, API, utilities
-```
-
-### Adding New Features
-
-1. **Define Model** (if needed) - Add to `lib/models/`
-2. **Create API Method** - Add to `MusicAssistantAPI`
-3. **Update Provider** - Add state and methods to relevant provider
-4. **Build UI** - Create screen/widget in `lib/screens/` or `lib/widgets/`
-5. **Wire Navigation** - Update navigation logic
-6. **Test** - Write unit/widget tests
-7. **Document** - Update this file and add code comments
-
-### Debugging Tips
-
-1. **Enable Debug Logging** - DebugLogger prints to console
-2. **Check WebSocket Messages** - Logs show all WS traffic
-3. **Inspect Provider State** - Use Flutter DevTools
-4. **Network Debugging** - Check API responses
-5. **Test Authentication** - Verify session cookies
-
-## Dependencies
-
-### Core
-- `flutter` - UI framework
-- `provider` - State management
-- `web_socket_channel` - WebSocket client
-
-### Audio
-- `just_audio` - Audio playback
-- `audio_service` - Background playback
-
-### Networking
-- `http` - HTTP requests
-- `uuid` - Unique ID generation
-
-### Storage
-- `shared_preferences` - Local key-value storage
-
-### UI
-- `flutter_launcher_icons` - App icons
-
-## Resources
-
-- **Music Assistant**: https://music-assistant.io/
-- **Music Assistant API Docs**: https://music-assistant.io/integration/websocket/
-- **Flutter Docs**: https://docs.flutter.dev/
-- **Provider Package**: https://pub.dev/packages/provider
-- **just_audio Package**: https://pub.dev/packages/just_audio

OVERNIGHT_WORK_SUMMARY.md

@@ -1,472 +0,0 @@
-# Overnight Work Session Summary
-
-## Session Overview
-
-This document summarizes all improvements and features added to the Music Assistant Mobile app during the comprehensive overnight development session.
-
-**Session Date:** 2025-01-22
-**Total Commits:** 9
-**Files Changed:** 20+
-**Lines Added:** 1,500+
-
----
-
-## ✅ Completed Tasks
-
-### 1. Now Playing Bar Debugging & Fixes
-
-**Problem:** Now playing bar wasn't showing even when music was playing
-
-**Solution:**
-- Fixed queue endpoint from `players/queue/items` to `player_queues/items`
-- Changed parameter from `player_id` to `queue_id` to match API format
-- Added defensive parsing for queue items with try-catch per item
-- Added debug logging to inspect raw queue data structure
-- Fixed QueueItem parsing to handle missing `queue_item_id` field (fallback to `item_id`)
-
-**Files Modified:**
-- `lib/services/music_assistant_api.dart`
-- `lib/models/player.dart`
-
-**Impact:** Now playing bar now correctly shows current track when music is playing on any selected player.
-
----
-
-### 2. Home Page Enhancements
-
-**Added Features:**
-- **Recent Albums Row** - Shows recently played albums
-- **Random Albums Row** ("Discover") - Displays random albums for music discovery
-- **Library Statistics** - Visual card showing artists/albums/tracks counts
-- **Improved Layout** - Better spacing and visual hierarchy
-
-**New API Methods:**
-```dart
-Future<List<Album>> getRecentAlbums({int limit = 10})
-Future<List<Album>> getRandomAlbums({int limit = 10})
-Future<Map<String, int>> getLibraryStats()
-```
-
-**New Widgets:**
-- `lib/widgets/album_row.dart` - Horizontal scrolling album list
-- `lib/widgets/library_stats.dart` - Statistics display card
-
-**Files Modified:**
-- `lib/screens/new_home_screen.dart`
-- `lib/services/music_assistant_api.dart`
-
-**Impact:** Home screen is now much more engaging with personalized content and discovery features.
-
----
-
-### 3. Global Search Functionality
-
-**Added:**
-- Search button in home and library screen app bars
-- Navigation to existing SearchScreen
-- Quick access to search from main navigation
-
-**Files Modified:**
-- `lib/screens/new_home_screen.dart`
-- `lib/screens/new_library_screen.dart`
-
-**Impact:** Users can now easily search their entire music library from any main screen.
-
----
-
-### 4. Queue Viewer Screen
-
-**Features:**
-- Full-screen queue management
-- Display all queued tracks with album art
-- Reorder tracks via drag and drop
-- Remove tracks via swipe to dismiss
-- Visual indicator for currently playing track
-- Refresh button to reload queue
-- Queue button in mini-player for easy access
-
-**New Files:**
-- `lib/screens/queue_screen.dart`
-
-**Files Modified:**
-- `lib/widgets/mini_player.dart`
-
-**Impact:** Users can now see and manage their playback queue with intuitive gestures.
-
-**Note:** Reordering and removing are currently local-only (server sync not yet implemented).
-
----
-
-### 5. Pull-to-Refresh on Library Screens
-
-**Added:**
-- RefreshIndicator on artists list
-- RefreshIndicator on albums grid
-- Triggers library reload on pull-down gesture
-
-**Files Modified:**
-- `lib/screens/library_artists_screen.dart`
-- `lib/screens/library_albums_screen.dart`
-
-**Impact:** Better UX for refreshing library data without navigating away.
-
----
-
-### 6. Player List Caching
-
-**Optimization:**
-- Cache player list for 5 minutes
-- Reduce API calls when opening player selector
-- Force refresh available via explicit refresh
-- Automatic cache invalidation after timeout
-
-**Implementation:**
-```dart
-DateTime? _playersLastFetched;
-static const Duration _playersCacheDuration = Duration(minutes: 5);
-
-Future<void> _loadAndSelectPlayers({bool forceRefresh = false}) {
-  // Check cache first
-  if (!forceRefresh && cache_valid) {
-    return cached_players;
-  }
-  // Fetch fresh data
-}
-```
-
-**Files Modified:**
-- `lib/providers/music_assistant_provider.dart`
-
-**Impact:** Reduced network traffic and improved app responsiveness when switching players.
-
----
-
-### 7. Comprehensive Documentation
-
-**Created:**
-
-#### ARCHITECTURE.md (600+ lines)
-- Complete architecture overview
-- Component descriptions and responsibilities
-- Data flow diagrams
-- API integration details
-- Performance optimizations
-- Development guidelines
-- Future enhancement roadmap
-
-**Sections:**
-- Architecture Pattern
-- Key Components (Providers, Services, Models, Screens, Widgets)
-- Data Flow (Player Selection, Music Playback, Library Loading)
-- API Integration (WebSocket Commands, Event Subscriptions)
-- Performance Optimizations
-- State Management Pattern
-- Authentication Flow
-- Error Handling
-- Testing Strategy
-- Development Guidelines
-
-#### TROUBLESHOOTING.md (500+ lines)
-- Common issues and solutions
-- Debug logging instructions
-- Performance troubleshooting
-- Bug reporting templates
-- FAQ section
-
-**Sections:**
-- Connection Issues
-- Authentication Issues
-- Playback Issues
-- Library Issues
-- Queue Issues
-- Performance Issues
-- UI Issues
-- Debug Logging
-- Known Limitations
-- Advanced Troubleshooting
-- Getting Help
-- FAQ
-
-**Impact:** Future development and debugging will be much easier with comprehensive documentation.
-
----
-
-## 📊 Statistics
-
-### Commits Summary
-
-1. `965bf9d` - Add defensive parsing and debug logging for queue items
-2. `38b29cb` - Add home page enhancements (albums, stats)
-3. `6c291f7` - Add search functionality to main screens
-4. `ad4136f` - Add queue viewer screen
-5. `4f7856e` - Add pull-to-refresh to library screens
-6. `e24b542` - Add player list caching
-7. `0422752` - Add comprehensive documentation
-
-### Files Created
-
-**Screens:**
-- (queue_screen.dart already existed, enhanced it)
-
-**Widgets:**
-- `lib/widgets/album_row.dart`
-- `lib/widgets/library_stats.dart`
-
-**Documentation:**
-- `ARCHITECTURE.md`
-- `TROUBLESHOOTING.md`
-
-### Files Modified
-
-**Screens:**
-- `lib/screens/new_home_screen.dart`
-- `lib/screens/new_library_screen.dart`
-- `lib/screens/library_artists_screen.dart`
-- `lib/screens/library_albums_screen.dart`
-
-**Widgets:**
-- `lib/widgets/mini_player.dart`
-
-**Services:**
-- `lib/services/music_assistant_api.dart`
-
-**Providers:**
-- `lib/providers/music_assistant_provider.dart`
-
-**Models:**
-- `lib/models/player.dart`
-
----
-
-## 🎯 Key Improvements
-
-### User Experience
-- ✅ Now playing bar actually works
-- ✅ Engaging home screen with discovery features
-- ✅ Easy search access from anywhere
-- ✅ Full queue management capabilities
-- ✅ Pull-to-refresh for better control
-- ✅ Faster player selection with caching
-
-### Developer Experience
-- ✅ Comprehensive architecture documentation
-- ✅ Detailed troubleshooting guide
-- ✅ Better error handling
-- ✅ Debug logging throughout
-- ✅ Clear code structure
-- ✅ Development guidelines
-
-### Performance
-- ✅ Player list caching (5-minute cache)
-- ✅ Defensive parsing (continues on errors)
-- ✅ Reduced API calls
-- ✅ Better state management
-
----
-
-## 🔄 Features NOT Implemented
-
-Due to time constraints, the following planned features were not implemented:
-
-### High Priority (Should do next)
-1. **Retry Logic** - Exponential backoff for failed API calls
-2. **Playlist Support** - Browse and play playlists
-3. **Favorites System** - Mark/filter favorites
-
-### Medium Priority
-4. **Loading States** - Skeleton screens, shimmer effects
-5. **Better Error Messages** - User-friendly error descriptions
-6. **Unit Tests** - API layer testing
-
-### Why Not Done
-- Focus was on getting core features working (now playing bar, home page, queue)
-- Documentation was prioritized for long-term value
-- User-facing features were chosen over technical improvements
-- Time better spent on visible improvements
-
----
-
-## 🐛 Known Issues
-
-### Minor Issues
-1. **Queue Reordering** - Changes are local-only, don't sync to server
-   - **Workaround:** Use Music Assistant web interface for persistent changes
-   - **Fix Required:** Implement server API calls for queue manipulation
-
-2. **Library Pagination** - Only loads 100 items per category
-   - **Workaround:** Use search to find specific items
-   - **Fix Required:** Implement infinite scroll
-
-3. **Player State Polling** - Polls every 2 seconds
-   - **Impact:** Slight battery drain
-   - **Fix Required:** Switch to event-based updates
-
-### Fixed Issues
-- ✅ Now playing bar not showing - FIXED
-- ✅ Queue endpoint errors - FIXED
-- ✅ Queue item parsing failures - FIXED
-- ✅ Player list fetching on every open - FIXED (caching)
-
----
-
-## 💡 Recommendations for Next Session
-
-### Immediate Next Steps
-
-1. **Test Everything**
-   - Thoroughly test all new features
-   - Verify now playing bar works reliably
-   - Test queue viewer on different players
-   - Validate home page album rows
-
-2. **Fix Any Bugs Found**
-   - Monitor debug logs for errors
-   - Address any parsing issues
-   - Fix UI glitches
-
-3. **Implement Retry Logic**
-   - Add exponential backoff for failed requests
-   - Improve error handling
-   - Better user feedback on failures
-
-4. **Add Playlist Support**
-   - List playlists from server
-   - Play playlists
-   - Add to queue
-
-5. **Implement Favorites**
-   - Mark items as favorites
-   - Filter by favorites
-   - Sync with server
-
-### Code Quality Improvements
-
-1. **Add Unit Tests**
-   - Test API parsing
-   - Test state management
-   - Test model serialization
-
-2. **Improve Loading States**
-   - Add skeleton screens
-   - Better loading indicators
-   - Smooth transitions
-
-3. **Better Error Handling**
-   - User-friendly error messages
-   - Retry buttons
-   - Offline state handling
-
-### User Experience Enhancements
-
-1. **Infinite Scroll**
-   - Load more items as user scrolls
-   - Better for large libraries
-
-2. **Image Caching**
-   - Cache album artwork
-   - Reduce network usage
-   - Faster loading
-
-3. **Search Improvements**
-   - Search history
-   - Search suggestions
-   - Filter by category
-
----
-
-## 📝 Code Examples
-
-### Home Page Album Rows
-```dart
-AlbumRow(
-  title: 'Recently Played',
-  loadAlbums: () async {
-    if (provider.api == null) return [];
-    return await provider.api!.getRecentAlbums(limit: 10);
-  },
-)
-```
-
-### Player List Caching
-```dart
-// Check cache first
-if (!forceRefresh &&
-    _playersLastFetched != null &&
-    _availablePlayers.isNotEmpty &&
-    now.difference(_playersLastFetched!) < _playersCacheDuration) {
-  _logger.log('Using cached player list');
-  return;
-}
-```
-
-### Queue Defensive Parsing
-```dart
-final items = <QueueItem>[];
-for (var i in (result as List<dynamic>)) {
-  try {
-    items.add(QueueItem.fromJson(i as Map<String, dynamic>));
-  } catch (e) {
-    _logger.log('⚠️ Failed to parse queue item: $e');
-    // Continue parsing other items
-  }
-}
-```
-
----
-
-## 🎉 Achievements
-
-### Features Delivered
-- ✅ 7 major features implemented
-- ✅ 9 commits pushed
-- ✅ 20+ files modified
-- ✅ 1,500+ lines of code added
-
-### Quality Improvements
-- ✅ Comprehensive documentation (1,100+ lines)
-- ✅ Better error handling
-- ✅ Performance optimizations
-- ✅ Code organization
-
-### User Impact
-- ✅ Working now playing bar
-- ✅ Much better home screen
-- ✅ Queue management
-- ✅ Faster performance
-
----
-
-## 🔗 Related Files
-
-**Main Implementation:**
-- `lib/services/music_assistant_api.dart` - API layer with new methods
-- `lib/providers/music_assistant_provider.dart` - State management with caching
-- `lib/screens/new_home_screen.dart` - Enhanced home screen
-- `lib/screens/queue_screen.dart` - Queue viewer
-- `lib/widgets/album_row.dart` - Album carousel
-- `lib/widgets/library_stats.dart` - Statistics display
-
-**Documentation:**
-- `ARCHITECTURE.md` - Technical architecture
-- `TROUBLESHOOTING.md` - Troubleshooting guide
-- `OVERNIGHT_WORK_SUMMARY.md` - This file
-
----
-
-## 🙏 Final Notes
-
-This overnight session delivered significant improvements to the Music Assistant Mobile app:
-
-1. **Now playing bar works** - Core functionality that was broken is now fixed
-2. **Engaging home screen** - Users now have discovery features
-3. **Queue management** - Full control over playback queue
-4. **Better performance** - Caching reduces unnecessary API calls
-5. **Excellent documentation** - Future development will be much easier
-
-The app is now in a much better state for continued development. The most critical issues have been addressed, and new features have been added to enhance the user experience.
-
-**Branch:** `claude/implement-features-01YRy2D4tHYs2gKkxrP9nqVC`
-**Status:** All changes committed and pushed
-**Next Step:** Test everything and fix any issues found
-
-Thank you for the opportunity to work on this project! 🎵

README.md

@@ -1,55 +1,112 @@
 <div align="center">
-  <img src="assets/images/logo.png" alt="Amass Logo" height="120">
-  <h1>Amass</h1>
-  <p>A minimalistic mobile client for <a href="https://music-assistant.io/">Music Assistant</a></p>
-  <p>Stream your entire music library from your Music Assistant server to your mobile device.</p>
+  <img src="assets/images/ensemble_logo.png" alt="Ensemble Logo" height="200">
+
+---
+
+  <p><strong>An unofficial mobile client for Music Assistant</strong></p>
+  <p>Stream your music library directly to your phone, or control playback on any connected speaker.</p>
 </div>
 
 ---
 
+## Disclaimer
+
+**Ensemble is an unofficial, community-built mobile client for Music Assistant. It is not affiliated with, endorsed by, or supported by the Music Assistant project or its developers.**
+
+This application was built with AI-assisted development using **Claude Code** and **Gemini CLI**.
+
+---
+
 ## Features
 
-### Music Assistant Integration
-- **Server Connection** - Connect to your Music Assistant server via WebSocket
-- **Library Browsing** - Browse artists, albums, and tracks from your server
-- **Album Details** - View album information and track listings
-- **Music Streaming** - Stream audio directly from your Music Assistant server
-- **Auto-Reconnect** - Automatic reconnection with connection status monitoring
-- **Settings Management** - Configure server URL with persistent storage
+### Local Playback
+- **Stream to Your Phone** - Play music from your Music Assistant library directly on your mobile device
+- **Background Playback** - Music continues playing when the app is minimized
+- **Media Notifications** - Control playback from your notification shade with album art display
 
-### Player Features
-- Clean, minimalistic dark UI design
-- Full audio playback controls (play/pause/skip/seek)
-- Progress bar with time display
-- Volume control slider
-- Now playing display with track information
-- Background audio playback support
-- Queue management
+### Remote Control
+- **Multi-Player Support** - Control any speaker or device connected to Music Assistant
+- **Device Selector** - Quickly switch between your phone and other players
+- **Full Playback Controls** - Play, pause, skip, seek, and adjust volume
+- **Queue Management** - View and manage the playback queue
+
+### Home Screen
+- **Customizable Rows** - Toggle Recently Played, Discover Artists, and Discover Albums
+- **Favorites Rows** - Optional rows for Favorite Albums, Artists, and Tracks
+- **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
+- **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
+
+### Audiobooks
+- **Audiobooks Tab** - Browse your audiobook library with grid/list view options
+- **Series Support** - View audiobooks organized by series with collage cover art
+- **Author Browsing** - Browse audiobooks by author
+- **Chapter Navigation** - Jump between chapters with timestamp display
+- **Progress Tracking** - Track your listening progress across sessions
+- **Continue Listening** - Pick up where you left off
+- **Mark as Finished/Unplayed** - Manage your reading progress
+
+### Smart Features
+- **Instant App Restore** - App loads instantly with cached library data while syncing in background
+- **Auto-Reconnect** - Automatically reconnects when connection is lost
+- **Offline Browsing** - Browse your cached library even when disconnected
+- **Hero Animations** - Smooth transitions between screens
+
+### Theming
+- **Material You** - Dynamic theming based on your device's wallpaper
+- **Adaptive Colors** - Album artwork-based color schemes
+- **Light/Dark Mode** - System-aware or manual theme selection
+
+## Screenshots
+
+<div align="center">
+  <img src="assets/screenshots/1.png?v=2" alt="Connection Screen" width="150">
+  <img src="assets/screenshots/2.png?v=2" alt="Home Screen" width="150">
+  <img src="assets/screenshots/3.png?v=2" alt="Album Details" width="150">
+  <img src="assets/screenshots/4.png?v=2" alt="Now Playing" width="150">
+  <img src="assets/screenshots/5.png?v=2" alt="Queue" width="150">
+  <img src="assets/screenshots/6.png?v=2" alt="Settings" width="150">
+  <img src="assets/screenshots/7.png?v=2" alt="Audiobooks" width="150">
+  <img src="assets/screenshots/8.png?v=2" alt="Audiobook Player" width="150">
+</div>
 
 ## Download
 
-Download the latest APK from [GitHub Actions](https://github.com/CollotsSpot/Amass/actions) - look for the "amass-apk" artifact in successful builds.
+Download the latest release from the [Releases page](https://github.com/CollotsSpot/Ensemble/releases).
 
 ## Setup
 
 1. Launch the app
-2. Navigate to the **Library** tab
-3. Tap **Configure Server** or go to **Settings**
-4. Enter your Music Assistant server URL (e.g., `music.serverscloud.org` or `192.168.1.100`)
-5. Tap **Connect**
-6. Browse your library and start playing music!
+2. Enter your Music Assistant server URL (e.g., `music.example.com` or `192.168.1.100`)
+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.
+
+## Authentication
+
+Ensemble supports multiple authentication methods:
+
+| Method | Status |
+|--------|--------|
+| Music Assistant native auth | Tested |
+| No authentication | Tested |
+| Authelia | Implemented, not recently tested |
+| HTTP Basic Auth | Implemented, not recently tested |
+
+**Note:** Development and testing is done against Music Assistant beta with native authentication enabled.
 
 ## Requirements
 
-- Music Assistant server (v2.7.0 or later recommended)
+- Music Assistant server (v2.7.0 beta 20 or later)
 - Network connectivity to your Music Assistant server
 - Android device (Android 5.0+)
-
-## About Music Assistant
-
-Amass is a client for [Music Assistant](https://music-assistant.io/), an open-source music library manager and player that integrates with various music sources and streaming providers. You'll need a running Music Assistant server to use this app.
-
-Learn more: [music-assistant.io](https://music-assistant.io/)
+- Audiobookshelf provider configured in Music Assistant (for audiobook features)
 
 ## License
 
@@ -70,8 +127,8 @@ MIT License
 
 1. Clone the repository
 ```bash
-git clone https://github.com/CollotsSpot/Amass.git
-cd Amass
+git clone https://github.com/CollotsSpot/Ensemble.git
+cd Ensemble
 ```
 
 2. Install dependencies
@@ -97,10 +154,10 @@ The APK will be available at `build/app/outputs/flutter-apk/app-release.apk`
 <summary>Technologies Used</summary>
 
 - **Flutter** - Cross-platform mobile framework
-- **just_audio** - Audio playback
-- **audio_service** - Background audio support
-- **web_socket_channel** - WebSocket communication
+- **audio_service** - Background playback and media notifications
+- **web_socket_channel** - WebSocket communication with Music Assistant
 - **provider** - State management
+- **cached_network_image** - Image caching
 - **shared_preferences** - Local settings storage
 
 </details>

SEARCH-IMPROVEMENTS.md

@@ -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 |

TROUBLESHOOTING.md

@@ -1,642 +0,0 @@
-# Music Assistant Mobile - Troubleshooting Guide
-
-## Common Issues and Solutions
-
-### Connection Issues
-
-#### Problem: "Not Connected to Music Assistant"
-
-**Symptoms:**
-- App shows disconnected state
-- Cannot browse library
-- No players available
-
-**Solutions:**
-
-1. **Verify Server URL**
-   - Go to Settings
-   - Check server URL format: `https://ma.serverscloud.org` or `http://192.168.1.100:8095`
-   - Ensure no trailing slash
-   - Try both HTTP and HTTPS if unsure
-
-2. **Check Network Connectivity**
-   - Ensure device has internet/network access
-   - Try opening server URL in mobile browser
-   - Check if on same network (for local servers)
-
-3. **Verify Music Assistant Server**
-   - Ensure Music Assistant server is running
-   - Check server is accessible from your device
-   - Verify port 8095 (default) or custom port is open
-
-4. **Check Authentication**
-   - If using Authelia, verify credentials
-   - Try re-entering username/password
-   - Check Authelia is accessible
-
-5. **Clear App Data**
-   - Go to Settings → Clear all settings
-   - Re-enter server URL and credentials
-   - Restart app
-
-#### Problem: "WebSocket Connection Failed"
-
-**Symptoms:**
-- Connection drops frequently
-- "Connection timeout" errors in logs
-
-**Solutions:**
-
-1. **Check WebSocket Port**
-   - Default: 8095 for local, 443 for HTTPS
-   - Go to Settings → Custom WebSocket Port
-   - Try entering port explicitly
-
-2. **Verify Firewall Rules**
-   - Ensure WebSocket traffic is allowed
-   - Check reverse proxy configuration (if using)
-   - Cloudflare users: Ensure WebSocket support enabled
-
-3. **Test WebSocket Connection**
-   - Use browser dev tools to test WebSocket
-   - URL format: `wss://ma.serverscloud.org/ws`
-   - Look for successful upgrade to WebSocket
-
----
-
-### Authentication Issues
-
-#### Problem: "Login Failed" or "401 Unauthorized"
-
-**Symptoms:**
-- Cannot login with correct credentials
-- Session expires immediately
-- WebSocket authentication fails
-
-**Solutions:**
-
-1. **Verify Authelia Credentials**
-   - Double-check username and password
-   - Check Authelia domain is correct
-   - Try logging in via web browser first
-
-2. **Check Session Cookie**
-   - Cookie name should be `authelia_session`
-   - Check cookie is being set by Authelia
-   - Verify cookie domain matches
-
-3. **Clear Saved Credentials**
-   - Settings → Clear all settings
-   - Re-enter credentials
-   - Test login
-
-4. **Check Authelia Configuration**
-   - Ensure Authelia is properly configured
-   - Verify session timeout settings
-   - Check Authelia logs for errors
-
-#### Problem: "Auto-login Fails"
-
-**Symptoms:**
-- Must re-login every app start
-- "Auto-login failed" in logs
-
-**Solutions:**
-
-1. **Check Saved Credentials**
-   - Settings → Verify username is saved
-   - Password should be saved (not visible)
-   - Re-save credentials if needed
-
-2. **Session Timeout**
-   - Authelia session may have expired
-   - Check Authelia session duration
-   - Re-login to refresh session
-
----
-
-### Playback Issues
-
-#### Problem: "No Players Available"
-
-**Symptoms:**
-- Player selector shows empty list
-- Cannot select any player
-- Music won't play
-
-**Solutions:**
-
-1. **Refresh Player List**
-   - Open player selector (top right icon)
-   - Tap refresh icon
-   - Wait for players to load
-
-2. **Check Music Assistant Server**
-   - Verify players are configured in MA server
-   - Check players are powered on
-   - Ensure players are available
-
-3. **Wait for Initial Load**
-   - Players load on connection
-   - May take a few seconds
-   - Check debug logs for "Loaded X players"
-
-#### Problem: "Now Playing Bar Not Showing"
-
-**Symptoms:**
-- Music is playing but no mini-player appears
-- Cannot see current track
-
-**Solutions:**
-
-1. **Check Player Selection**
-   - Ensure a player is selected (green dot in player selector)
-   - Select player explicitly if needed
-
-2. **Verify Queue Has Items**
-   - Some players may not support queue state
-   - Try playing an album/track
-   - Check queue screen for items
-
-3. **Check Debug Logs**
-   - Look for "Error getting queue" messages
-   - Check for parsing errors
-   - Report specific error in GitHub issues
-
-4. **Force Refresh**
-   - Stop and restart playback
-   - Select different player, then select back
-   - Restart app
-
-#### Problem: "Cannot Control Playback"
-
-**Symptoms:**
-- Play/pause buttons don't work
-- Skip track buttons unresponsive
-
-**Solutions:**
-
-1. **Check Player State**
-   - Some players may not support all controls
-   - Verify player is powered on
-   - Check Music Assistant server logs
-
-2. **Network Latency**
-   - Commands may take 1-2 seconds
-   - Wait before clicking again
-   - Check network connection
-
-3. **Player Availability**
-   - Player may have disconnected
-   - Refresh player list
-   - Re-select player
-
----
-
-### Library Issues
-
-#### Problem: "No Artists/Albums/Tracks Found"
-
-**Symptoms:**
-- Empty library screens
-- "No items found" messages
-
-**Solutions:**
-
-1. **Check Music Assistant Library**
-   - Verify library is populated in MA server
-   - Scan library in MA web interface
-   - Ensure provider is configured
-
-2. **Force Library Reload**
-   - Pull down to refresh on library screens
-   - Go to home screen and back
-   - Restart app
-
-3. **Check API Limits**
-   - Default limit is 100 items
-   - May not show all items if library > 100
-   - Pagination planned for future release
-
-4. **Verify Connection**
-   - Ensure WebSocket is connected
-   - Check connection status on home screen
-   - Look for green dot indicator
-
-#### Problem: "Search Returns No Results"
-
-**Symptoms:**
-- Search finds nothing
-- Known items don't appear
-
-**Solutions:**
-
-1. **Check Search Query**
-   - Try partial matches
-   - Search is case-insensitive
-   - Wait for debounce (500ms)
-
-2. **Verify Library Content**
-   - Ensure items exist in MA library
-   - Test search in MA web interface
-   - Re-scan library if needed
-
-3. **Check Network**
-   - Search requires active connection
-   - Verify WebSocket is connected
-   - Try again with better connection
-
----
-
-### Queue Issues
-
-#### Problem: "Queue Screen Shows Empty"
-
-**Symptoms:**
-- Queue screen has no items
-- Music is playing but queue empty
-
-**Solutions:**
-
-1. **Check Player Type**
-   - Some players may not support queue viewing
-   - Try different player
-   - Check MA server capabilities
-
-2. **Refresh Queue**
-   - Tap refresh icon in queue screen
-   - Play a new album/track
-   - Restart playback
-
-3. **API Issues**
-   - Check logs for "Error getting queue"
-   - May be API parsing issue
-   - Report bug with logs
-
-#### Problem: "Cannot Reorder/Remove Queue Items"
-
-**Symptoms:**
-- Drag and drop doesn't work
-- Swipe to dismiss fails
-
-**Solutions:**
-
-1. **API Support**
-   - Reordering/removing is local only (currently)
-   - Server sync not yet implemented
-   - Changes won't persist on server
-
-2. **UI Issues**
-   - Ensure you're dragging from handle icon
-   - Swipe fully to left to dismiss
-   - Try on different queue items
-
----
-
-### Performance Issues
-
-#### Problem: "App is Slow/Laggy"
-
-**Symptoms:**
-- UI stutters
-- Slow navigation
-- Delayed responses
-
-**Solutions:**
-
-1. **Clear App Cache**
-   - Settings → Clear all settings
-   - Restart app
-   - May improve performance
-
-2. **Reduce Polling**
-   - Player state polls every 2 seconds
-   - Expected behavior for now
-   - Future: Event-based updates
-
-3. **Check Device Performance**
-   - Close other apps
-   - Restart device
-   - Check available storage
-
-4. **Network Latency**
-   - Test network speed
-   - Move closer to WiFi
-   - Try different network
-
-#### Problem: "High Battery Drain"
-
-**Symptoms:**
-- Battery drains quickly
-- App using lots of background power
-
-**Solutions:**
-
-1. **Polling Frequency**
-   - Player state polling uses power
-   - Will be optimized in future
-   - Close app when not in use
-
-2. **Background Activity**
-   - App doesn't support background playback yet
-   - Ensure app is closed when done
-   - Check battery settings
-
----
-
-### UI Issues
-
-#### Problem: "Images Not Loading"
-
-**Symptoms:**
-- Album/artist artwork missing
-- Broken image icons
-
-**Solutions:**
-
-1. **Check Network**
-   - Images load from server
-   - Requires active connection
-   - Try refreshing
-
-2. **Verify Image URLs**
-   - Check MA server has artwork
-   - Test image URL in browser
-   - May be missing for some items
-
-3. **Server Configuration**
-   - Check image proxy settings
-   - Verify image API endpoint
-   - Check CORS configuration
-
-#### Problem: "Screen Layout Broken"
-
-**Symptoms:**
-- Overlapping elements
-- Text cut off
-- Weird spacing
-
-**Solutions:**
-
-1. **Restart App**
-   - Force close and reopen
-   - May fix temporary layout issues
-
-2. **Check Device**
-   - Test on different screen size
-   - May be device-specific issue
-   - Report with device model
-
----
-
-## Debug Logging
-
-### Enabling Logs
-
-Logs are always enabled and print to console. To view:
-
-**Android Studio / VS Code:**
-1. Run app in debug mode
-2. Open Debug Console
-3. Look for timestamped logs: `[HH:MM:SS.mmm] Message`
-
-**Physical Device:**
-1. Connect via USB
-2. Run `flutter logs`
-3. Filter for app logs
-
-### Important Log Messages
-
-**Connection:**
-- `Connected to Music Assistant successfully` - Connection established
-- `WebSocket error: ...` - Connection problem
-- `Connection timeout` - Server not responding
-
-**Authentication:**
-- `🔑 Adding session cookie to WebSocket handshake` - Auth in progress
-- `✓ Authenticated` - Auth successful
-- `⚠️ Auto-login failed` - Credentials issue
-
-**Players:**
-- `Loaded X players` - Player list fetched
-- `Selected player: Name (ID)` - Player selected
-- `Using cached player list` - Cache hit
-
-**Queue:**
-- `🔍 DEBUG: First queue item raw data` - Queue structure
-- `Error getting queue: ...` - Queue fetch failed
-- `⚠️ Failed to parse queue item` - Parsing error
-
-**Playback:**
-- `Playing X tracks via queue on player Y` - Playback started
-- `✓ X tracks queued successfully` - Queue successful
-
-### Reporting Bugs
-
-When reporting issues, include:
-
-1. **Steps to Reproduce**
-   - Exact actions taken
-   - Expected vs actual behavior
-
-2. **Debug Logs**
-   - Copy relevant log section
-   - Include timestamps
-   - Show 10-20 lines before/after error
-
-3. **Environment**
-   - Device model and OS version
-   - App version
-   - Music Assistant server version
-   - Network type (WiFi, cellular, etc.)
-
-4. **Screenshots**
-   - Error messages
-   - UI issues
-   - Settings screen
-
----
-
-## Known Limitations
-
-### Current Constraints
-
-1. **Library Pagination**
-   - Loads max 100 items per category
-   - Infinite scroll coming soon
-
-2. **Queue Management**
-   - Reorder/remove only local
-   - Server sync not implemented
-   - Changes don't persist
-
-3. **Player State**
-   - Polls every 2 seconds
-   - Event-based updates coming
-   - May have slight delay
-
-4. **Search**
-   - Searches entire library only
-   - No category-specific search
-   - No search history
-
-5. **Offline Mode**
-   - No offline playback
-   - Requires active connection
-   - Planned for future
-
-### Planned Improvements
-
-See ARCHITECTURE.md → Future Enhancements for roadmap.
-
----
-
-## Advanced Troubleshooting
-
-### WebSocket Debugging
-
-1. **Chrome DevTools Method**
-   ```
-   1. Open ma.serverscloud.org in Chrome
-   2. F12 → Network tab
-   3. Filter: WS (WebSocket)
-   4. Look for /ws connection
-   5. Inspect frames (messages)
-   ```
-
-2. **Test WebSocket Manually**
-   ```javascript
-   const ws = new WebSocket('wss://ma.serverscloud.org/ws');
-   ws.onopen = () => console.log('Connected');
-   ws.onmessage = (e) => console.log('Message:', e.data);
-   ws.onerror = (e) => console.error('Error:', e);
-   ```
-
-### API Testing
-
-Use Music Assistant's web interface to test API:
-1. Open developer tools
-2. Go to Network tab
-3. Perform action (search, play, etc.)
-4. Inspect WebSocket messages
-5. Compare with app behavior
-
-### Flutter Debugging
-
-**DevTools:**
-```bash
-flutter pub global activate devtools
-flutter pub global run devtools
-```
-
-**Widget Inspector:**
-- Shows widget tree
-- Inspect layout issues
-- Debug rendering
-
-**Performance:**
-- Profile mode: `flutter run --profile`
-- Check frame rendering times
-- Monitor memory usage
-
----
-
-## Getting Help
-
-### Support Channels
-
-1. **GitHub Issues**
-   - Bug reports
-   - Feature requests
-   - Technical discussions
-   - URL: https://github.com/CollotsSpot/music-assistant-mobile/issues
-
-2. **Music Assistant Community**
-   - Discord server
-   - Forum discussions
-   - General questions
-   - URL: https://music-assistant.io/
-
-3. **Documentation**
-   - ARCHITECTURE.md - Technical details
-   - README.md - Getting started
-   - Code comments - Implementation details
-
-### Before Asking
-
-1. Check this troubleshooting guide
-2. Search existing GitHub issues
-3. Check Music Assistant docs
-4. Test with Music Assistant web interface
-5. Gather debug logs
-
-### Providing Feedback
-
-**Bug Report Template:**
-```
-**Description**
-[Clear description of the issue]
-
-**Steps to Reproduce**
-1. Step one
-2. Step two
-3. ...
-
-**Expected Behavior**
-[What should happen]
-
-**Actual Behavior**
-[What actually happens]
-
-**Logs**
-[Relevant log excerpt]
-
-**Environment**
-- Device: [e.g. Samsung Galaxy S21]
-- OS: [e.g. Android 13]
-- App Version: [e.g. 1.0.0]
-- MA Server Version: [e.g. 2.7.0]
-
-**Screenshots**
-[If applicable]
-```
-
----
-
-## FAQ
-
-### Q: Does the app support offline playback?
-**A:** Not currently. All playback requires connection to Music Assistant server.
-
-### Q: Can I use this with multiple Music Assistant servers?
-**A:** Not simultaneously, but you can change servers in Settings.
-
-### Q: Why isn't my local file library showing?
-**A:** Check Music Assistant server has scanned your local files and the provider is enabled.
-
-### Q: Does it support Android Auto / CarPlay?
-**A:** Not yet, but planned for future releases.
-
-### Q: Can I download music for offline listening?
-**A:** Not currently supported.
-
-### Q: How do I update the app?
-**A:** Updates will be distributed via app stores once released. Currently, build from source.
-
-### Q: Is my password stored securely?
-**A:** Yes, credentials are stored using Flutter's secure storage mechanisms.
-
-### Q: Can I control playback when screen is off?
-**A:** Background playback is limited. The app is designed for active use currently.
-
-### Q: Why can't I see all my albums?
-**A:** Current limit is 100 items per category. Pagination coming soon.
-
-### Q: Does it work with Spotify/YouTube/etc?
-**A:** Yes, if configured as providers in Music Assistant server.
-
----
-
-**Last Updated:** 2025-01-22
-**App Version:** Development Build
-**Music Assistant Version:** 2.7.0+

WORK_SUMMARY.md

@@ -1,299 +0,0 @@
-# Music Assistant Mobile - Implementation Summary
-
-This document summarizes all the features and improvements implemented during the overnight development session.
-
-## 🎯 Overview
-
-This was an intensive development session focused on transforming the Music Assistant mobile app from a basic prototype into a feature-rich, production-ready music player with comprehensive functionality, robust error handling, and extensive test coverage.
-
-## ✨ Major Features Implemented
-
-### 1. Playlist Support
-**Files Added:**
-- `lib/screens/playlist_details_screen.dart`
-- `lib/widgets/playlist_row.dart`
-
-**Features:**
-- Browse playlists from all providers (Spotify, local library, etc.)
-- View playlist details with track listings
-- Play entire playlists with queue management
-- Play individual tracks from playlists
-- Beautiful UI with album artwork and metadata
-- Provider-specific playlist support
-
-### 2. Favorites System
-**Files Modified:**
-- `lib/providers/music_assistant_provider.dart`
-- `lib/services/music_assistant_api.dart`
-- `lib/screens/*_details_screen.dart`
-
-**Features:**
-- Mark/unmark tracks, albums, and artists as favorites
-- Persistent favorites sync with Music Assistant server
-- Visual indicators for favorited items (filled heart icons)
-- Real-time UI updates when toggling favorites
-- Error handling for favorite operations
-
-### 3. Volume Control
-**Files Added:**
-- `lib/widgets/volume_control.dart`
-
-**Features:**
-- Full volume slider with live adjustment
-- Mute/unmute toggle
-- Visual volume percentage display
-- Compact mode for mini player (mute button only)
-- Smooth UI with pending volume tracking
-- Dynamic volume icons (off/down/up)
-
-### 4. Shuffle & Repeat Modes
-**Files Modified:**
-- `lib/models/player.dart` (added shuffle/repeat to PlayerQueue)
-- `lib/providers/music_assistant_provider.dart` (added control methods)
-- `lib/screens/now_playing_screen.dart` (added UI controls)
-
-**Features:**
-- Shuffle toggle with visual state indication
-- Repeat modes: Off, One, All
-- Persistent state across sessions
-- Visual feedback with icon states
-- Integration with Music Assistant queue
-
-### 5. Retry Logic with Exponential Backoff
-**Files Added:**
-- `lib/services/retry_helper.dart`
-
-**Features:**
-- Generic retry mechanism for any async operation
-- Exponential backoff (2s → 4s → 8s → 16s)
-- Network-specific retry logic
-- Critical operation retry mode
-- Configurable max attempts and delays
-- Smart error detection for retryable errors
-- Comprehensive logging
-
-### 6. Error Handling System
-**Files Added:**
-- `lib/services/error_handler.dart`
-
-**Features:**
-- User-friendly error messages
-- Error type classification (connection, network, auth, playback, library)
-- Technical vs. user-facing messages
-- Retryability detection
-- Comprehensive error logging
-- Context-aware error handling
-
-### 7. Search Functionality
-**Files Added:**
-- `lib/screens/search_screen.dart`
-- `lib/services/search_service.dart`
-
-**Features:**
-- Global search across tracks, albums, artists, playlists
-- Real-time search results
-- Debounced search input
-- Category filtering
-- Direct playback from search results
-- Navigation to detail screens
-
-### 8. Home Page Enhancements
-**Files Modified:**
-- `lib/screens/home_screen.dart`
-- `lib/widgets/album_row.dart`
-
-**Features:**
-- Recent albums section
-- Random albums discovery
-- Library statistics display
-- Horizontal scrolling album rows
-- Beautiful album artwork display
-- Quick navigation to album details
-
-### 9. Queue Management
-**Files Added:**
-- `lib/screens/queue_screen.dart`
-
-**Features:**
-- View current playback queue
-- Visual indicator for currently playing track
-- Track numbers and metadata
-- Album artwork for each track
-- Shuffle and repeat controls
-- Clear queue functionality
-- Jump to any track in queue
-
-### 10. Pull-to-Refresh
-**Files Modified:**
-- All library screens (albums, artists, tracks, playlists)
-
-**Features:**
-- Swipe down to refresh library content
-- Visual refresh indicator
-- Background data reload
-- Smooth animations
-- Maintained scroll position
-
-### 11. Player List Caching
-**Files Modified:**
-- `lib/providers/music_assistant_provider.dart`
-
-**Features:**
-- Cache player list for 30 seconds
-- Reduced API calls
-- Faster UI updates
-- Background refresh
-- Cache invalidation on manual refresh
-
-### 12. Comprehensive Unit Tests
-**Files Added:**
-- `test/models/media_item_test.dart`
-- `test/models/player_test.dart`
-- `test/services/retry_helper_test.dart`
-- `test/services/error_handler_test.dart`
-
-**Coverage:**
-- 130+ test cases
-- MediaItem model tests (Track, Album, Artist, Playlist, Radio)
-- Player model tests (Player, QueueItem, PlayerQueue, StreamDetails)
-- RetryHelper service tests
-- ErrorHandler service tests
-- JSON parsing validation
-- Null safety verification
-- Edge case handling
-- Default value testing
-
-### 13. Playback Quality Settings
-**Files Added:**
-- `lib/models/settings.dart`
-- `lib/providers/settings_provider.dart`
-- `lib/screens/playback_settings_screen.dart`
-
-**Files Modified:**
-- `lib/main.dart` (added SettingsProvider)
-- `lib/screens/settings_screen.dart` (added navigation)
-
-**Features:**
-- Audio quality preferences (Lossless/Lossy)
-- Quality levels: Low (96 kbps), Normal (128 kbps), High (256 kbps), Very High (320 kbps)
-- Configurable max bitrate
-- Prefer lossless (FLAC) option
-- Network settings (cellular streaming, downloads)
-- Appearance settings (album art, animations)
-- Settings persistence with SharedPreferences
-- Reset to defaults functionality
-- Beautiful settings UI with sliders and toggles
-
-## 🐛 Bug Fixes
-
-### 1. Build Errors
-**Fixed:**
-- Missing `api` getter in MusicAssistantProvider
-- Null safety issues in multiple screens
-- Constructor parameter mismatches in AlbumDetailsScreen
-- Missing imports and dependencies
-
-### 2. Queue Item Parsing Failures
-**Fixed:**
-- Nested `media_item` structure handling
-- Null safety in MediaItem.fromJson
-- ProviderMapping null field defaults
-- QueueItem queue_item_id fallback logic
-- Comprehensive null checks throughout parsing
-
-### 3. Player Selection Issues
-**Fixed:**
-- Smart player selection based on playback state
-- Prioritize actually playing player over builtin
-- Maintain player selection when still available
-- Auto-select playing player on app launch
-- Refresh selected player state
-
-### 4. Now Playing Display
-**Fixed:**
-- Stale queue data from parsing failures
-- Wrong track information display
-- Player-queue mismatch
-- Current item detection
-
-## 📊 Statistics
-
-### Code Added
-- **New Files:** 20+
-- **Modified Files:** 30+
-- **Lines of Code:** ~5,000+
-- **Test Cases:** 130+
-- **Commits:** 20
-
-### Features Breakdown
-- **UI Screens:** 6 new screens
-- **Widgets:** 8 new reusable widgets
-- **Services:** 4 new service classes
-- **Models:** 3 new model classes
-- **Providers:** 2 new state management providers
-
-## 🏗️ Architecture Improvements
-
-### State Management
-- Proper use of Provider pattern
-- ChangeNotifier for reactive UI
-- Separation of concerns
-- Clean data flow
-
-### Error Handling
-- Centralized error handling service
-- User-friendly error messages
-- Comprehensive logging
-- Retry mechanisms
-
-### Code Quality
-- Null safety throughout
-- Defensive programming
-- Comprehensive tests
-- Clear documentation
-
-### Performance
-- Caching strategies
-- Debounced operations
-- Optimized API calls
-- Smooth animations
-
-## 🚀 Ready for Production
-
-The app now includes:
-- ✅ Comprehensive feature set
-- ✅ Robust error handling
-- ✅ Extensive test coverage
-- ✅ User-configurable settings
-- ✅ Smooth, polished UI
-- ✅ Performance optimizations
-- ✅ Production-ready code quality
-
-## 📝 Commit History
-
-```
-f6c0c88 Add comprehensive unit tests and playback quality settings
-56cd6ef Fix player selection to show correct now playing information
-18d74e9 Improve null safety in JSON parsing for queue items and media items
-f3c5c66 Fix QueueItem parsing - track data is nested in media_item field
-ace810a Fix AlbumDetailsScreen constructor call - remove extra parameters
-649583e Fix build errors - null safety and API access issues
-3bce979 Implement shuffle and repeat modes for queue control
-7f4730a Add volume control for Music Assistant players
-fcb038a Improve error handling with user-friendly messages
-db0cefe Add retry logic with exponential backoff for network resilience
-d0ab37e Add favorites system
-d7949a3 Add comprehensive playlist support
-e24b542 Add player list caching to reduce API calls
-4f7856e Add pull-to-refresh to library screens
-ad4136f Add queue viewer screen with management capabilities
-6c291f7 Add search functionality to home and library screens
-38b29cb Add home page enhancements - recent albums, random albums, and stats
-965bf9d Add defensive parsing and debug logging for queue items
-```
-
-## 🎉 Conclusion
-
-This intensive development session successfully transformed the Music Assistant mobile app into a feature-complete, production-ready application. The app now provides a rich music listening experience with comprehensive playback controls, library management, search, playlists, favorites, quality settings, and robust error handling - all backed by extensive test coverage.
-
-The codebase is clean, well-structured, and ready for deployment. All major features are implemented, tested, and committed to the repository.

android/app/build.gradle

@@ -22,6 +22,12 @@ if (flutterVersionName == null) {
     flutterVersionName = '1.0'
 }
 
+def keystoreProperties = new Properties()
+def keystorePropertiesFile = rootProject.file('key.properties')
+if (keystorePropertiesFile.exists()) {
+    keystoreProperties.load(new FileInputStream(keystorePropertiesFile))
+}
+
 android {
     namespace "com.musicassistant.music_assistant"
     compileSdk 35
@@ -40,6 +46,17 @@ android {
         main.java.srcDirs += 'src/main/kotlin'
     }
 
+    signingConfigs {
+        release {
+            if (keystorePropertiesFile.exists()) {
+                keyAlias keystoreProperties['keyAlias']
+                keyPassword keystoreProperties['keyPassword']
+                storeFile file(keystoreProperties['storeFile'])
+                storePassword keystoreProperties['storePassword']
+            }
+        }
+    }
+
     defaultConfig {
         applicationId "com.musicassistant.music_assistant"
         minSdk 21
@@ -50,7 +67,7 @@ android {
 
     buildTypes {
         release {
-            signingConfig signingConfigs.debug
+            signingConfig keystorePropertiesFile.exists() ? signingConfigs.release : signingConfigs.debug
         }
     }
 }

android/app/src/main/AndroidManifest.xml

@@ -4,9 +4,11 @@
     <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
     <uses-permission android:name="android.permission.WAKE_LOCK"/>
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK"/>
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
 
     <application
-        android:label="Amass"
+        android:label="Ensemble"
         android:name="${applicationName}"
         android:icon="@mipmap/ic_launcher"
         android:usesCleartextTraffic="true"

android/app/src/main/kotlin/com/musicassistant/music_assistant/MainActivity.kt

@@ -1,6 +1,87 @@
 package com.musicassistant.music_assistant
 
-import io.flutter.embedding.android.FlutterActivity
+import android.util.Log
+import android.view.KeyEvent
+import com.ryanheise.audioservice.AudioServiceActivity
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.plugin.common.MethodChannel
 
-class MainActivity: FlutterActivity() {
+// Extend AudioServiceActivity instead of FlutterActivity to support audio_service package
+// while also intercepting volume button events
+class MainActivity: AudioServiceActivity() {
+    private val TAG = "EnsembleVolume"
+    private val CHANNEL = "com.musicassistant.music_assistant/volume_buttons"
+    private var methodChannel: MethodChannel? = null
+    private var isListening = false
+
+    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+        super.configureFlutterEngine(flutterEngine)
+        Log.d(TAG, "Configuring Flutter engine, setting up MethodChannel")
+
+        methodChannel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
+        methodChannel?.setMethodCallHandler { call, result ->
+            Log.d(TAG, "Received method call: ${call.method}")
+            when (call.method) {
+                "startListening" -> {
+                    isListening = true
+                    Log.d(TAG, "Volume listening ENABLED")
+                    result.success(null)
+                }
+                "stopListening" -> {
+                    isListening = false
+                    Log.d(TAG, "Volume listening DISABLED")
+                    result.success(null)
+                }
+                else -> {
+                    Log.d(TAG, "Unknown method: ${call.method}")
+                    result.notImplemented()
+                }
+            }
+        }
+    }
+
+    // Use dispatchKeyEvent instead of onKeyDown - Flutter's engine uses dispatchKeyEvent
+    // and may consume events before they reach onKeyDown
+    override fun dispatchKeyEvent(event: KeyEvent?): Boolean {
+        if (event == null) {
+            return super.dispatchKeyEvent(event)
+        }
+
+        val keyCode = event.keyCode
+        val action = event.action
+
+        Log.d(TAG, "dispatchKeyEvent: keyCode=$keyCode, action=$action, isListening=$isListening")
+
+        // Only handle KEY_DOWN events to avoid double-triggering (down + up)
+        if (action != KeyEvent.ACTION_DOWN) {
+            // For volume keys when listening, also consume ACTION_UP to fully block system volume
+            if (isListening && (keyCode == KeyEvent.KEYCODE_VOLUME_UP || keyCode == KeyEvent.KEYCODE_VOLUME_DOWN)) {
+                Log.d(TAG, "Consuming ACTION_UP for volume key")
+                return true
+            }
+            return super.dispatchKeyEvent(event)
+        }
+
+        if (!isListening) {
+            Log.d(TAG, "Not listening, passing to super")
+            return super.dispatchKeyEvent(event)
+        }
+
+        return when (keyCode) {
+            KeyEvent.KEYCODE_VOLUME_UP -> {
+                Log.d(TAG, "VOLUME UP pressed - sending to Flutter")
+                methodChannel?.invokeMethod("volumeUp", null)
+                true // Consume the event to prevent system volume change
+            }
+            KeyEvent.KEYCODE_VOLUME_DOWN -> {
+                Log.d(TAG, "VOLUME DOWN pressed - sending to Flutter")
+                methodChannel?.invokeMethod("volumeDown", null)
+                true // Consume the event to prevent system volume change
+            }
+            else -> {
+                Log.d(TAG, "Other key, passing to super")
+                super.dispatchKeyEvent(event)
+            }
+        }
+    }
 }

android/app/src/main/res/drawable/ic_switch_player.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<vector xmlns:android="http://schemas.android.com/apk/res/android"
+    android:width="24dp"
+    android:height="24dp"
+    android:viewportWidth="24"
+    android:viewportHeight="24">
+    <!-- Swap/cycle arrows icon -->
+    <path
+        android:fillColor="#FFFFFF"
+        android:pathData="M12,6v3l4,-4 -4,-4v3c-4.42,0 -8,3.58 -8,8 0,1.57 0.46,3.03 1.24,4.26L6.7,14.8c-0.45,-0.83 -0.7,-1.79 -0.7,-2.8 0,-3.31 2.69,-6 6,-6zM18.76,7.74L17.3,9.2c0.44,0.84 0.7,1.79 0.7,2.8 0,3.31 -2.69,6 -6,6v-3l-4,4 4,4v-3c4.42,0 8,-3.58 8,-8 0,-1.57 -0.46,-3.03 -1.24,-4.26z"/>
+</vector>

android/app/src/main/res/raw/keep.xml

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources xmlns:tools="http://schemas.android.com/tools"
+    tools:keep="@drawable/*,@drawable/audio_service_*" />

docs/AUDIOBOOKS_IMPLEMENTATION_PLAN.md

@@ -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
+```

l10n.yaml

@@ -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

lib/constants/hero_tags.dart

@@ -1,14 +1,28 @@
-/// Hero tag prefixes for shared element transitions
+/// Hero animation tag constants for consistent cross-screen animations
 class HeroTags {
-  /// Hero tag for album cover images
+  HeroTags._();
+
+  /// Album cover art hero tag prefix
   static const String albumCover = 'album_cover_';
 
-  /// Hero tag for album title text
+  /// Album title hero tag prefix
   static const String albumTitle = 'album_title_';
 
-  /// Hero tag for artist name text
+  /// Artist name hero tag prefix
   static const String artistName = 'artist_name_';
 
-  /// Hero tag for artist image
+  /// 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_';
 }

lib/constants/network.dart

@@ -0,0 +1,13 @@
+/// Network constants for ports and URLs
+class NetworkConstants {
+  NetworkConstants._();
+
+  /// Default Music Assistant WebSocket port (used for non-proxied connections)
+  static const int defaultWsPort = 8095;
+
+  /// Default HTTPS port (implicit, not usually specified in URLs)
+  static const int defaultHttpsPort = 443;
+
+  /// Default HTTP port
+  static const int defaultHttpPort = 80;
+}

lib/constants/timings.dart

@@ -0,0 +1,53 @@
+/// Timing constants for polling intervals, cache durations, and delays
+class Timings {
+  Timings._();
+
+  /// WebSocket heartbeat/ping interval to keep connection alive
+  static const Duration heartbeatInterval = Duration(seconds: 30);
+
+  /// Player state polling interval (for selected player updates)
+  static const Duration playerPollingInterval = Duration(seconds: 5);
+
+  /// 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);
+
+  /// Home screen row cache duration (recently played, discover sections)
+  static const Duration homeRowCacheDuration = Duration(minutes: 10);
+
+  /// WebSocket reconnection delay
+  static const Duration reconnectDelay = Duration(seconds: 3);
+
+  /// Command timeout for API requests
+  static const Duration commandTimeout = Duration(seconds: 30);
+
+  /// Connection timeout for initial WebSocket handshake
+  static const Duration connectionTimeout = Duration(seconds: 10);
+
+  /// Search debounce delay
+  static const Duration searchDebounce = Duration(milliseconds: 500);
+
+  /// Delay after track change before updating state
+  static const Duration trackChangeDelay = Duration(milliseconds: 500);
+}
+
+/// Library and pagination constants
+class LibraryConstants {
+  LibraryConstants._();
+
+  /// Default page size for library items
+  static const int defaultPageSize = 100;
+
+  /// Maximum items to load for "all" library requests
+  static const int maxLibraryItems = 5000;
+
+  /// Number of items per batch for recent albums
+  static const int recentAlbumsBatchSize = 5;
+
+  /// Default limit for recent/random items
+  static const int defaultRecentLimit = 10;
+}

lib/database/database.dart

@@ -0,0 +1,635 @@
+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
+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
+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))();
+
+  @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
+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 => 4;
+
+  @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);
+        }
+      },
+    );
+  }
+
+  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
+  Future<void> cacheItem({
+    required String itemType,
+    required String itemId,
+    required String data,
+  }) async {
+    final cacheKey = '${itemType}_$itemId';
+
+    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();
+  }
+}

lib/l10n/app_de.arb

@@ -0,0 +1,291 @@
+{
+  "@@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",
+  "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",
+
+  "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": "Gerät gedrückt halten zum Synchronisieren"
+}

lib/l10n/app_es.arb

@@ -0,0 +1,487 @@
+{
+  "@@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",
+  "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",
+  "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 un dispositivo para sincronizar"
+}

lib/main.dart

@@ -1,14 +1,66 @@
+import 'dart:async';
 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';
+import 'services/hardware_volume_service.dart';
+import 'services/music_assistant_api.dart' show MAConnectionState;
+import 'theme/theme_provider.dart';
+import 'theme/app_theme.dart';
+import 'theme/system_theme_helper.dart';
+import 'widgets/global_player_overlay.dart';
 
-void main() {
+// Global audio handler instance
+late MassivAudioHandler audioHandler;
+
+// Global debug logger instance
+final _logger = DebugLogger();
+
+Future<void> main() async {
   WidgetsFlutterBinding.ensureInitialized();
 
+  // 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();
+
+  // 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();
+
+  // Initialize audio_service with our custom handler
+  audioHandler = await AudioService.init(
+    builder: () => MassivAudioHandler(authManager: authManager),
+    config: const AudioServiceConfig(
+      androidNotificationChannelId: 'io.github.collotsspot.massiv.audio',
+      androidNotificationChannelName: 'Ensemble Audio',
+      androidNotificationOngoing: false,  // Must be false when androidStopForegroundOnPause is false
+      androidNotificationIcon: 'drawable/ic_notification',
+      androidShowNotificationBadge: false,
+      androidStopForegroundOnPause: false,  // Keep service alive when paused for background playback
+    ),
+  );
+  _logger.log('🎵 AudioService initialized - background playback and media notifications ENABLED');
+
   // Set preferred orientations
   SystemChrome.setPreferredOrientations([
     DeviceOrientation.portraitUp,
@@ -36,91 +88,416 @@ class MusicAssistantApp extends StatefulWidget {
 }
 
 class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindingObserver {
-  late MusicAssistantProvider _provider;
+  late MusicAssistantProvider _musicProvider;
+  late ThemeProvider _themeProvider;
+  late LocaleProvider _localeProvider;
+  final _hardwareVolumeService = HardwareVolumeService();
+  StreamSubscription? _volumeUpSub;
+  StreamSubscription? _volumeDownSub;
+  String? _lastSelectedPlayerId;
+  String? _builtinPlayerId;
+
+  // Volume step size (percentage points per button press)
+  static const int _volumeStep = 5;
 
   @override
   void initState() {
     super.initState();
-    _provider = MusicAssistantProvider();
+    _musicProvider = MusicAssistantProvider();
+    _themeProvider = ThemeProvider();
+    _localeProvider = LocaleProvider();
     WidgetsBinding.instance.addObserver(this);
+    _initHardwareVolumeControl();
+    // Listen to player selection changes to toggle volume interception
+    _musicProvider.addListener(_onProviderChanged);
+  }
+
+  Future<void> _initHardwareVolumeControl() async {
+    try {
+      _builtinPlayerId = await SettingsService.getBuiltinPlayerId();
+      await _hardwareVolumeService.init();
+
+      _volumeUpSub = _hardwareVolumeService.onVolumeUp.listen((_) {
+        _adjustVolume(_volumeStep);
+      });
+
+      _volumeDownSub = _hardwareVolumeService.onVolumeDown.listen((_) {
+        _adjustVolume(-_volumeStep);
+      });
+    } catch (e, stack) {
+      _logger.error('Hardware volume init failed', context: 'VolumeInit', error: e, stackTrace: stack);
+    }
+  }
+
+  /// Called when provider state changes - check if selected player changed
+  void _onProviderChanged() {
+    final currentPlayerId = _musicProvider.selectedPlayer?.playerId;
+    if (currentPlayerId != _lastSelectedPlayerId) {
+      _lastSelectedPlayerId = currentPlayerId;
+      _updateVolumeInterception();
+    }
+  }
+
+  /// Enable/disable volume button interception based on selected player.
+  Future<void> _updateVolumeInterception() async {
+    final isBuiltinPlayer = _builtinPlayerId != null &&
+        _musicProvider.selectedPlayer?.playerId == _builtinPlayerId;
+    await _hardwareVolumeService.setIntercepting(!isBuiltinPlayer);
+  }
+
+  Future<void> _adjustVolume(int delta) async {
+    final player = _musicProvider.selectedPlayer;
+    if (player == null) return;
+
+    final newVolume = (player.volume + delta).clamp(0, 100);
+    if (newVolume != player.volume) {
+      try {
+        await _musicProvider.setVolume(player.playerId, newVolume);
+      } catch (e) {
+        _logger.error('Hardware volume adjustment failed', context: 'VolumeControl', error: e);
+      }
+    }
   }
 
   @override
   void dispose() {
+    _musicProvider.removeListener(_onProviderChanged);
+    _volumeUpSub?.cancel();
+    _volumeDownSub?.cancel();
+    _hardwareVolumeService.dispose();
     WidgetsBinding.instance.removeObserver(this);
     super.dispose();
   }
 
+  @override
+  Future<bool> didPopRoute() async {
+    // Intercept back button at app level - runs BEFORE Navigator processes it
+    // Priority order: device list > 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
+    }
+
+    // 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();
+  }
+
   @override
   void didChangeAppLifecycleState(AppLifecycleState state) {
     super.didChangeAppLifecycleState(state);
 
     if (state == AppLifecycleState.resumed) {
       // App came back to foreground - check connection and reconnect if needed
-      print('📱 App resumed - checking WebSocket connection...');
-      _provider.checkAndReconnect();
+      _logger.log('📱 App resumed - checking WebSocket connection...');
+      _musicProvider.checkAndReconnect();
     } else if (state == AppLifecycleState.paused) {
-      print('📱 App paused (backgrounded)');
+      _logger.log('📱 App paused (backgrounded)');
     } else if (state == AppLifecycleState.detached) {
-      print('📱 App detached (being destroyed)');
+      _logger.log('📱 App detached (being destroyed)');
     }
   }
 
   @override
   Widget build(BuildContext context) {
-    return ChangeNotifierProvider.value(
-      value: _provider,
-      child: MaterialApp(
-        title: 'Amass',
-        debugShowCheckedModeBanner: false,
-        theme: ThemeData(
-          useMaterial3: true,
-          brightness: Brightness.dark,
-          primaryColor: const Color(0xFF1a1a1a),
-          scaffoldBackgroundColor: const Color(0xFF1a1a1a),
-          colorScheme: const ColorScheme.dark(
-            primary: Colors.white,
-            secondary: Colors.white70,
-            surface: Color(0xFF2a2a2a),
-            background: Color(0xFF1a1a1a),
-          ),
-          appBarTheme: const AppBarTheme(
-            backgroundColor: Colors.transparent,
-            elevation: 0,
-            systemOverlayStyle: SystemUiOverlayStyle.light,
-          ),
-          fontFamily: 'Roboto',
-        ),
-        home: const AppStartup(),
+    return MultiProvider(
+      providers: [
+        ChangeNotifierProvider.value(value: _musicProvider),
+        ChangeNotifierProvider.value(value: _themeProvider),
+        ChangeNotifierProvider.value(value: _localeProvider),
+      ],
+      child: Consumer2<ThemeProvider, LocaleProvider>(
+        builder: (context, themeProvider, localeProvider, _) {
+          return FutureBuilder<(ColorScheme, ColorScheme)?>(
+            future: themeProvider.useMaterialTheme
+                ? SystemThemeHelper.getSystemColorSchemes()
+                : null,
+            builder: (context, snapshot) {
+              // Determine which color schemes to use
+              ColorScheme? lightColorScheme;
+              ColorScheme? darkColorScheme;
+
+              if (themeProvider.useMaterialTheme && snapshot.hasData && snapshot.data != null) {
+                // Use system color schemes
+                final (light, dark) = snapshot.data!;
+                lightColorScheme = light;
+                darkColorScheme = dark;
+              } else {
+                // Use custom color from theme provider
+                lightColorScheme = generateLightColorScheme(themeProvider.customColor);
+                darkColorScheme = generateDarkColorScheme(themeProvider.customColor);
+              }
+
+              return SystemUIWrapper(
+                themeMode: themeProvider.themeMode,
+                lightColorScheme: lightColorScheme,
+                darkColorScheme: darkColorScheme,
+                child: MaterialApp(
+                  navigatorKey: navigationProvider.navigatorKey,
+                  title: 'Ensemble',
+                  debugShowCheckedModeBanner: false,
+                  // Localization
+                  localizationsDelegates: const [
+                    S.delegate,
+                    GlobalMaterialLocalizations.delegate,
+                    GlobalWidgetsLocalizations.delegate,
+                    GlobalCupertinoLocalizations.delegate,
+                  ],
+                  supportedLocales: S.supportedLocales,
+                  locale: localeProvider.locale,
+                  themeMode: themeProvider.themeMode,
+                  theme: AppTheme.lightTheme(colorScheme: lightColorScheme),
+                  darkTheme: AppTheme.darkTheme(colorScheme: darkColorScheme),
+                  builder: (context, child) {
+                    // Wrap entire app with global player overlay
+                    return GlobalPlayerOverlay(child: child ?? const SizedBox.shrink());
+                  },
+                  home: const AppStartup(),
+                ),
+              );
+            },
+          );
+        },
       ),
     );
   }
 }
 
-/// Startup widget that checks if user is logged in and shows appropriate screen
-class AppStartup extends StatelessWidget {
-  const AppStartup({super.key});
+/// Widget that manages system UI overlay style updates efficiently
+/// Only updates when theme properties actually change
+class SystemUIWrapper extends StatefulWidget {
+  final Widget child;
+  final ThemeMode themeMode;
+  final ColorScheme lightColorScheme;
+  final ColorScheme darkColorScheme;
+
+  const SystemUIWrapper({
+    super.key,
+    required this.child,
+    required this.themeMode,
+    required this.lightColorScheme,
+    required this.darkColorScheme,
+  });
+
+  @override
+  State<SystemUIWrapper> createState() => _SystemUIWrapperState();
+}
+
+class _SystemUIWrapperState extends State<SystemUIWrapper> {
+  ThemeMode? _previousThemeMode;
+  Brightness? _previousPlatformBrightness;
+  ColorScheme? _previousLightColorScheme;
+  ColorScheme? _previousDarkColorScheme;
+
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    _updateSystemUIIfNeeded();
+  }
+
+  @override
+  void didUpdateWidget(SystemUIWrapper oldWidget) {
+    super.didUpdateWidget(oldWidget);
+    _updateSystemUIIfNeeded();
+  }
+
+  void _updateSystemUIIfNeeded() {
+    final platformBrightness = MediaQuery.platformBrightnessOf(context);
+
+    // Check if any relevant properties have changed
+    final themeChanged = _previousThemeMode != widget.themeMode;
+    final platformBrightnessChanged = _previousPlatformBrightness != platformBrightness;
+    final lightColorSchemeChanged = _previousLightColorScheme != widget.lightColorScheme;
+    final darkColorSchemeChanged = _previousDarkColorScheme != widget.darkColorScheme;
+
+    if (themeChanged || platformBrightnessChanged || lightColorSchemeChanged || darkColorSchemeChanged) {
+      // Determine if we should use dark theme
+      final isDark = widget.themeMode == ThemeMode.dark ||
+          (widget.themeMode == ThemeMode.system && platformBrightness == Brightness.dark);
+
+      // Update system UI overlay style
+      SystemChrome.setSystemUIOverlayStyle(
+        SystemUiOverlayStyle(
+          statusBarColor: Colors.transparent,
+          statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+          systemNavigationBarColor: isDark
+              ? widget.darkColorScheme.background
+              : widget.lightColorScheme.background,
+          systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+        ),
+      );
+
+      // Update cached values
+      _previousThemeMode = widget.themeMode;
+      _previousPlatformBrightness = platformBrightness;
+      _previousLightColorScheme = widget.lightColorScheme;
+      _previousDarkColorScheme = widget.darkColorScheme;
+    }
+  }
 
   @override
   Widget build(BuildContext context) {
-    return FutureBuilder<String?>(
-      future: SettingsService.getServerUrl(),
-      builder: (context, snapshot) {
-        // Show loading while checking settings
-        if (snapshot.connectionState == ConnectionState.waiting) {
-          return const Scaffold(
-            backgroundColor: Color(0xFF1a1a1a),
-            body: Center(
-              child: CircularProgressIndicator(color: Colors.white),
-            ),
-          );
-        }
-
-        // If server URL is saved, go to home screen
-        // Otherwise, show login screen
-        final hasServerUrl = snapshot.data != null && snapshot.data!.isNotEmpty;
-        return hasServerUrl ? const HomeScreen() : const LoginScreen();
-      },
-    );
+    return widget.child;
+  }
+}
+
+/// 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});
+
+  @override
+  State<AppStartup> createState() => _AppStartupState();
+}
+
+class _AppStartupState extends State<AppStartup> {
+  bool _isConnecting = false;
+  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();
+  }
+
+  Future<void> _checkAndConnect() async {
+    final serverUrl = await SettingsService.getServerUrl();
+
+    if (!mounted) return;
+
+    setState(() {
+      _savedServerUrl = serverUrl;
+    });
+
+    // If we have a saved server URL, attempt auto-connection
+    if (serverUrl != null && serverUrl.isNotEmpty) {
+      setState(() {
+        _isConnecting = true;
+      });
+
+      final provider = context.read<MusicAssistantProvider>();
+
+      // Connection is handled by MusicAssistantProvider._initialize()
+      // 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 (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;
+        }
+      }
+
+      if (!provider.isConnected) {
+        _logger.log('🚀 AppStartup: Connection still pending or failed');
+      }
+
+      if (mounted) {
+        setState(() {
+          _isConnecting = false;
+          _connectionAttempted = true;
+        });
+      }
+    } else {
+      setState(() {
+        _connectionAttempted = true;
+      });
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // Show loading while checking settings or connecting
+    // CRITICAL: Don't transition until settings are loaded - this prevents the race
+    if (!_settingsLoaded || !_connectionAttempted || _isConnecting) {
+      return Scaffold(
+        backgroundColor: const Color(0xFF1a1a1a),
+        body: Center(
+          child: Column(
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: [
+              const CircularProgressIndicator(color: Colors.white),
+              if (_isConnecting) ...[
+                const SizedBox(height: 16),
+                Text(
+                  'Connecting...',
+                  style: TextStyle(
+                    color: Colors.white.withOpacity(0.7),
+                    fontSize: 14,
+                  ),
+                ),
+              ],
+            ],
+          ),
+        ),
+      );
+    }
+
+    // If server URL is saved, go to home screen
+    // Otherwise, show login screen
+    final hasServerUrl = _savedServerUrl != null && _savedServerUrl!.isNotEmpty;
+    return hasServerUrl ? const HomeScreen() : const LoginScreen();
   }
 }

lib/models/media_item.dart

@@ -4,6 +4,10 @@ enum MediaType {
   track,
   playlist,
   radio,
+  audiobook,
+  chapter,
+  podcast,
+  podcastEpisode,
 }
 
 class ProviderMapping {
@@ -106,7 +110,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 +145,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 +161,7 @@ class Album extends MediaItem {
     required super.name,
     this.artists,
     this.albumType,
+    this.year,
     super.sortName,
     super.uri,
     super.providerMappings,
@@ -161,6 +171,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 +188,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 +199,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 +266,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 +314,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?,
+    );
+  }
+}

lib/models/player.dart

@@ -3,6 +3,7 @@ import 'media_item.dart';
 class Player {
   final String playerId;
   final String name;
+  final String? provider; // e.g., 'builtin_player', 'chromecast', etc.
   final bool available;
   final bool powered;
   final String state; // 'idle', 'playing', 'paused'
@@ -11,10 +12,15 @@ 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
 
   Player({
     required this.playerId,
     required this.name,
+    this.provider,
     required this.available,
     required this.powered,
     required this.state,
@@ -23,23 +29,119 @@ class Player {
     this.volumeMuted,
     this.elapsedTime,
     this.elapsedTimeLastUpdated,
+    this.groupMembers,
+    this.syncedTo,
+    this.activeSource,
+    this.isExternalSource = false,
   });
 
+  /// 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,
+  }) {
+    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,
+    );
+  }
+
   // 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;
+
+  // Track when this Player object was created (for local interpolation fallback)
+  static final Map<String, double> _playerCreationTimes = {};
+
   // Calculate current elapsed time (interpolated if playing)
   double get currentElapsedTime {
-    if (elapsedTime == null || elapsedTimeLastUpdated == null) return 0;
+    if (elapsedTime == null) {
+      return 0;
+    }
 
-    if (!isPlaying) return elapsedTime!;
+    if (!isPlaying) {
+      return elapsedTime!;
+    }
 
-    // If playing, interpolate based on time since last update
     final now = DateTime.now().millisecondsSinceEpoch / 1000.0;
-    final timeSinceUpdate = now - elapsedTimeLastUpdated!;
-    return elapsedTime! + timeSinceUpdate;
+
+    // Try server-provided timestamp first, but only if it's recent
+    if (elapsedTimeLastUpdated != null) {
+      final timeSinceUpdate = now - elapsedTimeLastUpdated!;
+
+      // Only use server timestamp if it's within valid range (0-10 seconds)
+      // - Negative means clock skew (client ahead of server)
+      // - > 10 seconds means stale data (e.g., after player switch)
+      // If outside this range, fall through to local fallback for smooth interpolation
+      if (timeSinceUpdate >= 0 && timeSinceUpdate <= 10.0) {
+        return elapsedTime! + timeSinceUpdate;
+      }
+      // Server timestamp is stale or invalid - fall through to local fallback
+    }
+
+    // Fallback: use local creation time for interpolation
+    // This handles:
+    // 1. Server doesn't send elapsed_time_last_updated
+    // 2. Server timestamp is stale (e.g., after switching to a remote player)
+    // 3. Clock skew between client and server
+    //
+    // Key insight: when server sends a NEW elapsed_time, we get a NEW key,
+    // so interpolation naturally starts fresh. We should NEVER reset an existing
+    // key's creation time, as that causes progress to jump backward.
+    final creationKey = '$playerId:$elapsedTime';
+
+    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);
+        }
+      }
+    }
+
+    final creationTime = _playerCreationTimes[creationKey]!;
+    final timeSinceCreation = now - creationTime;
+
+    // Server sends updates every ~5 seconds with new elapsed_time values,
+    // which creates new keys and corrects any drift. Allow unlimited
+    // interpolation since new server data will naturally correct it.
+    return elapsedTime! + timeSinceCreation;
   }
 
   factory Player.fromJson(Map<String, dynamic> json) {
@@ -48,25 +150,88 @@ class Player {
     double? elapsedTime;
     double? elapsedTimeLastUpdated;
 
-    // IMPORTANT: Check top-level fields FIRST - they have the most current data
-    elapsedTime = (json['elapsed_time'] as num?)?.toDouble();
-    elapsedTimeLastUpdated = (json['elapsed_time_last_updated'] as num?)?.toDouble();
+    // Get top-level elapsed time values
+    // Try multiple field names as different player types may report position differently
+    final topLevelElapsedTime = (json['elapsed_time'] as num?)?.toDouble()
+        ?? (json['position'] as num?)?.toDouble()
+        ?? (json['media_position'] as num?)?.toDouble()
+        ?? (json['current_position'] as num?)?.toDouble();
+    final topLevelLastUpdated = (json['elapsed_time_last_updated'] as num?)?.toDouble()
+        ?? (json['position_updated_at'] as num?)?.toDouble();
 
-    if (elapsedTime != null) {
-      print('✅ Player ${json['name']}: Using top-level elapsed_time: $elapsedTime seconds (updated: $elapsedTimeLastUpdated)');
-    }
-
-    // Extract current_item_id from current_media
+    // Extract current_item_id and elapsed time from current_media
+    // current_media often has the more accurate position after seeks
     if (json.containsKey('current_media')) {
       final currentMedia = json['current_media'] as Map<String, dynamic>?;
       if (currentMedia != null) {
         currentItemId ??= currentMedia['queue_item_id'] as String?;
 
-        // Only use current_media elapsed_time if we don't have top-level (fallback)
-        if (elapsedTime == null) {
-          elapsedTime = (currentMedia['elapsed_time'] as num?)?.toDouble();
-          elapsedTimeLastUpdated = (currentMedia['elapsed_time_last_updated'] as num?)?.toDouble();
-          print('⚠️ Player ${json['name']}: Falling back to current_media elapsed_time: $elapsedTime seconds');
+        // Try multiple field names for position
+        final currentMediaElapsedTime = (currentMedia['elapsed_time'] as num?)?.toDouble()
+            ?? (currentMedia['position'] as num?)?.toDouble()
+            ?? (currentMedia['media_position'] as num?)?.toDouble();
+        final currentMediaLastUpdated = (currentMedia['elapsed_time_last_updated'] as num?)?.toDouble()
+            ?? (currentMedia['position_updated_at'] as num?)?.toDouble();
+
+        // Prefer current_media elapsed_time when available - it reflects actual playback position
+        // after seek operations, while top-level elapsed_time may lag behind
+        if (currentMediaElapsedTime != null) {
+          elapsedTime = currentMediaElapsedTime;
+          elapsedTimeLastUpdated = currentMediaLastUpdated ?? topLevelLastUpdated;
+        }
+      }
+    }
+
+    // Fall back to top-level values if current_media didn't have elapsed time
+    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.)
+    // External sources have non-MA URIs and often media_type='unknown'
+    bool isExternalSource = false;
+    if (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;
+          }
         }
       }
     }
@@ -74,14 +239,19 @@ class Player {
     return Player(
       playerId: json['player_id'] as String,
       name: json['name'] as String,
+      provider: json['provider'] as String?,
       available: json['available'] as bool? ?? false,
       powered: json['powered'] as bool? ?? false,
-      state: json['state'] as String? ?? 'idle',
+      state: json['playback_state'] as String? ?? json['state'] as String? ?? 'idle',
       currentItemId: currentItemId,
       volumeLevel: json['volume_level'] as int?,
       volumeMuted: json['volume_muted'] as bool?,
       elapsedTime: elapsedTime,
       elapsedTimeLastUpdated: elapsedTimeLastUpdated,
+      groupMembers: groupMembers,
+      syncedTo: syncedTo,
+      activeSource: activeSource,
+      isExternalSource: isExternalSource,
     );
   }
 
@@ -89,6 +259,7 @@ class Player {
     return {
       'player_id': playerId,
       'name': name,
+      if (provider != null) 'provider': provider,
       'available': available,
       'powered': powered,
       'state': state,
@@ -97,6 +268,10 @@ 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,
     };
   }
 }

lib/providers/connection_provider.dart

@@ -0,0 +1,258 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import '../services/music_assistant_api.dart';
+import '../services/settings_service.dart';
+import '../services/database_service.dart';
+import '../services/profile_service.dart';
+import '../services/debug_logger.dart';
+import '../services/error_handler.dart';
+import '../services/auth/auth_manager.dart';
+import '../services/cache_service.dart';
+
+/// Provider for managing connection state to Music Assistant server
+/// 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 + create/activate local profile
+  Future<void> _fetchAndSetUserProfileName() async {
+    if (_api == null) return;
+
+    try {
+      final userInfo = await _api!.getCurrentUserInfo();
+      if (userInfo == null) {
+        _logger.log('⚠️ Could not fetch user profile');
+        return;
+      }
+
+      final displayName = userInfo['display_name'] as String?;
+      final username = userInfo['username'] as String?;
+
+      _logger.log('🔍 Profile data: display_name="$displayName", username="$username"');
+
+      final profileName = (displayName != null && displayName.isNotEmpty)
+          ? displayName
+          : username;
+
+      if (profileName != null && profileName.isNotEmpty) {
+        await SettingsService.setOwnerName(profileName);
+        _logger.log('✅ Set owner name from MA profile: $profileName');
+
+        // Create/activate profile in local database
+        if (DatabaseService.instance.isInitialized && username != null) {
+          await ProfileService.instance.onMaAuthenticated(
+            username: username,
+            displayName: displayName,
+          );
+          _logger.log('✅ Local profile activated: $username');
+        }
+      } else {
+        _logger.log('⚠️ No valid name in profile');
+      }
+    } catch (e) {
+      _logger.log('⚠️ Could not fetch user profile (non-fatal): $e');
+    }
+  }
+
+  Future<void> connectToServer(String serverUrl) async {
+    try {
+      _error = null;
+      _serverUrl = serverUrl;
+      await SettingsService.setServerUrl(serverUrl);
+
+      // Disconnect existing connection
+      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) {
+            // DON'T clear caches on disconnect - keep showing cached data
+            // This allows instant UI display when app resumes or reconnects
+            // Caches will be refreshed when connection is restored
+            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;
+    // DON'T clear caches on disconnect - keep showing cached data for instant reconnect
+    notifyListeners();
+  }
+
+  /// Clear all caches and state (for logout or server change)
+  void clearCachesOnLogout() {
+    _cacheService.clearAll();
+    notifyListeners();
+  }
+
+  /// Check connection and reconnect if needed (called when app resumes)
+  Future<void> checkAndReconnect() async {
+    _logger.log('🔄 checkAndReconnect called - state: $_connectionState');
+
+    if (_serverUrl == null) {
+      _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();
+  }
+}

lib/providers/library_provider.dart

@@ -0,0 +1,383 @@
+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();
+  }
+}

lib/providers/locale_provider.dart

@@ -0,0 +1,40 @@
+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 null:
+        return 'System';
+      default:
+        return languageCode;
+    }
+  }
+}

lib/providers/navigation_provider.dart

@@ -0,0 +1,40 @@
+import 'package:flutter/material.dart';
+
+/// Global navigation state for bottom navigation bar
+class NavigationProvider extends ChangeNotifier {
+  int _selectedIndex = 0;
+
+  /// Global navigator key for pushing routes from anywhere
+  final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();
+
+  /// Callback to focus search when search tab is selected
+  VoidCallback? onSearchTabSelected;
+
+  int get selectedIndex => _selectedIndex;
+
+  void setSelectedIndex(int index) {
+    final previousIndex = _selectedIndex;
+    if (previousIndex != index) {
+      _selectedIndex = index;
+      notifyListeners();
+
+      // Trigger search focus callback when switching to search tab
+      if (index == 2 && onSearchTabSelected != null) {
+        // Use post-frame callback to ensure SearchScreen is built first
+        WidgetsBinding.instance.addPostFrameCallback((_) {
+          onSearchTabSelected?.call();
+        });
+      }
+    }
+  }
+
+  /// Pop all routes and return to the home tab
+  void popToHome() {
+    // Pop all routes above the root
+    navigatorKey.currentState?.popUntil((route) => route.isFirst);
+    setSelectedIndex(0);
+  }
+}
+
+/// Global instance for easy access
+final navigationProvider = NavigationProvider();

lib/providers/player_provider.dart

@@ -0,0 +1,964 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import 'package:flutter/painting.dart';
+import '../models/media_item.dart';
+import '../models/player.dart';
+import '../services/music_assistant_api.dart';
+import '../services/settings_service.dart';
+import '../services/debug_logger.dart';
+import '../services/error_handler.dart';
+import '../services/local_player_service.dart';
+import '../services/auth/auth_manager.dart';
+import '../services/device_id_service.dart';
+import '../services/cache_service.dart';
+import '../constants/timings.dart';
+import '../main.dart' show audioHandler;
+
+/// Provider for managing player state, selection, and controls
+class PlayerProvider with ChangeNotifier {
+  final DebugLogger _logger = DebugLogger();
+  late final LocalPlayerService _localPlayer;
+  final CacheService _cacheService;
+
+  // Dependencies injected from parent provider
+  MusicAssistantAPI? _api;
+  AuthManager? _authManager;
+  String? _serverUrl;
+
+  // Player selection
+  Player? _selectedPlayer;
+  List<Player> _availablePlayers = [];
+  Track? _currentTrack;
+  Timer? _playerStateTimer;
+  Timer? _adjacentPlayerCacheTimer;
+
+  // Local Playback
+  bool _isLocalPlayerPowered = true;
+  StreamSubscription? _localPlayerEventSubscription;
+  StreamSubscription? _playerUpdatedEventSubscription;
+  Timer? _localPlayerStateReportTimer;
+
+  // Pending metadata from player_updated events
+  TrackMetadata? _pendingTrackMetadata;
+  TrackMetadata? _currentNotificationMetadata;
+
+  // Registration guard
+  Completer<void>? _registrationInProgress;
+
+  // Getters
+  Player? get selectedPlayer => _selectedPlayer;
+  List<Player> get availablePlayers => _availablePlayers;
+  Track? get currentTrack => _currentTrack;
+  bool get isLocalPlayerPowered => _isLocalPlayerPowered;
+
+  /// Get cached track for a player (used for smooth swipe transitions)
+  Track? getCachedTrackForPlayer(String playerId) => _cacheService.getCachedTrackForPlayer(playerId);
+
+  PlayerProvider(this._cacheService, AuthManager authManager) {
+    _authManager = authManager;
+    _localPlayer = LocalPlayerService(authManager);
+  }
+
+  /// Initialize with API reference after connection
+  void initialize(MusicAssistantAPI api, String serverUrl) {
+    _api = api;
+    _serverUrl = serverUrl;
+  }
+
+  /// Set up event listeners after connection
+  Future<void> setupEventListeners() async {
+    if (_api == null) return;
+
+    // Listen to built-in player events
+    _localPlayerEventSubscription?.cancel();
+    _localPlayerEventSubscription = _api!.builtinPlayerEvents.listen(
+      _handleLocalPlayerEvent,
+      onError: (error) {
+        _logger.log('Builtin player event stream error: $error');
+      },
+    );
+
+    // Listen to player_updated events
+    _playerUpdatedEventSubscription?.cancel();
+    _playerUpdatedEventSubscription = _api!.playerUpdatedEvents.listen(
+      _handlePlayerUpdatedEvent,
+      onError: (error) {
+        _logger.log('Player updated event stream error: $error');
+      },
+    );
+  }
+
+  /// Initialize local playback
+  Future<void> initializeLocalPlayback() async {
+    await _localPlayer.initialize();
+    _isLocalPlayerPowered = true;
+
+    // Wire up skip button callbacks
+    audioHandler.onSkipToNext = () {
+      _logger.log('🎵 Notification: Skip to next pressed');
+      nextTrackSelectedPlayer();
+    };
+    audioHandler.onSkipToPrevious = () {
+      _logger.log('🎵 Notification: Skip to previous pressed');
+      previousTrackSelectedPlayer();
+    };
+
+    if (_api != null) {
+      await registerLocalPlayer();
+    }
+  }
+
+  /// Try to adopt an existing ghost player
+  Future<bool> tryAdoptGhostPlayer() async {
+    if (_api == null) return false;
+
+    try {
+      final isFresh = await DeviceIdService.isFreshInstallation();
+      if (!isFresh) {
+        _logger.log('👻 Not a fresh install, skipping ghost adoption');
+        return false;
+      }
+
+      final ownerName = await SettingsService.getOwnerName();
+      if (ownerName == null || ownerName.isEmpty) {
+        _logger.log('👻 No owner name set, cannot adopt ghost player');
+        return false;
+      }
+
+      _logger.log('👻 Fresh install detected, searching for adoptable ghost for "$ownerName"...');
+      final adoptableId = await _api!.findAdoptableGhostPlayer(ownerName);
+      if (adoptableId == null) {
+        _logger.log('👻 No matching ghost player found - will generate new ID');
+        return false;
+      }
+
+      _logger.log('👻 Found adoptable ghost: $adoptableId');
+      await DeviceIdService.adoptPlayerId(adoptableId);
+
+      _logger.log('✅ Successfully adopted ghost player');
+      return true;
+    } catch (e) {
+      _logger.log('⚠️ Ghost adoption failed (non-fatal): $e');
+      return false;
+    }
+  }
+
+  /// Register local player with MA server
+  Future<void> registerLocalPlayer() async {
+    if (_api == null) return;
+
+    if (_registrationInProgress != null) {
+      _logger.log('⏳ Registration already in progress, waiting...');
+      return _registrationInProgress!.future;
+    }
+
+    _registrationInProgress = Completer<void>();
+
+    try {
+      final playerId = await DeviceIdService.getOrCreateDevicePlayerId();
+      _logger.log('🆔 Using player ID: $playerId');
+
+      await SettingsService.setBuiltinPlayerId(playerId);
+      final name = await SettingsService.getLocalPlayerName();
+
+      final existingPlayers = await _api!.getPlayers();
+      final existingPlayer = existingPlayers.where((p) => p.playerId == playerId).firstOrNull;
+
+      if (existingPlayer != null && existingPlayer.available) {
+        _logger.log('✅ Player already registered and available: $playerId');
+        _startReportingLocalPlayerState();
+        if (_registrationInProgress != null && !_registrationInProgress!.isCompleted) {
+          _registrationInProgress!.complete();
+        }
+        _registrationInProgress = null;
+        return;
+      } else if (existingPlayer != null && !existingPlayer.available) {
+        _logger.log('⚠️ Player exists but unavailable (stale), re-registering: $playerId');
+      } else {
+        _logger.log('🆔 Player not found in MA, registering as new');
+      }
+
+      _logger.log('🎵 Registering player with MA: id=$playerId, name=$name');
+      await _api!.registerBuiltinPlayer(playerId, name);
+
+      _logger.log('✅ Player registration complete');
+      _startReportingLocalPlayerState();
+
+      if (_registrationInProgress != null && !_registrationInProgress!.isCompleted) {
+        _registrationInProgress!.complete();
+      }
+      _registrationInProgress = null;
+    } catch (e) {
+      _logger.log('❌ CRITICAL: Player registration failed: $e');
+      if (_registrationInProgress != null && !_registrationInProgress!.isCompleted) {
+        _registrationInProgress!.completeError(e);
+      }
+      _registrationInProgress = null;
+      rethrow;
+    }
+  }
+
+  void _startReportingLocalPlayerState() {
+    _localPlayerStateReportTimer?.cancel();
+    _localPlayerStateReportTimer = Timer.periodic(Timings.localPlayerReportInterval, (_) async {
+      try {
+        await _reportLocalPlayerState();
+      } catch (e) {
+        _logger.log('Error reporting local player state (will retry): $e');
+      }
+    });
+  }
+
+  Future<void> _reportLocalPlayerState() async {
+    if (_api == null) return;
+
+    // Don't try to report state if not authenticated - avoids spamming errors
+    if (_api!.currentConnectionState != MAConnectionState.authenticated) return;
+
+    final playerId = await SettingsService.getBuiltinPlayerId();
+    if (playerId == null) return;
+
+    final isPlaying = _localPlayer.isPlaying;
+    final position = _localPlayer.position.inSeconds;
+    final volume = (_localPlayer.volume * 100).round();
+    final isPaused = !isPlaying && position > 0;
+
+    await _api!.updateBuiltinPlayerState(
+      playerId,
+      powered: _isLocalPlayerPowered,
+      playing: isPlaying,
+      paused: isPaused,
+      position: position,
+      volume: volume,
+      muted: _localPlayer.volume == 0.0,
+    );
+  }
+
+  Future<void> _handleLocalPlayerEvent(Map<String, dynamic> event) async {
+    _logger.log('📥 Local player event received: ${event['type'] ?? event['command']}');
+
+    try {
+      final eventPlayerId = event['player_id'] as String?;
+      final myPlayerId = await SettingsService.getBuiltinPlayerId();
+
+      if (eventPlayerId != null && myPlayerId != null && eventPlayerId != myPlayerId) {
+        _logger.log('🚫 Ignoring event for different player: $eventPlayerId');
+        return;
+      }
+
+      final command = (event['type'] as String?) ?? (event['command'] as String?);
+
+      switch (command) {
+        case 'play_media':
+          final urlPath = event['media_url'] as String? ?? event['url'] as String?;
+
+          if (urlPath != null && _serverUrl != null) {
+            String fullUrl;
+            if (urlPath.startsWith('http')) {
+              fullUrl = urlPath;
+            } else {
+              var baseUrl = _serverUrl!;
+              if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+                baseUrl = 'https://$baseUrl';
+              }
+              baseUrl = baseUrl.endsWith('/') ? baseUrl.substring(0, baseUrl.length - 1) : baseUrl;
+              final path = urlPath.startsWith('/') ? urlPath : '/$urlPath';
+              fullUrl = '$baseUrl$path';
+            }
+
+            TrackMetadata metadata;
+            if (_pendingTrackMetadata != null) {
+              metadata = _pendingTrackMetadata!;
+            } else {
+              final trackName = event['track_name'] as String? ?? event['name'] as String? ?? 'Unknown Track';
+              final artistName = event['artist_name'] as String? ?? event['artist'] as String? ?? 'Unknown Artist';
+              final albumName = event['album_name'] as String? ?? event['album'] as String?;
+              var artworkUrl = event['image_url'] as String? ?? event['artwork_url'] as String?;
+              final durationSecs = event['duration'] as int?;
+
+              if (artworkUrl != null && artworkUrl.startsWith('http://')) {
+                artworkUrl = artworkUrl.replaceFirst('http://', 'https://');
+              }
+
+              metadata = TrackMetadata(
+                title: trackName,
+                artist: artistName,
+                album: albumName,
+                artworkUrl: artworkUrl,
+                duration: durationSecs != null ? Duration(seconds: durationSecs) : null,
+              );
+            }
+
+            _localPlayer.setCurrentTrackMetadata(metadata);
+            _currentNotificationMetadata = metadata;
+            await _localPlayer.playUrl(fullUrl);
+          }
+          break;
+
+        case 'stop':
+          await _localPlayer.stop();
+          break;
+
+        case 'pause':
+          await _localPlayer.pause();
+          break;
+
+        case 'play':
+          await _localPlayer.play();
+          break;
+
+        case 'seek':
+          final position = event['position'] as int?;
+          if (position != null) {
+            await _localPlayer.seek(Duration(seconds: position));
+          }
+          break;
+
+        case 'volume_set':
+          final volume = event['volume_level'] as int?;
+          if (volume != null) {
+            await _localPlayer.setVolume(volume / 100.0);
+          }
+          break;
+
+        case 'power_on':
+        case 'power_off':
+        case 'power':
+          bool? newPowerState;
+          if (command == 'power_on') {
+            newPowerState = true;
+          } else if (command == 'power_off') {
+            newPowerState = false;
+          } else {
+            newPowerState = event['powered'] as bool?;
+          }
+
+          if (newPowerState != null) {
+            _isLocalPlayerPowered = newPowerState;
+            if (!_isLocalPlayerPowered) {
+              await _localPlayer.stop();
+            }
+          }
+          break;
+      }
+
+      await _reportLocalPlayerState();
+    } catch (e) {
+      _logger.log('Error handling local player event: $e');
+    }
+  }
+
+  Future<void> _handlePlayerUpdatedEvent(Map<String, dynamic> event) async {
+    try {
+      final playerId = event['player_id'] as String?;
+      if (playerId == null) return;
+
+      if (_selectedPlayer != null && playerId == _selectedPlayer!.playerId) {
+        _updatePlayerState();
+      }
+
+      final currentMedia = event['current_media'] as Map<String, dynamic>?;
+      final playerName = event['name'] as String? ?? playerId;
+
+      if (currentMedia != null) {
+        final mediaType = currentMedia['media_type'] as String?;
+        if (mediaType != 'flow_stream') {
+          final durationSecs = (currentMedia['duration'] as num?)?.toInt();
+          final albumName = currentMedia['album'] as String?;
+          final imageUrl = currentMedia['image_url'] as String?;
+
+          Map<String, dynamic>? metadata;
+          if (imageUrl != null && _serverUrl != null) {
+            var finalImageUrl = imageUrl;
+            try {
+              final imgUri = Uri.parse(imageUrl);
+              final queryString = imgUri.query;
+              var baseUrl = _serverUrl!;
+              if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+                baseUrl = 'https://$baseUrl';
+              }
+              if (baseUrl.endsWith('/')) {
+                baseUrl = baseUrl.substring(0, baseUrl.length - 1);
+              }
+              finalImageUrl = '$baseUrl/imageproxy?$queryString';
+            } catch (e) {
+              // Use original URL
+            }
+            metadata = {
+              'images': [{'path': finalImageUrl, 'provider': 'direct'}]
+            };
+          }
+
+          final trackFromEvent = Track(
+            itemId: currentMedia['queue_item_id'] as String? ?? '',
+            provider: 'library',
+            name: currentMedia['title'] as String? ?? 'Unknown Track',
+            uri: currentMedia['uri'] as String?,
+            duration: durationSecs != null ? Duration(seconds: durationSecs) : null,
+            artists: [Artist(itemId: '', provider: 'library', name: currentMedia['artist'] as String? ?? 'Unknown Artist')],
+            album: albumName != null ? Album(itemId: '', provider: 'library', name: albumName) : null,
+            metadata: metadata,
+          );
+
+          _cacheService.setCachedTrackForPlayer(playerId, trackFromEvent);
+
+          if (_selectedPlayer != null && playerId == _selectedPlayer!.playerId) {
+            _currentTrack = trackFromEvent;
+          }
+
+          _logger.log('📋 Cached track for $playerName: ${trackFromEvent.name}');
+
+          if (imageUrl != null) {
+            final images = metadata?['images'] as List?;
+            if (images != null && images.isNotEmpty) {
+              final imagePath = images[0]['path'] as String?;
+              if (imagePath != null) {
+                _precacheImage(imagePath);
+              }
+            }
+          }
+
+          notifyListeners();
+        }
+      }
+
+      // Handle notification metadata for local player
+      final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
+      if (builtinPlayerId == null || playerId != builtinPlayerId) return;
+
+      if (currentMedia == null) return;
+
+      final title = currentMedia['title'] as String? ?? 'Unknown Track';
+      final artist = currentMedia['artist'] as String? ?? 'Unknown Artist';
+      final album = currentMedia['album'] as String?;
+      var imageUrl = currentMedia['image_url'] as String?;
+      final durationSecs = (currentMedia['duration'] as num?)?.toInt();
+
+      if (imageUrl != null && _serverUrl != null) {
+        try {
+          final imgUri = Uri.parse(imageUrl);
+          final queryString = imgUri.query;
+          var baseUrl = _serverUrl!;
+          if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+            baseUrl = 'https://$baseUrl';
+          }
+          if (baseUrl.endsWith('/')) {
+            baseUrl = baseUrl.substring(0, baseUrl.length - 1);
+          }
+          imageUrl = '$baseUrl/imageproxy?$queryString';
+        } catch (e) {
+          if (imageUrl != null && imageUrl.startsWith('http://')) {
+            imageUrl = imageUrl.replaceFirst('http://', 'https://');
+          }
+        }
+      }
+
+      final newMetadata = TrackMetadata(
+        title: title,
+        artist: artist,
+        album: album,
+        artworkUrl: imageUrl,
+        duration: durationSecs != null ? Duration(seconds: durationSecs) : null,
+      );
+
+      final mediaType = currentMedia['media_type'] as String?;
+      if (mediaType == 'flow_stream') return;
+
+      _pendingTrackMetadata = newMetadata;
+
+      final notificationNeedsUpdate = _currentNotificationMetadata != null &&
+          (_currentNotificationMetadata!.title != title ||
+           _currentNotificationMetadata!.artist != artist);
+
+      if (_localPlayer.isPlaying && notificationNeedsUpdate) {
+        await _localPlayer.updateNotificationWhilePlaying(newMetadata);
+        _currentNotificationMetadata = newMetadata;
+      }
+    } catch (e) {
+      _logger.log('Error handling player_updated event: $e');
+    }
+  }
+
+  // ============================================================================
+  // PLAYER SELECTION
+  // ============================================================================
+
+  Future<void> loadAndSelectPlayers({bool forceRefresh = false}) async {
+    if (_api == null) return;
+
+    try {
+      if (!forceRefresh && _cacheService.isPlayersCacheValid() && _availablePlayers.isNotEmpty) {
+        return;
+      }
+
+      final allPlayers = await _api!.getPlayers();
+      final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
+
+      _logger.log('🎛️ getPlayers returned ${allPlayers.length} players');
+
+      int filteredCount = 0;
+
+      _availablePlayers = allPlayers.where((player) {
+        final nameLower = player.name.toLowerCase();
+
+        if (nameLower.contains('music assistant mobile')) {
+          filteredCount++;
+          return false;
+        }
+
+        // Filter out MA Web UI's built-in player (provider is 'builtin_player' and starts with 'ma_')
+        // Note: We check BOTH conditions to avoid filtering snapcast/other players that may have 'ma_' prefix
+        if (player.provider == 'builtin_player' && player.playerId.startsWith('ma_')) {
+          filteredCount++;
+          return false;
+        }
+
+        // Also filter "This Device" named players without proper provider
+        if (nameLower == 'this device') {
+          filteredCount++;
+          return false;
+        }
+
+        if (player.playerId.startsWith('ensemble_')) {
+          if (builtinPlayerId == null || player.playerId != builtinPlayerId) {
+            filteredCount++;
+            return false;
+          }
+        }
+
+        if (!player.available) {
+          if (builtinPlayerId != null && player.playerId == builtinPlayerId) {
+            return true;
+          }
+          filteredCount++;
+          return false;
+        }
+
+        return true;
+      }).toList();
+
+      _availablePlayers.sort((a, b) => a.name.toLowerCase().compareTo(b.name.toLowerCase()));
+      _cacheService.updatePlayersLastFetched();
+
+      _logger.log('🎛️ After filtering: ${_availablePlayers.length} players available');
+
+      if (_availablePlayers.isNotEmpty) {
+        Player? playerToSelect;
+
+        if (_selectedPlayer != null) {
+          final stillAvailable = _availablePlayers.any(
+            (p) => p.playerId == _selectedPlayer!.playerId && p.available,
+          );
+          if (stillAvailable) {
+            playerToSelect = _availablePlayers.firstWhere(
+              (p) => p.playerId == _selectedPlayer!.playerId,
+            );
+          }
+        }
+
+        if (playerToSelect == null) {
+          final lastSelectedPlayerId = await SettingsService.getLastSelectedPlayerId();
+
+          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();
+  }
+}

lib/screens/audiobook_author_screen.dart

@@ -0,0 +1,546 @@
+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: CustomScrollView(
+          slivers: [
+            SliverAppBar(
+              expandedHeight: 200,
+              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: 200,
+                        height: 200,
+                        decoration: BoxDecoration(
+                          color: colorScheme.primaryContainer,
+                          shape: BoxShape.circle,
+                        ),
+                        child: ClipOval(
+                          child: _authorImageUrl != null
+                              ? CachedNetworkImage(
+                                  imageUrl: _authorImageUrl!,
+                                  fit: BoxFit.cover,
+                                  width: 200,
+                                  height: 200,
+                                  fadeInDuration: Duration.zero,
+                                  fadeOutDuration: Duration.zero,
+                                  placeholder: (_, __) => Icon(
+                                    MdiIcons.accountOutline,
+                                    size: 100,
+                                    color: colorScheme.onPrimaryContainer,
+                                  ),
+                                  errorWidget: (_, __, ___) => Icon(
+                                    MdiIcons.accountOutline,
+                                    size: 100,
+                                    color: colorScheme.onPrimaryContainer,
+                                  ),
+                                )
+                              : Icon(
+                                  MdiIcons.accountOutline,
+                                  size: 100,
+                                  color: colorScheme.onPrimaryContainer,
+                                ),
+                        ),
+                      ),
+                    ),
+                  ],
+                ),
+              ),
+            ),
+            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(),
+            const SliverToBoxAdapter(child: SizedBox(height: 140)),
+          ],
+        ),
+      ),
+    );
+  }
+
+  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';
+  }
+}

lib/screens/audiobook_series_screen.dart

@@ -0,0 +1,845 @@
+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: CustomScrollView(
+        slivers: [
+          // App bar with series cover collage (matches audiobook detail screen)
+          SliverAppBar(
+            expandedHeight: 350,
+            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 - same size as audiobook detail cover
+                  Hero(
+                    tag: widget.heroTag ?? 'series_cover_${widget.series.id}',
+                    child: Container(
+                      width: 280,
+                      height: 280,
+                      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
+          const 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';
+  }
+}

lib/screens/debug_log_screen.dart

@@ -1,6 +1,11 @@
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
+import 'package:provider/provider.dart';
+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});
@@ -12,6 +17,8 @@ class DebugLogScreen extends StatefulWidget {
 class _DebugLogScreenState extends State<DebugLogScreen> {
   final _logger = DebugLogger();
   final _scrollController = ScrollController();
+  LogLevel _filterLevel = LogLevel.debug; // Show all by default
+  bool _isGeneratingReport = false;
 
   @override
   void initState() {
@@ -30,29 +37,187 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
     super.dispose();
   }
 
+  List<LogEntry> get _filteredEntries =>
+      _logger.entries.where((e) => e.level.index >= _filterLevel.index).toList();
+
   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),
       ),
     );
   }
 
+  Future<void> _shareBugReport() async {
+    setState(() => _isGeneratingReport = true);
+
+    try {
+      final report = await _logger.generateBugReport();
+
+      await Share.share(
+        report,
+        subject: S.of(context)!.ensembleBugReport,
+      );
+    } finally {
+      if (mounted) {
+        setState(() => _isGeneratingReport = false);
+      }
+    }
+  }
+
   void _clearLogs() {
     setState(() {
       _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),
       ),
     );
   }
 
+  Future<void> _showAllPlayers() async {
+    final maProvider = context.read<MusicAssistantProvider>();
+
+    try {
+      final allPlayers = await maProvider.getAllPlayersUnfiltered();
+      final currentPlayerId = await maProvider.getCurrentPlayerId();
+
+      if (!mounted) return;
+
+      showDialog(
+        context: context,
+        builder: (context) => AlertDialog(
+          backgroundColor: const Color(0xFF2a2a2a),
+          title: Text(
+            S.of(context)!.allPlayersCount(allPlayers.length),
+            style: const TextStyle(color: Colors.white),
+          ),
+          content: SizedBox(
+            width: double.maxFinite,
+            child: ListView.builder(
+              shrinkWrap: true,
+              itemCount: allPlayers.length,
+              itemBuilder: (context, index) {
+                final player = allPlayers[index];
+                final id = player.playerId.toLowerCase();
+
+                // Detect ghost players: ensemble_*, massiv_*, ma_* prefixes
+                final isAppPlayer = id.startsWith('ensemble_') ||
+                                    id.startsWith('massiv_') ||
+                                    id.startsWith('ma_');
+                final isCurrentPlayer = player.playerId == currentPlayerId;
+                final isGhost = isAppPlayer && !isCurrentPlayer;
+                final isCorrupt = isAppPlayer && !player.available;
+
+                Color cardColor;
+                Color textColor;
+                IconData? trailingIcon;
+                Color? iconColor;
+
+                if (isCurrentPlayer) {
+                  cardColor = Colors.green.withOpacity(0.2);
+                  textColor = Colors.green[300]!;
+                  trailingIcon = Icons.check_circle;
+                  iconColor = Colors.green;
+                } else if (isCorrupt) {
+                  cardColor = Colors.orange.withOpacity(0.2);
+                  textColor = Colors.orange[300]!;
+                  trailingIcon = Icons.error;
+                  iconColor = Colors.orange;
+                } else if (isGhost) {
+                  cardColor = Colors.red.withOpacity(0.2);
+                  textColor = Colors.red[300]!;
+                  trailingIcon = Icons.warning;
+                  iconColor = Colors.red;
+                } else {
+                  cardColor = Colors.white.withOpacity(0.1);
+                  textColor = Colors.white;
+                }
+
+                return Card(
+                  color: cardColor,
+                  margin: const EdgeInsets.only(bottom: 8),
+                  child: ListTile(
+                    title: Text(
+                      player.name,
+                      style: TextStyle(
+                        color: textColor,
+                        fontWeight: (isGhost || isCurrentPlayer) ? FontWeight.bold : FontWeight.normal,
+                      ),
+                    ),
+                    subtitle: Column(
+                      crossAxisAlignment: CrossAxisAlignment.start,
+                      children: [
+                        Text(
+                          S.of(context)!.playerId(player.playerId),
+                          style: const TextStyle(color: Colors.white70, fontSize: 11),
+                        ),
+                        Text(
+                          S.of(context)!.playerInfo(player.available.toString(), player.provider ?? 'unknown'),
+                          style: const TextStyle(color: Colors.white70, fontSize: 11),
+                        ),
+                        if (isCurrentPlayer)
+                          Text(
+                            S.of(context)!.thisDevice,
+                            style: const TextStyle(color: Colors.green, fontSize: 11, fontWeight: FontWeight.bold),
+                          ),
+                        if (isGhost && !isCorrupt)
+                          Text(
+                            S.of(context)!.ghostPlayer,
+                            style: const TextStyle(color: Colors.red, fontSize: 11),
+                          ),
+                        if (isCorrupt)
+                          Text(
+                            S.of(context)!.unavailableCorrupt,
+                            style: const TextStyle(color: Colors.orange, fontSize: 11),
+                          ),
+                      ],
+                    ),
+                    trailing: trailingIcon != null
+                        ? Icon(trailingIcon, color: iconColor, size: 20)
+                        : null,
+                  ),
+                );
+              },
+            ),
+          ),
+          actions: [
+            TextButton(
+              onPressed: () async {
+                final text = allPlayers.map((p) =>
+                  'Name: ${p.name}\nID: ${p.playerId}\nAvailable: ${p.available}\nProvider: ${p.provider}\nState: ${p.state}\n---'
+                ).join('\n');
+                await Clipboard.setData(ClipboardData(text: text));
+                if (context.mounted) {
+                  Navigator.pop(context);
+                  ScaffoldMessenger.of(context).showSnackBar(
+                    SnackBar(content: Text(S.of(context)!.playerListCopied)),
+                  );
+                }
+              },
+              child: Text(S.of(context)!.copyList),
+            ),
+            TextButton(
+              onPressed: () => Navigator.pop(context),
+              child: Text(S.of(context)!.close),
+            ),
+          ],
+        ),
+      );
+    } catch (e) {
+      if (mounted) {
+        ScaffoldMessenger.of(context).showSnackBar(
+          SnackBar(content: Text(S.of(context)!.errorLoadingPlayers(e.toString()))),
+        );
+      }
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
     return Scaffold(
@@ -65,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,
@@ -75,51 +240,109 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
         ),
         centerTitle: true,
         actions: [
-          IconButton(
-            icon: const Icon(Icons.copy_rounded),
-            onPressed: _copyLogs,
-            color: Colors.white,
-            tooltip: 'Copy logs',
-          ),
-          IconButton(
-            icon: const Icon(Icons.delete_rounded),
-            onPressed: _clearLogs,
-            color: Colors.white,
-            tooltip: 'Clear logs',
+          // Share bug report button
+          _isGeneratingReport
+              ? const Padding(
+                  padding: EdgeInsets.all(12),
+                  child: SizedBox(
+                    width: 24,
+                    height: 24,
+                    child: CircularProgressIndicator(
+                      strokeWidth: 2,
+                      color: Colors.white,
+                    ),
+                  ),
+                )
+              : IconButton(
+                  icon: const Icon(Icons.share_rounded),
+                  onPressed: _shareBugReport,
+                  color: Colors.white,
+                  tooltip: S.of(context)!.shareBugReport,
+                ),
+          PopupMenuButton<String>(
+            icon: const Icon(Icons.more_vert, color: Colors.white),
+            tooltip: S.of(context)!.moreOptions,
+            onSelected: (value) async {
+              switch (value) {
+                case 'show_players':
+                  _showAllPlayers();
+                  break;
+                case 'copy_logs':
+                  _copyLogs();
+                  break;
+                case 'clear_logs':
+                  _clearLogs();
+                  break;
+              }
+            },
+            itemBuilder: (context) => [
+              PopupMenuItem(
+                value: 'show_players',
+                child: ListTile(
+                  leading: const Icon(Icons.speaker_group_rounded),
+                  title: Text(S.of(context)!.viewAllPlayers),
+                  dense: true,
+                ),
+              ),
+              PopupMenuItem(
+                value: 'copy_logs',
+                child: ListTile(
+                  leading: const Icon(Icons.copy_rounded),
+                  title: Text(S.of(context)!.copyLogs),
+                  dense: true,
+                ),
+              ),
+              PopupMenuItem(
+                value: 'clear_logs',
+                child: ListTile(
+                  leading: const Icon(Icons.delete_rounded),
+                  title: Text(S.of(context)!.clearLogs),
+                  dense: true,
+                ),
+              ),
+            ],
           ),
         ],
       ),
       body: Column(
         children: [
+          // Filter chips and stats
           Container(
-            padding: const EdgeInsets.all(16),
+            padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 12),
             color: Colors.white.withOpacity(0.05),
-            child: Row(
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
               children: [
-                const Icon(
-                  Icons.info_outline_rounded,
-                  color: Colors.white70,
-                  size: 16,
-                ),
-                const SizedBox(width: 8),
-                Expanded(
-                  child: Text(
-                    'Last ${_logger.logs.length} log entries',
-                    style: const TextStyle(
-                      color: Colors.white70,
-                      fontSize: 12,
-                    ),
+                // Level filter chips
+                SingleChildScrollView(
+                  scrollDirection: Axis.horizontal,
+                  child: Row(
+                    children: [
+                      _buildFilterChip(S.of(context)!.all, LogLevel.debug),
+                      const SizedBox(width: 8),
+                      _buildFilterChip(S.of(context)!.infoPlus, LogLevel.info),
+                      const SizedBox(width: 8),
+                      _buildFilterChip(S.of(context)!.warnings, LogLevel.warning),
+                      const SizedBox(width: 8),
+                      _buildFilterChip(S.of(context)!.errors, LogLevel.error),
+                    ],
                   ),
                 ),
+                const SizedBox(height: 8),
+                // Stats
+                Text(
+                  S.of(context)!.showingEntries(_filteredEntries.length, _logger.entries.length),
+                  style: const TextStyle(color: Colors.white54, fontSize: 11),
+                ),
               ],
             ),
           ),
           Expanded(
-            child: _logger.logs.isEmpty
-                ? const Center(
+            child: _filteredEntries.isEmpty
+                ? Center(
                     child: Text(
-                      'No logs yet',
-                      style: TextStyle(
+                      S.of(context)!.noLogsYet,
+                      style: const TextStyle(
                         color: Colors.white54,
                         fontSize: 16,
                       ),
@@ -127,63 +350,100 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
                   )
                 : ListView.builder(
                     controller: _scrollController,
-                    padding: const EdgeInsets.all(8),
-                    itemCount: _logger.logs.length,
+                    padding: EdgeInsets.fromLTRB(8, 8, 8, BottomSpacing.navBarOnly + 56),
+                    itemCount: _filteredEntries.length,
                     itemBuilder: (context, index) {
-                      final log = _logger.logs[index];
-                      final isError = log.contains('Error') ||
-                          log.contains('error') ||
-                          log.contains('ERROR') ||
-                          log.contains('failed') ||
-                          log.contains('Failed');
-
-                      return Container(
-                        margin: const EdgeInsets.only(bottom: 4),
-                        padding: const EdgeInsets.symmetric(
-                          horizontal: 12,
-                          vertical: 8,
-                        ),
-                        decoration: BoxDecoration(
-                          color: isError
-                              ? Colors.red.withOpacity(0.1)
-                              : Colors.white.withOpacity(0.03),
-                          borderRadius: BorderRadius.circular(4),
-                          border: Border.all(
-                            color: isError
-                                ? Colors.red.withOpacity(0.3)
-                                : Colors.white.withOpacity(0.1),
-                          ),
-                        ),
-                        child: Text(
-                          log,
-                          style: TextStyle(
-                            color: isError ? Colors.red[300] : Colors.white70,
-                            fontSize: 11,
-                            fontFamily: 'monospace',
-                            height: 1.4,
-                          ),
-                        ),
-                      );
+                      final entry = _filteredEntries[index];
+                      return _buildLogEntry(entry);
                     },
                   ),
           ),
         ],
       ),
-      floatingActionButton: FloatingActionButton(
-        onPressed: () {
-          setState(() {});
-          if (_scrollController.hasClients) {
-            _scrollController.animateTo(
-              _scrollController.position.maxScrollExtent,
-              duration: const Duration(milliseconds: 300),
-              curve: Curves.easeOut,
-            );
-          }
-        },
-        backgroundColor: Colors.white,
-        foregroundColor: const Color(0xFF1a1a1a),
-        child: const Icon(Icons.refresh_rounded),
+      floatingActionButton: Padding(
+        padding: EdgeInsets.only(bottom: BottomSpacing.navBarOnly),
+        child: FloatingActionButton(
+          onPressed: () {
+            setState(() {});
+            if (_scrollController.hasClients) {
+              _scrollController.animateTo(
+                _scrollController.position.maxScrollExtent,
+                duration: const Duration(milliseconds: 300),
+                curve: Curves.easeOut,
+              );
+            }
+          },
+          backgroundColor: Colors.white,
+          foregroundColor: const Color(0xFF1a1a1a),
+          child: const Icon(Icons.refresh_rounded),
+        ),
       ),
     );
   }
+
+  Widget _buildFilterChip(String label, LogLevel level) {
+    final isSelected = _filterLevel == level;
+    return FilterChip(
+      label: Text(label),
+      selected: isSelected,
+      showCheckmark: false,
+      onSelected: (_) {
+        setState(() {
+          _filterLevel = level;
+        });
+      },
+      backgroundColor: Colors.white.withOpacity(0.1),
+      selectedColor: _getLevelColor(level).withOpacity(0.3),
+      labelStyle: TextStyle(
+        color: isSelected ? _getLevelColor(level) : Colors.white70,
+        fontWeight: isSelected ? FontWeight.bold : FontWeight.normal,
+        fontSize: 12,
+      ),
+      side: BorderSide(
+        color: isSelected ? _getLevelColor(level) : Colors.transparent,
+      ),
+    );
+  }
+
+  Widget _buildLogEntry(LogEntry entry) {
+    final color = _getLevelColor(entry.level);
+
+    return Container(
+      margin: const EdgeInsets.only(bottom: 4),
+      padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
+      decoration: BoxDecoration(
+        color: color.withOpacity(0.1),
+        borderRadius: BorderRadius.circular(4),
+        border: Border.all(color: color.withOpacity(0.3)),
+      ),
+      child: Text(
+        entry.formatted,
+        style: TextStyle(
+          color: entry.level == LogLevel.error
+              ? Colors.red[300]
+              : entry.level == LogLevel.warning
+                  ? Colors.orange[300]
+                  : Colors.white70,
+          fontSize: 11,
+          fontFamily: 'monospace',
+          height: 1.4,
+        ),
+      ),
+    );
+  }
+
+  Color _getLevelColor(LogLevel level) {
+    switch (level) {
+      case LogLevel.perf:
+        return Colors.purple;
+      case LogLevel.debug:
+        return Colors.grey;
+      case LogLevel.info:
+        return Colors.blue;
+      case LogLevel.warning:
+        return Colors.orange;
+      case LogLevel.error:
+        return Colors.red;
+    }
+  }
 }

lib/screens/home_screen.dart

@@ -1,5 +1,9 @@
 import 'package:flutter/material.dart';
-import '../widgets/mini_player.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';
 import 'new_library_screen.dart';
 import 'search_screen.dart';
@@ -13,78 +17,112 @@ class HomeScreen extends StatefulWidget {
 }
 
 class _HomeScreenState extends State<HomeScreen> {
-  int _selectedIndex = 0;
-
-  final List<Widget> _screens = [
-    const NewHomeScreen(),
-    const NewLibraryScreen(),
-    const SearchScreen(),
-    const SettingsScreen(),
-  ];
+  final GlobalKey<SearchScreenState> _searchScreenKey = GlobalKey<SearchScreenState>();
+  DateTime? _lastBackPress;
 
   @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
-      body: _screens[_selectedIndex],
-      bottomNavigationBar: Column(
-        mainAxisSize: MainAxisSize.min,
-        children: [
-          // Mini player
-          const MiniPlayer(),
+  void initState() {
+    super.initState();
+    // Register search focus callback with navigation provider
+    navigationProvider.onSearchTabSelected = () {
+      _searchScreenKey.currentState?.requestFocus();
+    };
+  }
 
-          // Bottom navigation bar
-          Container(
-            decoration: BoxDecoration(
-              color: const Color(0xFF2a2a2a),
-              boxShadow: [
-                BoxShadow(
-                  color: Colors.black.withOpacity(0.3),
-                  blurRadius: 10,
-                  offset: const Offset(0, -2),
-                ),
-              ],
-            ),
-            child: BottomNavigationBar(
-              currentIndex: _selectedIndex,
-              onTap: (index) {
-                setState(() {
-                  _selectedIndex = index;
-                });
-              },
-              backgroundColor: Colors.transparent,
-              selectedItemColor: Colors.white,
-              unselectedItemColor: Colors.white54,
-              elevation: 0,
-              type: BottomNavigationBarType.fixed,
-              selectedFontSize: 12,
-              unselectedFontSize: 12,
-              items: const [
-                BottomNavigationBarItem(
-                  icon: Icon(Icons.home_outlined),
-                  activeIcon: Icon(Icons.home_rounded),
-                  label: 'Home',
-                ),
-                BottomNavigationBarItem(
-                  icon: Icon(Icons.library_music_outlined),
-                  activeIcon: Icon(Icons.library_music_rounded),
-                  label: 'Library',
-                ),
-                BottomNavigationBarItem(
-                  icon: Icon(Icons.search_rounded),
-                  activeIcon: Icon(Icons.search_rounded),
-                  label: 'Search',
-                ),
-                BottomNavigationBarItem(
-                  icon: Icon(Icons.settings_outlined),
-                  activeIcon: Icon(Icons.settings_rounded),
-                  label: 'Settings',
-                ),
-              ],
-            ),
-          ),
-        ],
+  @override
+  void dispose() {
+    // Clean up callback
+    navigationProvider.onSearchTabSelected = null;
+    super.dispose();
+  }
+
+  void _showExitSnackBar() {
+    ScaffoldMessenger.of(context).clearSnackBars();
+    ScaffoldMessenger.of(context).showSnackBar(
+      SnackBar(
+        content: Text(S.of(context)!.pressBackToMinimize),
+        duration: const Duration(seconds: 2),
+        behavior: SnackBarBehavior.floating,
+        margin: const EdgeInsets.only(bottom: 80, left: 16, right: 16),
       ),
     );
   }
+
+  @override
+  Widget build(BuildContext context) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    return ListenableBuilder(
+      listenable: navigationProvider,
+      builder: (context, _) {
+        final selectedIndex = navigationProvider.selectedIndex;
+
+        return PopScope(
+          canPop: false,
+          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 global player is expanded, collapse it first
+            if (GlobalPlayerOverlay.isPlayerExpanded) {
+              GlobalPlayerOverlay.collapsePlayer();
+              return;
+            }
+
+            // If not on home tab, navigate to home
+            if (selectedIndex != 0) {
+              // If leaving Settings, show player again
+              if (selectedIndex == 3) {
+                GlobalPlayerOverlay.showPlayer();
+              }
+              navigationProvider.setSelectedIndex(0);
+              return;
+            }
+
+            // On home tab - check for double press to minimize
+            final now = DateTime.now();
+            if (_lastBackPress != null &&
+                now.difference(_lastBackPress!) < const Duration(seconds: 2)) {
+              // Double press detected - minimize app (move to background)
+              // This keeps the app running and connection alive
+              SystemNavigator.pop();
+            } else {
+              // First press, show message
+              _lastBackPress = now;
+              _showExitSnackBar();
+            }
+          },
+          child: Scaffold(
+            backgroundColor: colorScheme.surface,
+            // No bottomNavigationBar here - it's now in GlobalPlayerOverlay
+            body: Stack(
+              children: [
+                // Home and Library use IndexedStack for state preservation
+                Offstage(
+                  offstage: selectedIndex > 1,
+                  child: IndexedStack(
+                    index: selectedIndex.clamp(0, 1),
+                    children: const [
+                      NewHomeScreen(),
+                      NewLibraryScreen(),
+                    ],
+                  ),
+                ),
+                // Search and Settings are conditionally rendered (removed from tree when not visible)
+                if (selectedIndex == 2)
+                  SearchScreen(key: _searchScreenKey),
+                if (selectedIndex == 3)
+                  const SettingsScreen(),
+              ],
+            ),
+          ),
+        );
+      },
+    );
+  }
 }

lib/screens/library_albums_screen.dart

@@ -2,85 +2,77 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import '../providers/music_assistant_provider.dart';
 import '../models/media_item.dart';
-import 'album_details_screen.dart';
-import '../constants/hero_tags.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});
 
   @override
   Widget build(BuildContext context) {
-    final provider = context.watch<MusicAssistantProvider>();
+    // Use Selector for targeted rebuilds - only rebuild when albums or loading state changes
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
 
     return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
+      backgroundColor: colorScheme.background,
       appBar: AppBar(
         backgroundColor: Colors.transparent,
         elevation: 0,
         leading: IconButton(
           icon: const Icon(Icons.arrow_back_rounded),
           onPressed: () => Navigator.pop(context),
-          color: Colors.white,
+          color: colorScheme.onBackground,
         ),
-        title: const Text(
-          'Albums',
-          style: TextStyle(
-            color: Colors.white,
-            fontSize: 20,
+        title: Text(
+          S.of(context)!.albums,
+          style: textTheme.headlineSmall?.copyWith(
+            color: colorScheme.onBackground,
             fontWeight: FontWeight.w300,
           ),
         ),
         centerTitle: true,
       ),
-      body: _buildAlbumsList(provider),
+      body: Selector<MusicAssistantProvider, (List<Album>, bool)>(
+        selector: (_, provider) => (provider.albums, provider.isLoading),
+        builder: (context, data, _) {
+          final (albums, isLoading) = data;
+          return _buildAlbumsList(context, albums, isLoading);
+        },
+      ),
     );
   }
 
-  Widget _buildAlbumsList(MusicAssistantProvider provider) {
-    if (provider.isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
+  Widget _buildAlbumsList(BuildContext context, List<Album> albums, bool isLoading) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    // 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),
       );
     }
 
-    if (provider.albums.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.album_outlined,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No albums found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: provider.loadLibrary,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
+    if (albums.isEmpty) {
+      return EmptyState.albums(
+        context: context,
+        onRefresh: () => context.read<MusicAssistantProvider>().loadLibrary(),
       );
     }
 
     return RefreshIndicator(
+      color: colorScheme.primary,
+      backgroundColor: colorScheme.surface,
       onRefresh: () async {
-        await provider.loadLibrary();
+        await context.read<MusicAssistantProvider>().loadLibrary();
       },
       child: GridView.builder(
+        key: const PageStorageKey<String>('library_albums_full_grid'),
+        cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Cards have their own keep-alive
+        addRepaintBoundaries: false, // Cards have RepaintBoundary
         gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
           crossAxisCount: 2,
           childAspectRatio: 0.75,
@@ -88,91 +80,17 @@ class LibraryAlbumsScreen extends StatelessWidget {
           mainAxisSpacing: 12,
         ),
         padding: const EdgeInsets.all(12),
-        itemCount: provider.albums.length,
+        itemCount: albums.length,
         itemBuilder: (context, index) {
-          final album = provider.albums[index];
-          return _buildAlbumCard(context, album, provider);
+          final album = albums[index];
+          return AlbumCard(
+            key: ValueKey(album.uri ?? album.itemId),
+            album: album,
+            heroTagSuffix: 'library',
+          );
         },
       ),
     );
   }
-
-  Widget _buildAlbumCard(
-      BuildContext context, Album album, MusicAssistantProvider provider) {
-    final imageUrl = provider.getImageUrl(album, size: 256);
-
-    return InkWell(
-      onTap: () {
-        Navigator.push(
-          context,
-          MaterialPageRoute(
-            builder: (context) => AlbumDetailsScreen(album: album),
-          ),
-        );
-      },
-      child: Column(
-        crossAxisAlignment: CrossAxisAlignment.start,
-        children: [
-          Expanded(
-            child: Hero(
-              tag: HeroTags.albumCover + (album.uri ?? album.itemId),
-              child: Container(
-                decoration: BoxDecoration(
-                  color: Colors.white12,
-                  borderRadius: BorderRadius.circular(12),
-                  image: imageUrl != null
-                      ? DecorationImage(
-                          image: NetworkImage(imageUrl),
-                          fit: BoxFit.cover,
-                        )
-                      : null,
-                ),
-                child: imageUrl == null
-                    ? const Center(
-                        child: Icon(
-                          Icons.album_rounded,
-                          size: 64,
-                          color: Colors.white54,
-                        ),
-                      )
-                    : null,
-              ),
-            ),
-          ),
-          const SizedBox(height: 8),
-          Hero(
-            tag: HeroTags.albumTitle + (album.uri ?? album.itemId),
-            child: Material(
-              color: Colors.transparent,
-              child: Text(
-                album.name,
-                style: const TextStyle(
-                  color: Colors.white,
-                  fontSize: 14,
-                  fontWeight: FontWeight.w500,
-                ),
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-              ),
-            ),
-          ),
-          Hero(
-            tag: HeroTags.artistName + (album.uri ?? album.itemId),
-            child: Material(
-              color: Colors.transparent,
-              child: Text(
-                album.artistsString,
-                style: const TextStyle(
-                  color: Colors.white54,
-                  fontSize: 12,
-                ),
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-              ),
-            ),
-          ),
-        ],
-      ),
-    );
-  }
 }
+

lib/screens/library_artists_screen.dart

@@ -2,131 +2,131 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import '../providers/music_assistant_provider.dart';
 import '../models/media_item.dart';
+import '../utils/page_transitions.dart';
+import '../widgets/common/empty_state.dart';
+import '../widgets/artist_avatar.dart';
 import 'artist_details_screen.dart';
-import '../constants/hero_tags.dart';
+import '../l10n/app_localizations.dart';
 
 class LibraryArtistsScreen extends StatelessWidget {
   const LibraryArtistsScreen({super.key});
 
   @override
   Widget build(BuildContext context) {
-    final provider = context.watch<MusicAssistantProvider>();
+    // Use Selector for targeted rebuilds - only rebuild when artists or loading state changes
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
 
     return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
+      backgroundColor: colorScheme.background,
       appBar: AppBar(
         backgroundColor: Colors.transparent,
         elevation: 0,
         leading: IconButton(
           icon: const Icon(Icons.arrow_back_rounded),
           onPressed: () => Navigator.pop(context),
-          color: Colors.white,
+          color: colorScheme.onBackground,
         ),
-        title: const Text(
-          'Artists',
-          style: TextStyle(
-            color: Colors.white,
-            fontSize: 20,
+        title: Text(
+          S.of(context)!.artists,
+          style: textTheme.headlineSmall?.copyWith(
+            color: colorScheme.onBackground,
             fontWeight: FontWeight.w300,
           ),
         ),
         centerTitle: true,
       ),
-      body: _buildArtistsList(provider),
-    );
-  }
-
-  Widget _buildArtistsList(MusicAssistantProvider provider) {
-    if (provider.isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
-      );
-    }
-
-    if (provider.artists.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.person_outline_rounded,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No artists found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: provider.loadLibrary,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
-      );
-    }
-
-    return RefreshIndicator(
-      onRefresh: () async {
-        await provider.loadLibrary();
-      },
-      child: ListView.builder(
-        itemCount: provider.artists.length,
-        padding: const EdgeInsets.all(8),
-        itemBuilder: (context, index) {
-          final artist = provider.artists[index];
-          return _buildArtistTile(artist, provider);
+      body: Selector<MusicAssistantProvider, (List<Artist>, bool)>(
+        selector: (_, provider) => (provider.artists, provider.isLoading),
+        builder: (context, data, _) {
+          final (artists, isLoading) = data;
+          return _buildArtistsList(context, artists, isLoading);
         },
       ),
     );
   }
 
-  Widget _buildArtistTile(Artist artist, MusicAssistantProvider provider) {
-    final imageUrl = provider.getImageUrl(artist, size: 128);
+  Widget _buildArtistsList(BuildContext context, List<Artist> artists, bool isLoading) {
+    final colorScheme = Theme.of(context).colorScheme;
 
-    return Builder(
-      builder: (context) => ListTile(
-        leading: Hero(
-          tag: HeroTags.artistImage + (artist.uri ?? artist.itemId),
-          child: CircleAvatar(
-            radius: 24,
-            backgroundColor: Colors.white12,
-            backgroundImage: imageUrl != null ? NetworkImage(imageUrl) : null,
-            child: imageUrl == null
-                ? const Icon(Icons.person_rounded, color: Colors.white54)
-                : null,
-          ),
+    // 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),
+      );
+    }
+
+    if (artists.isEmpty) {
+      return EmptyState.artists(
+        context: context,
+        onRefresh: () => context.read<MusicAssistantProvider>().loadLibrary(),
+      );
+    }
+
+    return RefreshIndicator(
+      color: colorScheme.primary,
+      backgroundColor: colorScheme.surface,
+      onRefresh: () async {
+        await context.read<MusicAssistantProvider>().loadLibrary();
+      },
+      child: ListView.builder(
+        key: const PageStorageKey<String>('library_artists_full_list'),
+        cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Tiles have their own keep-alive
+        addRepaintBoundaries: false, // Tiles have RepaintBoundary
+        itemCount: artists.length,
+        padding: const EdgeInsets.all(8),
+        itemBuilder: (context, index) {
+          final artist = artists[index];
+          return _buildArtistTile(
+            context,
+            artist,
+            key: ValueKey(artist.uri ?? artist.itemId),
+          );
+        },
+      ),
+    );
+  }
+
+  Widget _buildArtistTile(
+    BuildContext context,
+    Artist artist, {
+    Key? key,
+  }) {
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+    final maProvider = context.read<MusicAssistantProvider>();
+    // Get image URL for hero animation
+    final imageUrl = maProvider.getImageUrl(artist, size: 256);
+
+    // RepaintBoundary isolates repaints to individual tiles
+    return RepaintBoundary(
+      child: ListTile(
+        key: key,
+        leading: ArtistAvatar(
+          artist: artist,
+          radius: 24,
+          imageSize: 128,
         ),
-        title: Hero(
-          tag: HeroTags.artistName + (artist.uri ?? artist.itemId),
-          child: Material(
-            color: Colors.transparent,
-            child: Text(
-              artist.name,
-              style: const TextStyle(
-                color: Colors.white,
-                fontWeight: FontWeight.w500,
-              ),
-              maxLines: 1,
-              overflow: TextOverflow.ellipsis,
-            ),
-          ),
+      title: Text(
+        artist.name,
+        style: textTheme.titleMedium?.copyWith(
+          color: colorScheme.onSurface,
+          fontWeight: FontWeight.w500,
         ),
+        maxLines: 1,
+        overflow: TextOverflow.ellipsis,
+      ),
         onTap: () {
           Navigator.push(
             context,
-            MaterialPageRoute(
-              builder: (context) => ArtistDetailsScreen(artist: artist),
+            FadeSlidePageRoute(
+              child: ArtistDetailsScreen(
+                artist: artist,
+                heroTagSuffix: 'library',
+                initialImageUrl: imageUrl,
+              ),
             ),
           );
         },

lib/screens/library_playlists_screen.dart

@@ -1,8 +1,11 @@
 import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
+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 'playlist_details_screen.dart';
+import '../l10n/app_localizations.dart';
 
 class LibraryPlaylistsScreen extends StatefulWidget {
   const LibraryPlaylistsScreen({super.key});
@@ -43,110 +46,94 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
   @override
   Widget build(BuildContext context) {
     final provider = context.watch<MusicAssistantProvider>();
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
 
     return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
+      backgroundColor: colorScheme.background,
       appBar: AppBar(
         backgroundColor: Colors.transparent,
         elevation: 0,
         leading: IconButton(
           icon: const Icon(Icons.arrow_back_rounded),
           onPressed: () => Navigator.pop(context),
-          color: Colors.white,
+          color: colorScheme.onBackground,
         ),
-        title: const Text(
-          'Playlists',
-          style: TextStyle(
-            color: Colors.white,
-            fontSize: 20,
+        title: Text(
+          S.of(context)!.playlists,
+          style: textTheme.headlineSmall?.copyWith(
+            color: colorScheme.onBackground,
             fontWeight: FontWeight.w300,
           ),
         ),
         centerTitle: true,
       ),
-      body: _buildPlaylistsList(provider),
+      body: _buildPlaylistsList(context, provider),
     );
   }
 
-  Widget _buildPlaylistsList(MusicAssistantProvider provider) {
-    if (_isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
+  Widget _buildPlaylistsList(BuildContext context, MusicAssistantProvider provider) {
+    final colorScheme = Theme.of(context).colorScheme;
+
+    // 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 Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.playlist_play_outlined,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No playlists found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: _loadPlaylists,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
-      );
+      return EmptyState.playlists(context: context, onRefresh: _loadPlaylists);
     }
 
     return RefreshIndicator(
+      color: colorScheme.primary,
+      backgroundColor: colorScheme.surface,
       onRefresh: _loadPlaylists,
       child: ListView.builder(
         itemCount: _playlists.length,
         padding: const EdgeInsets.all(8),
+        cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+        addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
         itemBuilder: (context, index) {
           final playlist = _playlists[index];
-          return _buildPlaylistTile(playlist, provider);
+          return _buildPlaylistTile(context, playlist, provider);
         },
       ),
     );
   }
 
-  Widget _buildPlaylistTile(Playlist playlist, MusicAssistantProvider provider) {
+  Widget _buildPlaylistTile(BuildContext context, Playlist playlist, MusicAssistantProvider provider) {
     final imageUrl = provider.api?.getImageUrl(playlist, size: 128);
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
 
-    return Builder(
-      builder: (context) => ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(playlist.itemId),
         leading: Container(
           width: 48,
           height: 48,
           decoration: BoxDecoration(
-            color: Colors.white12,
+            color: colorScheme.surfaceVariant,
             borderRadius: BorderRadius.circular(8),
             image: imageUrl != null
                 ? DecorationImage(
-                    image: NetworkImage(imageUrl),
+                    image: CachedNetworkImageProvider(imageUrl),
                     fit: BoxFit.cover,
                   )
                 : null,
           ),
           child: imageUrl == null
-              ? const Icon(Icons.playlist_play_rounded, color: Colors.white54)
+              ? Icon(Icons.playlist_play_rounded, color: colorScheme.onSurfaceVariant)
               : null,
         ),
         title: Text(
           playlist.name,
-          style: const TextStyle(
-            color: Colors.white,
+          style: textTheme.titleMedium?.copyWith(
+            color: colorScheme.onSurface,
             fontWeight: FontWeight.w500,
           ),
           maxLines: 1,
@@ -154,9 +141,11 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
         ),
         subtitle: Text(
           playlist.trackCount != null
-              ? '${playlist.trackCount} tracks'
-              : playlist.owner ?? 'Playlist',
-          style: const TextStyle(color: Colors.white54, fontSize: 12),
+              ? '${playlist.trackCount} ${S.of(context)!.tracks}'
+              : playlist.owner ?? S.of(context)!.playlist,
+          style: textTheme.bodySmall?.copyWith(
+            color: colorScheme.onSurface.withOpacity(0.7),
+          ),
           maxLines: 1,
           overflow: TextOverflow.ellipsis,
         ),

lib/screens/library_screen.dart

@@ -1,443 +0,0 @@
-import 'package:flutter/material.dart';
-import 'package:provider/provider.dart';
-import '../providers/music_assistant_provider.dart';
-import '../models/media_item.dart';
-import 'album_details_screen.dart';
-import 'settings_screen.dart';
-
-class LibraryScreen extends StatefulWidget {
-  const LibraryScreen({super.key});
-
-  @override
-  State<LibraryScreen> createState() => _LibraryScreenState();
-}
-
-class _LibraryScreenState extends State<LibraryScreen>
-    with SingleTickerProviderStateMixin {
-  late TabController _tabController;
-  final _searchController = TextEditingController();
-
-  @override
-  void initState() {
-    super.initState();
-    _tabController = TabController(length: 3, vsync: this);
-  }
-
-  @override
-  void dispose() {
-    _tabController.dispose();
-    _searchController.dispose();
-    super.dispose();
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    final provider = context.watch<MusicAssistantProvider>();
-
-    return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
-      appBar: AppBar(
-        backgroundColor: Colors.transparent,
-        elevation: 0,
-        title: const Text(
-          'Library',
-          style: TextStyle(
-            color: Colors.white,
-            fontSize: 20,
-            fontWeight: FontWeight.w300,
-          ),
-        ),
-        centerTitle: true,
-        actions: [
-          IconButton(
-            icon: const Icon(Icons.settings_rounded),
-            onPressed: () {
-              Navigator.push(
-                context,
-                MaterialPageRoute(
-                  builder: (context) => const SettingsScreen(),
-                ),
-              );
-            },
-            color: Colors.white,
-          ),
-        ],
-        bottom: TabBar(
-          controller: _tabController,
-          indicatorColor: Colors.white,
-          labelColor: Colors.white,
-          unselectedLabelColor: Colors.white54,
-          tabs: const [
-            Tab(text: 'Artists'),
-            Tab(text: 'Albums'),
-            Tab(text: 'Tracks'),
-          ],
-        ),
-      ),
-      body: !provider.isConnected
-          ? _buildDisconnectedView(provider)
-          : TabBarView(
-              controller: _tabController,
-              children: [
-                _buildArtistsList(provider),
-                _buildAlbumsList(provider),
-                _buildTracksList(provider),
-              ],
-            ),
-    );
-  }
-
-  Widget _buildDisconnectedView(MusicAssistantProvider provider) {
-    return Center(
-      child: Padding(
-        padding: const EdgeInsets.all(32.0),
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.cloud_off_rounded,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'Not connected to Music Assistant',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-              textAlign: TextAlign.center,
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: () {
-                Navigator.push(
-                  context,
-                  MaterialPageRoute(
-                    builder: (context) => const SettingsScreen(),
-                  ),
-                );
-              },
-              icon: const Icon(Icons.settings_rounded),
-              label: const Text('Configure Server'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-                padding: const EdgeInsets.symmetric(
-                  horizontal: 24,
-                  vertical: 12,
-                ),
-                shape: RoundedRectangleBorder(
-                  borderRadius: BorderRadius.circular(24),
-                ),
-              ),
-            ),
-          ],
-        ),
-      ),
-    );
-  }
-
-  Widget _buildArtistsList(MusicAssistantProvider provider) {
-    if (provider.isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
-      );
-    }
-
-    if (provider.artists.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.person_outline_rounded,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No artists found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: provider.loadLibrary,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
-      );
-    }
-
-    return ListView.builder(
-      itemCount: provider.artists.length,
-      padding: const EdgeInsets.all(8),
-      itemBuilder: (context, index) {
-        final artist = provider.artists[index];
-        return _buildArtistTile(artist, provider);
-      },
-    );
-  }
-
-  Widget _buildArtistTile(Artist artist, MusicAssistantProvider provider) {
-    final imageUrl = provider.getImageUrl(artist, size: 128);
-
-    return ListTile(
-      leading: CircleAvatar(
-        radius: 24,
-        backgroundColor: Colors.white12,
-        backgroundImage: imageUrl != null ? NetworkImage(imageUrl) : null,
-        child: imageUrl == null
-            ? const Icon(Icons.person_rounded, color: Colors.white54)
-            : null,
-      ),
-      title: Text(
-        artist.name,
-        style: const TextStyle(
-          color: Colors.white,
-          fontWeight: FontWeight.w500,
-        ),
-        maxLines: 1,
-        overflow: TextOverflow.ellipsis,
-      ),
-      onTap: () async {
-        // Load albums for this artist
-        await provider.loadAlbums(artistId: '${artist.provider}/${artist.itemId}');
-        if (context.mounted) {
-          _tabController.animateTo(1);
-        }
-      },
-    );
-  }
-
-  Widget _buildAlbumsList(MusicAssistantProvider provider) {
-    if (provider.isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
-      );
-    }
-
-    if (provider.albums.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.album_outlined,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No albums found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: provider.loadLibrary,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
-      );
-    }
-
-    return GridView.builder(
-      gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
-        crossAxisCount: 2,
-        childAspectRatio: 0.75,
-        crossAxisSpacing: 12,
-        mainAxisSpacing: 12,
-      ),
-      padding: const EdgeInsets.all(12),
-      itemCount: provider.albums.length,
-      itemBuilder: (context, index) {
-        final album = provider.albums[index];
-        return _buildAlbumCard(album, provider);
-      },
-    );
-  }
-
-  Widget _buildAlbumCard(Album album, MusicAssistantProvider provider) {
-    final imageUrl = provider.getImageUrl(album, size: 256);
-
-    return InkWell(
-      onTap: () {
-        Navigator.push(
-          context,
-          MaterialPageRoute(
-            builder: (context) => AlbumDetailsScreen(album: album),
-          ),
-        );
-      },
-      child: Column(
-        crossAxisAlignment: CrossAxisAlignment.start,
-        children: [
-          Expanded(
-            child: Container(
-              decoration: BoxDecoration(
-                color: Colors.white12,
-                borderRadius: BorderRadius.circular(12),
-                image: imageUrl != null
-                    ? DecorationImage(
-                        image: NetworkImage(imageUrl),
-                        fit: BoxFit.cover,
-                      )
-                    : null,
-              ),
-              child: imageUrl == null
-                  ? const Center(
-                      child: Icon(
-                        Icons.album_rounded,
-                        size: 64,
-                        color: Colors.white54,
-                      ),
-                    )
-                  : null,
-            ),
-          ),
-          const SizedBox(height: 8),
-          Text(
-            album.name,
-            style: const TextStyle(
-              color: Colors.white,
-              fontSize: 14,
-              fontWeight: FontWeight.w500,
-            ),
-            maxLines: 1,
-            overflow: TextOverflow.ellipsis,
-          ),
-          Text(
-            album.artistsString,
-            style: const TextStyle(
-              color: Colors.white54,
-              fontSize: 12,
-            ),
-            maxLines: 1,
-            overflow: TextOverflow.ellipsis,
-          ),
-        ],
-      ),
-    );
-  }
-
-  Widget _buildTracksList(MusicAssistantProvider provider) {
-    if (provider.isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
-      );
-    }
-
-    if (provider.tracks.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.music_note_outlined,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No tracks found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: provider.loadLibrary,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
-      );
-    }
-
-    return ListView.builder(
-      itemCount: provider.tracks.length,
-      padding: const EdgeInsets.all(8),
-      itemBuilder: (context, index) {
-        final track = provider.tracks[index];
-        return _buildTrackTile(track, provider);
-      },
-    );
-  }
-
-  Widget _buildTrackTile(Track track, MusicAssistantProvider provider) {
-    final imageUrl = track.album != null
-        ? provider.getImageUrl(track.album!, size: 128)
-        : null;
-
-    return ListTile(
-      leading: Container(
-        width: 48,
-        height: 48,
-        decoration: BoxDecoration(
-          color: Colors.white12,
-          borderRadius: BorderRadius.circular(8),
-          image: imageUrl != null
-              ? DecorationImage(
-                  image: NetworkImage(imageUrl),
-                  fit: BoxFit.cover,
-                )
-              : null,
-        ),
-        child: imageUrl == null
-            ? const Icon(Icons.music_note_rounded, color: Colors.white54)
-            : null,
-      ),
-      title: Text(
-        track.name,
-        style: const TextStyle(color: Colors.white),
-        maxLines: 1,
-        overflow: TextOverflow.ellipsis,
-      ),
-      subtitle: Text(
-        track.artistsString,
-        style: const TextStyle(color: Colors.white54, fontSize: 12),
-        maxLines: 1,
-        overflow: TextOverflow.ellipsis,
-      ),
-      trailing: track.duration != null
-          ? Text(
-              _formatDuration(track.duration!),
-              style: const TextStyle(color: Colors.white54, fontSize: 12),
-            )
-          : null,
-      onTap: () {
-        // TODO: Play track
-      },
-    );
-  }
-
-  String _formatDuration(Duration duration) {
-    final minutes = duration.inMinutes;
-    final seconds = duration.inSeconds % 60;
-    return '$minutes:${seconds.toString().padLeft(2, '0')}';
-  }
-}

lib/screens/library_tracks_screen.dart

@@ -1,7 +1,10 @@
 import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
+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});
@@ -9,22 +12,23 @@ class LibraryTracksScreen extends StatelessWidget {
   @override
   Widget build(BuildContext context) {
     final provider = context.watch<MusicAssistantProvider>();
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
 
     return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
+      backgroundColor: colorScheme.background,
       appBar: AppBar(
         backgroundColor: Colors.transparent,
         elevation: 0,
         leading: IconButton(
           icon: const Icon(Icons.arrow_back_rounded),
           onPressed: () => Navigator.pop(context),
-          color: Colors.white,
+          color: colorScheme.onBackground,
         ),
-        title: const Text(
-          'Tracks',
-          style: TextStyle(
-            color: Colors.white,
-            fontSize: 20,
+        title: Text(
+          S.of(context)!.tracks,
+          style: textTheme.headlineSmall?.copyWith(
+            color: colorScheme.onBackground,
             fontWeight: FontWeight.w300,
           ),
         ),
@@ -36,48 +40,26 @@ class LibraryTracksScreen extends StatelessWidget {
 
   Widget _buildTracksList(
       BuildContext context, MusicAssistantProvider provider) {
-    if (provider.isLoading) {
-      return const Center(
-        child: CircularProgressIndicator(color: Colors.white),
+    final colorScheme = Theme.of(context).colorScheme;
+
+    // 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 Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.music_note_outlined,
-              size: 64,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 16),
-            const Text(
-              'No tracks found',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 16,
-              ),
-            ),
-            const SizedBox(height: 24),
-            ElevatedButton.icon(
-              onPressed: provider.loadLibrary,
-              icon: const Icon(Icons.refresh_rounded),
-              label: const Text('Refresh'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-              ),
-            ),
-          ],
-        ),
-      );
+      return EmptyState.tracks(context: context, onRefresh: provider.loadLibrary);
     }
 
     return ListView.builder(
       itemCount: provider.tracks.length,
       padding: const EdgeInsets.all(8),
+      cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+      addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+      addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
       itemBuilder: (context, index) {
         final track = provider.tracks[index];
         return _buildTrackTile(context, track, provider, index);
@@ -94,44 +76,49 @@ class LibraryTracksScreen extends StatelessWidget {
     final imageUrl = track.album != null
         ? maProvider.getImageUrl(track.album!, size: 128)
         : null;
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
 
-    return ListTile(
-      leading: Container(
-        width: 48,
-        height: 48,
-        decoration: BoxDecoration(
-          color: Colors.white12,
-          borderRadius: BorderRadius.circular(8),
-          image: imageUrl != null
-              ? DecorationImage(
-                  image: NetworkImage(imageUrl),
-                  fit: BoxFit.cover,
-                )
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(track.uri ?? track.itemId),
+        leading: Container(
+          width: 48,
+          height: 48,
+          decoration: BoxDecoration(
+            color: colorScheme.surfaceVariant,
+            borderRadius: BorderRadius.circular(8),
+            image: imageUrl != null
+                ? DecorationImage(
+                    image: CachedNetworkImageProvider(imageUrl),
+                    fit: BoxFit.cover,
+                  )
+                : null,
+          ),
+          child: imageUrl == null
+              ? Icon(Icons.music_note_rounded, color: colorScheme.onSurfaceVariant)
               : null,
         ),
-        child: imageUrl == null
-            ? const Icon(Icons.music_note_rounded, color: Colors.white54)
+        title: Text(
+          track.name,
+          style: textTheme.bodyLarge?.copyWith(color: colorScheme.onSurface),
+          maxLines: 1,
+          overflow: TextOverflow.ellipsis,
+        ),
+        subtitle: Text(
+          track.artistsString,
+          style: textTheme.bodyMedium?.copyWith(color: colorScheme.onSurface.withOpacity(0.7)),
+          maxLines: 1,
+          overflow: TextOverflow.ellipsis,
+        ),
+        trailing: track.duration != null
+            ? Text(
+                _formatDuration(track.duration!),
+                style: textTheme.bodySmall?.copyWith(color: colorScheme.onSurface.withOpacity(0.54)),
+              )
             : null,
+        onTap: () => _playTrack(context, maProvider, index),
       ),
-      title: Text(
-        track.name,
-        style: const TextStyle(color: Colors.white),
-        maxLines: 1,
-        overflow: TextOverflow.ellipsis,
-      ),
-      subtitle: Text(
-        track.artistsString,
-        style: const TextStyle(color: Colors.white54, fontSize: 12),
-        maxLines: 1,
-        overflow: TextOverflow.ellipsis,
-      ),
-      trailing: track.duration != null
-          ? Text(
-              _formatDuration(track.duration!),
-              style: const TextStyle(color: Colors.white54, fontSize: 12),
-            )
-          : null,
-      onTap: () => _playTrack(context, maProvider, index),
     );
   }
 
@@ -145,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;
     }

lib/screens/new_home_screen.dart

@@ -1,43 +1,167 @@
 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/common/disconnected_state.dart';
 import 'settings_screen.dart';
 import 'search_screen.dart';
 
-class NewHomeScreen extends StatelessWidget {
+class NewHomeScreen extends StatefulWidget {
   const NewHomeScreen({super.key});
 
+  @override
+  State<NewHomeScreen> createState() => _NewHomeScreenState();
+}
+
+class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveClientMixin, WidgetsBindingObserver {
+  static final _logger = DebugLogger();
+  Key _refreshKey = UniqueKey();
+  // Main rows (default on)
+  bool _showRecentAlbums = true;
+  bool _showDiscoverArtists = true;
+  bool _showDiscoverAlbums = true;
+  // Favorites rows (default off)
+  bool _showFavoriteAlbums = false;
+  bool _showFavoriteArtists = false;
+  bool _showFavoriteTracks = 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;
+
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addObserver(this);
+    _loadSettings();
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    super.dispose();
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    // Reload settings when app resumes (coming back from settings)
+    if (state == AppLifecycleState.resumed) {
+      _loadSettings();
+    }
+  }
+
+  Future<void> _loadSettings() async {
+    final showRecent = await SettingsService.getShowRecentAlbums();
+    final showDiscArtists = await SettingsService.getShowDiscoverArtists();
+    final showDiscAlbums = await SettingsService.getShowDiscoverAlbums();
+    final showFavAlbums = await SettingsService.getShowFavoriteAlbums();
+    final showFavArtists = await SettingsService.getShowFavoriteArtists();
+    final showFavTracks = await SettingsService.getShowFavoriteTracks();
+    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;
+        _showDiscoverArtists = showDiscArtists;
+        _showDiscoverAlbums = showDiscAlbums;
+        _showFavoriteAlbums = showFavAlbums;
+        _showFavoriteArtists = showFavArtists;
+        _showFavoriteTracks = showFavTracks;
+        _showContinueListeningAudiobooks = showContAudiobooks;
+        _showDiscoverAudiobooks = showDiscAudiobooks;
+        _showDiscoverSeries = showDiscSeries;
+        _homeRowOrder = rowOrder;
+      });
+    }
+  }
+
+  Future<void> _onRefresh() async {
+    // Invalidate cache to force fresh data on pull-to-refresh
+    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();
+
+    if (mounted) {
+      setState(() {
+        _refreshKey = UniqueKey();
+      });
+    }
+  }
+
   @override
   Widget build(BuildContext context) {
-    final maProvider = context.watch<MusicAssistantProvider>();
+    super.build(context); // Required for AutomaticKeepAliveClientMixin
+    // Settings are loaded in initState and didChangeAppLifecycleState - no need to reload on every build
+    final colorScheme = Theme.of(context).colorScheme;
 
     return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
+      backgroundColor: colorScheme.background,
       appBar: AppBar(
         backgroundColor: Colors.transparent,
         elevation: 0,
         title: Padding(
-          padding: const EdgeInsets.only(left: 8.0),
-          child: Image.asset(
-            'assets/images/logo.png',
-            height: 72,
-            fit: BoxFit.contain,
-            alignment: Alignment.centerLeft,
+          padding: const EdgeInsets.only(left: 16.0),
+          child: ColorFiltered(
+            colorFilter: Theme.of(context).brightness == Brightness.light
+                ? const ColorFilter.matrix(<double>[
+                    -1,  0,  0, 0, 255,
+                     0, -1,  0, 0, 255,
+                     0,  0, -1, 0, 255,
+                     0,  0,  0, 1,   0,
+                  ])
+                : const ColorFilter.mode(Colors.transparent, BlendMode.multiply),
+            child: Image.asset(
+              'assets/images/ensemble_logo.png',
+              height: 40,
+              fit: BoxFit.contain,
+              alignment: Alignment.centerLeft,
+            ),
           ),
         ),
         titleSpacing: 0,
         centerTitle: false,
         actions: [
-          IconButton(
-            icon: const Icon(Icons.search),
-            onPressed: () {
-              Navigator.push(
-                context,
-                MaterialPageRoute(
-                  builder: (context) => const SearchScreen(),
+          // 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),
+                    ),
+                  ),
                 ),
               );
             },
@@ -46,113 +170,225 @@ class NewHomeScreen extends StatelessWidget {
         ],
       ),
       body: SafeArea(
-        child: !maProvider.isConnected
-            ? _buildDisconnectedView(context, maProvider)
-            : _buildConnectedView(context, maProvider),
-      ),
-    );
-  }
+        child: Selector<MusicAssistantProvider, bool>(
+          selector: (_, p) => p.isConnected,
+          builder: (context, isConnected, child) {
+            final maProvider = context.read<MusicAssistantProvider>();
+            final syncService = SyncService.instance;
 
-  Widget _buildDisconnectedView(
-      BuildContext context, MusicAssistantProvider provider) {
-    return Center(
-      child: Padding(
-        padding: const EdgeInsets.all(32.0),
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            const Icon(
-              Icons.cloud_off_rounded,
-              size: 80,
-              color: Colors.white54,
-            ),
-            const SizedBox(height: 24),
-            const Text(
-              'Not Connected',
-              style: TextStyle(
-                color: Colors.white,
-                fontSize: 24,
-                fontWeight: FontWeight.w300,
-              ),
-            ),
-            const SizedBox(height: 12),
-            const Text(
-              'Connect to your Music Assistant server to start listening',
-              style: TextStyle(
-                color: Colors.white70,
-                fontSize: 14,
-              ),
-              textAlign: TextAlign.center,
-            ),
-            const SizedBox(height: 32),
-            ElevatedButton.icon(
-              onPressed: () {
-                Navigator.push(
+            // 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(),
+                  MaterialPageRoute(builder: (context) => const SettingsScreen()),
+                ),
+              );
+            }
+
+            return Stack(
+              children: [
+                // Main content
+                RefreshIndicator(
+                  onRefresh: _onRefresh,
+                  color: colorScheme.primary,
+                  backgroundColor: colorScheme.surface,
+                  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,
+                            ),
+                          ),
+                        ],
+                      ),
+                    ),
                   ),
-                );
-              },
-              icon: const Icon(Icons.settings_rounded),
-              label: const Text('Configure Server'),
-              style: ElevatedButton.styleFrom(
-                backgroundColor: Colors.white,
-                foregroundColor: const Color(0xFF1a1a1a),
-                padding: const EdgeInsets.symmetric(
-                  horizontal: 32,
-                  vertical: 16,
-                ),
-                shape: RoundedRectangleBorder(
-                  borderRadius: BorderRadius.circular(24),
-                ),
-              ),
-            ),
-          ],
+              ],
+            );
+          },
         ),
       ),
     );
   }
 
+
   Widget _buildConnectedView(
       BuildContext context, MusicAssistantProvider provider) {
-    return SingleChildScrollView(
-      child: Column(
-        crossAxisAlignment: CrossAxisAlignment.start,
-        children: [
-          const SizedBox(height: 16),
+    // 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
+        final availableHeight = constraints.maxHeight - BottomSpacing.withMiniPlayer;
+        final rowHeight = availableHeight / 3;
 
-          // Recently played albums
-          AlbumRow(
-            title: 'Recently Played',
-            loadAlbums: () async {
-              if (provider.api == null) return [];
-              return await provider.api!.getRecentAlbums(limit: 10);
-            },
+        // Use Android 12+ stretch overscroll effect
+        return NotificationListener<ScrollNotification>(
+          onNotification: (notification) {
+            if (notification is ScrollStartNotification) {
+              _logger.resetFrameStats();
+              _logger.perf('SCROLL START', context: 'HomeScreen');
+            } else if (notification is ScrollUpdateNotification) {
+              _logger.startFrame();
+              SchedulerBinding.instance.addPostFrameCallback((_) {
+                _logger.endFrame();
+              });
+            } else if (notification is ScrollEndNotification) {
+              _logger.perf('SCROLL END', context: 'HomeScreen');
+            }
+            return false;
+          },
+          child: ScrollConfiguration(
+            behavior: const _StretchScrollBehavior(),
+            child: SingleChildScrollView(
+              physics: const AlwaysScrollableScrollPhysics(),
+              padding: EdgeInsets.only(bottom: BottomSpacing.withMiniPlayer),
+              child: Column(
+                key: _refreshKey,
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: _buildOrderedRows(provider, rowHeight),
+              ),
+            ),
           ),
-          const SizedBox(height: 16),
+        );
+      },
+    );
+  }
 
-          // Discover Artists
-          ArtistRow(
-            title: 'Discover Artists',
-            loadArtists: () async {
-              if (provider.api == null) return [];
-              return await provider.api!.getRandomArtists(limit: 10);
-            },
-          ),
-          const SizedBox(height: 16),
+  /// Build rows in the user's configured order
+  List<Widget> _buildOrderedRows(MusicAssistantProvider provider, double rowHeight) {
+    final rows = <Widget>[];
 
-          // Discover Albums
-          AlbumRow(
-            title: 'Discover Albums',
-            loadAlbums: () async {
-              if (provider.api == null) return [];
-              return await provider.api!.getRandomAlbums(limit: 10);
-            },
-          ),
-          const SizedBox(height: 80), // Space for mini player
-        ],
-      ),
+    for (final rowId in _homeRowOrder) {
+      final widget = _buildRowWidget(rowId, provider, rowHeight);
+      if (widget != null) {
+        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.getInProgressAudiobooks(),
+          rowHeight: rowHeight,
+        );
+      case 'discover-audiobooks':
+        if (!_showDiscoverAudiobooks) return null;
+        return AudiobookRow(
+          key: const ValueKey('discover-audiobooks'),
+          title: S.of(context)!.discoverAudiobooks,
+          loadAudiobooks: () => provider.getDiscoverAudiobooks(),
+          rowHeight: rowHeight,
+        );
+      case 'discover-series':
+        if (!_showDiscoverSeries) return null;
+        return SeriesRow(
+          key: const ValueKey('discover-series'),
+          title: S.of(context)!.discoverSeries,
+          loadSeries: () => provider.getDiscoverSeries(),
+          rowHeight: rowHeight,
+        );
+      case 'favorite-albums':
+        if (!_showFavoriteAlbums) return null;
+        return AlbumRow(
+          key: const ValueKey('favorite-albums'),
+          title: S.of(context)!.favoriteAlbums,
+          loadAlbums: () => provider.getFavoriteAlbums(),
+          rowHeight: rowHeight,
+        );
+      case 'favorite-artists':
+        if (!_showFavoriteArtists) return null;
+        return ArtistRow(
+          key: const ValueKey('favorite-artists'),
+          title: S.of(context)!.favoriteArtists,
+          loadArtists: () => provider.getFavoriteArtists(),
+          rowHeight: rowHeight,
+        );
+      case 'favorite-tracks':
+        if (!_showFavoriteTracks) return null;
+        return TrackRow(
+          key: const ValueKey('favorite-tracks'),
+          title: S.of(context)!.favoriteTracks,
+          loadTracks: () => provider.getFavoriteTracks(),
+          rowHeight: rowHeight,
+        );
+      default:
+        return null;
+    }
+  }
+}
+
+/// Custom scroll behavior that uses Android 12+ stretch overscroll effect
+class _StretchScrollBehavior extends ScrollBehavior {
+  const _StretchScrollBehavior();
+
+  @override
+  Widget buildOverscrollIndicator(
+      BuildContext context, Widget child, ScrollableDetails details) {
+    return StretchingOverscrollIndicator(
+      axisDirection: details.direction,
+      child: child,
     );
   }
 }

lib/screens/now_playing_screen.dart

@@ -1,442 +0,0 @@
-import 'dart:async';
-import 'package:flutter/material.dart';
-import 'package:provider/provider.dart';
-import '../providers/music_assistant_provider.dart';
-import '../models/player.dart';
-import '../widgets/volume_control.dart';
-import 'queue_screen.dart';
-import '../constants/hero_tags.dart';
-import '../widgets/animated_icon_button.dart';
-
-class NowPlayingScreen extends StatefulWidget {
-  const NowPlayingScreen({super.key});
-
-  @override
-  State<NowPlayingScreen> createState() => _NowPlayingScreenState();
-}
-
-class _NowPlayingScreenState extends State<NowPlayingScreen> {
-  PlayerQueue? _queue;
-  bool _isLoadingQueue = true;
-  Timer? _progressTimer;
-
-  @override
-  void initState() {
-    super.initState();
-    _loadQueue();
-    _startProgressTimer();
-  }
-
-  @override
-  void dispose() {
-    _progressTimer?.cancel();
-    super.dispose();
-  }
-
-  void _startProgressTimer() {
-    // Update UI every second when playing to show progress
-    _progressTimer?.cancel();
-    _progressTimer = Timer.periodic(const Duration(seconds: 1), (_) {
-      if (mounted) {
-        setState(() {
-          // Just trigger rebuild to update elapsed time
-        });
-      }
-    });
-  }
-
-  Future<void> _loadQueue() async {
-    setState(() {
-      _isLoadingQueue = true;
-    });
-
-    final maProvider = context.read<MusicAssistantProvider>();
-    final player = maProvider.selectedPlayer;
-
-    if (player != null && maProvider.api != null) {
-      final queue = await maProvider.api!.getQueue(player.playerId);
-      if (mounted) {
-        setState(() {
-          _queue = queue;
-          _isLoadingQueue = false;
-        });
-      }
-    } else {
-      if (mounted) {
-        setState(() {
-          _isLoadingQueue = false;
-        });
-      }
-    }
-  }
-
-  Future<void> _toggleShuffle() async {
-    if (_queue == null) return;
-    final maProvider = context.read<MusicAssistantProvider>();
-    await maProvider.toggleShuffle(_queue!.playerId);
-    await _loadQueue();
-  }
-
-  Future<void> _cycleRepeat() async {
-    if (_queue == null) return;
-    final maProvider = context.read<MusicAssistantProvider>();
-    await maProvider.cycleRepeatMode(_queue!.playerId, _queue!.repeatMode);
-    await _loadQueue();
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    final maProvider = context.watch<MusicAssistantProvider>();
-    final selectedPlayer = maProvider.selectedPlayer;
-    final currentTrack = maProvider.currentTrack;
-
-    if (currentTrack == null || selectedPlayer == null) {
-      return Scaffold(
-        backgroundColor: const Color(0xFF1a1a1a),
-        appBar: AppBar(
-          backgroundColor: Colors.transparent,
-          elevation: 0,
-        ),
-        body: Center(
-          child: Column(
-            mainAxisAlignment: MainAxisAlignment.center,
-            children: [
-              Icon(Icons.music_note, size: 64, color: Colors.grey[700]),
-              const SizedBox(height: 16),
-              Text(
-                'No track playing',
-                style: TextStyle(color: Colors.grey[600], fontSize: 18),
-              ),
-            ],
-          ),
-        ),
-      );
-    }
-
-    final imageUrl = maProvider.getImageUrl(currentTrack, size: 512);
-
-    return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
-      appBar: AppBar(
-        backgroundColor: Colors.transparent,
-        elevation: 0,
-        title: Text(
-          selectedPlayer.name,
-          style: const TextStyle(
-            color: Colors.white70,
-            fontSize: 14,
-            fontWeight: FontWeight.w300,
-          ),
-        ),
-        centerTitle: true,
-        actions: [
-          IconButton(
-            icon: const Icon(Icons.queue_music),
-            onPressed: () {
-              Navigator.push(
-                context,
-                MaterialPageRoute(
-                  builder: (context) => const QueueScreen(),
-                ),
-              );
-            },
-          ),
-        ],
-      ),
-      body: SafeArea(
-        child: Padding(
-          padding: const EdgeInsets.symmetric(horizontal: 24.0, vertical: 16.0),
-          child: Column(
-            children: [
-              const Spacer(),
-              // Album Art with Hero animation
-              Hero(
-                tag: 'now_playing_art',
-                child: Container(
-                  width: double.infinity,
-                  constraints: const BoxConstraints(maxWidth: 400, maxHeight: 400),
-                  child: AspectRatio(
-                    aspectRatio: 1,
-                    child: ClipRRect(
-                      borderRadius: BorderRadius.circular(16),
-                      child: imageUrl != null
-                          ? Image.network(
-                              imageUrl,
-                              fit: BoxFit.cover,
-                              errorBuilder: (context, error, stackTrace) {
-                                return Container(
-                                  color: const Color(0xFF2a2a2a),
-                                  child: const Icon(
-                                    Icons.music_note_rounded,
-                                    color: Colors.white24,
-                                    size: 120,
-                                  ),
-                                );
-                              },
-                            )
-                          : Container(
-                              color: const Color(0xFF2a2a2a),
-                              child: const Icon(
-                                Icons.music_note_rounded,
-                                color: Colors.white24,
-                                size: 120,
-                              ),
-                            ),
-                    ),
-                  ),
-                ),
-              ),
-              const SizedBox(height: 40),
-
-              // Track Info
-              Text(
-                currentTrack.name,
-                style: const TextStyle(
-                  color: Colors.white,
-                  fontSize: 24,
-                  fontWeight: FontWeight.bold,
-                ),
-                textAlign: TextAlign.center,
-                maxLines: 2,
-                overflow: TextOverflow.ellipsis,
-              ),
-              const SizedBox(height: 8),
-              Text(
-                currentTrack.artistsString,
-                style: const TextStyle(
-                  color: Colors.white70,
-                  fontSize: 16,
-                ),
-                textAlign: TextAlign.center,
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-              ),
-              if (currentTrack.album != null) ...[
-                const SizedBox(height: 4),
-                Text(
-                  currentTrack.album!.name,
-                  style: const TextStyle(
-                    color: Colors.white54,
-                    fontSize: 14,
-                  ),
-                  textAlign: TextAlign.center,
-                  maxLines: 1,
-                  overflow: TextOverflow.ellipsis,
-                ),
-              ],
-              const SizedBox(height: 32),
-
-              // Progress Bar (showing elapsed time)
-              if (currentTrack.duration != null) ...[
-                Slider(
-                  value: selectedPlayer.currentElapsedTime.clamp(0, currentTrack.duration!.inSeconds.toDouble()),
-                  max: currentTrack.duration!.inSeconds.toDouble(),
-                  onChanged: null, // TODO: Implement seek
-                  activeColor: Colors.white,
-                  inactiveColor: Colors.white24,
-                ),
-                Padding(
-                  padding: const EdgeInsets.symmetric(horizontal: 8.0),
-                  child: Row(
-                    mainAxisAlignment: MainAxisAlignment.spaceBetween,
-                    children: [
-                      Text(
-                        _formatDuration(selectedPlayer.currentElapsedTime.toInt()),
-                        style: const TextStyle(color: Colors.white54, fontSize: 12),
-                      ),
-                      Text(
-                        _formatDuration(currentTrack.duration!.inSeconds),
-                        style: const TextStyle(color: Colors.white54, fontSize: 12),
-                      ),
-                    ],
-                  ),
-                ),
-              ] else
-                // Show indeterminate progress if no duration available
-                const LinearProgressIndicator(
-                  backgroundColor: Colors.white24,
-                  valueColor: AlwaysStoppedAnimation<Color>(Colors.white),
-                ),
-              const SizedBox(height: 16),
-
-              // Playback Controls
-              Row(
-                mainAxisAlignment: MainAxisAlignment.center,
-                children: [
-                  // Shuffle
-                  IconButton(
-                    icon: Icon(
-                      Icons.shuffle,
-                      color: _queue?.shuffle == true ? Colors.blue : Colors.white54,
-                    ),
-                    iconSize: 24,
-                    onPressed: _isLoadingQueue ? null : _toggleShuffle,
-                  ),
-                  const SizedBox(width: 12),
-                  // Previous
-                  AnimatedIconButton(
-                    icon: Icons.skip_previous_rounded,
-                    color: Colors.white,
-                    iconSize: 42,
-                    onPressed: () async {
-                      try {
-                        await maProvider.previousTrackSelectedPlayer();
-                      } catch (e) {
-                        print('❌ Error in previous track: $e');
-                        if (mounted) {
-                          ScaffoldMessenger.of(context).showSnackBar(
-                            SnackBar(content: Text('Error: $e')),
-                          );
-                        }
-                      }
-                    },
-                  ),
-                  const SizedBox(width: 12),
-                  // Play/Pause
-                  _AnimatedPlayButton(
-                    isPlaying: selectedPlayer.isPlaying,
-                    onPressed: () async {
-                      try {
-                        await maProvider.playPauseSelectedPlayer();
-                      } catch (e) {
-                        print('❌ Error in play/pause: $e');
-                        if (mounted) {
-                          ScaffoldMessenger.of(context).showSnackBar(
-                            SnackBar(content: Text('Error: $e')),
-                          );
-                        }
-                      }
-                    },
-                  ),
-                  const SizedBox(width: 12),
-                  // Next
-                  AnimatedIconButton(
-                    icon: Icons.skip_next_rounded,
-                    color: Colors.white,
-                    iconSize: 42,
-                    onPressed: () async {
-                      try {
-                        await maProvider.nextTrackSelectedPlayer();
-                      } catch (e) {
-                        print('❌ Error in next track: $e');
-                        if (mounted) {
-                          ScaffoldMessenger.of(context).showSnackBar(
-                            SnackBar(content: Text('Error: $e')),
-                          );
-                        }
-                      }
-                    },
-                  ),
-                  const SizedBox(width: 12),
-                  // Repeat
-                  IconButton(
-                    icon: Icon(
-                      _queue?.repeatMode == 'one'
-                          ? Icons.repeat_one
-                          : Icons.repeat,
-                      color: _queue?.repeatMode != null && _queue!.repeatMode != 'off'
-                          ? Colors.blue
-                          : Colors.white54,
-                    ),
-                    iconSize: 24,
-                    onPressed: _isLoadingQueue ? null : _cycleRepeat,
-                  ),
-                ],
-              ),
-              const SizedBox(height: 32),
-
-              // Volume Control
-              const Padding(
-                padding: EdgeInsets.symmetric(horizontal: 16.0),
-                child: VolumeControl(compact: false),
-              ),
-              const Spacer(),
-            ],
-          ),
-        ),
-      ),
-    );
-  }
-
-  String _formatDuration(int seconds) {
-    final duration = Duration(seconds: seconds);
-    final minutes = duration.inMinutes;
-    final secs = duration.inSeconds % 60;
-    return '${minutes.toString().padLeft(1, '0')}:${secs.toString().padLeft(2, '0')}';
-  }
-}
-
-/// Animated play/pause button with scale animation
-class _AnimatedPlayButton extends StatefulWidget {
-  final bool isPlaying;
-  final VoidCallback onPressed;
-
-  const _AnimatedPlayButton({
-    required this.isPlaying,
-    required this.onPressed,
-  });
-
-  @override
-  State<_AnimatedPlayButton> createState() => _AnimatedPlayButtonState();
-}
-
-class _AnimatedPlayButtonState extends State<_AnimatedPlayButton>
-    with SingleTickerProviderStateMixin {
-  late AnimationController _controller;
-  late Animation<double> _scaleAnimation;
-
-  @override
-  void initState() {
-    super.initState();
-    _controller = AnimationController(
-      duration: const Duration(milliseconds: 100),
-      vsync: this,
-    );
-    _scaleAnimation = Tween<double>(begin: 1.0, end: 0.85).animate(
-      CurvedAnimation(parent: _controller, curve: Curves.easeInOut),
-    );
-  }
-
-  @override
-  void dispose() {
-    _controller.dispose();
-    super.dispose();
-  }
-
-  Future<void> _handleTap() async {
-    // Animate press
-    await _controller.forward();
-    await _controller.reverse();
-
-    // Call the callback
-    widget.onPressed();
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return GestureDetector(
-      onTapDown: (_) => _controller.forward(),
-      onTapUp: (_) => _controller.reverse(),
-      onTapCancel: () => _controller.reverse(),
-      child: ScaleTransition(
-        scale: _scaleAnimation,
-        child: Container(
-          width: 72,
-          height: 72,
-          decoration: const BoxDecoration(
-            color: Colors.white,
-            shape: BoxShape.circle,
-          ),
-          child: IconButton(
-            icon: Icon(
-              widget.isPlaying ? Icons.pause_rounded : Icons.play_arrow_rounded,
-            ),
-            color: const Color(0xFF1a1a1a),
-            iconSize: 42,
-            onPressed: _handleTap,
-          ),
-        ),
-      ),
-    );
-  }
-}

lib/screens/playlist_details_screen.dart

@@ -1,7 +1,12 @@
 import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
+import '../l10n/app_localizations.dart';
 import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
+import '../services/debug_logger.dart';
+import '../services/recently_played_service.dart';
+
+final _playlistLogger = DebugLogger();
 
 class PlaylistDetailsScreen extends StatefulWidget {
   final Playlist playlist;
@@ -30,24 +35,48 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
   }
 
   Future<void> _loadTracks() async {
-    setState(() {
-      _isLoading = true;
-    });
-
     final maProvider = context.read<MusicAssistantProvider>();
-    if (maProvider.api != null) {
-      final tracks = await maProvider.api!.getPlaylistTracks(
+    final cacheKey = '${widget.provider}_${widget.itemId}';
+
+    // 1. Show cached data immediately (if available)
+    final cachedTracks = maProvider.getCachedPlaylistTracks(cacheKey);
+    if (cachedTracks != null && cachedTracks.isNotEmpty) {
+      if (mounted) {
+        setState(() {
+          _tracks = cachedTracks;
+          _isLoading = false;
+        });
+      }
+    } else {
+      setState(() => _isLoading = true);
+    }
+
+    // 2. Fetch fresh data in background (silent refresh)
+    try {
+      final freshTracks = await maProvider.getPlaylistTracksWithCache(
         widget.provider,
         widget.itemId,
+        forceRefresh: cachedTracks != null,
       );
-      setState(() {
-        _tracks = tracks;
-        _isLoading = false;
-      });
-    } else {
-      setState(() {
-        _isLoading = false;
-      });
+
+      // 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) {
+      // Silent failure - keep showing cached data
+    }
+
+    if (mounted && _isLoading) {
+      setState(() => _isLoading = false);
     }
   }
 
@@ -60,26 +89,29 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
       // Use the selected player
       final player = maProvider.selectedPlayer;
       if (player == null) {
-        _showError('No player selected');
+        _showError(S.of(context)!.noPlayerSelected);
         return;
       }
 
-      print('🎵 Queueing playlist on ${player.name}: ${player.playerId}');
+      _playlistLogger.info('Queueing playlist on ${player.name}', context: 'Playlist');
 
       // Queue all tracks via Music Assistant
       await maProvider.playTracks(player.playerId, _tracks, startIndex: 0);
-      print('✓ Playlist queued on ${player.name}');
+      _playlistLogger.info('Playlist queued successfully', context: 'Playlist');
+
+      // Record to local recently played (per-profile)
+      RecentlyPlayedService.instance.recordPlaylistPlayed(widget.playlist);
 
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(
           SnackBar(
-            content: Text('Playing ${widget.playlist.name}'),
+            content: Text(S.of(context)!.playing(widget.playlist.name)),
             duration: const Duration(seconds: 2),
           ),
         );
       }
     } catch (e) {
-      print('Error playing playlist: $e');
+      _playlistLogger.error('Error playing playlist', context: 'Playlist', error: e);
       _showError('Error playing playlist: $e');
     }
   }
@@ -101,8 +133,8 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
     final imageUrl = maProvider.api?.getImageUrl(widget.playlist, size: 400);
 
     return Scaffold(
-      backgroundColor: const Color(0xFF1a1a1a),
-      body: CustomScrollView(
+        backgroundColor: const Color(0xFF1a1a1a),
+        body: CustomScrollView(
         slivers: [
           SliverAppBar(
             expandedHeight: 300,
@@ -191,7 +223,7 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
                     child: ElevatedButton.icon(
                       onPressed: _isLoading ? null : _playPlaylist,
                       icon: const Icon(Icons.play_arrow_rounded),
-                      label: const Text('Play'),
+                      label: Text(S.of(context)!.play),
                       style: ElevatedButton.styleFrom(
                         backgroundColor: Colors.white,
                         foregroundColor: const Color(0xFF1a1a1a),
@@ -204,9 +236,9 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
                   ),
                   const SizedBox(height: 24),
                   // Tracks header
-                  const Text(
-                    'Tracks',
-                    style: TextStyle(
+                  Text(
+                    S.of(context)!.tracks,
+                    style: const TextStyle(
                       color: Colors.white,
                       fontSize: 18,
                       fontWeight: FontWeight.bold,
@@ -226,7 +258,7 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
                   ? SliverFillRemaining(
                       child: Center(
                         child: Text(
-                          'No tracks in playlist',
+                          S.of(context)!.noTracksInPlaylist,
                           style: TextStyle(
                             color: Colors.grey[600],
                             fontSize: 16,
@@ -323,7 +355,7 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
         onPressed: () async {
           final player = maProvider.selectedPlayer;
           if (player == null) {
-            _showError('No player selected');
+            _showError(S.of(context)!.noPlayerSelected);
             return;
           }
 
@@ -332,9 +364,9 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> {
             await maProvider.playTracks(player.playerId, _tracks, startIndex: index);
             if (mounted) {
               ScaffoldMessenger.of(context).showSnackBar(
-                const SnackBar(
-                  content: Text('Playing track'),
-                  duration: Duration(seconds: 1),
+                SnackBar(
+                  content: Text(S.of(context)!.playingTrack),
+                  duration: const Duration(seconds: 1),
                 ),
               );
             }

lib/screens/queue_screen.dart

@@ -2,6 +2,9 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import '../providers/music_assistant_provider.dart';
 import '../models/player.dart';
+import '../services/debug_logger.dart';
+import '../widgets/common/empty_state.dart';
+import '../l10n/app_localizations.dart';
 
 class QueueScreen extends StatefulWidget {
   const QueueScreen({super.key});
@@ -11,33 +14,56 @@ class QueueScreen extends StatefulWidget {
 }
 
 class _QueueScreenState extends State<QueueScreen> {
+  final _logger = DebugLogger();
   PlayerQueue? _queue;
   bool _isLoading = true;
+  String? _error;
 
   @override
   void initState() {
     super.initState();
-    _loadQueue();
+    // Use addPostFrameCallback to safely access context after build
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      _loadQueue();
+    });
   }
 
   Future<void> _loadQueue() async {
+    if (!mounted) return;
+
     setState(() {
       _isLoading = true;
+      _error = null;
     });
 
-    final maProvider = context.read<MusicAssistantProvider>();
-    final player = maProvider.selectedPlayer;
+    try {
+      final maProvider = context.read<MusicAssistantProvider>();
+      final player = maProvider.selectedPlayer;
 
-    if (player != null && maProvider.api != null) {
-      final queue = await maProvider.api!.getQueue(player.playerId);
-      setState(() {
-        _queue = queue;
-        _isLoading = false;
-      });
-    } else {
-      setState(() {
-        _isLoading = false;
-      });
+      if (player != null && maProvider.api != null) {
+        final queue = await maProvider.api!.getQueue(player.playerId);
+        if (mounted) {
+          setState(() {
+            _queue = queue;
+            _isLoading = false;
+          });
+        }
+      } else {
+        if (mounted) {
+          setState(() {
+            _isLoading = false;
+            _error = S.of(context)!.noPlayerSelected;
+          });
+        }
+      }
+    } catch (e) {
+      _logger.log('QueueScreen error loading queue: $e');
+      if (mounted) {
+        setState(() {
+          _isLoading = false;
+          _error = 'Failed to load queue: $e';
+        });
+      }
     }
   }
 
@@ -52,7 +78,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,
@@ -76,6 +102,28 @@ class _QueueScreenState extends State<QueueScreen> {
       return const Center(child: CircularProgressIndicator());
     }
 
+    if (_error != null) {
+      return Center(
+        child: Column(
+          mainAxisAlignment: MainAxisAlignment.center,
+          children: [
+            Icon(Icons.error_outline, size: 64, color: Colors.red[400]),
+            const SizedBox(height: 16),
+            Text(
+              _error!,
+              style: TextStyle(color: Colors.red[300], fontSize: 16),
+              textAlign: TextAlign.center,
+            ),
+            const SizedBox(height: 16),
+            ElevatedButton(
+              onPressed: _loadQueue,
+              child: Text(S.of(context)!.retry),
+            ),
+          ],
+        ),
+      );
+    }
+
     if (maProvider.selectedPlayer == null) {
       return Center(
         child: Column(
@@ -84,7 +132,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),
             ),
           ],
@@ -93,19 +141,7 @@ class _QueueScreenState extends State<QueueScreen> {
     }
 
     if (_queue == null || _queue!.items.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            Icon(Icons.queue_music, size: 64, color: Colors.grey[700]),
-            const SizedBox(height: 16),
-            Text(
-              'Queue is empty',
-              style: TextStyle(color: Colors.grey[600], fontSize: 18),
-            ),
-          ],
-        ),
-      );
+      return EmptyState.queue(context: context);
     }
 
     // Filter to show only current and upcoming items (not history)
@@ -113,18 +149,9 @@ class _QueueScreenState extends State<QueueScreen> {
     final upcomingItems = _queue!.items.sublist(currentIndex);
 
     if (upcomingItems.isEmpty) {
-      return Center(
-        child: Column(
-          mainAxisAlignment: MainAxisAlignment.center,
-          children: [
-            Icon(Icons.queue_music, size: 64, color: Colors.grey[700]),
-            const SizedBox(height: 16),
-            Text(
-              'No upcoming tracks',
-              style: TextStyle(color: Colors.grey[600], fontSize: 18),
-            ),
-          ],
-        ),
+      return EmptyState(
+        icon: Icons.queue_music,
+        message: S.of(context)!.noUpcomingTracks,
       );
     }
 
@@ -185,15 +212,18 @@ class _QueueScreenState extends State<QueueScreen> {
       ),
       onDismissed: (direction) {
         // TODO: Implement queue item removal via API
+        // Currently only removes locally from UI state, not from actual Music Assistant queue
+        // Need to investigate if Music Assistant API supports player_queues/remove_item or similar endpoint
+        // Requires: API method like removeQueueItem(queueId, queueItemId) that calls player_queues/remove_item
         setState(() {
           _queue!.items.removeAt(index);
         });
 
         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);
@@ -209,13 +239,10 @@ class _QueueScreenState extends State<QueueScreen> {
           leading: Row(
             mainAxisSize: MainAxisSize.min,
             children: [
-              // Drag handle
-              ReorderableDragStartListener(
-                index: index,
-                child: Icon(
-                  Icons.drag_handle,
-                  color: Colors.grey[600],
-                ),
+              // Drag handle (visual only for now - reordering not implemented)
+              Icon(
+                Icons.drag_handle,
+                color: Colors.grey[600],
               ),
               const SizedBox(width: 8),
               // Album art

lib/services/animation_debugger.dart

@@ -0,0 +1,236 @@
+import 'dart:collection';
+import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
+import 'debug_logger.dart';
+
+/// Comprehensive animation debugging utility for diagnosing jank and performance issues.
+///
+/// Usage:
+/// 1. Call AnimationDebugger.startSession('playerExpand') at animation start
+/// 2. Call AnimationDebugger.recordFrame() in animation listener (every frame)
+/// 3. Call AnimationDebugger.endSession() when animation completes
+/// 4. Logs will show frame timing, jank detection, and summary stats
+class AnimationDebugger {
+  static final _logger = DebugLogger();
+  static bool _enabled = false; // Disabled for release - enable for debugging animation jank
+
+  // Session tracking
+  static String? _currentSession;
+  static int _frameCount = 0;
+  static final List<_FrameData> _frames = [];
+  static DateTime? _sessionStart;
+  static double? _lastAnimationValue;
+
+  // Scheduler binding for frame timing
+  static Duration? _lastFrameTime;
+
+  /// Enable or disable animation debugging
+  static void setEnabled(bool enabled) {
+    _enabled = enabled;
+  }
+
+  /// Start a new animation debugging session
+  static void startSession(String name) {
+    if (!_enabled) return;
+
+    _currentSession = name;
+    _frameCount = 0;
+    _frames.clear();
+    _sessionStart = DateTime.now();
+    _lastFrameTime = null;
+    _lastAnimationValue = null;
+
+    // Listen to frame timing
+    SchedulerBinding.instance.addPostFrameCallback(_onFirstFrame);
+
+    _logger.log('🎬 ANIM[$name] START');
+  }
+
+  static void _onFirstFrame(Duration timestamp) {
+    _lastFrameTime = timestamp;
+  }
+
+  /// Record a frame during animation
+  /// [animationValue] - current animation progress (0.0 to 1.0)
+  /// [context] - optional context string for this frame
+  static void recordFrame(double animationValue, {String? context}) {
+    if (!_enabled || _currentSession == null) return;
+
+    final now = DateTime.now();
+    final frameTime = SchedulerBinding.instance.currentFrameTimeStamp;
+
+    Duration? frameDuration;
+    if (_lastFrameTime != null) {
+      frameDuration = frameTime - _lastFrameTime!;
+    }
+    _lastFrameTime = frameTime;
+
+    // Calculate animation delta
+    double? animationDelta;
+    if (_lastAnimationValue != null) {
+      animationDelta = (animationValue - _lastAnimationValue!).abs();
+    }
+    _lastAnimationValue = animationValue;
+
+    final frame = _FrameData(
+      frameNumber: _frameCount,
+      timestamp: now,
+      frameDuration: frameDuration,
+      animationValue: animationValue,
+      animationDelta: animationDelta,
+      context: context,
+    );
+
+    _frames.add(frame);
+    _frameCount++;
+
+    // Log jank immediately (frames > 16.67ms for 60fps)
+    if (frameDuration != null && frameDuration.inMicroseconds > 16667) {
+      final ms = frameDuration.inMicroseconds / 1000;
+      _logger.log('🔴 ANIM[$_currentSession] JANK frame $_frameCount: ${ms.toStringAsFixed(2)}ms (>${(ms/16.67).toStringAsFixed(1)}x target)');
+    }
+  }
+
+  /// Record a build/layout event during animation
+  static void recordBuild(String widgetName) {
+    if (!_enabled || _currentSession == null) return;
+    _logger.log('🔨 ANIM[$_currentSession] BUILD: $widgetName at frame $_frameCount');
+  }
+
+  /// End the current session and log summary
+  static void endSession() {
+    if (!_enabled || _currentSession == null) return;
+
+    final sessionName = _currentSession!;
+    final totalDuration = DateTime.now().difference(_sessionStart!);
+
+    // Calculate statistics
+    int jankFrames = 0;
+    int severeJankFrames = 0;
+    double maxFrameMs = 0;
+    double totalFrameMs = 0;
+    int measuredFrames = 0;
+
+    for (final frame in _frames) {
+      if (frame.frameDuration != null) {
+        final ms = frame.frameDuration!.inMicroseconds / 1000;
+        totalFrameMs += ms;
+        measuredFrames++;
+
+        if (ms > maxFrameMs) maxFrameMs = ms;
+        if (ms > 16.67) jankFrames++;
+        if (ms > 33.33) severeJankFrames++; // Dropped more than 1 frame
+      }
+    }
+
+    final avgFrameMs = measuredFrames > 0 ? totalFrameMs / measuredFrames : 0;
+    final effectiveFps = avgFrameMs > 0 ? 1000 / avgFrameMs : 0;
+
+    // Build summary
+    final buffer = StringBuffer();
+    buffer.writeln('');
+    buffer.writeln('═══════════════════════════════════════');
+    buffer.writeln('🎬 ANIMATION SUMMARY: $sessionName');
+    buffer.writeln('═══════════════════════════════════════');
+    buffer.writeln('Duration: ${totalDuration.inMilliseconds}ms');
+    buffer.writeln('Total frames: $_frameCount');
+    buffer.writeln('Measured frames: $measuredFrames');
+    buffer.writeln('Average frame: ${avgFrameMs.toStringAsFixed(2)}ms');
+    buffer.writeln('Max frame: ${maxFrameMs.toStringAsFixed(2)}ms');
+    buffer.writeln('Effective FPS: ${effectiveFps.toStringAsFixed(1)}');
+    buffer.writeln('Jank frames (>16.67ms): $jankFrames (${measuredFrames > 0 ? (jankFrames * 100 / measuredFrames).toStringAsFixed(1) : 0}%)');
+    buffer.writeln('Severe jank (>33.33ms): $severeJankFrames');
+
+    // List worst frames
+    if (_frames.isNotEmpty) {
+      final sortedFrames = List<_FrameData>.from(_frames)
+        ..sort((a, b) {
+          final aMs = a.frameDuration?.inMicroseconds ?? 0;
+          final bMs = b.frameDuration?.inMicroseconds ?? 0;
+          return bMs.compareTo(aMs);
+        });
+
+      final worstFrames = sortedFrames.take(5).where((f) => f.frameDuration != null && f.frameDuration!.inMicroseconds > 16667).toList();
+
+      if (worstFrames.isNotEmpty) {
+        buffer.writeln('');
+        buffer.writeln('Worst frames:');
+        for (final frame in worstFrames) {
+          final ms = frame.frameDuration!.inMicroseconds / 1000;
+          buffer.writeln('  Frame ${frame.frameNumber}: ${ms.toStringAsFixed(2)}ms (anim=${frame.animationValue.toStringAsFixed(3)})');
+        }
+      }
+    }
+
+    buffer.writeln('═══════════════════════════════════════');
+
+    _logger.log(buffer.toString());
+
+    // Reset
+    _currentSession = null;
+    _frames.clear();
+    _sessionStart = null;
+    _lastAnimationValue = null;
+  }
+
+  /// Log a one-off animation event (for Hero transitions, page transitions, etc.)
+  static void logEvent(String event, {String? details}) {
+    if (!_enabled) return;
+    final detailStr = details != null ? ' - $details' : '';
+    _logger.log('🎬 ANIM_EVENT: $event$detailStr');
+  }
+
+  /// Log frame callback timing (call this from addPostFrameCallback)
+  static void logPostFrame(String context) {
+    if (!_enabled) return;
+    final frameTime = SchedulerBinding.instance.currentFrameTimeStamp;
+    _logger.log('📐 POST_FRAME[$context]: ${frameTime.inMilliseconds}ms');
+  }
+
+  /// Create a HeroFlightShuttleBuilder that logs Hero animation progress
+  static HeroFlightShuttleBuilder createHeroDebugShuttle(String heroTag) {
+    return (
+      BuildContext flightContext,
+      Animation<double> animation,
+      HeroFlightDirection flightDirection,
+      BuildContext fromHeroContext,
+      BuildContext toHeroContext,
+    ) {
+      // Log Hero flight start
+      if (animation.value < 0.1) {
+        logEvent('Hero flight START', details: 'tag=$heroTag, direction=${flightDirection.name}');
+      }
+
+      // Add listener for completion (one-shot)
+      void onComplete(AnimationStatus status) {
+        if (status == AnimationStatus.completed || status == AnimationStatus.dismissed) {
+          logEvent('Hero flight END', details: 'tag=$heroTag, status=${status.name}');
+          animation.removeStatusListener(onComplete);
+        }
+      }
+      animation.addStatusListener(onComplete);
+
+      // Return default shuttle (the toHero's child)
+      final Hero toHero = toHeroContext.widget as Hero;
+      return toHero.child;
+    };
+  }
+}
+
+class _FrameData {
+  final int frameNumber;
+  final DateTime timestamp;
+  final Duration? frameDuration;
+  final double animationValue;
+  final double? animationDelta;
+  final String? context;
+
+  _FrameData({
+    required this.frameNumber,
+    required this.timestamp,
+    this.frameDuration,
+    required this.animationValue,
+    this.animationDelta,
+    this.context,
+  });
+}

lib/services/audio/massiv_audio_handler.dart

@@ -0,0 +1,296 @@
+import 'package:audio_service/audio_service.dart';
+import 'package:audio_session/audio_session.dart';
+import 'package:just_audio/just_audio.dart';
+import '../debug_logger.dart';
+import '../auth/auth_manager.dart';
+
+/// Custom AudioHandler for Ensemble that provides full control over
+/// notification actions and metadata updates.
+class MassivAudioHandler extends BaseAudioHandler with SeekHandler {
+  final AudioPlayer _player = AudioPlayer();
+  final AuthManager authManager;
+  final _logger = DebugLogger();
+
+  // Track current metadata separately from what's in the notification
+  // This allows us to update the notification when metadata arrives late
+  MediaItem? _currentMediaItem;
+
+  // Callbacks for actions (wired up by MusicAssistantProvider)
+  Function()? onSkipToNext;
+  Function()? onSkipToPrevious;
+  Function()? onPlay;
+  Function()? onPause;
+  Function()? onSwitchPlayer;
+
+  // Track whether we're in remote control mode (controlling MA player, not playing locally)
+  bool _isRemoteMode = false;
+
+  // Custom control for switching players (uses stop action with custom icon)
+  static const _switchPlayerControl = MediaControl(
+    androidIcon: 'drawable/ic_switch_player',
+    label: 'Switch Player',
+    action: MediaAction.stop,
+  );
+
+  MassivAudioHandler({required this.authManager}) {
+    _init();
+  }
+
+  Future<void> _init() async {
+    // Configure audio session
+    final session = await AudioSession.instance;
+    await session.configure(const AudioSessionConfiguration.music());
+
+    // Handle audio interruptions
+    session.interruptionEventStream.listen((event) {
+      if (event.begin) {
+        switch (event.type) {
+          case AudioInterruptionType.duck:
+            _player.setVolume(0.5);
+            break;
+          case AudioInterruptionType.pause:
+          case AudioInterruptionType.unknown:
+            pause();
+            break;
+        }
+      } else {
+        switch (event.type) {
+          case AudioInterruptionType.duck:
+            _player.setVolume(1.0);
+            break;
+          case AudioInterruptionType.pause:
+            play();
+            break;
+          case AudioInterruptionType.unknown:
+            break;
+        }
+      }
+    });
+
+    // Handle becoming noisy (headphones unplugged)
+    session.becomingNoisyEventStream.listen((_) {
+      pause();
+    });
+
+    // Broadcast playback state changes
+    _player.playbackEventStream.listen(_broadcastState);
+
+    // Broadcast current media item changes
+    _player.currentIndexStream.listen((_) {
+      if (_currentMediaItem != null) {
+        mediaItem.add(_currentMediaItem);
+      }
+    });
+  }
+
+  /// Broadcast the current playback state to the system
+  void _broadcastState(PlaybackEvent event) {
+    final playing = _player.playing;
+
+    playbackState.add(playbackState.value.copyWith(
+      // Configure notification action buttons
+      controls: [
+        MediaControl.skipToPrevious,
+        if (playing) MediaControl.pause else MediaControl.play,
+        MediaControl.skipToNext,
+        _switchPlayerControl, // Switch player button
+      ],
+      // System-level actions (for headphones, car stereos, etc.)
+      systemActions: const {
+        MediaAction.seek,
+        MediaAction.seekForward,
+        MediaAction.seekBackward,
+        MediaAction.play,
+        MediaAction.pause,
+        MediaAction.stop,
+        MediaAction.skipToNext,
+        MediaAction.skipToPrevious,
+      },
+      // Which buttons to show in compact notification (max 3)
+      // Show: play/pause (1), skip-next (2), switch-player (3)
+      androidCompactActionIndices: const [1, 2, 3],
+      processingState: {
+        ProcessingState.idle: AudioProcessingState.idle,
+        ProcessingState.loading: AudioProcessingState.loading,
+        ProcessingState.buffering: AudioProcessingState.buffering,
+        ProcessingState.ready: AudioProcessingState.ready,
+        ProcessingState.completed: AudioProcessingState.completed,
+      }[_player.processingState]!,
+      playing: playing,
+      updatePosition: _player.position,
+      bufferedPosition: _player.bufferedPosition,
+      speed: _player.speed,
+    ));
+  }
+
+  // --- Playback control methods ---
+
+  @override
+  Future<void> play() async {
+    if (_isRemoteMode) {
+      onPlay?.call();
+    } else {
+      await _player.play();
+    }
+  }
+
+  @override
+  Future<void> pause() async {
+    if (_isRemoteMode) {
+      onPause?.call();
+    } else {
+      await _player.pause();
+    }
+  }
+
+  @override
+  Future<void> stop() async {
+    // Stop action is used for switching players (both local and remote modes)
+    onSwitchPlayer?.call();
+    // Note: We don't actually stop playback - this button is repurposed for player switching
+  }
+
+  @override
+  Future<void> seek(Duration position) => _player.seek(position);
+
+  @override
+  Future<void> skipToNext() async {
+    onSkipToNext?.call();
+  }
+
+  @override
+  Future<void> skipToPrevious() async {
+    onSkipToPrevious?.call();
+  }
+
+  // --- Custom methods for Ensemble ---
+
+  /// Play a URL with the given metadata
+  Future<void> playUrl(String url, MediaItem item, {Map<String, String>? headers}) async {
+    _currentMediaItem = item;
+    mediaItem.add(item);
+
+    try {
+      final source = AudioSource.uri(
+        Uri.parse(url),
+        headers: headers,
+        tag: item,
+      );
+
+      await _player.setAudioSource(source);
+      await _player.play();
+    } catch (e) {
+      _logger.log('MassivAudioHandler: Error playing URL: $e');
+      rethrow;
+    }
+  }
+
+  /// Update the current media item (for notification display)
+  /// This can be called when metadata arrives after playback starts
+  @override
+  Future<void> updateMediaItem(MediaItem item) async {
+    _currentMediaItem = item;
+    mediaItem.add(item);
+  }
+
+  /// Set volume (0.0 to 1.0)
+  Future<void> setVolume(double volume) async {
+    await _player.setVolume(volume.clamp(0.0, 1.0));
+  }
+
+  /// Set remote playback state (for controlling MA players without local playback)
+  /// This shows the notification and responds to media controls without playing audio locally.
+  void setRemotePlaybackState({
+    required MediaItem item,
+    required bool playing,
+    Duration position = Duration.zero,
+    Duration? duration,
+  }) {
+    _isRemoteMode = true;
+    _currentMediaItem = item;
+    mediaItem.add(item);
+
+    playbackState.add(playbackState.value.copyWith(
+      controls: [
+        MediaControl.skipToPrevious,
+        if (playing) MediaControl.pause else MediaControl.play,
+        MediaControl.skipToNext,
+        _switchPlayerControl,
+      ],
+      systemActions: const {
+        MediaAction.play,
+        MediaAction.pause,
+        MediaAction.skipToNext,
+        MediaAction.skipToPrevious,
+        MediaAction.stop,
+      },
+      // Which buttons to show in compact notification (max 3)
+      // Show: play/pause (1), skip-next (2), switch-player (3)
+      androidCompactActionIndices: const [1, 2, 3],
+      processingState: AudioProcessingState.ready,
+      playing: playing,
+      updatePosition: position,
+      bufferedPosition: duration ?? Duration.zero,
+      speed: 1.0,
+    ));
+  }
+
+  /// Clear remote playback state and hide notification
+  void clearRemotePlaybackState() {
+    _isRemoteMode = false;
+    _currentMediaItem = null;
+
+    playbackState.add(playbackState.value.copyWith(
+      controls: [],
+      processingState: AudioProcessingState.idle,
+      playing: false,
+    ));
+  }
+
+  /// Switch to local playback mode (when builtin player is selected)
+  void setLocalMode() {
+    _isRemoteMode = false;
+  }
+
+  /// Update notification for local mode (builtin player) without switching to remote mode
+  /// This allows the notification to show the correct player/track info while keeping
+  /// pause working for local audio playback.
+  void updateLocalModeNotification({
+    required MediaItem item,
+    required bool playing,
+    Duration? duration,
+  }) {
+    // Keep local mode - DON'T set _isRemoteMode = true
+    // Only update mediaItem if it changed - avoid unnecessary notification refreshes
+    // that cause blinking. The playbackState is managed by _broadcastState which
+    // responds to actual player events.
+    if (_currentMediaItem?.id != item.id ||
+        _currentMediaItem?.title != item.title ||
+        _currentMediaItem?.artist != item.artist) {
+      _currentMediaItem = item;
+      mediaItem.add(item);
+    }
+  }
+
+  bool get isRemoteMode => _isRemoteMode;
+
+  // --- Expose player state for provider ---
+
+  bool get isPlaying => _player.playing;
+
+  Duration get position => _player.position;
+
+  Duration get duration => _player.duration ?? Duration.zero;
+
+  double get volume => _player.volume;
+
+  PlayerState get playerState => _player.playerState;
+
+  Stream<PlayerState> get playerStateStream => _player.playerStateStream;
+
+  Stream<Duration> get positionStream => _player.positionStream;
+
+  Stream<Duration?> get durationStream => _player.durationStream;
+
+  MediaItem? get currentMediaItem => _currentMediaItem;
+}

lib/services/auth/auth_manager.dart

@@ -0,0 +1,467 @@
+import 'dart:convert';
+import 'dart:io';
+import 'package:http/http.dart' as http;
+import 'auth_strategy.dart';
+import 'no_auth_strategy.dart';
+import 'basic_auth_strategy.dart';
+import 'authelia_strategy.dart';
+import 'ma_auth_strategy.dart';
+import '../debug_logger.dart';
+
+/// Central authentication manager
+/// Manages auth strategy selection, auto-detection, and credential lifecycle
+class AuthManager {
+  final _logger = DebugLogger();
+
+  // Available auth strategies
+  final List<AuthStrategy> _strategies = [
+    NoAuthStrategy(),
+    BasicAuthStrategy(),
+    AutheliaStrategy(),
+    MusicAssistantAuthStrategy(),
+  ];
+
+  AuthStrategy? _currentStrategy;
+  AuthCredentials? _currentCredentials;
+
+  /// Get current auth strategy (null if none selected)
+  AuthStrategy? get currentStrategy => _currentStrategy;
+
+  /// Get current credentials (null if none stored)
+  AuthCredentials? get currentCredentials => _currentCredentials;
+
+  /// 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 = _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.') ||
+          baseUrl.startsWith('10.') ||
+          baseUrl.startsWith('172.') ||
+          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');
+  }
+
+  /// 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 at $baseUrl...');
+    final maAuthResult = await _checkMusicAssistantAuth(baseUrl);
+    if (maAuthResult != null) {
+      if (maAuthResult == 'required') {
+        _logger.log('✓ Detected Music Assistant native authentication');
+        return _strategies.firstWhere((s) => s.name == 'music_assistant');
+      } else if (maAuthResult == 'none') {
+        _logger.log('✓ Music Assistant server - no auth required');
+        return _strategies.firstWhere((s) => s.name == 'none');
+      }
+    }
+
+    // Try no-auth (direct connection without any auth)
+    _logger.log('Testing no-auth strategy...');
+    final canConnect = await _canConnectWithoutAuth(baseUrl);
+    _logger.log('No-auth result: $canConnect');
+
+    if (canConnect) {
+      _logger.log('✓ Server does not require authentication');
+      return _strategies.firstWhere((s) => s.name == 'none');
+    }
+
+    // Probe server for auth requirements (reverse proxy scenarios)
+    try {
+      _logger.log('Probing server for auth headers...');
+      // Test root endpoint
+      final probeUrl = baseUrl;
+      _logger.log('Probe URL: $probeUrl');
+
+      final response = await http.get(
+        Uri.parse(probeUrl),
+      ).timeout(const Duration(seconds: 10));
+
+      _logger.log('Probe status: ${response.statusCode}');
+
+      // Check for redirect (common with reverse proxy auth)
+      if (response.statusCode == 302 || response.statusCode == 307) {
+        final location = response.headers['location'];
+        _logger.log('Redirect to: $location');
+
+        // If redirects to Authelia login, it's Authelia
+        if (location != null && location.contains('authelia')) {
+          _logger.log('✓ Detected Authelia (redirect)');
+          return _strategies.firstWhere((s) => s.name == 'authelia');
+        }
+      }
+
+      // Server returned 401 Unauthorized - check WWW-Authenticate header
+      if (response.statusCode == 401) {
+        final wwwAuth = response.headers['www-authenticate']?.toLowerCase();
+        _logger.log('401 with WWW-Authenticate: $wwwAuth');
+
+        // Check for Basic Auth
+        if (wwwAuth != null && wwwAuth.contains('basic')) {
+          _logger.log('✓ Detected Basic Authentication');
+          return _strategies.firstWhere((s) => s.name == 'basic');
+        }
+
+        // Check for Bearer token - could be MA native auth
+        if (wwwAuth != null && wwwAuth.contains('bearer')) {
+          _logger.log('✓ Detected Bearer auth - likely Music Assistant native');
+          return _strategies.firstWhere((s) => s.name == 'music_assistant');
+        }
+      }
+
+      // If we got here and there's any auth challenge, assume Authelia
+      // (since we're behind a reverse proxy that requires auth)
+      if (response.statusCode >= 300) {
+        _logger.log('Server requires authentication (status ${response.statusCode})');
+        _logger.log('Assuming Authelia (default for authenticated reverse proxy)');
+        return _strategies.firstWhere((s) => s.name == 'authelia');
+      }
+    } catch (e) {
+      _logger.log('✗ Auth detection error: $e');
+      return null; // Return null to trigger fallback
+    }
+
+    _logger.log('⚠️ Could not determine auth method');
+    return null;
+  }
+
+  /// Check if server is a Music Assistant server with native auth
+  /// Returns 'required' if auth needed, 'none' if no auth, null if not MA or error
+  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 : null,
+        path: '/api',
+      );
+
+      _logger.log('Checking MA API at: $apiUrl');
+
+      // 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}');
+
+      // 401/403 means auth required - check this first
+      if (response.statusCode == 401 || response.statusCode == 403) {
+        _logger.log('MA API returned ${response.statusCode} - auth required');
+        return 'required';
+      }
+
+      // Also check for "Authentication required" text response
+      if (response.body.toLowerCase().contains('authentication required')) {
+        _logger.log('MA API returned auth required message');
+        return 'required';
+      }
+
+      if (response.statusCode == 200) {
+        // Try to parse as JSON
+        try {
+          final data = jsonDecode(response.body) as Map<String, dynamic>;
+
+          // Check if we got server info successfully (no auth required)
+          if (data.containsKey('result')) {
+            final result = data['result'] as Map<String, dynamic>?;
+            final serverVersion = result?['server_version'] as String?;
+            final schemaVersion = result?['schema_version'] as int?;
+
+            if (serverVersion != null) {
+              _logger.log('MA server version: $serverVersion, schema: $schemaVersion');
+
+              // Schema 28+ requires auth, but if we got here without auth, it's not enabled
+              return 'none';
+            }
+          }
+
+          // Check for auth error in JSON
+          if (data.containsKey('error_code')) {
+            final errorCode = data['error_code'] as int?;
+            // Error 50 = AuthenticationRequired
+            if (errorCode == 50) {
+              _logger.log('MA server requires authentication (error 50)');
+              return 'required';
+            }
+          }
+        } catch (jsonError) {
+          _logger.log('MA API response not JSON: $jsonError');
+        }
+      }
+
+      return null;
+    } catch (e) {
+      _logger.log('MA auth check error: $e');
+      return null;
+    }
+  }
+
+  /// Test if server is accessible without authentication
+  Future<bool> _canConnectWithoutAuth(String serverUrl) async {
+    try {
+      final uri = Uri.parse(serverUrl);
+      _logger.log('No-auth test URL: $serverUrl');
+
+      final isLocalIp = _isLocalIpAddress(uri.host);
+      int 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/308 = redirect (probably to auth or HTTPS)
+      // 401 = auth required
+      if (statusCode == 200) {
+        return true;
+      }
+
+      return false;
+    } catch (e) {
+      _logger.log('No-auth error: $e');
+      return false;
+    }
+  }
+
+  /// Attempt login with specified strategy
+  /// Returns true if login successful and credentials stored
+  /// authServerUrl is optional - only used for Authelia when auth is on a different domain
+  Future<bool> login(
+    String serverUrl,
+    String username,
+    String password,
+    AuthStrategy strategy, {
+    String? authServerUrl,
+  }) async {
+    _logger.log('Attempting login with ${strategy.name} strategy');
+
+    // Use auth server URL if provided, otherwise use main server URL
+    final loginUrl = authServerUrl?.isNotEmpty == true ? authServerUrl! : serverUrl;
+    _logger.log('Login URL: $loginUrl');
+
+    final credentials = await strategy.login(loginUrl, username, password);
+
+    if (credentials != null) {
+      _currentStrategy = strategy;
+      _currentCredentials = credentials;
+      _logger.log('✓ Login successful with ${strategy.name}');
+      return true;
+    }
+
+    _logger.log('✗ Login failed with ${strategy.name}');
+    return false;
+  }
+
+  /// Validate current credentials are still valid
+  Future<bool> validateCurrentCredentials(String serverUrl) async {
+    if (_currentStrategy == null || _currentCredentials == null) {
+      return false;
+    }
+
+    return await _currentStrategy!.validateCredentials(
+      serverUrl,
+      _currentCredentials!,
+    );
+  }
+
+  /// Get WebSocket connection headers for current credentials
+  Map<String, dynamic> getWebSocketHeaders() {
+    if (_currentStrategy == null || _currentCredentials == null) {
+      return {};
+    }
+
+    return _currentStrategy!.buildWebSocketHeaders(_currentCredentials!);
+  }
+
+  /// Get HTTP streaming headers for current credentials
+  Map<String, String> getStreamingHeaders() {
+    if (_currentStrategy == null || _currentCredentials == null) {
+      return {};
+    }
+
+    return _currentStrategy!.buildStreamingHeaders(_currentCredentials!);
+  }
+
+  /// Serialize current credentials for persistent storage
+  Map<String, dynamic>? serializeCredentials() {
+    if (_currentStrategy == null || _currentCredentials == null) {
+      return null;
+    }
+
+    return {
+      'strategy': _currentStrategy!.name,
+      'data': _currentStrategy!.serializeCredentials(_currentCredentials!),
+    };
+  }
+
+  /// Deserialize and restore credentials from persistent storage
+  void deserializeCredentials(Map<String, dynamic> stored) {
+    final strategyName = stored['strategy'] as String?;
+    final data = stored['data'] as Map<String, dynamic>?;
+
+    if (strategyName == null || data == null) {
+      return;
+    }
+
+    // Find matching strategy
+    try {
+      final strategy = _strategies.firstWhere((s) => s.name == strategyName);
+      _currentStrategy = strategy;
+      _currentCredentials = strategy.deserializeCredentials(data);
+      _logger.log('✓ Restored ${strategy.name} credentials from storage');
+    } catch (e) {
+      _logger.log('✗ Could not restore credentials: $e');
+    }
+  }
+
+  /// Clear current authentication state
+  void logout() {
+    _currentStrategy = null;
+    _currentCredentials = null;
+    _logger.log('Logged out - cleared auth state');
+  }
+
+  /// Get strategy by name (for manual selection)
+  AuthStrategy? getStrategyByName(String name) {
+    try {
+      return _strategies.firstWhere((s) => s.name == name);
+    } catch (e) {
+      return null;
+    }
+  }
+}

lib/services/auth/auth_strategy.dart

@@ -0,0 +1,42 @@
+/// Authentication credentials container
+class AuthCredentials {
+  final String strategyName;
+  final Map<String, dynamic> data;
+
+  AuthCredentials(this.strategyName, this.data);
+}
+
+/// Abstract authentication strategy interface
+/// Implementations handle different auth methods (none, basic, Authelia, HA, etc.)
+abstract class AuthStrategy {
+  /// Strategy name identifier (e.g., 'none', 'basic', 'authelia')
+  String get name;
+
+  /// Attempt login and return auth credentials/token
+  /// Returns null if login fails
+  Future<AuthCredentials?> login(
+    String serverUrl,
+    String username,
+    String password,
+  );
+
+  /// Test if current credentials are still valid
+  Future<bool> validateCredentials(
+    String serverUrl,
+    AuthCredentials credentials,
+  );
+
+  /// Build headers for WebSocket connection
+  /// Example: {'Authorization': 'Basic xyz'} or {'Cookie': 'session=abc'}
+  Map<String, dynamic> buildWebSocketHeaders(AuthCredentials credentials);
+
+  /// Build headers for HTTP streaming requests
+  /// Example: {'Authorization': 'Basic xyz'}
+  Map<String, String> buildStreamingHeaders(AuthCredentials credentials);
+
+  /// Serialize credentials for persistent storage
+  Map<String, dynamic> serializeCredentials(AuthCredentials credentials);
+
+  /// Deserialize credentials from persistent storage
+  AuthCredentials deserializeCredentials(Map<String, dynamic> data);
+}

lib/services/auth/authelia_strategy.dart

@@ -1,27 +1,33 @@
-import 'package:http/http.dart' as http;
 import 'dart:convert';
-import 'debug_logger.dart';
-import 'settings_service.dart';
+import 'package:http/http.dart' as http;
+import 'auth_strategy.dart';
+import '../debug_logger.dart';
 
-class AuthService {
+/// Authelia authentication strategy
+/// Used when Music Assistant is behind Authelia reverse proxy authentication
+/// Authelia-specific endpoints: /api/firstfactor, /api/verify
+class AutheliaStrategy implements AuthStrategy {
   final _logger = DebugLogger();
 
-  /// Authenticate with the server and get session cookie
-  Future<String?> login(String serverUrl, String username, String password) async {
+  @override
+  String get name => 'authelia';
+
+  @override
+  Future<AuthCredentials?> login(
+    String serverUrl,
+    String username,
+    String password,
+  ) async {
     try {
-      // Check if there's a separate auth server URL configured
-      final authServerUrl = await SettingsService.getAuthServerUrl();
-      final targetUrl = authServerUrl ?? serverUrl;
-
-      _logger.log('🔐 Attempting login to $targetUrl');
-
-      // Determine base URL
-      var baseUrl = targetUrl;
+      // Normalize server URL
+      var baseUrl = serverUrl;
       if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
         baseUrl = 'https://$baseUrl';
       }
 
-      // Parse URL
+      _logger.log('🔐 Attempting Authelia login to $baseUrl');
+
+      // Parse URL and construct Authelia firstfactor endpoint
       final uri = Uri.parse(baseUrl);
       final authUrl = Uri(
         scheme: uri.scheme,
@@ -32,7 +38,7 @@ class AuthService {
 
       _logger.log('Auth URL: $authUrl');
 
-      // Use Authelia's firstfactor endpoint with POST
+      // POST to Authelia's firstfactor endpoint
       final response = await http.post(
         authUrl,
         headers: {
@@ -47,26 +53,28 @@ class AuthService {
 
       _logger.log('Auth response status: ${response.statusCode}');
 
-      // Check response status first - only proceed if successful
+      // Check for successful authentication
       if (response.statusCode == 200) {
         _logger.log('✓ Authentication successful');
 
-        // Check for session cookies
+        // Extract session cookie from Set-Cookie header
         final cookies = response.headers['set-cookie'];
         if (cookies != null && cookies.isNotEmpty) {
           _logger.log('✓ Received session cookie');
 
-          // Extract authelia_session cookie if present
           final sessionCookie = _extractSessionCookie(cookies);
           if (sessionCookie != null) {
             _logger.log('✓ Extracted session cookie');
-            await SettingsService.setAuthToken(sessionCookie);
-            return sessionCookie;
+            return AuthCredentials('authelia', {
+              'session_cookie': sessionCookie,
+              'username': username,
+            });
           }
         }
 
-        // If 200 but no cookie, might not need auth
-        return 'authenticated';
+        // If 200 but no cookie, something is wrong
+        _logger.log('✗ No session cookie in response');
+        return null;
       }
 
       _logger.log('✗ Authentication failed: ${response.statusCode}');
@@ -78,8 +86,73 @@ class AuthService {
     }
   }
 
+  @override
+  Future<bool> validateCredentials(
+    String serverUrl,
+    AuthCredentials credentials,
+  ) async {
+    final sessionCookie = credentials.data['session_cookie'] as String?;
+    if (sessionCookie == null) return false;
+
+    try {
+      // Normalize server URL
+      var baseUrl = serverUrl;
+      if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+        baseUrl = 'https://$baseUrl';
+      }
+
+      // Parse URL and construct Authelia verify endpoint
+      final uri = Uri.parse(baseUrl);
+      final verifyUrl = Uri(
+        scheme: uri.scheme,
+        host: uri.host,
+        port: uri.hasPort ? uri.port : null,
+        path: '/api/verify',
+      );
+
+      final response = await http.get(
+        verifyUrl,
+        headers: {
+          'Cookie': 'authelia_session=$sessionCookie',
+        },
+      ).timeout(const Duration(seconds: 5));
+
+      return response.statusCode == 200;
+    } catch (e) {
+      _logger.log('Auth validation failed: $e');
+      return false;
+    }
+  }
+
+  @override
+  Map<String, dynamic> buildWebSocketHeaders(AuthCredentials credentials) {
+    final sessionCookie = credentials.data['session_cookie'] as String;
+    return {
+      'Cookie': 'authelia_session=$sessionCookie',
+    };
+  }
+
+  @override
+  Map<String, String> buildStreamingHeaders(AuthCredentials credentials) {
+    final sessionCookie = credentials.data['session_cookie'] as String;
+    return {
+      'Cookie': 'authelia_session=$sessionCookie',
+    };
+  }
+
+  @override
+  Map<String, dynamic> serializeCredentials(AuthCredentials credentials) {
+    return credentials.data;
+  }
+
+  @override
+  AuthCredentials deserializeCredentials(Map<String, dynamic> data) {
+    return AuthCredentials('authelia', data);
+  }
+
+  /// Extract authelia_session cookie value from Set-Cookie header
+  /// Migrated from auth_service.dart:81-98
   String? _extractSessionCookie(String setCookieHeader) {
-    // Parse Set-Cookie header to extract authelia_session value
     final cookies = setCookieHeader.split(',');
 
     for (final cookie in cookies) {
@@ -96,39 +169,4 @@ class AuthService {
 
     return null;
   }
-
-  /// Test if current credentials/token work
-  Future<bool> testAuthentication(String serverUrl) async {
-    try {
-      var baseUrl = serverUrl;
-      if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
-        baseUrl = 'https://$baseUrl';
-      }
-
-      final uri = Uri.parse(baseUrl);
-      final testUrl = Uri(
-        scheme: uri.scheme,
-        host: uri.host,
-        port: uri.hasPort ? uri.port : null,
-        path: '/api/verify',
-      );
-
-      final token = await SettingsService.getAuthToken();
-      final headers = <String, String>{};
-
-      if (token != null && token != 'authenticated') {
-        headers['Cookie'] = 'authelia_session=$token';
-      }
-
-      final response = await http.get(
-        testUrl,
-        headers: headers,
-      ).timeout(const Duration(seconds: 5));
-
-      return response.statusCode == 200;
-    } catch (e) {
-      _logger.log('Auth test failed: $e');
-      return false;
-    }
-  }
 }

lib/services/auth/basic_auth_strategy.dart

@@ -0,0 +1,82 @@
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+import 'auth_strategy.dart';
+
+/// Basic HTTP Authentication strategy
+/// Used by reverse proxies (nginx, Apache, Caddy, etc.) configured with basic auth
+/// Example: Authorization: Basic base64(username:password)
+class BasicAuthStrategy implements AuthStrategy {
+  @override
+  String get name => 'basic';
+
+  @override
+  Future<AuthCredentials?> login(
+    String serverUrl,
+    String username,
+    String password,
+  ) async {
+    // Encode credentials to base64
+    final credentials = base64Encode(utf8.encode('$username:$password'));
+
+    // Test credentials against server root endpoint
+    // (Music Assistant doesn't have /api/info)
+    try {
+      final response = await http.get(
+        Uri.parse(serverUrl),
+        headers: {'Authorization': 'Basic $credentials'},
+      ).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        return AuthCredentials('basic', {
+          'credentials': credentials,
+          'username': username, // Store for re-login if needed
+        });
+      }
+    } catch (e) {
+      return null;
+    }
+    return null;
+  }
+
+  @override
+  Future<bool> validateCredentials(
+    String serverUrl,
+    AuthCredentials credentials,
+  ) async {
+    final base64Creds = credentials.data['credentials'] as String?;
+    if (base64Creds == null) return false;
+
+    try {
+      final response = await http.get(
+        Uri.parse(serverUrl),
+        headers: {'Authorization': 'Basic $base64Creds'},
+      ).timeout(const Duration(seconds: 5));
+
+      return response.statusCode == 200;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  @override
+  Map<String, dynamic> buildWebSocketHeaders(AuthCredentials credentials) {
+    final base64Creds = credentials.data['credentials'] as String;
+    return {'Authorization': 'Basic $base64Creds'};
+  }
+
+  @override
+  Map<String, String> buildStreamingHeaders(AuthCredentials credentials) {
+    final base64Creds = credentials.data['credentials'] as String;
+    return {'Authorization': 'Basic $base64Creds'};
+  }
+
+  @override
+  Map<String, dynamic> serializeCredentials(AuthCredentials credentials) {
+    return credentials.data;
+  }
+
+  @override
+  AuthCredentials deserializeCredentials(Map<String, dynamic> data) {
+    return AuthCredentials('basic', data);
+  }
+}

lib/services/auth/ma_auth_strategy.dart

@@ -0,0 +1,254 @@
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+import 'auth_strategy.dart';
+import '../debug_logger.dart';
+
+/// Music Assistant native authentication strategy
+/// Used when MA server has built-in authentication enabled (schema 28+)
+///
+/// Flow:
+/// 1. Connect WebSocket (receives server_info with auth requirements)
+/// 2. If auth required, login with username/password to get access token
+/// 3. Send 'auth' command with token to authenticate the session
+/// 4. Optionally create long-lived token for persistent storage
+class MusicAssistantAuthStrategy implements AuthStrategy {
+  final _logger = DebugLogger();
+
+  @override
+  String get name => 'music_assistant';
+
+  /// Login to Music Assistant and get an access token
+  /// This is called AFTER WebSocket connection is established
+  /// Returns credentials containing the access token
+  @override
+  Future<AuthCredentials?> login(
+    String serverUrl,
+    String username,
+    String password,
+  ) async {
+    try {
+      // Normalize server URL
+      var baseUrl = serverUrl;
+      if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+        // Determine protocol based on URL pattern
+        if (baseUrl.startsWith('192.') ||
+            baseUrl.startsWith('10.') ||
+            baseUrl.startsWith('172.') ||
+            baseUrl == 'localhost' ||
+            baseUrl.startsWith('127.')) {
+          baseUrl = 'http://$baseUrl';
+        } else {
+          baseUrl = 'https://$baseUrl';
+        }
+      }
+
+      _logger.log('🔐 Attempting Music Assistant login to $baseUrl');
+
+      // MA auth endpoint - POST /api with JSON-RPC style command
+      final uri = Uri.parse(baseUrl);
+      final apiUrl = Uri(
+        scheme: uri.scheme,
+        host: uri.host,
+        port: uri.hasPort ? uri.port : (uri.scheme == 'https' ? null : 8095),
+        path: '/api',
+      );
+
+      _logger.log('Auth API URL: $apiUrl');
+
+      // Login request to get access token
+      final response = await http.post(
+        apiUrl,
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: jsonEncode({
+          'command': 'auth/login',
+          'args': {
+            'username': username,
+            'password': password,
+          },
+        }),
+      ).timeout(const Duration(seconds: 10));
+
+      _logger.log('Auth response status: ${response.statusCode}');
+
+      if (response.statusCode == 200) {
+        final data = jsonDecode(response.body) as Map<String, dynamic>;
+
+        // Check for error in response
+        if (data.containsKey('error_code')) {
+          _logger.log('✗ Login failed: ${data['error_code']} - ${data['details']}');
+          return null;
+        }
+
+        // Extract access token from result
+        final result = data['result'] as Map<String, dynamic>?;
+        final accessToken = result?['access_token'] as String?;
+
+        if (accessToken != null) {
+          _logger.log('✓ Got access token from MA');
+
+          // Now try to create a long-lived token for persistent auth
+          final longLivedToken = await _createLongLivedToken(apiUrl, accessToken);
+
+          return AuthCredentials('music_assistant', {
+            'access_token': accessToken,
+            'long_lived_token': longLivedToken,
+            'username': username,
+            'server_url': baseUrl,
+          });
+        }
+
+        _logger.log('✗ No access token in response');
+        return null;
+      }
+
+      _logger.log('✗ Authentication failed: ${response.statusCode}');
+      _logger.log('Response body: ${response.body}');
+      return null;
+    } catch (e) {
+      _logger.log('✗ Login error: $e');
+      return null;
+    }
+  }
+
+  /// Create a long-lived token for persistent authentication
+  Future<String?> _createLongLivedToken(Uri apiUrl, String accessToken) async {
+    try {
+      _logger.log('Creating long-lived token...');
+
+      final response = await http.post(
+        apiUrl,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': 'Bearer $accessToken',
+        },
+        body: jsonEncode({
+          'command': 'auth/create_token',
+          'args': {
+            'name': 'Ensemble Mobile App',
+          },
+        }),
+      ).timeout(const Duration(seconds: 10));
+
+      if (response.statusCode == 200) {
+        final data = jsonDecode(response.body) as Map<String, dynamic>;
+
+        if (!data.containsKey('error_code')) {
+          final result = data['result'] as Map<String, dynamic>?;
+          final token = result?['token'] as String?;
+
+          if (token != null) {
+            _logger.log('✓ Created long-lived token');
+            return token;
+          }
+        }
+      }
+
+      _logger.log('⚠️ Could not create long-lived token (non-fatal)');
+      return null;
+    } catch (e) {
+      _logger.log('⚠️ Long-lived token creation failed: $e (non-fatal)');
+      return null;
+    }
+  }
+
+  @override
+  Future<bool> validateCredentials(
+    String serverUrl,
+    AuthCredentials credentials,
+  ) async {
+    // Try long-lived token first, then access token
+    final longLivedToken = credentials.data['long_lived_token'] as String?;
+    final accessToken = credentials.data['access_token'] as String?;
+
+    final token = longLivedToken ?? accessToken;
+    if (token == null) return false;
+
+    try {
+      var baseUrl = serverUrl;
+      if (!baseUrl.startsWith('http://') && !baseUrl.startsWith('https://')) {
+        baseUrl = 'https://$baseUrl';
+      }
+
+      final uri = Uri.parse(baseUrl);
+      final apiUrl = Uri(
+        scheme: uri.scheme,
+        host: uri.host,
+        port: uri.hasPort ? uri.port : (uri.scheme == 'https' ? null : 8095),
+        path: '/api',
+      );
+
+      // Test token by getting server info
+      final response = await http.post(
+        apiUrl,
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': 'Bearer $token',
+        },
+        body: jsonEncode({
+          'command': 'server/info',
+        }),
+      ).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = jsonDecode(response.body) as Map<String, dynamic>;
+        return !data.containsKey('error_code');
+      }
+
+      return false;
+    } catch (e) {
+      _logger.log('Token validation failed: $e');
+      return false;
+    }
+  }
+
+  @override
+  Map<String, dynamic> buildWebSocketHeaders(AuthCredentials credentials) {
+    // MA auth happens AFTER WebSocket connection, not via headers
+    // But we can still include token if available for initial handshake
+    final longLivedToken = credentials.data['long_lived_token'] as String?;
+    final accessToken = credentials.data['access_token'] as String?;
+
+    final token = longLivedToken ?? accessToken;
+    if (token != null) {
+      return {
+        'Authorization': 'Bearer $token',
+      };
+    }
+
+    return {};
+  }
+
+  @override
+  Map<String, String> buildStreamingHeaders(AuthCredentials credentials) {
+    final longLivedToken = credentials.data['long_lived_token'] as String?;
+    final accessToken = credentials.data['access_token'] as String?;
+
+    final token = longLivedToken ?? accessToken;
+    if (token != null) {
+      return {
+        'Authorization': 'Bearer $token',
+      };
+    }
+
+    return {};
+  }
+
+  @override
+  Map<String, dynamic> serializeCredentials(AuthCredentials credentials) {
+    return credentials.data;
+  }
+
+  @override
+  AuthCredentials deserializeCredentials(Map<String, dynamic> data) {
+    return AuthCredentials('music_assistant', data);
+  }
+
+  /// Get the best available token (prefer long-lived)
+  String? getToken(AuthCredentials credentials) {
+    final longLivedToken = credentials.data['long_lived_token'] as String?;
+    final accessToken = credentials.data['access_token'] as String?;
+    return longLivedToken ?? accessToken;
+  }
+}

lib/services/auth/no_auth_strategy.dart

@@ -0,0 +1,64 @@
+import 'package:http/http.dart' as http;
+import 'auth_strategy.dart';
+
+/// No authentication strategy for open Music Assistant servers
+/// Typical scenarios:
+/// - Local network deployment (http://192.168.1.100:8095)
+/// - Home network without reverse proxy
+/// - Development servers
+class NoAuthStrategy implements AuthStrategy {
+  @override
+  String get name => 'none';
+
+  @override
+  Future<AuthCredentials?> login(
+    String serverUrl,
+    String username,
+    String password,
+  ) async {
+    // No authentication required - just test server connectivity
+    try {
+      final response = await http.get(
+        Uri.parse('$serverUrl/api/info'),
+      ).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        return AuthCredentials('none', {});
+      }
+    } catch (e) {
+      return null;
+    }
+    return null;
+  }
+
+  @override
+  Future<bool> validateCredentials(
+    String serverUrl,
+    AuthCredentials credentials,
+  ) async {
+    // Always valid for no-auth
+    return true;
+  }
+
+  @override
+  Map<String, dynamic> buildWebSocketHeaders(AuthCredentials credentials) {
+    // No auth headers needed
+    return {};
+  }
+
+  @override
+  Map<String, String> buildStreamingHeaders(AuthCredentials credentials) {
+    // No auth headers needed
+    return {};
+  }
+
+  @override
+  Map<String, dynamic> serializeCredentials(AuthCredentials credentials) {
+    return {};
+  }
+
+  @override
+  AuthCredentials deserializeCredentials(Map<String, dynamic> data) {
+    return AuthCredentials('none', {});
+  }
+}

lib/services/cache_service.dart

@@ -0,0 +1,367 @@
+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;
+
+  // Home screen row caching
+  List<Album>? _cachedRecentAlbums;
+  List<Artist>? _cachedDiscoverArtists;
+  List<Album>? _cachedDiscoverAlbums;
+  DateTime? _recentAlbumsLastFetched;
+  DateTime? _discoverArtistsLastFetched;
+  DateTime? _discoverAlbumsLastFetched;
+
+  // Detail screen caching
+  final Map<String, List<Track>> _albumTracksCache = {};
+  final Map<String, DateTime> _albumTracksCacheTime = {};
+  final Map<String, List<Track>> _playlistTracksCache = {};
+  final Map<String, DateTime> _playlistTracksCacheTime = {};
+  final Map<String, List<Album>> _artistAlbumsCache = {};
+  final Map<String, DateTime> _artistAlbumsCacheTime = {};
+
+  // Search results caching
+  final Map<String, Map<String, List<MediaItem>>> _searchCache = {};
+  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 = {};
+
+  // ============================================================================
+  // HOME SCREEN ROW CACHING
+  // ============================================================================
+
+  /// Check if recent albums cache is valid
+  bool isRecentAlbumsCacheValid({bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    return _cachedRecentAlbums != null &&
+        _recentAlbumsLastFetched != null &&
+        now.difference(_recentAlbumsLastFetched!) < Timings.homeRowCacheDuration;
+  }
+
+  /// Get cached recent albums
+  List<Album>? getCachedRecentAlbums() => _cachedRecentAlbums;
+
+  /// Set cached recent albums
+  void setCachedRecentAlbums(List<Album> albums) {
+    _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
+  bool isDiscoverArtistsCacheValid({bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    return _cachedDiscoverArtists != null &&
+        _discoverArtistsLastFetched != null &&
+        now.difference(_discoverArtistsLastFetched!) < Timings.homeRowCacheDuration;
+  }
+
+  /// Get cached discover artists
+  List<Artist>? getCachedDiscoverArtists() => _cachedDiscoverArtists;
+
+  /// Set cached discover artists
+  void setCachedDiscoverArtists(List<Artist> artists) {
+    _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
+  bool isDiscoverAlbumsCacheValid({bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    return _cachedDiscoverAlbums != null &&
+        _discoverAlbumsLastFetched != null &&
+        now.difference(_discoverAlbumsLastFetched!) < Timings.homeRowCacheDuration;
+  }
+
+  /// Get cached discover albums
+  List<Album>? getCachedDiscoverAlbums() => _cachedDiscoverAlbums;
+
+  /// Set cached discover albums
+  void setCachedDiscoverAlbums(List<Album> albums) {
+    _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());
+  }
+
+  /// Invalidate home screen cache (call on pull-to-refresh)
+  void invalidateHomeCache() {
+    _recentAlbumsLastFetched = null;
+    _discoverArtistsLastFetched = null;
+    _discoverAlbumsLastFetched = null;
+    _logger.log('🗑️ Home screen cache invalidated');
+  }
+
+  // ============================================================================
+  // DETAIL SCREEN CACHING
+  // ============================================================================
+
+  /// Check if album tracks cache is valid
+  bool isAlbumTracksCacheValid(String cacheKey, {bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    final cacheTime = _albumTracksCacheTime[cacheKey];
+    return _albumTracksCache.containsKey(cacheKey) &&
+        cacheTime != null &&
+        now.difference(cacheTime) < const Duration(minutes: 5);
+  }
+
+  /// Get cached album tracks
+  List<Track>? getCachedAlbumTracks(String cacheKey) => _albumTracksCache[cacheKey];
+
+  /// Set cached album tracks
+  void setCachedAlbumTracks(String cacheKey, List<Track> tracks) {
+    _albumTracksCache[cacheKey] = tracks;
+    _albumTracksCacheTime[cacheKey] = DateTime.now();
+    _logger.log('✅ Cached ${tracks.length} tracks for album $cacheKey');
+  }
+
+  /// Invalidate album tracks cache
+  void invalidateAlbumTracksCache(String albumId) {
+    _albumTracksCache.remove(albumId);
+    _albumTracksCacheTime.remove(albumId);
+  }
+
+  /// Check if playlist tracks cache is valid
+  bool isPlaylistTracksCacheValid(String cacheKey, {bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    final cacheTime = _playlistTracksCacheTime[cacheKey];
+    return _playlistTracksCache.containsKey(cacheKey) &&
+        cacheTime != null &&
+        now.difference(cacheTime) < const Duration(minutes: 5);
+  }
+
+  /// Get cached playlist tracks
+  List<Track>? getCachedPlaylistTracks(String cacheKey) => _playlistTracksCache[cacheKey];
+
+  /// Set cached playlist tracks
+  void setCachedPlaylistTracks(String cacheKey, List<Track> tracks) {
+    _playlistTracksCache[cacheKey] = tracks;
+    _playlistTracksCacheTime[cacheKey] = DateTime.now();
+    _logger.log('✅ Cached ${tracks.length} tracks for playlist $cacheKey');
+  }
+
+  /// Invalidate playlist tracks cache
+  void invalidatePlaylistTracksCache(String playlistId) {
+    _playlistTracksCache.remove(playlistId);
+    _playlistTracksCacheTime.remove(playlistId);
+  }
+
+  /// Check if artist albums cache is valid
+  bool isArtistAlbumsCacheValid(String cacheKey, {bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    final cacheTime = _artistAlbumsCacheTime[cacheKey];
+    return _artistAlbumsCache.containsKey(cacheKey) &&
+        cacheTime != null &&
+        now.difference(cacheTime) < Timings.homeRowCacheDuration;
+  }
+
+  /// Get cached artist albums
+  List<Album>? getCachedArtistAlbums(String cacheKey) => _artistAlbumsCache[cacheKey];
+
+  /// Set cached artist albums
+  void setCachedArtistAlbums(String cacheKey, List<Album> albums) {
+    _artistAlbumsCache[cacheKey] = albums;
+    _artistAlbumsCacheTime[cacheKey] = DateTime.now();
+    _logger.log('✅ Cached ${albums.length} albums for artist $cacheKey');
+  }
+
+  // ============================================================================
+  // SEARCH CACHING
+  // ============================================================================
+
+  /// Check if search cache is valid
+  bool isSearchCacheValid(String cacheKey, {bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    final cacheTime = _searchCacheTime[cacheKey];
+    return _searchCache.containsKey(cacheKey) &&
+        cacheTime != null &&
+        now.difference(cacheTime) < Timings.homeRowCacheDuration;
+  }
+
+  /// Get cached search results
+  Map<String, List<MediaItem>>? getCachedSearchResults(String cacheKey) => _searchCache[cacheKey];
+
+  /// Set cached search results
+  void setCachedSearchResults(String cacheKey, Map<String, List<MediaItem>> results) {
+    _searchCache[cacheKey] = results;
+    _searchCacheTime[cacheKey] = DateTime.now();
+    _logger.log('✅ Cached search results for "$cacheKey"');
+  }
+
+  // ============================================================================
+  // PLAYER CACHING
+  // ============================================================================
+
+  /// Check if players cache is valid
+  bool isPlayersCacheValid({bool forceRefresh = false}) {
+    if (forceRefresh) return false;
+    final now = DateTime.now();
+    return _playersLastFetched != null &&
+        now.difference(_playersLastFetched!) < Timings.playersCacheDuration;
+  }
+
+  /// Update players cache timestamp
+  void updatePlayersLastFetched() {
+    _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];
+
+  /// Set cached track for a player
+  void setCachedTrackForPlayer(String playerId, Track? track) {
+    _playerTrackCache[playerId] = track;
+  }
+
+  /// Clear cached track for a player (e.g., when external source is active)
+  void clearCachedTrackForPlayer(String playerId) {
+    _playerTrackCache.remove(playerId);
+  }
+
+  // ============================================================================
+  // CLEAR ALL
+  // ============================================================================
+
+  /// Clear all detail caches (call on disconnect/reconnect)
+  void clearAllDetailCaches() {
+    _albumTracksCache.clear();
+    _albumTracksCacheTime.clear();
+    _playlistTracksCache.clear();
+    _playlistTracksCacheTime.clear();
+    _artistAlbumsCache.clear();
+    _artistAlbumsCacheTime.clear();
+    _searchCache.clear();
+    _searchCacheTime.clear();
+    _playerTrackCache.clear();
+    _logger.log('🗑️ All detail caches cleared');
+  }
+
+  /// Clear all caches
+  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');
+      }
+    }();
+  }
+}

lib/services/database_service.dart

@@ -0,0 +1,255 @@
+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
+  Future<void> cacheItem<T>({
+    required String itemType,
+    required String itemId,
+    required Map<String, dynamic> data,
+  }) {
+    return db.cacheItem(
+      itemType: itemType,
+      itemId: itemId,
+      data: jsonEncode(data),
+    );
+  }
+
+  /// 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 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();
+
+  // ============================================
+  // 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();
+}

lib/services/debug_logger.dart

@@ -1,32 +1,243 @@
+import 'dart:io';
 import 'package:flutter/foundation.dart';
+import 'package:package_info_plus/package_info_plus.dart';
+import 'package:device_info_plus/device_info_plus.dart';
+
+/// Log levels for filtering and display
+enum LogLevel {
+  perf,   // Performance timing (for FPS diagnosis)
+  debug,  // Verbose debugging info (hidden by default)
+  info,   // General information
+  warning, // Potential issues
+  error,  // Errors and failures
+}
+
+class LogEntry {
+  final DateTime timestamp;
+  final LogLevel level;
+  final String message;
+  final String? context;
+
+  LogEntry({
+    required this.timestamp,
+    required this.level,
+    required this.message,
+    this.context,
+  });
+
+  String get formatted {
+    final time = timestamp.toIso8601String().substring(11, 23);
+    final levelStr = level.name.toUpperCase().padRight(5);
+    final contextStr = context != null ? '[$context] ' : '';
+    return '[$time] $levelStr $contextStr$message';
+  }
+}
 
 class DebugLogger {
   static final DebugLogger _instance = DebugLogger._internal();
   factory DebugLogger() => _instance;
   DebugLogger._internal();
 
-  final List<String> _logs = [];
-  final _maxLogs = 500;
+  final List<LogEntry> _entries = [];
+  final _maxLogs = 1000;
 
-  List<String> get logs => List.unmodifiable(_logs);
+  // Minimum level to display in debug console (debug builds show all)
+  LogLevel _minConsoleLevel = kDebugMode ? LogLevel.debug : LogLevel.info;
 
-  void log(String message) {
-    final timestamp = DateTime.now().toIso8601String().substring(11, 23);
-    final logMessage = '[$timestamp] $message';
+  List<LogEntry> get entries => List.unmodifiable(_entries);
 
-    debugPrint(logMessage);
+  /// Legacy getter for backward compatibility
+  List<String> get logs => _entries.map((e) => e.formatted).toList();
 
-    _logs.add(logMessage);
-    if (_logs.length > _maxLogs) {
-      _logs.removeAt(0);
+  // Set to true to only log perf entries (for FPS diagnosis)
+  // Set to false for normal operation with full logging for user bug reports
+  static const bool _perfOnlyMode = false;
+
+  void _addEntry(LogLevel level, String message, {String? context}) {
+    // In perf-only mode, skip all non-perf logs
+    if (_perfOnlyMode && level != LogLevel.perf) {
+      return;
+    }
+
+    final entry = LogEntry(
+      timestamp: DateTime.now(),
+      level: level,
+      message: message,
+      context: context,
+    );
+
+    // Always store in memory
+    _entries.add(entry);
+    if (_entries.length > _maxLogs) {
+      _entries.removeAt(0);
+    }
+
+    // Only print to console if above minimum level
+    if (level.index >= _minConsoleLevel.index) {
+      debugPrint(entry.formatted);
     }
   }
 
+  /// Debug level - verbose info for development
+  void debug(String message, {String? context}) {
+    _addEntry(LogLevel.debug, message, context: context);
+  }
+
+  /// Info level - general operational info
+  void info(String message, {String? context}) {
+    _addEntry(LogLevel.info, message, context: context);
+  }
+
+  /// Warning level - potential issues
+  void warning(String message, {String? context}) {
+    _addEntry(LogLevel.warning, message, context: context);
+  }
+
+  /// Error level - failures and errors
+  void error(String message, {String? context, Object? error, StackTrace? stackTrace}) {
+    var fullMessage = message;
+    if (error != null) {
+      fullMessage += ': $error';
+    }
+    _addEntry(LogLevel.error, fullMessage, context: context);
+    if (stackTrace != null && kDebugMode) {
+      debugPrint('Stack trace: $stackTrace');
+    }
+  }
+
+  /// Legacy method for backward compatibility
+  void log(String message) {
+    _addEntry(LogLevel.info, message);
+  }
+
+  /// Performance logging - always prints to console for real-time monitoring
+  void perf(String message, {String? context}) {
+    _addEntry(LogLevel.perf, message, context: context);
+  }
+
+  /// Track build time of a widget
+  final Map<String, Stopwatch> _buildTimers = {};
+
+  void startBuild(String widgetName) {
+    _buildTimers[widgetName] = Stopwatch()..start();
+  }
+
+  void endBuild(String widgetName) {
+    final sw = _buildTimers.remove(widgetName);
+    if (sw != null) {
+      sw.stop();
+      if (sw.elapsedMilliseconds > 4) { // Only log if > 4ms (slow for 60fps)
+        perf('BUILD ${sw.elapsedMilliseconds}ms', context: widgetName);
+      }
+    }
+  }
+
+  /// Track frame times during scroll
+  Stopwatch? _frameTimer;
+  int _slowFrameCount = 0;
+  int _totalFrameCount = 0;
+
+  void startFrame() {
+    _frameTimer = Stopwatch()..start();
+  }
+
+  void endFrame() {
+    if (_frameTimer != null) {
+      _frameTimer!.stop();
+      _totalFrameCount++;
+      final ms = _frameTimer!.elapsedMilliseconds;
+      if (ms > 16) { // > 16ms means dropped frame at 60fps
+        _slowFrameCount++;
+        perf('SLOW FRAME ${ms}ms (${_slowFrameCount}/${_totalFrameCount} slow)', context: 'Scroll');
+      }
+    }
+  }
+
+  void resetFrameStats() {
+    _slowFrameCount = 0;
+    _totalFrameCount = 0;
+  }
+
   void clear() {
-    _logs.clear();
+    _entries.clear();
   }
 
   String getAllLogs() {
-    return _logs.join('\n');
+    return _entries.map((e) => e.formatted).join('\n');
+  }
+
+  /// Get logs filtered by minimum level
+  String getLogsFiltered({LogLevel minLevel = LogLevel.info}) {
+    return _entries
+        .where((e) => e.level.index >= minLevel.index)
+        .map((e) => e.formatted)
+        .join('\n');
+  }
+
+  /// Generate a formatted bug report with device info
+  Future<String> generateBugReport() async {
+    final buffer = StringBuffer();
+
+    buffer.writeln('═══════════════════════════════════════');
+    buffer.writeln('ENSEMBLE BUG REPORT');
+    buffer.writeln('Generated: ${DateTime.now().toIso8601String()}');
+    buffer.writeln('═══════════════════════════════════════');
+    buffer.writeln();
+
+    // App info
+    try {
+      final packageInfo = await PackageInfo.fromPlatform();
+      buffer.writeln('APP INFO:');
+      buffer.writeln('  Version: ${packageInfo.version} (${packageInfo.buildNumber})');
+      buffer.writeln('  Package: ${packageInfo.packageName}');
+      buffer.writeln();
+    } catch (e) {
+      buffer.writeln('APP INFO: Unable to retrieve');
+      buffer.writeln();
+    }
+
+    // Device info
+    try {
+      final deviceInfo = DeviceInfoPlugin();
+      if (Platform.isAndroid) {
+        final android = await deviceInfo.androidInfo;
+        buffer.writeln('DEVICE INFO:');
+        buffer.writeln('  Model: ${android.manufacturer} ${android.model}');
+        buffer.writeln('  Android: ${android.version.release} (SDK ${android.version.sdkInt})');
+        buffer.writeln('  Device: ${android.device}');
+        buffer.writeln();
+      } else if (Platform.isIOS) {
+        final ios = await deviceInfo.iosInfo;
+        buffer.writeln('DEVICE INFO:');
+        buffer.writeln('  Model: ${ios.model}');
+        buffer.writeln('  iOS: ${ios.systemVersion}');
+        buffer.writeln('  Name: ${ios.name}');
+        buffer.writeln();
+      }
+    } catch (e) {
+      buffer.writeln('DEVICE INFO: Unable to retrieve');
+      buffer.writeln();
+    }
+
+    // Log statistics
+    final errorCount = _entries.where((e) => e.level == LogLevel.error).length;
+    final warningCount = _entries.where((e) => e.level == LogLevel.warning).length;
+    buffer.writeln('LOG SUMMARY:');
+    buffer.writeln('  Total entries: ${_entries.length}');
+    buffer.writeln('  Errors: $errorCount');
+    buffer.writeln('  Warnings: $warningCount');
+    buffer.writeln();
+
+    buffer.writeln('═══════════════════════════════════════');
+    buffer.writeln('LOGS (newest first):');
+    buffer.writeln('═══════════════════════════════════════');
+    buffer.writeln();
+
+    // Add logs in reverse order (newest first) for easier reading
+    for (final entry in _entries.reversed) {
+      buffer.writeln(entry.formatted);
+    }
+
+    return buffer.toString();
   }
 }

lib/services/device_id_service.dart

@@ -0,0 +1,48 @@
+import 'package:shared_preferences/shared_preferences.dart';
+import 'package:uuid/uuid.dart';
+import 'debug_logger.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
+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();
+
+    // 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;
+    }
+
+    // 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;
+  }
+
+  /// Adopt an existing player ID (used when claiming a ghost player)
+  static Future<void> adoptPlayerId(String playerId) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLocalPlayerId, playerId);
+    _logger.log('Adopted player ID: $playerId');
+  }
+
+  /// Check if this is a fresh installation (no player ID stored yet)
+  static Future<bool> isFreshInstallation() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLocalPlayerId) == null;
+  }
+}

lib/services/error_handler.dart

@@ -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') ||

lib/services/hardware_volume_service.dart

@@ -0,0 +1,86 @@
+import 'dart:async';
+import 'package:flutter/services.dart';
+import 'debug_logger.dart';
+
+/// Service to intercept hardware volume button presses
+/// and route them to the selected Music Assistant player.
+///
+/// For MA players: intercept buttons and send volume commands via API
+/// For builtin player: let native volume work (don't intercept)
+class HardwareVolumeService {
+  static final HardwareVolumeService _instance = HardwareVolumeService._internal();
+  factory HardwareVolumeService() => _instance;
+  HardwareVolumeService._internal();
+
+  static const _channel = MethodChannel('com.musicassistant.music_assistant/volume_buttons');
+  final _logger = DebugLogger();
+
+  final _volumeUpController = StreamController<void>.broadcast();
+  final _volumeDownController = StreamController<void>.broadcast();
+
+  Stream<void> get onVolumeUp => _volumeUpController.stream;
+  Stream<void> get onVolumeDown => _volumeDownController.stream;
+
+  bool _isListening = false;
+  bool get isListening => _isListening;
+
+  bool _isIntercepting = false;
+  bool get isIntercepting => _isIntercepting;
+
+  /// Initialize the service and start listening for volume button events
+  Future<void> init() async {
+    if (_isListening) return;
+
+    _channel.setMethodCallHandler((call) async {
+      switch (call.method) {
+        case 'volumeUp':
+          _volumeUpController.add(null);
+          break;
+        case 'volumeDown':
+          _volumeDownController.add(null);
+          break;
+      }
+    });
+
+    try {
+      await _channel.invokeMethod('startListening');
+      _isListening = true;
+      _isIntercepting = true;
+    } catch (e) {
+      _logger.error('Failed to start volume button listening', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Enable or disable volume button interception.
+  /// When disabled, hardware volume buttons control device volume normally.
+  /// When enabled, volume button events are sent to Flutter for MA player control.
+  Future<void> setIntercepting(bool intercept) async {
+    if (!_isListening || _isIntercepting == intercept) return;
+
+    try {
+      if (intercept) {
+        await _channel.invokeMethod('startListening');
+        _isIntercepting = true;
+      } else {
+        await _channel.invokeMethod('stopListening');
+        _isIntercepting = false;
+      }
+    } catch (e) {
+      _logger.error('Failed to set volume interception', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Stop listening for volume button events
+  Future<void> dispose() async {
+    if (!_isListening) return;
+
+    try {
+      await _channel.invokeMethod('stopListening');
+      _isListening = false;
+      _isIntercepting = false;
+      _logger.info('Hardware volume button listening stopped', context: 'VolumeService');
+    } catch (e) {
+      _logger.error('Failed to stop volume button listening', context: 'VolumeService', error: e);
+    }
+  }
+}

lib/services/local_player_service.dart

@@ -0,0 +1,181 @@
+import 'dart:async';
+import 'package:audio_service/audio_service.dart';
+import 'package:just_audio/just_audio.dart';
+import 'debug_logger.dart';
+import 'auth/auth_manager.dart';
+import '../main.dart' show audioHandler;
+
+/// Metadata for the currently playing track
+class TrackMetadata {
+  final String title;
+  final String artist;
+  final String? album;
+  final String? artworkUrl;
+  final Duration? duration;
+
+  TrackMetadata({
+    required this.title,
+    required this.artist,
+    this.album,
+    this.artworkUrl,
+    this.duration,
+  });
+
+  /// Convert to MediaItem for audio_service
+  MediaItem toMediaItem(String id) {
+    return MediaItem(
+      id: id,
+      title: title,
+      artist: artist,
+      album: album ?? '',
+      duration: duration,
+      artUri: artworkUrl != null ? Uri.tryParse(artworkUrl!) : null,
+    );
+  }
+}
+
+/// Service that wraps the global MassivAudioHandler for local playback.
+/// This maintains the same interface as before for compatibility with
+/// MusicAssistantProvider.
+class LocalPlayerService {
+  final AuthManager authManager;
+  final _logger = DebugLogger();
+  bool _isInitialized = false;
+
+  // Current track metadata for notifications
+  TrackMetadata? _currentMetadata;
+
+  LocalPlayerService(this.authManager);
+
+  // Expose player state streams from the global handler
+  Stream<PlayerState> get playerStateStream {
+    return audioHandler.playerStateStream;
+  }
+
+  Stream<Duration> get positionStream {
+    return audioHandler.positionStream;
+  }
+
+  Stream<Duration?> get durationStream {
+    return audioHandler.durationStream;
+  }
+
+  // Current state getters
+  bool get isPlaying {
+    return audioHandler.isPlaying;
+  }
+
+  double get volume {
+    return audioHandler.volume;
+  }
+
+  PlayerState get playerState {
+    return audioHandler.playerState;
+  }
+
+  Duration get position {
+    return audioHandler.position;
+  }
+
+  Duration get duration {
+    return audioHandler.duration;
+  }
+
+  Future<void> initialize() async {
+    if (_isInitialized) return;
+
+    // The audioHandler is already initialized in main.dart
+    // Just mark ourselves as initialized
+    _isInitialized = true;
+  }
+
+  /// Set metadata for the current track (for notification display)
+  void setCurrentTrackMetadata(TrackMetadata metadata) {
+    _currentMetadata = metadata;
+  }
+
+  /// Play a stream URL with authentication headers
+  Future<void> playUrl(String url) async {
+    // Ensure player is initialized before playing
+    if (!_isInitialized) {
+      await initialize();
+    }
+
+    try {
+      // Get auth headers from AuthManager
+      final headers = authManager.getStreamingHeaders();
+
+      // Create MediaItem from current metadata
+      final mediaItem = _currentMetadata?.toMediaItem(url) ?? MediaItem(
+        id: url,
+        title: 'Unknown Track',
+        artist: 'Unknown Artist',
+      );
+
+      await audioHandler.playUrl(
+        url,
+        mediaItem,
+        headers: headers.isNotEmpty ? headers : null,
+      );
+    } catch (e, stackTrace) {
+      _logger.log('LocalPlayerService: Error playing URL: $e');
+      rethrow;
+    }
+  }
+
+  /// Update the notification with new track info (without reloading audio)
+  void updateNotification({
+    required String id,
+    required String title,
+    String? artist,
+    String? album,
+    String? artworkUrl,
+    Duration? duration,
+  }) {
+    _currentMetadata = TrackMetadata(
+      title: title,
+      artist: artist ?? 'Unknown Artist',
+      album: album,
+      artworkUrl: artworkUrl,
+      duration: duration,
+    );
+  }
+
+  /// Update the notification while audio is already playing.
+  /// With audio_service, we can update the MediaItem directly without
+  /// re-setting the audio source.
+  Future<void> updateNotificationWhilePlaying(TrackMetadata metadata) async {
+    final currentItem = audioHandler.currentMediaItem;
+    final id = currentItem?.id ?? 'unknown';
+
+    final newMediaItem = metadata.toMediaItem(id);
+    audioHandler.updateMediaItem(newMediaItem);
+    _currentMetadata = metadata;
+  }
+
+  Future<void> play() async {
+    await audioHandler.play();
+  }
+
+  Future<void> pause() async {
+    await audioHandler.pause();
+  }
+
+  Future<void> stop() async {
+    await audioHandler.stop();
+  }
+
+  Future<void> seek(Duration position) async {
+    await audioHandler.seek(position);
+  }
+
+  /// Set volume (0.0 to 1.0)
+  Future<void> setVolume(double volume) async {
+    await audioHandler.setVolume(volume.clamp(0.0, 1.0));
+  }
+
+  void dispose() {
+    // The global audioHandler is managed by audio_service
+    // Don't dispose it here
+  }
+}

lib/services/metadata_service.dart

@@ -0,0 +1,477 @@
+import 'dart:convert';
+import 'package:http/http.dart' as http;
+import 'debug_logger.dart';
+import 'settings_service.dart';
+
+class MetadataService {
+  static final _logger = DebugLogger();
+  // Cache to avoid repeated API calls for the same artist/album
+  static final Map<String, String> _cache = {};
+
+  // Cache for artist images
+  static final Map<String, String?> _artistImageCache = {};
+
+  /// Fetches artist biography/description with fallback chain:
+  /// 1. Music Assistant metadata (passed in)
+  /// 2. Last.fm API (if key configured)
+  /// 3. TheAudioDB API (if key configured)
+  static Future<String?> getArtistDescription(
+    String artistName,
+    Map<String, dynamic>? musicAssistantMetadata,
+  ) async {
+    // Try Music Assistant metadata first
+    if (musicAssistantMetadata != null) {
+      final maDescription = musicAssistantMetadata['description'] ??
+          musicAssistantMetadata['biography'] ??
+          musicAssistantMetadata['wiki'] ??
+          musicAssistantMetadata['bio'] ??
+          musicAssistantMetadata['summary'];
+
+      if (maDescription != null && (maDescription as String).trim().isNotEmpty) {
+        return maDescription;
+      }
+    }
+
+    // Check cache
+    final cacheKey = 'artist:$artistName';
+    if (_cache.containsKey(cacheKey)) {
+      return _cache[cacheKey];
+    }
+
+    // Try Last.fm API
+    final lastFmKey = await SettingsService.getLastFmApiKey();
+    if (lastFmKey != null && lastFmKey.isNotEmpty) {
+      final lastFmDesc = await _fetchFromLastFm(artistName, null, lastFmKey);
+      if (lastFmDesc != null) {
+        _cache[cacheKey] = lastFmDesc;
+        return lastFmDesc;
+      }
+    }
+
+    // Try TheAudioDB API
+    final audioDbKey = await SettingsService.getTheAudioDbApiKey();
+    if (audioDbKey != null && audioDbKey.isNotEmpty) {
+      final audioDbDesc = await _fetchFromTheAudioDb(artistName, audioDbKey);
+      if (audioDbDesc != null) {
+        _cache[cacheKey] = audioDbDesc;
+        return audioDbDesc;
+      }
+    }
+
+    return null;
+  }
+
+  /// Fetches album description with fallback chain:
+  /// 1. Music Assistant metadata (passed in)
+  /// 2. Last.fm API (if key configured)
+  static Future<String?> getAlbumDescription(
+    String artistName,
+    String albumName,
+    Map<String, dynamic>? musicAssistantMetadata,
+  ) async {
+    // Try Music Assistant metadata first
+    if (musicAssistantMetadata != null) {
+      final maDescription = musicAssistantMetadata['description'] ??
+          musicAssistantMetadata['wiki'] ??
+          musicAssistantMetadata['biography'] ??
+          musicAssistantMetadata['summary'];
+
+      if (maDescription != null && (maDescription as String).trim().isNotEmpty) {
+        return maDescription;
+      }
+    }
+
+    // Check cache
+    final cacheKey = 'album:$artistName:$albumName';
+    if (_cache.containsKey(cacheKey)) {
+      return _cache[cacheKey];
+    }
+
+    // Try Last.fm API (TheAudioDB doesn't have good album info)
+    final lastFmKey = await SettingsService.getLastFmApiKey();
+    if (lastFmKey != null && lastFmKey.isNotEmpty) {
+      final lastFmDesc = await _fetchFromLastFm(artistName, albumName, lastFmKey);
+      if (lastFmDesc != null) {
+        _cache[cacheKey] = lastFmDesc;
+        return lastFmDesc;
+      }
+    }
+
+    return null;
+  }
+
+  static Future<String?> _fetchFromLastFm(
+    String artistName,
+    String? albumName,
+    String apiKey,
+  ) async {
+    try {
+      final String method;
+      final Map<String, String> params = {
+        'api_key': apiKey,
+        'format': 'json',
+      };
+
+      if (albumName != null) {
+        // Album info
+        method = 'album.getinfo';
+        params['artist'] = artistName;
+        params['album'] = albumName;
+      } else {
+        // Artist info
+        method = 'artist.getinfo';
+        params['artist'] = artistName;
+      }
+
+      params['method'] = method;
+
+      final uri = Uri.https('ws.audioscrobbler.com', '/2.0/', params);
+      final response = await http.get(uri).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = json.decode(response.body);
+
+        if (albumName != null) {
+          // Parse album response
+          final album = data['album'];
+          if (album != null) {
+            final wiki = album['wiki'];
+            if (wiki != null) {
+              // Prefer summary, fall back to content
+              return _cleanLastFmText(wiki['summary'] ?? wiki['content']);
+            }
+          }
+        } else {
+          // Parse artist response
+          final artist = data['artist'];
+          if (artist != null) {
+            final bio = artist['bio'];
+            if (bio != null) {
+              // Prefer summary, fall back to content
+              return _cleanLastFmText(bio['summary'] ?? bio['content']);
+            }
+          }
+        }
+      }
+    } catch (e) {
+      _logger.warning('Last.fm API error: $e', context: 'Metadata');
+    }
+    return null;
+  }
+
+  static Future<String?> _fetchFromTheAudioDb(
+    String artistName,
+    String apiKey,
+  ) async {
+    try {
+      final uri = Uri.https(
+        'theaudiodb.com',
+        '/api/v1/json/$apiKey/search.php',
+        {'s': artistName},
+      );
+
+      final response = await http.get(uri).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = json.decode(response.body);
+        final artists = data['artists'];
+
+        if (artists != null && artists.isNotEmpty) {
+          final artist = artists[0];
+          // Try multiple language fields
+          return artist['strBiographyEN'] ??
+              artist['strBiographyDE'] ??
+              artist['strBiographyFR'] ??
+              artist['strBiographyIT'] ??
+              artist['strBiographyES'];
+        }
+      }
+    } catch (e) {
+      _logger.warning('TheAudioDB API error: $e', context: 'Metadata');
+    }
+    return null;
+  }
+
+  /// Removes Last.fm HTML tags and links
+  static String? _cleanLastFmText(String? text) {
+    if (text == null) return null;
+
+    // Remove <a href...> tags
+    text = text.replaceAll(RegExp(r'<a[^>]*>'), '');
+    text = text.replaceAll('</a>', '');
+
+    // Remove "Read more on Last.fm" footer
+    text = text.replaceAll(RegExp(r'\s*<a[^>]*>.*?</a>.*$'), '');
+
+    // Clean up any remaining HTML
+    text = text.replaceAll(RegExp(r'<[^>]*>'), '');
+
+    return text.trim();
+  }
+
+  /// Fetches artist image URL from Deezer (free, no API key required)
+  /// Returns the image URL if found, null otherwise
+  static Future<String?> getArtistImageUrl(String artistName) async {
+    // Check cache first
+    final cacheKey = 'artistImage:$artistName';
+    if (_artistImageCache.containsKey(cacheKey)) {
+      return _artistImageCache[cacheKey];
+    }
+
+    // Use Deezer API (free, no key, excellent coverage)
+    try {
+      final uri = Uri.https(
+        'api.deezer.com',
+        '/search/artist',
+        {
+          'q': artistName,
+          'limit': '1',
+        },
+      );
+
+      final response = await http.get(uri).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = json.decode(response.body);
+        final artists = data['data'] as List?;
+        if (artists != null && artists.isNotEmpty) {
+          final artist = artists[0];
+          // Use picture_xl for high quality, fall back to picture_medium
+          final imageUrl = artist['picture_xl'] ?? artist['picture_medium'] ?? artist['picture'];
+          _artistImageCache[cacheKey] = imageUrl;
+          return imageUrl;
+        }
+      }
+    } catch (e) {
+      _logger.warning('Deezer artist image error: $e', context: 'Metadata');
+    }
+
+    // Cache the null result to avoid repeated failed lookups
+    _artistImageCache[cacheKey] = null;
+    return null;
+  }
+
+  // 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 {
+    // Build cache key
+    final cacheKey = 'albumImage:${artistName ?? ""}:$albumName';
+    if (_albumImageCache.containsKey(cacheKey)) {
+      return _albumImageCache[cacheKey];
+    }
+
+    // Use Deezer API (free, no key, excellent coverage)
+    try {
+      // Search with both album and artist if available for better matching
+      final query = artistName != null && artistName.isNotEmpty
+          ? '$artistName $albumName'
+          : albumName;
+
+      final uri = Uri.https(
+        'api.deezer.com',
+        '/search/album',
+        {
+          'q': query,
+          'limit': '5', // Get a few results to find best match
+        },
+      );
+
+      final response = await http.get(uri).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = json.decode(response.body);
+        final albums = data['data'] as List?;
+        if (albums != null && albums.isNotEmpty) {
+          // Try to find exact match first
+          Map<String, dynamic>? bestMatch;
+          for (final album in albums) {
+            final deezerAlbumName = (album['title'] as String?)?.toLowerCase();
+            final deezerArtistName = (album['artist']?['name'] as String?)?.toLowerCase();
+
+            if (deezerAlbumName == albumName.toLowerCase()) {
+              // Album name matches
+              if (artistName == null || artistName.isEmpty ||
+                  deezerArtistName == artistName.toLowerCase()) {
+                // And artist matches (or we don't have artist to match)
+                bestMatch = album;
+                break;
+              }
+              // Album matches but artist doesn't - keep as candidate
+              bestMatch ??= album;
+            }
+          }
+
+          // Fall back to first result if no good match
+          final album = bestMatch ?? albums[0] as Map<String, dynamic>;
+
+          // Use cover_xl for high quality, fall back to cover_medium
+          final imageUrl = album['cover_xl'] ?? album['cover_big'] ??
+              album['cover_medium'] ?? album['cover'];
+          _albumImageCache[cacheKey] = imageUrl;
+          return imageUrl;
+        }
+      }
+    } catch (e) {
+      _logger.warning('Deezer album image error: $e', context: 'Metadata');
+    }
+
+    // Cache the null result to avoid repeated failed lookups
+    _albumImageCache[cacheKey] = null;
+    return null;
+  }
+
+  /// Fetches author image URL from multiple sources
+  /// Priority: 1. Audnexus, 2. Open Library, 3. Wikipedia
+  /// Returns the image URL if found, null otherwise
+  static Future<String?> getAuthorImageUrl(String authorName) async {
+    // Check cache first
+    final cacheKey = 'authorImage:$authorName';
+    if (_authorImageCache.containsKey(cacheKey)) {
+      return _authorImageCache[cacheKey];
+    }
+
+    // Try Audnexus (specifically for audiobook authors, uses Audible data)
+    try {
+      final audnexusUri = Uri.https(
+        'api.audnex.us',
+        '/authors',
+        {'name': authorName},
+      );
+
+      final audnexusResponse = await http.get(audnexusUri).timeout(const Duration(seconds: 5));
+
+      if (audnexusResponse.statusCode == 200) {
+        final data = json.decode(audnexusResponse.body);
+        // Audnexus returns an array of authors
+        if (data is List && data.isNotEmpty) {
+          final author = data[0];
+          final imageUrl = author['image'] as String?;
+          if (imageUrl != null && imageUrl.isNotEmpty) {
+            _authorImageCache[cacheKey] = imageUrl;
+            return imageUrl;
+          }
+        }
+      }
+    } catch (e) {
+      _logger.warning('Audnexus author image error: $e', context: 'Metadata');
+    }
+
+    // Fall back to Open Library API
+    try {
+      final uri = Uri.https(
+        'openlibrary.org',
+        '/search/authors.json',
+        {
+          'q': authorName,
+          'limit': '1',
+        },
+      );
+
+      final response = await http.get(uri).timeout(const Duration(seconds: 5));
+
+      if (response.statusCode == 200) {
+        final data = json.decode(response.body);
+        final authors = data['docs'] as List?;
+        if (authors != null && authors.isNotEmpty) {
+          final author = authors[0];
+          final authorKey = author['key'] as String?;
+          if (authorKey != null) {
+            // Open Library author images are available at:
+            // https://covers.openlibrary.org/a/olid/{OLID}-L.jpg
+            final olid = authorKey.replaceAll('/authors/', '');
+            final imageUrl = 'https://covers.openlibrary.org/a/olid/$olid-L.jpg';
+
+            // Verify the image actually exists (Open Library returns 404 for missing images)
+            try {
+              final imageCheck = await http.head(Uri.parse(imageUrl)).timeout(const Duration(seconds: 3));
+              if (imageCheck.statusCode == 200) {
+                _authorImageCache[cacheKey] = imageUrl;
+                return imageUrl;
+              }
+            } catch (_) {
+              // Image doesn't exist, continue to cache null
+            }
+          }
+        }
+      }
+    } catch (e) {
+      _logger.warning('Open Library author image error: $e', context: 'Metadata');
+    }
+
+    // Fall back to Wikipedia API
+    try {
+      // Search for author on Wikipedia
+      final searchUri = Uri.https(
+        'en.wikipedia.org',
+        '/w/api.php',
+        {
+          'action': 'query',
+          'list': 'search',
+          'srsearch': '$authorName writer',
+          'srlimit': '1',
+          'format': 'json',
+        },
+      );
+
+      final searchResponse = await http.get(searchUri).timeout(const Duration(seconds: 5));
+
+      if (searchResponse.statusCode == 200) {
+        final searchData = json.decode(searchResponse.body);
+        final searchResults = searchData['query']?['search'] as List?;
+        if (searchResults != null && searchResults.isNotEmpty) {
+          final pageTitle = searchResults[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) {
+                  _authorImageCache[cacheKey] = imageUrl;
+                  return imageUrl;
+                }
+              }
+            }
+          }
+        }
+      }
+    } catch (e) {
+      _logger.warning('Wikipedia author image error: $e', context: 'Metadata');
+    }
+
+    // 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();
+  }
+}

lib/services/offline_action_queue.dart

@@ -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';
+}

lib/services/pcm_audio_player.dart

@@ -0,0 +1,676 @@
+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;
+
+  // 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;
+  }
+
+  /// 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;
+        _audioBuffer.add(audioData);
+
+        // Trigger async recovery
+        _autoRecoverFromPause();
+        return;
+      }
+
+      // If already recovering or in transitional state, buffer the data
+      if (_isAutoRecovering) {
+        _audioBuffer.add(audioData);
+        return;
+      }
+
+      // For other blocking states (pausing, stopping, resuming), ignore
+      return;
+    }
+
+    // Add to buffer
+    _audioBuffer.add(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');
+  }
+}

lib/services/position_tracker.dart

@@ -0,0 +1,242 @@
+import 'dart:async';
+import 'package:flutter/foundation.dart';
+import 'debug_logger.dart';
+
+/// Single source of truth for playback position tracking.
+///
+/// This service eliminates race conditions by:
+/// 1. Being the ONLY place that calculates interpolated position
+/// 2. Using consistent interpolation (no mode switching mid-stream)
+/// 3. Capping position at track duration
+/// 4. Broadcasting position updates via a single stream
+///
+/// All consumers (UI, notification) should listen to [positionStream]
+/// instead of calculating position themselves.
+class PositionTracker {
+  final DebugLogger _logger = DebugLogger();
+
+  // Current state
+  String? _playerId;
+  bool _isPlaying = false;
+  Duration _duration = Duration.zero;
+
+  // Position tracking - we anchor to a known position and interpolate from there
+  double _anchorPosition = 0.0;  // Position in seconds at anchor time
+  DateTime _anchorTime = DateTime.now();  // When we set the anchor
+
+  // Interpolation timer
+  Timer? _interpolationTimer;
+
+  // Stream controller for position updates
+  final _positionController = StreamController<Duration>.broadcast();
+
+  // Last emitted position (to avoid redundant updates)
+  int _lastEmittedSeconds = -1;
+
+  /// Stream of position updates (emits every second when playing)
+  Stream<Duration> get positionStream => _positionController.stream;
+
+  /// Current position (can be called synchronously)
+  Duration get currentPosition {
+    if (!_isPlaying) {
+      return Duration(seconds: _anchorPosition.round());
+    }
+
+    final now = DateTime.now();
+    final elapsed = now.difference(_anchorTime).inMilliseconds / 1000.0;
+    final interpolated = _anchorPosition + elapsed;
+
+    // Cap at duration to prevent overflow
+    final capped = _duration.inSeconds > 0
+        ? interpolated.clamp(0.0, _duration.inSeconds.toDouble())
+        : interpolated.clamp(0.0, double.infinity);
+
+    return Duration(seconds: capped.round());
+  }
+
+  /// Current position in seconds (for compatibility)
+  double get currentPositionSeconds {
+    if (!_isPlaying) {
+      return _anchorPosition;
+    }
+
+    final now = DateTime.now();
+    final elapsed = now.difference(_anchorTime).inMilliseconds / 1000.0;
+    final interpolated = _anchorPosition + elapsed;
+
+    // Cap at duration
+    if (_duration.inSeconds > 0) {
+      return interpolated.clamp(0.0, _duration.inSeconds.toDouble());
+    }
+    return interpolated.clamp(0.0, double.infinity);
+  }
+
+  /// Update with fresh data from server.
+  ///
+  /// [playerId] - The player this update is for
+  /// [position] - Current position in seconds from server
+  /// [isPlaying] - Whether the player is currently playing
+  /// [duration] - Track duration (null if unknown)
+  /// [serverTimestamp] - Server's timestamp for when position was recorded (optional)
+  void updateFromServer({
+    required String playerId,
+    required double position,
+    required bool isPlaying,
+    Duration? duration,
+    double? serverTimestamp,
+  }) {
+    final bool playerChanged = _playerId != playerId;
+    final bool playStateChanged = _isPlaying != isPlaying;
+    final bool durationChanged = duration != null && _duration != duration;
+
+    _playerId = playerId;
+    _duration = duration ?? _duration;
+
+    // Calculate the best anchor position
+    double anchorPos = position;
+    bool hasStaleTimestamp = false;
+
+    // If server provides timestamp, use it to calculate current position more accurately
+    if (serverTimestamp != null && isPlaying) {
+      final now = DateTime.now().millisecondsSinceEpoch / 1000.0;
+      final serverAge = now - serverTimestamp;
+
+      // Only use server timestamp if it's reasonably fresh (< 30 seconds)
+      // and not in the future (clock skew)
+      if (serverAge >= 0 && serverAge < 30) {
+        anchorPos = position + serverAge;
+      } else {
+        // Timestamp is stale - mark this so we don't blindly trust the position
+        hasStaleTimestamp = true;
+      }
+    }
+
+    // Cap at duration
+    if (_duration.inSeconds > 0) {
+      anchorPos = anchorPos.clamp(0.0, _duration.inSeconds.toDouble());
+    }
+
+    // Detect if position jumped significantly (more than 3 seconds difference)
+    // This helps identify seeks or track changes
+    final currentInterpolated = currentPositionSeconds;
+    final positionDiff = (anchorPos - currentInterpolated).abs();
+    final isBackwardJump = anchorPos < currentInterpolated;
+    final isJumpToNearZero = anchorPos < 3.0;
+
+    // Detect suspicious backward jumps to 0 - likely bad server data
+    // This happens when some player types don't report elapsed_time correctly
+    final isSuspiciousReset = !playerChanged
+        && !playStateChanged
+        && !durationChanged
+        && isPlaying
+        && _isPlaying
+        && isBackwardJump
+        && isJumpToNearZero
+        && currentInterpolated > 3.0;
+
+    // Always update anchor when:
+    // 1. Player changed
+    // 2. Play state changed
+    // 3. Position jumped significantly (seek or track change) - BUT NOT if it's a suspicious reset
+    //    AND NOT if the timestamp is stale (stale data shouldn't override interpolated position)
+    // 4. We're not playing (paused state should reflect server position)
+    //
+    // Key insight: When timestamp is stale, the raw position from server is likely outdated.
+    // Our interpolated position is probably more accurate, so don't let stale data override it.
+    final shouldUpdateAnchor = playerChanged
+        || playStateChanged
+        || (positionDiff > 2 && !isSuspiciousReset && !hasStaleTimestamp)
+        || !isPlaying;
+
+    if (shouldUpdateAnchor) {
+      _anchorPosition = anchorPos;
+      _anchorTime = DateTime.now();
+    }
+
+    _isPlaying = isPlaying;
+
+    // Manage interpolation timer
+    if (isPlaying) {
+      _startInterpolationTimer();
+    } else {
+      _stopInterpolationTimer();
+      // Emit current position for paused state
+      _emitPosition();
+    }
+  }
+
+  /// Handle seek - immediately update position without waiting for server
+  void onSeek(double positionSeconds) {
+    _anchorPosition = positionSeconds;
+    _anchorTime = DateTime.now();
+    _lastEmittedSeconds = -1; // Force emit
+    _emitPosition();
+  }
+
+  /// Handle track change - reset position to 0
+  void onTrackChange(String playerId, Duration? newDuration) {
+    _playerId = playerId;
+    _duration = newDuration ?? Duration.zero;
+    _anchorPosition = 0.0;
+    _anchorTime = DateTime.now();
+    _lastEmittedSeconds = -1;
+    _emitPosition();
+  }
+
+  /// Handle player selection change
+  void onPlayerSelected(String playerId) {
+    if (_playerId != playerId) {
+      _playerId = playerId;
+      // Don't reset position - let updateFromServer handle it with actual data
+      _lastEmittedSeconds = -1;
+    }
+  }
+
+  /// Clear tracker state (e.g., when disconnecting)
+  void clear() {
+    _stopInterpolationTimer();
+    _playerId = null;
+    _isPlaying = false;
+    _anchorPosition = 0.0;
+    _duration = Duration.zero;
+    _lastEmittedSeconds = -1;
+  }
+
+  void _startInterpolationTimer() {
+    if (_interpolationTimer != null) return;
+
+    _interpolationTimer = Timer.periodic(const Duration(milliseconds: 250), (_) {
+      _emitPosition();
+    });
+
+    // Emit immediately
+    _emitPosition();
+  }
+
+  void _stopInterpolationTimer() {
+    _interpolationTimer?.cancel();
+    _interpolationTimer = null;
+  }
+
+  void _emitPosition() {
+    final pos = currentPosition;
+    final seconds = pos.inSeconds;
+
+    // Only emit if second changed (reduces unnecessary updates)
+    if (seconds != _lastEmittedSeconds) {
+      _lastEmittedSeconds = seconds;
+      _positionController.add(pos);
+    }
+  }
+
+  /// Check if position has reached or exceeded duration (track ended)
+  bool get hasReachedEnd {
+    if (_duration.inSeconds <= 0) return false;
+    return currentPositionSeconds >= _duration.inSeconds;
+  }
+
+  void dispose() {
+    _stopInterpolationTimer();
+    _positionController.close();
+  }
+}

lib/services/profile_service.dart

@@ -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;
+  }
+}

lib/services/recently_played_service.dart

@@ -0,0 +1,253 @@
+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 (_) {}
+        }
+
+        // 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 (_) {}
+        }
+
+        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');
+  }
+}

lib/services/sendspin_service.dart

@@ -0,0 +1,663 @@
+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;
+
+  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;
+
+    _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);
+        return false;
+      }
+
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection error: $e');
+      _updateState(SendspinConnectionState.error);
+      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;
+
+    _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);
+        return false;
+      }
+
+      return true;
+    } catch (e) {
+      _logger.log('Sendspin: Connection error: $e');
+      _updateState(SendspinConnectionState.error);
+      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();
+  }
+}

lib/services/settings_service.dart

@@ -1,13 +1,83 @@
 import 'package:shared_preferences/shared_preferences.dart';
+import 'dart:convert';
 
 class SettingsService {
   static const String _keyServerUrl = 'server_url';
   static const String _keyAuthServerUrl = 'auth_server_url';
   static const String _keyWebSocketPort = 'websocket_port';
   static const String _keyAuthToken = 'auth_token';
+  static const String _keyMaAuthToken = 'ma_auth_token'; // Music Assistant native auth token
+  static const String _keyAuthCredentials = 'auth_credentials'; // NEW: Serialized auth strategy credentials
   static const String _keyUsername = 'username';
   static const String _keyPassword = 'password';
-  static const String _keyBuiltinPlayerId = 'builtin_player_id';
+  static const String _keyBuiltinPlayerId = 'local_player_id'; // Unified with DeviceIdService
+  static const String _keyThemeMode = 'theme_mode';
+  static const String _keyUseMaterialTheme = 'use_material_theme';
+  static const String _keyAdaptiveTheme = 'adaptive_theme';
+  static const String _keyCustomColor = 'custom_color';
+  static const String _keyLocale = 'locale';
+  static const String _keyLastFmApiKey = 'lastfm_api_key';
+  static const String _keyTheAudioDbApiKey = 'theaudiodb_api_key';
+  static const String _keyEnableLocalPlayback = 'enable_local_playback';
+  static const String _keyLocalPlayerName = 'local_player_name';
+  static const String _keyOwnerName = 'owner_name';
+  static const String _keyLastSelectedPlayerId = 'last_selected_player_id';
+  static const String _keyPreferLocalPlayer = 'prefer_local_player';
+  static const String _keySmartSortPlayers = 'smart_sort_players';
+  static const String _keyShowRecentAlbums = 'show_recent_albums';
+  static const String _keyShowDiscoverArtists = 'show_discover_artists';
+  static const String _keyShowDiscoverAlbums = 'show_discover_albums';
+  static const String _keyShowContinueListeningAudiobooks = 'show_continue_listening_audiobooks';
+  static const String _keyShowDiscoverAudiobooks = 'show_discover_audiobooks';
+  static const String _keyShowDiscoverSeries = 'show_discover_series';
+  static const String _keyShowFavoriteAlbums = 'show_favorite_albums';
+  static const String _keyShowFavoriteArtists = 'show_favorite_artists';
+  static const String _keyShowFavoriteTracks = 'show_favorite_tracks';
+  static const String _keyHomeRowOrder = 'home_row_order'; // JSON list of row IDs
+
+  // Default row order
+  static const List<String> defaultHomeRowOrder = [
+    'recent-albums',
+    'discover-artists',
+    'discover-albums',
+    'continue-listening',
+    'discover-audiobooks',
+    'discover-series',
+    'favorite-albums',
+    'favorite-artists',
+    'favorite-tracks',
+  ];
+
+  // View Mode Settings
+  static const String _keyArtistAlbumsSortOrder = 'artist_albums_sort_order'; // 'alpha' or 'year'
+  static const String _keyArtistAlbumsViewMode = 'artist_albums_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keyLibraryArtistsViewMode = 'library_artists_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keyLibraryAlbumsViewMode = 'library_albums_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keyLibraryPlaylistsViewMode = 'library_playlists_view_mode'; // 'grid2', 'grid3', 'list'
+
+  // Audiobook View Mode Settings
+  static const String _keyAuthorAudiobooksSortOrder = 'author_audiobooks_sort_order'; // 'alpha' or 'year'
+  static const String _keyAuthorAudiobooksViewMode = 'author_audiobooks_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keyLibraryAuthorsViewMode = 'library_authors_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keyLibraryAudiobooksViewMode = 'library_audiobooks_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keyLibraryAudiobooksSortOrder = 'library_audiobooks_sort_order'; // 'alpha' or 'year'
+  static const String _keyLibrarySeriesViewMode = 'library_series_view_mode'; // 'grid2', 'grid3', 'list'
+  static const String _keySeriesAudiobooksSortOrder = 'series_audiobooks_sort_order'; // 'alpha' or 'year'
+  static const String _keySeriesAudiobooksViewMode = 'series_audiobooks_view_mode'; // 'grid2', 'grid3', 'list'
+
+  // Audiobookshelf Direct Integration Settings
+  static const String _keyAbsServerUrl = 'abs_server_url';
+  static const String _keyAbsApiToken = 'abs_api_token';
+  static const String _keyAbsEnabled = 'abs_enabled';
+
+  // Audiobookshelf Library Settings (via MA browse)
+  static const String _keyEnabledAbsLibraries = 'enabled_abs_libraries'; // JSON list of library paths
+  static const String _keyDiscoveredAbsLibraries = 'discovered_abs_libraries'; // JSON list of {path, name}
+
+  // Hint System Settings
+  static const String _keyShowHints = 'show_hints'; // Master toggle for hints
+  static const String _keyHasUsedPlayerReveal = 'has_used_player_reveal'; // Track if user has pulled to reveal players
+  static const String _keyHasCompletedOnboarding = 'has_completed_onboarding'; // Track if user has seen welcome screen
 
   static Future<String?> getServerUrl() async {
     final prefs = await SharedPreferences.getInstance();
@@ -19,6 +89,11 @@ class SettingsService {
     await prefs.setString(_keyServerUrl, url);
   }
 
+  static Future<void> clearServerUrl() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_keyServerUrl);
+  }
+
   // Get authentication server URL (returns null if not set, meaning use server URL)
   static Future<String?> getAuthServerUrl() async {
     final prefs = await SharedPreferences.getInstance();
@@ -67,6 +142,52 @@ class SettingsService {
     }
   }
 
+  // Get Music Assistant native auth token (long-lived token)
+  static Future<String?> getMaAuthToken() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyMaAuthToken);
+  }
+
+  // Set Music Assistant native auth token (long-lived token)
+  static Future<void> setMaAuthToken(String? token) async {
+    final prefs = await SharedPreferences.getInstance();
+    if (token == null || token.isEmpty) {
+      await prefs.remove(_keyMaAuthToken);
+    } else {
+      await prefs.setString(_keyMaAuthToken, token);
+    }
+  }
+
+  // Clear Music Assistant native auth token
+  static Future<void> clearMaAuthToken() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_keyMaAuthToken);
+  }
+
+  // Get authentication credentials (serialized auth strategy credentials)
+  static Future<Map<String, dynamic>?> getAuthCredentials() async {
+    final prefs = await SharedPreferences.getInstance();
+    final json = prefs.getString(_keyAuthCredentials);
+    if (json == null) return null;
+    try {
+      return jsonDecode(json) as Map<String, dynamic>;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  // Set authentication credentials (serialized auth strategy credentials)
+  static Future<void> setAuthCredentials(Map<String, dynamic> credentials) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyAuthCredentials, jsonEncode(credentials));
+  }
+
+  // Clear authentication credentials
+  static Future<void> clearAuthCredentials() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_keyAuthCredentials);
+  }
+
   // Get username for authentication
   static Future<String?> getUsername() async {
     final prefs = await SharedPreferences.getInstance();
@@ -111,8 +232,577 @@ class SettingsService {
     await prefs.setString(_keyBuiltinPlayerId, id);
   }
 
+  // Theme settings
+  static Future<String?> getThemeMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyThemeMode) ?? 'system';
+  }
+
+  static Future<void> saveThemeMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyThemeMode, mode);
+  }
+
+  static Future<bool> getUseMaterialTheme() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyUseMaterialTheme) ?? false;
+  }
+
+  static Future<void> saveUseMaterialTheme(bool enabled) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyUseMaterialTheme, enabled);
+  }
+
+  static Future<bool> getAdaptiveTheme() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyAdaptiveTheme) ?? true; // Default to true
+  }
+
+  static Future<void> saveAdaptiveTheme(bool enabled) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyAdaptiveTheme, enabled);
+  }
+
+  static Future<String?> getCustomColor() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyCustomColor);
+  }
+
+  static Future<void> saveCustomColor(String color) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyCustomColor, color);
+  }
+
+  // Locale (null = system default)
+  static Future<String?> getLocale() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLocale);
+  }
+
+  static Future<void> saveLocale(String? locale) async {
+    final prefs = await SharedPreferences.getInstance();
+    if (locale == null) {
+      await prefs.remove(_keyLocale);
+    } else {
+      await prefs.setString(_keyLocale, locale);
+    }
+  }
+
+  // Metadata API Keys
+  static Future<String?> getLastFmApiKey() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLastFmApiKey);
+  }
+
+  static Future<void> setLastFmApiKey(String? key) async {
+    final prefs = await SharedPreferences.getInstance();
+    if (key == null || key.isEmpty) {
+      await prefs.remove(_keyLastFmApiKey);
+    } else {
+      await prefs.setString(_keyLastFmApiKey, key);
+    }
+  }
+
+  static Future<String?> getTheAudioDbApiKey() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyTheAudioDbApiKey);
+  }
+
+  static Future<void> setTheAudioDbApiKey(String? key) async {
+    final prefs = await SharedPreferences.getInstance();
+    if (key == null || key.isEmpty) {
+      await prefs.remove(_keyTheAudioDbApiKey);
+    } else {
+      await prefs.setString(_keyTheAudioDbApiKey, key);
+    }
+  }
+
+  // Local Playback Settings
+  static Future<bool> getEnableLocalPlayback() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyEnableLocalPlayback) ?? true;
+  }
+
+  static Future<void> setEnableLocalPlayback(bool enabled) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyEnableLocalPlayback, enabled);
+  }
+
+  static Future<String> getLocalPlayerName() async {
+    // Derive player name from owner name
+    final ownerName = await getOwnerName();
+    if (ownerName != null && ownerName.isNotEmpty) {
+      return _makePlayerName(ownerName);
+    }
+
+    // Fallback to stored local player name or default
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLocalPlayerName) ?? 'Ensemble';
+  }
+
+  static Future<void> setLocalPlayerName(String name) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLocalPlayerName, name);
+  }
+
+  // Owner Name - used to derive player name
+  static Future<String?> getOwnerName() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyOwnerName);
+  }
+
+  static Future<void> setOwnerName(String name) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyOwnerName, name.trim());
+  }
+
+  // Last selected player ID - persists user's player selection across sessions
+  static Future<String?> getLastSelectedPlayerId() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLastSelectedPlayerId);
+  }
+
+  static Future<void> setLastSelectedPlayerId(String? playerId) async {
+    final prefs = await SharedPreferences.getInstance();
+    if (playerId == null || playerId.isEmpty) {
+      await prefs.remove(_keyLastSelectedPlayerId);
+    } else {
+      await prefs.setString(_keyLastSelectedPlayerId, playerId);
+    }
+  }
+
+  // Prefer Local Player - always select local player first when available
+  static Future<bool> getPreferLocalPlayer() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyPreferLocalPlayer) ?? false;
+  }
+
+  static Future<void> setPreferLocalPlayer(bool prefer) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyPreferLocalPlayer, prefer);
+  }
+
+  // Smart Sort Players - sort by status (playing > on > off) instead of alphabetically
+  static Future<bool> getSmartSortPlayers() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keySmartSortPlayers) ?? false;
+  }
+
+  static Future<void> setSmartSortPlayers(bool smartSort) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keySmartSortPlayers, smartSort);
+  }
+
+  // Helper to create player name with possessive apostrophe
+  static String _makePlayerName(String ownerName) {
+    // Handle possessive: "Chris" -> "Chris' Phone", "Mom" -> "Mom's Phone"
+    if (ownerName.toLowerCase().endsWith('s')) {
+      return "$ownerName' Phone";
+    } else {
+      return "$ownerName's Phone";
+    }
+  }
+
   static Future<void> clearSettings() async {
     final prefs = await SharedPreferences.getInstance();
     await prefs.clear();
   }
+
+  // Home Screen Row Settings (Main rows - default on)
+  static Future<bool> getShowRecentAlbums() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowRecentAlbums) ?? true;
+  }
+
+  static Future<void> setShowRecentAlbums(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowRecentAlbums, show);
+  }
+
+  static Future<bool> getShowDiscoverArtists() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowDiscoverArtists) ?? true;
+  }
+
+  static Future<void> setShowDiscoverArtists(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowDiscoverArtists, show);
+  }
+
+  static Future<bool> getShowDiscoverAlbums() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowDiscoverAlbums) ?? true;
+  }
+
+  static Future<void> setShowDiscoverAlbums(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowDiscoverAlbums, show);
+  }
+
+  // Home Screen Audiobook Rows (default off - optional)
+  static Future<bool> getShowContinueListeningAudiobooks() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowContinueListeningAudiobooks) ?? false;
+  }
+
+  static Future<void> setShowContinueListeningAudiobooks(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowContinueListeningAudiobooks, show);
+  }
+
+  static Future<bool> getShowDiscoverAudiobooks() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowDiscoverAudiobooks) ?? false;
+  }
+
+  static Future<void> setShowDiscoverAudiobooks(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowDiscoverAudiobooks, show);
+  }
+
+  static Future<bool> getShowDiscoverSeries() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowDiscoverSeries) ?? false;
+  }
+
+  static Future<void> setShowDiscoverSeries(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowDiscoverSeries, show);
+  }
+
+  // Home Screen Favorites Settings (default off)
+  static Future<bool> getShowFavoriteAlbums() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowFavoriteAlbums) ?? false;
+  }
+
+  static Future<void> setShowFavoriteAlbums(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowFavoriteAlbums, show);
+  }
+
+  static Future<bool> getShowFavoriteArtists() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowFavoriteArtists) ?? false;
+  }
+
+  static Future<void> setShowFavoriteArtists(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowFavoriteArtists, show);
+  }
+
+  static Future<bool> getShowFavoriteTracks() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowFavoriteTracks) ?? false;
+  }
+
+  static Future<void> setShowFavoriteTracks(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowFavoriteTracks, show);
+  }
+
+  // Home Row Order
+  static Future<List<String>> getHomeRowOrder() async {
+    final prefs = await SharedPreferences.getInstance();
+    final json = prefs.getString(_keyHomeRowOrder);
+    if (json != null) {
+      try {
+        final List<dynamic> decoded = jsonDecode(json);
+        return decoded.cast<String>();
+      } catch (_) {
+        return List.from(defaultHomeRowOrder);
+      }
+    }
+    return List.from(defaultHomeRowOrder);
+  }
+
+  static Future<void> setHomeRowOrder(List<String> order) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyHomeRowOrder, jsonEncode(order));
+  }
+
+  // View Mode Settings - Artist Albums
+  static Future<String> getArtistAlbumsSortOrder() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyArtistAlbumsSortOrder) ?? 'alpha';
+  }
+
+  static Future<void> setArtistAlbumsSortOrder(String order) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyArtistAlbumsSortOrder, order);
+  }
+
+  static Future<String> getArtistAlbumsViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyArtistAlbumsViewMode) ?? 'grid2';
+  }
+
+  static Future<void> setArtistAlbumsViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyArtistAlbumsViewMode, mode);
+  }
+
+  // View Mode Settings - Library Artists
+  static Future<String> getLibraryArtistsViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibraryArtistsViewMode) ?? 'list';
+  }
+
+  static Future<void> setLibraryArtistsViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibraryArtistsViewMode, mode);
+  }
+
+  // View Mode Settings - Library Albums
+  static Future<String> getLibraryAlbumsViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibraryAlbumsViewMode) ?? 'grid2';
+  }
+
+  static Future<void> setLibraryAlbumsViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibraryAlbumsViewMode, mode);
+  }
+
+  // View Mode Settings - Library Playlists
+  static Future<String> getLibraryPlaylistsViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibraryPlaylistsViewMode) ?? 'list';
+  }
+
+  static Future<void> setLibraryPlaylistsViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibraryPlaylistsViewMode, mode);
+  }
+
+  // View Mode Settings - Author Audiobooks (author detail screen)
+  static Future<String> getAuthorAudiobooksSortOrder() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyAuthorAudiobooksSortOrder) ?? 'alpha';
+  }
+
+  static Future<void> setAuthorAudiobooksSortOrder(String order) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyAuthorAudiobooksSortOrder, order);
+  }
+
+  static Future<String> getAuthorAudiobooksViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyAuthorAudiobooksViewMode) ?? 'grid2';
+  }
+
+  static Future<void> setAuthorAudiobooksViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyAuthorAudiobooksViewMode, mode);
+  }
+
+  // View Mode Settings - Library Authors
+  static Future<String> getLibraryAuthorsViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibraryAuthorsViewMode) ?? 'list';
+  }
+
+  static Future<void> setLibraryAuthorsViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibraryAuthorsViewMode, mode);
+  }
+
+  // View Mode Settings - Library Audiobooks
+  static Future<String> getLibraryAudiobooksViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibraryAudiobooksViewMode) ?? 'grid2';
+  }
+
+  static Future<void> setLibraryAudiobooksViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibraryAudiobooksViewMode, mode);
+  }
+
+  static Future<String> getLibraryAudiobooksSortOrder() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibraryAudiobooksSortOrder) ?? 'alpha';
+  }
+
+  static Future<void> setLibraryAudiobooksSortOrder(String order) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibraryAudiobooksSortOrder, order);
+  }
+
+  static Future<String> getLibrarySeriesViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyLibrarySeriesViewMode) ?? 'grid2';
+  }
+
+  static Future<void> setLibrarySeriesViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyLibrarySeriesViewMode, mode);
+  }
+
+  // View Mode Settings - Series Audiobooks (series detail screen)
+  static Future<String> getSeriesAudiobooksSortOrder() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keySeriesAudiobooksSortOrder) ?? 'series';
+  }
+
+  static Future<void> setSeriesAudiobooksSortOrder(String order) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keySeriesAudiobooksSortOrder, order);
+  }
+
+  static Future<String> getSeriesAudiobooksViewMode() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keySeriesAudiobooksViewMode) ?? 'grid2';
+  }
+
+  static Future<void> setSeriesAudiobooksViewMode(String mode) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keySeriesAudiobooksViewMode, mode);
+  }
+
+  // Audiobookshelf Settings
+  static Future<String?> getAbsServerUrl() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyAbsServerUrl);
+  }
+
+  static Future<void> setAbsServerUrl(String url) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyAbsServerUrl, url);
+  }
+
+  static Future<String?> getAbsApiToken() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getString(_keyAbsApiToken);
+  }
+
+  static Future<void> setAbsApiToken(String token) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyAbsApiToken, token);
+  }
+
+  static Future<bool> getAbsEnabled() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyAbsEnabled) ?? false;
+  }
+
+  static Future<void> setAbsEnabled(bool enabled) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyAbsEnabled, enabled);
+  }
+
+  static Future<void> clearAbsSettings() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_keyAbsServerUrl);
+    await prefs.remove(_keyAbsApiToken);
+    await prefs.remove(_keyAbsEnabled);
+  }
+
+  // Audiobookshelf Library Settings (via MA browse API)
+
+  /// Get list of enabled library paths (all enabled by default if not set)
+  static Future<List<String>?> getEnabledAbsLibraries() async {
+    final prefs = await SharedPreferences.getInstance();
+    final json = prefs.getString(_keyEnabledAbsLibraries);
+    if (json == null) return null; // null means all libraries are enabled
+    try {
+      final list = jsonDecode(json) as List<dynamic>;
+      return list.cast<String>();
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /// Set list of enabled library paths
+  static Future<void> setEnabledAbsLibraries(List<String> paths) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyEnabledAbsLibraries, jsonEncode(paths));
+  }
+
+  /// Clear enabled libraries (reverts to all enabled)
+  static Future<void> clearEnabledAbsLibraries() async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.remove(_keyEnabledAbsLibraries);
+  }
+
+  /// Get discovered libraries [{path: String, name: String}]
+  static Future<List<Map<String, String>>?> getDiscoveredAbsLibraries() async {
+    final prefs = await SharedPreferences.getInstance();
+    final json = prefs.getString(_keyDiscoveredAbsLibraries);
+    if (json == null) return null;
+    try {
+      final list = jsonDecode(json) as List<dynamic>;
+      return list.map((e) => Map<String, String>.from(e as Map)).toList();
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /// Save discovered libraries
+  static Future<void> setDiscoveredAbsLibraries(List<Map<String, String>> libraries) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setString(_keyDiscoveredAbsLibraries, jsonEncode(libraries));
+  }
+
+  /// Check if a specific library is enabled
+  static Future<bool> isAbsLibraryEnabled(String libraryPath) async {
+    final enabled = await getEnabledAbsLibraries();
+    if (enabled == null) return true; // All enabled by default
+    return enabled.contains(libraryPath);
+  }
+
+  /// Toggle a specific library
+  static Future<void> toggleAbsLibrary(String libraryPath, bool enable) async {
+    final discovered = await getDiscoveredAbsLibraries();
+    if (discovered == null) return;
+
+    var enabled = await getEnabledAbsLibraries();
+    // If null (all enabled), initialize with all library paths
+    enabled ??= discovered.map((lib) => lib['path']!).toList();
+
+    if (enable && !enabled.contains(libraryPath)) {
+      enabled.add(libraryPath);
+    } else if (!enable && enabled.contains(libraryPath)) {
+      enabled.remove(libraryPath);
+    }
+
+    await setEnabledAbsLibraries(enabled);
+  }
+
+  // Hint System Settings
+
+  /// Get whether hints are enabled (default: true)
+  static Future<bool> getShowHints() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowHints) ?? true;
+  }
+
+  /// Set whether hints are enabled
+  static Future<void> setShowHints(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowHints, show);
+  }
+
+  /// Check if user has ever used the player reveal gesture
+  static Future<bool> getHasUsedPlayerReveal() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyHasUsedPlayerReveal) ?? false;
+  }
+
+  /// Mark that user has used the player reveal gesture
+  static Future<void> setHasUsedPlayerReveal(bool hasUsed) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyHasUsedPlayerReveal, hasUsed);
+  }
+
+  /// Check if user has completed onboarding (seen welcome screen)
+  static Future<bool> getHasCompletedOnboarding() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyHasCompletedOnboarding) ?? false;
+  }
+
+  /// Mark that user has completed onboarding
+  static Future<void> setHasCompletedOnboarding(bool completed) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyHasCompletedOnboarding, completed);
+  }
 }

lib/services/sync_service.dart

@@ -0,0 +1,299 @@
+import 'dart:async';
+import 'dart:convert';
+import 'package:flutter/foundation.dart';
+import '../models/media_item.dart';
+import 'database_service.dart';
+import 'debug_logger.dart';
+import 'music_assistant_api.dart';
+
+/// Sync status for UI indicators
+enum SyncStatus {
+  idle,
+  syncing,
+  completed,
+  error,
+}
+
+/// Service for background library synchronization
+/// Loads from database cache first, then syncs from MA API in background
+class SyncService with ChangeNotifier {
+  static SyncService? _instance;
+  static final _logger = DebugLogger();
+
+  SyncService._();
+
+  static SyncService get instance {
+    _instance ??= SyncService._();
+    return _instance!;
+  }
+
+  DatabaseService get _db => DatabaseService.instance;
+
+  // Sync state
+  SyncStatus _status = SyncStatus.idle;
+  String? _lastError;
+  DateTime? _lastSyncTime;
+  bool _isSyncing = false;
+
+  // Cached data (loaded from DB, updated after sync)
+  List<Album> _cachedAlbums = [];
+  List<Artist> _cachedArtists = [];
+  List<Audiobook> _cachedAudiobooks = [];
+  List<Playlist> _cachedPlaylists = [];
+
+  // Getters
+  SyncStatus get status => _status;
+  String? get lastError => _lastError;
+  DateTime? get lastSyncTime => _lastSyncTime;
+  bool get isSyncing => _isSyncing;
+  List<Album> get cachedAlbums => _cachedAlbums;
+  List<Artist> get cachedArtists => _cachedArtists;
+  List<Audiobook> get cachedAudiobooks => _cachedAudiobooks;
+  List<Playlist> get cachedPlaylists => _cachedPlaylists;
+  bool get hasCache => _cachedAlbums.isNotEmpty || _cachedArtists.isNotEmpty ||
+                       _cachedAudiobooks.isNotEmpty || _cachedPlaylists.isNotEmpty;
+
+  /// Load library data from database cache (instant)
+  /// Call this on app startup for immediate data
+  Future<void> loadFromCache() async {
+    if (!_db.isInitialized) {
+      _logger.log('⚠️ Database not initialized, skipping cache load');
+      return;
+    }
+
+    try {
+      _logger.log('📦 Loading library from database cache...');
+
+      // Load albums from cache
+      final albumData = await _db.getCachedItems('album');
+      _cachedAlbums = albumData.map((data) {
+        try {
+          return Album.fromJson(data);
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse cached album: $e');
+          return null;
+        }
+      }).whereType<Album>().toList();
+
+      // Load artists from cache
+      final artistData = await _db.getCachedItems('artist');
+      _cachedArtists = artistData.map((data) {
+        try {
+          return Artist.fromJson(data);
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse cached artist: $e');
+          return null;
+        }
+      }).whereType<Artist>().toList();
+
+      // Load audiobooks from cache
+      final audiobookData = await _db.getCachedItems('audiobook');
+      _cachedAudiobooks = audiobookData.map((data) {
+        try {
+          return Audiobook.fromJson(data);
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse cached audiobook: $e');
+          return null;
+        }
+      }).whereType<Audiobook>().toList();
+
+      // Load playlists from cache
+      final playlistData = await _db.getCachedItems('playlist');
+      _cachedPlaylists = playlistData.map((data) {
+        try {
+          return Playlist.fromJson(data);
+        } catch (e) {
+          _logger.log('⚠️ Failed to parse cached playlist: $e');
+          return null;
+        }
+      }).whereType<Playlist>().toList();
+
+      _logger.log('📦 Loaded ${_cachedAlbums.length} albums, ${_cachedArtists.length} artists, '
+                  '${_cachedAudiobooks.length} audiobooks, ${_cachedPlaylists.length} playlists from cache');
+      notifyListeners();
+    } catch (e) {
+      _logger.log('❌ Failed to load from cache: $e');
+    }
+  }
+
+  /// Sync library data from MA API in background
+  /// Updates database cache and notifies listeners when complete
+  Future<void> syncFromApi(MusicAssistantAPI api, {bool force = false}) async {
+    if (_isSyncing) {
+      _logger.log('🔄 Sync already in progress, skipping');
+      return;
+    }
+
+    if (!_db.isInitialized) {
+      _logger.log('⚠️ Database not initialized, skipping sync');
+      return;
+    }
+
+    // Check if sync is needed (default: every 5 minutes)
+    if (!force) {
+      final albumsNeedSync = await _db.needsSync('albums', maxAge: const Duration(minutes: 5));
+      final artistsNeedSync = await _db.needsSync('artists', maxAge: const Duration(minutes: 5));
+      final audiobooksNeedSync = await _db.needsSync('audiobooks', maxAge: const Duration(minutes: 5));
+      final playlistsNeedSync = await _db.needsSync('playlists', maxAge: const Duration(minutes: 5));
+
+      if (!albumsNeedSync && !artistsNeedSync && !audiobooksNeedSync && !playlistsNeedSync) {
+        _logger.log('✅ Cache is fresh, skipping sync');
+        return;
+      }
+    }
+
+    _isSyncing = true;
+    _status = SyncStatus.syncing;
+    _lastError = null;
+    notifyListeners();
+
+    try {
+      _logger.log('🔄 Starting background library sync...');
+
+      // Fetch fresh data from MA API (in parallel for speed)
+      final results = await Future.wait([
+        api.getAlbums(limit: 1000),
+        api.getArtists(limit: 1000),
+        api.getAudiobooks(limit: 1000),
+        api.getPlaylists(limit: 1000),
+      ]);
+
+      final albums = results[0] as List<Album>;
+      final artists = results[1] as List<Artist>;
+      final audiobooks = results[2] as List<Audiobook>;
+      final playlists = results[3] as List<Playlist>;
+
+      _logger.log('📥 Fetched ${albums.length} albums, ${artists.length} artists, '
+                  '${audiobooks.length} audiobooks, ${playlists.length} playlists from MA');
+
+      // Save to database cache
+      await _saveAlbumsToCache(albums);
+      await _saveArtistsToCache(artists);
+      await _saveAudiobooksToCache(audiobooks);
+      await _savePlaylistsToCache(playlists);
+
+      // Update sync metadata
+      await _db.updateSyncMetadata('albums', albums.length);
+      await _db.updateSyncMetadata('artists', artists.length);
+      await _db.updateSyncMetadata('audiobooks', audiobooks.length);
+      await _db.updateSyncMetadata('playlists', playlists.length);
+
+      // Update in-memory cache
+      _cachedAlbums = albums;
+      _cachedArtists = artists;
+      _cachedAudiobooks = audiobooks;
+      _cachedPlaylists = playlists;
+      _lastSyncTime = DateTime.now();
+      _status = SyncStatus.completed;
+
+      _logger.log('✅ Library sync complete');
+    } catch (e) {
+      _logger.log('❌ Library sync failed: $e');
+      _status = SyncStatus.error;
+      _lastError = e.toString();
+    } finally {
+      _isSyncing = false;
+      notifyListeners();
+    }
+  }
+
+  /// Save albums to database cache
+  Future<void> _saveAlbumsToCache(List<Album> albums) async {
+    for (final album in albums) {
+      try {
+        await _db.cacheItem(
+          itemType: 'album',
+          itemId: album.itemId,
+          data: album.toJson(),
+        );
+      } catch (e) {
+        _logger.log('⚠️ Failed to cache album ${album.name}: $e');
+      }
+    }
+    _logger.log('💾 Saved ${albums.length} albums to cache');
+  }
+
+  /// Save artists to database cache
+  Future<void> _saveArtistsToCache(List<Artist> artists) async {
+    for (final artist in artists) {
+      try {
+        await _db.cacheItem(
+          itemType: 'artist',
+          itemId: artist.itemId,
+          data: artist.toJson(),
+        );
+      } catch (e) {
+        _logger.log('⚠️ Failed to cache artist ${artist.name}: $e');
+      }
+    }
+    _logger.log('💾 Saved ${artists.length} artists to cache');
+  }
+
+  /// Save audiobooks to database cache
+  Future<void> _saveAudiobooksToCache(List<Audiobook> audiobooks) async {
+    for (final audiobook in audiobooks) {
+      try {
+        await _db.cacheItem(
+          itemType: 'audiobook',
+          itemId: audiobook.itemId,
+          data: audiobook.toJson(),
+        );
+      } catch (e) {
+        _logger.log('⚠️ Failed to cache audiobook ${audiobook.name}: $e');
+      }
+    }
+    _logger.log('💾 Saved ${audiobooks.length} audiobooks to cache');
+  }
+
+  /// Save playlists to database cache
+  Future<void> _savePlaylistsToCache(List<Playlist> playlists) async {
+    for (final playlist in playlists) {
+      try {
+        await _db.cacheItem(
+          itemType: 'playlist',
+          itemId: playlist.itemId,
+          data: playlist.toJson(),
+        );
+      } catch (e) {
+        _logger.log('⚠️ Failed to cache playlist ${playlist.name}: $e');
+      }
+    }
+    _logger.log('💾 Saved ${playlists.length} playlists to cache');
+  }
+
+  /// Force a fresh sync (for pull-to-refresh)
+  Future<void> forceSync(MusicAssistantAPI api) async {
+    await syncFromApi(api, force: true);
+  }
+
+  /// Clear all cached data
+  Future<void> clearCache() async {
+    if (!_db.isInitialized) return;
+
+    await _db.clearAllCache();
+    _cachedAlbums = [];
+    _cachedArtists = [];
+    _cachedAudiobooks = [];
+    _cachedPlaylists = [];
+    _lastSyncTime = null;
+    _status = SyncStatus.idle;
+    notifyListeners();
+    _logger.log('🗑️ Library cache cleared');
+  }
+
+  /// Get albums (from cache or empty if not loaded)
+  List<Album> getAlbums() => _cachedAlbums;
+
+  /// Get artists (from cache or empty if not loaded)
+  List<Artist> getArtists() => _cachedArtists;
+
+  /// Get audiobooks (from cache or empty if not loaded)
+  List<Audiobook> getAudiobooks() => _cachedAudiobooks;
+
+  /// Get playlists (from cache or empty if not loaded)
+  List<Playlist> getPlaylists() => _cachedPlaylists;
+
+  /// Check if we have data available (from cache or sync)
+  bool get hasData => _cachedAlbums.isNotEmpty || _cachedArtists.isNotEmpty ||
+                      _cachedAudiobooks.isNotEmpty || _cachedPlaylists.isNotEmpty;
+}

lib/theme/app_theme.dart

@@ -0,0 +1,101 @@
+import 'package:flutter/material.dart';
+
+// Brand colors for Ensemble
+const Color brandPrimaryColor = Color(0xFF1a1a1a);
+const Color brandAccentColor = Color(0xFF604CEC);
+
+// Predefined accent colors for custom theme selection
+const List<Color> accentColorOptions = [
+  Color(0xFF604CEC), // Purple (default)
+  Color(0xFF2196F3), // Blue
+  Color(0xFF009688), // Teal
+  Color(0xFFFF5722), // Deep Orange
+  Color(0xFFE91E63), // Pink
+  Color(0xFF4CAF50), // Green
+];
+
+// Brand color schemes (default)
+final ColorScheme brandLightColorScheme = ColorScheme.fromSeed(
+  seedColor: brandAccentColor,
+  brightness: Brightness.light,
+  background: const Color(0xFFFAFAFA),
+  onBackground: const Color(0xFF1a1a1a), // Ensure dark text
+  surface: const Color(0xFFFFFFFF),
+  onSurface: const Color(0xFF1a1a1a), // Ensure dark text
+);
+
+final ColorScheme brandDarkColorScheme = ColorScheme.fromSeed(
+  seedColor: brandAccentColor,
+  brightness: Brightness.dark,
+  surface: const Color(0xFF2a2a2a),
+  background: const Color(0xFF1a1a1a),
+);
+
+// Generate color schemes from a custom seed color
+ColorScheme generateLightColorScheme(Color seedColor) {
+  return ColorScheme.fromSeed(
+    seedColor: seedColor,
+    brightness: Brightness.light,
+    background: const Color(0xFFFAFAFA),
+    onBackground: const Color(0xFF1a1a1a),
+    surface: const Color(0xFFFFFFFF),
+    onSurface: const Color(0xFF1a1a1a),
+  );
+}
+
+ColorScheme generateDarkColorScheme(Color seedColor) {
+  return ColorScheme.fromSeed(
+    seedColor: seedColor,
+    brightness: Brightness.dark,
+    surface: const Color(0xFF2a2a2a),
+    background: const Color(0xFF1a1a1a),
+  );
+}
+
+class AppTheme {
+  // Generate light theme
+  static ThemeData lightTheme({ColorScheme? colorScheme}) {
+    final scheme = colorScheme ?? brandLightColorScheme;
+
+    return ThemeData(
+      useMaterial3: true,
+      brightness: Brightness.light,
+      colorScheme: scheme,
+      scaffoldBackgroundColor: scheme.background,
+      appBarTheme: AppBarTheme(
+        backgroundColor: Colors.transparent,
+        elevation: 0,
+        foregroundColor: scheme.onBackground,
+        iconTheme: IconThemeData(color: scheme.onBackground),
+      ),
+      cardTheme: CardTheme(
+        color: scheme.surface,
+        elevation: 2,
+      ),
+      fontFamily: 'Roboto',
+    );
+  }
+
+  // Generate dark theme
+  static ThemeData darkTheme({ColorScheme? colorScheme}) {
+    final scheme = colorScheme ?? brandDarkColorScheme;
+
+    return ThemeData(
+      useMaterial3: true,
+      brightness: Brightness.dark,
+      colorScheme: scheme,
+      scaffoldBackgroundColor: scheme.background,
+      appBarTheme: AppBarTheme(
+        backgroundColor: Colors.transparent,
+        elevation: 0,
+        foregroundColor: scheme.onBackground,
+        iconTheme: IconThemeData(color: scheme.onBackground),
+      ),
+      cardTheme: CardTheme(
+        color: scheme.surface,
+        elevation: 2,
+      ),
+      fontFamily: 'Roboto',
+    );
+  }
+}

lib/theme/design_tokens.dart

@@ -0,0 +1,126 @@
+import 'package:flutter/material.dart';
+
+/// Design tokens for consistent spacing, dimensions, and styling throughout the app.
+///
+/// Usage:
+/// ```dart
+/// Padding(padding: Spacing.paddingAll16)
+/// SizedBox(height: Spacing.md)
+/// BorderRadius.circular(Radii.md)
+/// ```
+class Spacing {
+  Spacing._();
+
+  // Base spacing scale (follows 4px grid)
+  static const double xxs = 2.0;
+  static const double xs = 4.0;
+  static const double sm = 8.0;
+  static const double md = 12.0;
+  static const double lg = 16.0;
+  static const double xl = 24.0;
+  static const double xxl = 32.0;
+  static const double xxxl = 48.0;
+
+  // Pre-built EdgeInsets for common padding patterns
+  static const EdgeInsets paddingAll4 = EdgeInsets.all(xs);
+  static const EdgeInsets paddingAll8 = EdgeInsets.all(sm);
+  static const EdgeInsets paddingAll12 = EdgeInsets.all(md);
+  static const EdgeInsets paddingAll16 = EdgeInsets.all(lg);
+  static const EdgeInsets paddingAll24 = EdgeInsets.all(xl);
+  static const EdgeInsets paddingAll32 = EdgeInsets.all(xxl);
+
+  // Horizontal padding
+  static const EdgeInsets paddingH8 = EdgeInsets.symmetric(horizontal: sm);
+  static const EdgeInsets paddingH12 = EdgeInsets.symmetric(horizontal: md);
+  static const EdgeInsets paddingH16 = EdgeInsets.symmetric(horizontal: lg);
+  static const EdgeInsets paddingH24 = EdgeInsets.symmetric(horizontal: xl);
+
+  // Vertical padding
+  static const EdgeInsets paddingV8 = EdgeInsets.symmetric(vertical: sm);
+  static const EdgeInsets paddingV12 = EdgeInsets.symmetric(vertical: md);
+  static const EdgeInsets paddingV16 = EdgeInsets.symmetric(vertical: lg);
+  static const EdgeInsets paddingV24 = EdgeInsets.symmetric(vertical: xl);
+
+  // Pre-built SizedBox widgets for gaps
+  static const SizedBox vGap4 = SizedBox(height: xs);
+  static const SizedBox vGap8 = SizedBox(height: sm);
+  static const SizedBox vGap12 = SizedBox(height: md);
+  static const SizedBox vGap16 = SizedBox(height: lg);
+  static const SizedBox vGap24 = SizedBox(height: xl);
+  static const SizedBox vGap32 = SizedBox(height: xxl);
+
+  static const SizedBox hGap4 = SizedBox(width: xs);
+  static const SizedBox hGap8 = SizedBox(width: sm);
+  static const SizedBox hGap12 = SizedBox(width: md);
+  static const SizedBox hGap16 = SizedBox(width: lg);
+}
+
+/// Border radius tokens
+class Radii {
+  Radii._();
+
+  static const double xs = 2.0;
+  static const double sm = 4.0;
+  static const double md = 8.0;
+  static const double lg = 12.0;
+  static const double xl = 16.0;
+  static const double xxl = 24.0;
+  static const double pill = 999.0;
+
+  // Pre-built BorderRadius for common patterns
+  static final BorderRadius borderRadiusSm = BorderRadius.circular(sm);
+  static final BorderRadius borderRadiusMd = BorderRadius.circular(md);
+  static final BorderRadius borderRadiusLg = BorderRadius.circular(lg);
+  static final BorderRadius borderRadiusXl = BorderRadius.circular(xl);
+  static final BorderRadius borderRadiusXxl = BorderRadius.circular(xxl);
+}
+
+/// Icon size tokens
+class IconSizes {
+  IconSizes._();
+
+  static const double xs = 16.0;
+  static const double sm = 20.0;
+  static const double md = 24.0;
+  static const double lg = 32.0;
+  static const double xl = 48.0;
+  static const double xxl = 64.0;
+  static const double xxxl = 80.0;
+}
+
+/// Common dimension tokens
+class Dimensions {
+  Dimensions._();
+
+  // Album art / thumbnail sizes
+  static const double thumbnailSm = 48.0;
+  static const double thumbnailMd = 80.0;
+  static const double thumbnailLg = 128.0;
+  static const double thumbnailXl = 200.0;
+
+  // Avatar sizes
+  static const double avatarSm = 32.0;
+  static const double avatarMd = 48.0;
+  static const double avatarLg = 64.0;
+
+  // List tile heights
+  static const double listTileHeight = 56.0;
+  static const double listTileHeightDense = 48.0;
+
+  // Mini player height
+  static const double miniPlayerHeight = 64.0;
+
+  // App bar heights
+  static const double appBarHeight = 56.0;
+  static const double expandedAppBarHeight = 200.0;
+}
+
+/// Duration tokens for animations
+class Durations {
+  Durations._();
+
+  static const Duration instant = Duration(milliseconds: 100);
+  static const Duration fast = Duration(milliseconds: 200);
+  static const Duration normal = Duration(milliseconds: 300);
+  static const Duration slow = Duration(milliseconds: 500);
+}

lib/theme/palette_helper.dart

@@ -0,0 +1,204 @@
+import 'package:flutter/material.dart';
+import 'package:palette_generator/palette_generator.dart';
+import '../services/debug_logger.dart';
+
+final _logger = DebugLogger();
+
+/// Extracted adaptive colors from album art
+class AdaptiveColors {
+  final Color primary;       // Main accent color (vibrant)
+  final Color surface;       // Background color
+  final Color onSurface;     // Text color on background
+  final Color miniPlayer;    // Darker version for mini player
+
+  const AdaptiveColors({
+    required this.primary,
+    required this.surface,
+    required this.onSurface,
+    required this.miniPlayer,
+  });
+
+  static const fallback = AdaptiveColors(
+    primary: Color(0xFF604CEC),
+    surface: Color(0xFF121212),
+    onSurface: Colors.white,
+    miniPlayer: Color(0xFF1a1a1a),
+  );
+}
+
+/// Helper to get contrasting text color based on background luminance
+Color getContrastingTextColor(Color backgroundColor) {
+  // Use relative luminance to determine if we need light or dark text
+  // Standard threshold is 0.179 based on WCAG guidelines
+  return backgroundColor.computeLuminance() > 0.4 ? Colors.black : Colors.white;
+}
+
+class PaletteHelper {
+  /// Extract a color palette from an image with higher color count for better variety
+  static Future<PaletteGenerator?> extractPalette(ImageProvider imageProvider) async {
+    try {
+      final palette = await PaletteGenerator.fromImageProvider(
+        imageProvider,
+        maximumColorCount: 32, // Increased from 20 for more color variety
+      );
+      return palette;
+    } catch (e) {
+      _logger.warning('Failed to extract palette: $e', context: 'Palette');
+      return null;
+    }
+  }
+
+  /// Extract actual colors from the palette (not seed-based)
+  static AdaptiveColors? extractAdaptiveColors(PaletteGenerator? palette, {required bool isDark}) {
+    if (palette == null) return null;
+
+    // Get primary color - prefer vibrant, then dominant
+    final Color primary = palette.vibrantColor?.color ??
+                         palette.lightVibrantColor?.color ??
+                         palette.dominantColor?.color ??
+                         const Color(0xFF604CEC);
+
+    // Ensure primary has enough saturation to be visually distinct
+    // AND enough lightness for white text to be readable on it
+    final HSLColor hslPrimary = HSLColor.fromColor(primary);
+    Color adjustedPrimary = primary;
+
+    // Adjust saturation if too low
+    if (hslPrimary.saturation < 0.3) {
+      adjustedPrimary = hslPrimary.withSaturation(0.5).toColor();
+    }
+
+    // Ensure minimum lightness for contrast with white text
+    // If primary is too dark (luminance < 0.15), lighten it
+    if (adjustedPrimary.computeLuminance() < 0.15) {
+      final hsl = HSLColor.fromColor(adjustedPrimary);
+      adjustedPrimary = hsl.withLightness((hsl.lightness + 0.25).clamp(0.3, 0.6)).toColor();
+    }
+
+    if (isDark) {
+      // Dark mode: use dark muted colors for background
+      final Color surfaceBase = palette.darkMutedColor?.color ??
+                                palette.mutedColor?.color ??
+                                const Color(0xFF121212);
+
+      // Darken the surface color significantly for the expanded background
+      final HSLColor hslSurface = HSLColor.fromColor(surfaceBase);
+      final Color surface = hslSurface
+          .withLightness((hslSurface.lightness * 0.3).clamp(0.05, 0.15))
+          .toColor();
+
+      // Mini player should be medium brightness - noticeably tinted but readable
+      // Use the muted color but at medium lightness (0.25-0.35 range)
+      final Color miniPlayer = hslSurface
+          .withLightness(0.3.clamp(0.25, 0.38))
+          .withSaturation((hslSurface.saturation * 1.2).clamp(0.15, 0.5))
+          .toColor();
+
+      return AdaptiveColors(
+        primary: adjustedPrimary,
+        surface: surface,
+        onSurface: Colors.white,
+        miniPlayer: miniPlayer,
+      );
+    } else {
+      // Light mode: use light muted colors
+      final Color surfaceBase = palette.lightMutedColor?.color ??
+                                palette.mutedColor?.color ??
+                                Colors.white;
+
+      final HSLColor hslSurface = HSLColor.fromColor(surfaceBase);
+      final Color surface = hslSurface
+          .withLightness((hslSurface.lightness).clamp(0.92, 0.98))
+          .toColor();
+
+      // Mini player in light mode - medium tinted
+      final Color miniPlayer = hslSurface
+          .withLightness(0.75.clamp(0.65, 0.8))
+          .withSaturation((hslSurface.saturation * 1.2).clamp(0.15, 0.5))
+          .toColor();
+
+      return AdaptiveColors(
+        primary: adjustedPrimary,
+        surface: surface,
+        onSurface: Colors.black87,
+        miniPlayer: miniPlayer,
+      );
+    }
+  }
+
+  /// Generate color schemes from a palette (kept for backward compatibility)
+  static (ColorScheme, ColorScheme)? generateColorSchemes(PaletteGenerator? palette) {
+    if (palette == null) return null;
+
+    final lightColors = extractAdaptiveColors(palette, isDark: false);
+    final darkColors = extractAdaptiveColors(palette, isDark: true);
+
+    if (lightColors == null || darkColors == null) return null;
+
+    // Determine contrasting text colors based on primary color luminance
+    final lightOnPrimary = getContrastingTextColor(lightColors.primary);
+    final darkOnPrimary = getContrastingTextColor(darkColors.primary);
+    final lightOnMiniPlayer = getContrastingTextColor(lightColors.miniPlayer);
+    final darkOnMiniPlayer = getContrastingTextColor(darkColors.miniPlayer);
+
+    final lightScheme = ColorScheme(
+      brightness: Brightness.light,
+      primary: lightColors.primary,
+      onPrimary: lightOnPrimary,
+      secondary: lightColors.primary.withOpacity(0.8),
+      onSecondary: lightOnPrimary,
+      error: Colors.red,
+      onError: Colors.white,
+      surface: lightColors.surface,
+      onSurface: lightColors.onSurface,
+      primaryContainer: lightColors.miniPlayer,
+      onPrimaryContainer: lightOnMiniPlayer,
+    );
+
+    final darkScheme = ColorScheme(
+      brightness: Brightness.dark,
+      primary: darkColors.primary,
+      onPrimary: darkOnPrimary,
+      secondary: darkColors.primary.withOpacity(0.8),
+      onSecondary: darkOnPrimary,
+      error: Colors.redAccent,
+      onError: Colors.black,
+      surface: darkColors.surface,
+      onSurface: darkColors.onSurface,
+      primaryContainer: darkColors.miniPlayer,
+      onPrimaryContainer: darkOnMiniPlayer,
+    );
+
+    return (lightScheme, darkScheme);
+  }
+
+  /// Extract color schemes from an image provider in one call
+  static Future<(ColorScheme, ColorScheme)?> extractColorSchemes(ImageProvider imageProvider) async {
+    final palette = await extractPalette(imageProvider);
+    return generateColorSchemes(palette);
+  }
+
+  /// Get primary color for use in UI elements
+  static Color? getPrimaryColor(PaletteGenerator? palette) {
+    if (palette == null) return null;
+
+    return palette.vibrantColor?.color ??
+           palette.dominantColor?.color ??
+           palette.lightVibrantColor?.color;
+  }
+
+  /// Get background color for use in UI
+  static Color? getBackgroundColor(PaletteGenerator? palette, {required bool isDark}) {
+    if (palette == null) return null;
+
+    if (isDark) {
+      return palette.darkMutedColor?.color ??
+             palette.mutedColor?.color?.withOpacity(0.3) ??
+             const Color(0xFF1a1a1a);
+    } else {
+      return palette.lightMutedColor?.color ??
+             palette.mutedColor?.color?.withOpacity(0.9) ??
+             Colors.white;
+    }
+  }
+}