Bump version to 3.0.3+55 for v3.0.3-beta release

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

AUDIT-PROMPT.md

@@ -1,391 +0,0 @@
-# Ensemble Codebase Intensive Audit Prompt
-
-## Overview
-
-You are tasked with conducting an intensive, comprehensive audit of the **Ensemble** Flutter application - a Music Assistant client for Android with multi-device synchronization, local playback, and Sendspin raw audio streaming capabilities.
-
-**Codebase Statistics:**
-- 90 Dart files, ~40,583 lines of code
-- 18 screens, 27 services, 6 providers
-- Architecture: Provider pattern with ChangeNotifier
-- Audio: just_audio + flutter_pcm_sound + audio_service
-- Networking: WebSocket (JSON-RPC) + HTTP + Sendspin binary protocol
-
----
-
-## Audit Scope
-
-Perform a thorough audit covering ALL of the following areas. For each issue found, provide:
-1. **File path and line number(s)**
-2. **Severity**: CRITICAL / HIGH / MEDIUM / LOW
-3. **Description** of the issue
-4. **Impact** if left unfixed
-5. **Recommended fix** with code example where applicable
-
----
-
-## SECTION 1: SECURITY AUDIT
-
-### 1.1 Credential Storage (CRITICAL PRIORITY)
-Audit `/lib/services/settings_service.dart` for:
-- [ ] Plaintext password storage in SharedPreferences (lines 209-222)
-- [ ] Auth tokens stored without encryption
-- [ ] Serialized credentials in JSON format (lines 169-190)
-
-**Expected Finding:** Credentials stored insecurely. Recommend flutter_secure_storage.
-
-### 1.2 Certificate Validation
-Audit `/lib/services/auth/auth_manager.dart` for:
-- [ ] HTTPS redirect handling for local IPs
-- [ ] Certificate validation disabled scenarios
-- [ ] MITM vulnerability exposure
-
-### 1.3 Authentication Strategies
-Audit all files in `/lib/services/auth/`:
-- [ ] `basic_auth_strategy.dart` - Base64 encoding (not encryption)
-- [ ] `authelia_strategy.dart` - Session cookie handling, timing attack (line 159)
-- [ ] `ma_auth_strategy.dart` - Token refresh mechanism
-- [ ] `no_auth_strategy.dart` - Public server exposure
-
-### 1.4 Input Validation
-Audit `/lib/services/music_assistant_api.dart`:
-- [ ] URI construction without validation (lines 1346-1360)
-- [ ] Provider/itemId injection risks
-- [ ] WebSocket message validation
-
-### 1.5 Information Disclosure
-- [ ] Debug logs exposing sensitive data (check all `_logger.log()` calls)
-- [ ] Server version exposure via `server_info`
-- [ ] Error messages leaking technical details
-
----
-
-## SECTION 2: MEMORY MANAGEMENT AUDIT
-
-### 2.1 Static Memory Leaks
-Audit `/lib/models/player.dart`:
-- [ ] `_playerCreationTimes` static map (lines 96-144) - grows unbounded
-- [ ] Cleanup only removes 50 of 100+ entries
-
-### 2.2 Unbounded Caches
-Audit `/lib/services/cache_service.dart`:
-- [ ] `_albumTracksCache` - no size limit
-- [ ] `_artistAlbumsCache` - no TTL expiration
-- [ ] `_searchCache` - never evicted
-- [ ] `_playerTrackCache` - only cleared on disconnect
-
-### 2.3 Stream/Timer Cleanup
-Audit `/lib/providers/music_assistant_provider.dart`:
-- [ ] `_playerStateTimer` disposal (line 4435-4445)
-- [ ] `_notificationPositionTimer` multiple creation paths (lines 2925-2940)
-- [ ] `_localPlayerEventSubscription` cleanup
-- [ ] `_playerUpdatedEventSubscription` cleanup
-- [ ] `_playerAddedEventSubscription` cleanup
-
-Audit `/lib/services/hardware_volume_service.dart`:
-- [ ] `_volumeUpController` never closed (lines 74-85)
-- [ ] `_volumeDownController` never closed
-
-### 2.4 Stream Subscription Leaks
-Audit `/lib/providers/music_assistant_provider.dart`:
-- [ ] `_api!.connectionState.listen()` - subscription not stored
-- [ ] Old subscriptions not cancelled before new API instance
-
----
-
-## SECTION 3: RACE CONDITION AUDIT
-
-### 3.1 Player State Dual Updates
-Audit `/lib/providers/music_assistant_provider.dart`:
-- [ ] Timer polling (every 5s) vs WebSocket events racing
-- [ ] `_updatePlayerState()` called from both paths
-- [ ] No mutex/lock protection
-
-### 3.2 Async Method Reentrancy
-Audit `selectPlayer()` method:
-- [ ] `async` method without guard against concurrent calls
-- [ ] `_selectedPlayer` modified before and after `await`
-- [ ] State could change during await
-
-### 3.3 Fire-and-Forget Operations
-Search for `unawaited(` and `() async {` patterns:
-- [ ] `_persistPlaybackState()` - database save not awaited
-- [ ] Pause operations fire-and-forget (lines 3876-3894)
-- [ ] Preload operations (line 2707)
-
-### 3.4 PCM Player State Machine
-Audit `/lib/services/pcm_audio_player.dart`:
-- [ ] 9-state machine with complex transitions (lines 32-37)
-- [ ] Auto-recovery race condition (lines 215-229)
-- [ ] Feed loop during pause transition (lines 174-179)
-
----
-
-## SECTION 4: ERROR HANDLING AUDIT
-
-### 4.1 Silent Exception Handlers (CRITICAL)
-Find all instances of:
-```dart
-} catch (e) {}
-} catch (_) {}
-```
-
-Known locations:
-- [ ] `music_assistant_provider.dart` (multiple)
-- [ ] `player_provider.dart` (3 instances)
-- [ ] `recently_played_service.dart`
-
-### 4.2 Missing Error Recovery
-- [ ] No exponential backoff on connection retry
-- [ ] No retry logic for failed API calls
-- [ ] WebSocket timeout handling (30 seconds - too long?)
-
-### 4.3 Null Safety Violations
-Find all `!` (null assertion) operators:
-- [ ] `search_screen.dart` (20+ instances)
-- [ ] `models/media_item.dart`
-- [ ] `models/player.dart`
-- [ ] `item.mediaItem! as Artist` patterns
-
----
-
-## SECTION 5: ARCHITECTURAL ISSUES
-
-### 5.1 God Class
-Audit `/lib/providers/music_assistant_provider.dart`:
-- [ ] 4,469 lines - violates Single Responsibility
-- [ ] 386 conditional branches
-- [ ] Mixing: connection, players, library, sync, audio, position tracking
-
-**Recommend splitting into:**
-- ConnectionProvider (~500 LOC)
-- PlayerManager (~800 LOC)
-- LibraryProvider (~1000 LOC)
-- LocalPlaybackManager (~600 LOC)
-
-### 5.2 Oversized Widget Files
-- [ ] `expandable_player.dart` - 2,485 lines (should be <500)
-- [ ] `global_player_overlay.dart` - 737 lines
-- [ ] `new_library_screen.dart` - 2,521 lines
-
-### 5.3 Global Key Anti-Pattern
-Audit `/lib/widgets/global_player_overlay.dart`:
-- [ ] `globalPlayerKey` for state access
-- [ ] `_overlayStateKey` for overlay state
-- [ ] Should use Provider/context instead
-
-### 5.4 Primitive Obsession
-- [ ] View modes as strings ('grid2', 'grid3', 'list')
-- [ ] Media types as strings ('track', 'album', 'artist')
-- [ ] Should be strongly-typed enums
-
----
-
-## SECTION 6: CODE QUALITY ISSUES
-
-### 6.1 Testing (CRITICAL)
-- [ ] **ZERO test files exist** - confirm this
-- [ ] No unit tests, widget tests, or integration tests
-- [ ] flutter_test dependency exists but unused
-
-### 6.2 Hardcoded Values
-Find and document all:
-- [ ] Color hex codes (50+ instances of `Color(0xFF...`)
-- [ ] Duration values not using `Timings` constants
-- [ ] Magic numbers (16, 4, 5, 100, 50)
-- [ ] String literals for media types
-
-### 6.3 Mixed Async Patterns
-- [ ] `.then()` chains alongside async/await
-- [ ] `.whenComplete()` usage
-- [ ] Consolidate to async/await
-
-### 6.4 Dead Code
-- [ ] `@Deprecated` methods still implemented
-- [ ] `animation_debugger.dart` - dev-only?
-- [ ] Unused imports
-
-### 6.5 TODO Comments
-Document all actionable TODOs:
-- [ ] `queue_screen.dart:214` - queue item removal
-- [ ] `audiobook_detail_screen.dart:261,312` - progress sync
-- [ ] `music_assistant_provider.dart:793,799` - playlist modification
-
----
-
-## SECTION 7: UI/UX AUDIT
-
-### 7.1 Accessibility (CRITICAL)
-Audit for missing:
-- [ ] `Semantics` widgets on interactive elements
-- [ ] `Tooltip` on icon buttons
-- [ ] Screen reader support
-- [ ] Touch target sizes (minimum 48dp)
-- [ ] Color contrast validation (WCAG AA)
-
-### 7.2 Performance Issues
-Audit `/lib/widgets/expandable_player.dart`:
-- [ ] No `RepaintBoundary` wrappers
-- [ ] 55+ `setState()` calls
-- [ ] 3 AnimationControllers with multiple listeners
-- [ ] Title height cache invalidation (lines 118+)
-
-### 7.3 Double Opacity Bug
-Audit `/lib/widgets/player/player_controls.dart`:
-```dart
-color: (shuffle == true ? primaryColor : textColor.withOpacity(0.5))
-    .withOpacity(expandedElementsOpacity),
-```
-- [ ] Double `.withOpacity()` application
-
-### 7.4 Missing Features
-- [ ] No landscape orientation support
-- [ ] No tablet layout optimization
-- [ ] No loading skeleton animations
-- [ ] No haptic feedback (except one location)
-
----
-
-## SECTION 8: AUDIO PLAYBACK AUDIT
-
-### 8.1 Position Interpolation
-Audit `/lib/services/position_tracker.dart`:
-- [ ] No timeout on anchor updates - unbounded drift possible
-- [ ] Duration interpolation can exceed track duration
-- [ ] Stale timestamp handling (>30 seconds)
-
-### 8.2 Sendspin Protocol
-Audit `/lib/services/sendspin_service.dart`:
-- [ ] Proxy auth retry without deduplication (lines 188-209)
-- [ ] WebSocket binary frame parsing
-- [ ] Clock synchronization accuracy
-
-### 8.3 Audio Resource Cleanup
-Audit `/lib/services/audio/massiv_audio_handler.dart`:
-- [ ] Audio session interrupt listeners not disposed
-- [ ] Audio focus not explicitly released
-
-### 8.4 Mixed Playback Modes
-- [ ] just_audio initialized but unused during Sendspin
-- [ ] Resource allocation for unused player
-- [ ] Potential audio focus conflicts
-
----
-
-## SECTION 9: NETWORKING AUDIT
-
-### 9.1 WebSocket Lifecycle
-Audit `/lib/services/music_assistant_api.dart`:
-- [ ] Heartbeat interval (30s) - appropriate?
-- [ ] Reconnection logic and timing
-- [ ] Pending request cleanup on disconnect
-
-### 9.2 Caching Strategy
-- [ ] No incremental/delta sync (full library every 5 minutes)
-- [ ] Cache staleness not communicated to UI
-- [ ] No query result pagination (fetches up to 5000 items)
-
-### 9.3 Rate Limiting
-- [ ] No client-side rate limiting
-- [ ] Search requests not throttled
-- [ ] Could overload server
-
-### 9.4 Offline Support
-Audit `/lib/services/offline_action_queue.dart`:
-- [ ] Queue execution not atomic (lines 118-130)
-- [ ] Action could execute twice on crash
-- [ ] Queue stored unencrypted
-
----
-
-## SECTION 10: DATABASE AUDIT
-
-### 10.1 Schema Review
-Audit `/lib/database/database.dart`:
-- [ ] Table indexes for query performance
-- [ ] Foreign key constraints
-- [ ] Migration strategy
-
-### 10.2 Query Patterns
-- [ ] N+1 query prevention
-- [ ] Transaction usage for atomic operations
-- [ ] Connection pooling
-
-### 10.3 Data Consistency
-- [ ] Tier 1 (DB) vs Tier 2 (API sync) race conditions
-- [ ] User modifications during background sync
-- [ ] Conflict resolution strategy
-
----
-
-## Deliverables
-
-After completing the audit, provide:
-
-### 1. Executive Summary
-- Overall code quality score (1-10)
-- Top 5 critical issues requiring immediate attention
-- Estimated technical debt in developer-hours
-
-### 2. Issue Tracker
-Create a prioritized list of all issues found:
-| ID | Severity | Category | File:Line | Description | Effort |
-|----|----------|----------|-----------|-------------|--------|
-
-### 3. Recommended Roadmap
-Sprint-based plan to address findings:
-- Sprint 1 (Immediate): Security fixes, silent exception handlers
-- Sprint 2-3: God class decomposition, test infrastructure
-- Sprint 4-6: Memory leak fixes, accessibility
-- Long-term: Performance optimization, monitoring
-
-### 4. Code Examples
-For each CRITICAL and HIGH severity issue, provide:
-- Current problematic code
-- Recommended refactored code
-- Migration steps
-
----
-
-## Files to Prioritize
-
-Start your audit with these critical files:
-
-1. `/lib/providers/music_assistant_provider.dart` (4,469 LOC) - God class
-2. `/lib/services/settings_service.dart` - Credential storage
-3. `/lib/services/music_assistant_api.dart` (2,929 LOC) - Networking
-4. `/lib/widgets/expandable_player.dart` (2,485 LOC) - UI complexity
-5. `/lib/services/auth/` directory - Security
-6. `/lib/models/player.dart` - Memory leaks
-7. `/lib/services/cache_service.dart` - Unbounded caches
-8. `/lib/services/position_tracker.dart` - Audio sync issues
-
----
-
-## Known Critical Issues (Pre-Identified)
-
-These issues have been identified and MUST be verified and documented:
-
-1. **CRITICAL: Plaintext credential storage** - SharedPreferences without encryption
-2. **CRITICAL: Zero test coverage** - No unit, widget, or integration tests
-3. **CRITICAL: 4,469 line god class** - MusicAssistantProvider violates SRP
-4. **CRITICAL: Silent exception handlers** - `catch (e) {}` patterns
-5. **HIGH: Static memory leak** - `_playerCreationTimes` unbounded growth
-6. **HIGH: Race conditions** - Player state polling vs events
-7. **HIGH: No accessibility** - Missing Semantics, screen reader support
-8. **HIGH: Certificate validation disabled** - MITM vulnerability for local IPs
-9. **MEDIUM: Double opacity bug** - `.withOpacity().withOpacity()` in player controls
-10. **MEDIUM: Position tracker drift** - No timeout on anchor updates
-
----
-
-## Audit Execution Notes
-
-- Use `Grep` tool to search for patterns across the codebase
-- Use `Read` tool to examine specific file sections
-- Document line numbers for all findings
-- Provide code snippets for context
-- Cross-reference related issues across files
-- Verify pre-identified issues exist and document their exact locations
-
-**Total estimated audit time: 4-6 hours for thorough coverage**

AUDIT-REPORT.md

@@ -1,419 +0,0 @@
-# Ensemble Codebase - Comprehensive Audit Report
-
-**Audit Date:** 2026-01-01
-**Codebase:** Ensemble Flutter App (Music Assistant Client)
-**Version:** 2.7.3-beta+35
-**Total Lines of Code:** ~40,583 Dart
-**Files Analyzed:** 90 Dart files
-
----
-
-## Executive Summary
-
-### Overall Code Quality Score: 5.5/10
-
-The Ensemble codebase demonstrates **strong architectural foundations** with a well-organized service layer, effective caching strategies, and sophisticated audio handling. However, the audit revealed **critical security vulnerabilities**, **zero test coverage**, and significant **technical debt** that must be addressed before production release.
-
-### Critical Statistics
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| Test Coverage | 0% | CRITICAL |
-| God Class Size | 4,469 LOC | CRITICAL |
-| Silent Exception Handlers | 7 | CRITICAL |
-| Plaintext Credentials | 4 locations | CRITICAL |
-| Memory Leak Locations | 6 | HIGH |
-| Race Conditions | 4 | HIGH |
-| Accessibility (Semantics) | 0 widgets | CRITICAL |
-
----
-
-## Issue Summary by Severity
-
-| Severity | Count | Categories |
-|----------|-------|------------|
-| **CRITICAL** | 12 | Security, Testing, Architecture, Accessibility |
-| **HIGH** | 18 | Memory, Race Conditions, Networking, Audio |
-| **MEDIUM** | 22 | Error Handling, UI, Caching, Code Quality |
-| **LOW** | 14 | Naming, Documentation, Minor Improvements |
-
----
-
-## CRITICAL ISSUES (Immediate Action Required)
-
-### 1. Plaintext Credential Storage
-**File:** `/lib/services/settings_service.dart`
-**Lines:** 131-143, 147-159, 169-190, 209-222
-
-Passwords and auth tokens stored in SharedPreferences without encryption.
-
-```dart
-// VULNERABLE CODE
-static Future<void> setPassword(String? password) async {
-  final prefs = await SharedPreferences.getInstance();
-  await prefs.setString(_keyPassword, password);  // PLAINTEXT!
-}
-```
-
-**Fix:** Use `flutter_secure_storage` for all sensitive data.
-
----
-
-### 2. Zero Test Coverage
-**Location:** Entire codebase
-
-No unit tests, widget tests, or integration tests exist. The `flutter_test` dependency is unused.
-
-**Impact:** Cannot safely refactor, high regression risk, no confidence in correctness.
-
-**Fix:** Establish test infrastructure immediately. Start with:
-- Unit tests for `MusicAssistantAPI`, `CacheService`, `ErrorHandler`
-- Widget tests for player controls
-- Integration tests for playback flows
-
----
-
-### 3. God Class - MusicAssistantProvider
-**File:** `/lib/providers/music_assistant_provider.dart`
-**Size:** 4,469 lines, ~140 methods, 744 conditional branches
-
-Single class handles: connection, players, library, cache, audio, sync, offline queue.
-
-**Fix:** Split into:
-- `ConnectionManager` (~500 LOC)
-- `PlayerManager` (~800 LOC)
-- `LibraryCacheService` (~600 LOC)
-- `SendspinManager` (~400 LOC)
-- `MusicAssistantProvider` - Facade composing above (~800 LOC)
-
----
-
-### 4. Zero Accessibility Support
-**Files:** `/lib/widgets/`, `/lib/screens/` (all)
-
-- **0** `Semantics` widgets
-- **0** `semanticLabel` properties
-- **1** `Tooltip` (entire app)
-- Screen readers cannot navigate the app
-
-**Fix:** Add Semantics to all interactive elements:
-```dart
-Semantics(
-  button: true,
-  label: isPlaying ? 'Pause playback' : 'Play',
-  child: IconButton(...)
-)
-```
-
----
-
-### 5. Silent Exception Handlers
-**Locations:** 7 instances across codebase
-
-| File | Line | Code |
-|------|------|------|
-| player_provider.dart | 567, 575, 584 | `catch (e) {}` |
-| music_assistant_provider.dart | 2690 | `catch (e) {}` |
-| music_assistant_api.dart | 2542 | `catch (e) {}` |
-| recently_played_service.dart | 154, 206 | `catch (_) {}` |
-
-**Fix:** Add logging or use `firstWhereOrNull` instead of try/catch around `firstWhere`.
-
----
-
-### 6. Audio Session Listeners Not Disposed
-**File:** `/lib/services/audio/massiv_audio_handler.dart`
-**Lines:** 45-73
-
-Stream subscriptions created but never cancelled - causes memory leaks and zombie listeners.
-
-**Fix:** Store subscriptions and cancel in dispose():
-```dart
-StreamSubscription? _interruptionSubscription;
-_interruptionSubscription = session.interruptionEventStream.listen(...);
-
-void dispose() {
-  _interruptionSubscription?.cancel();
-}
-```
-
----
-
-## HIGH SEVERITY ISSUES
-
-### 7. Connection State Subscription Not Stored
-**File:** `/lib/providers/music_assistant_provider.dart:575-614`
-
-The `connectionState.listen()` return value is not stored - causes listener accumulation on reconnect.
-
----
-
-### 8. Player State Race Condition
-**File:** `/lib/providers/music_assistant_provider.dart`
-
-Timer polling (every 5s) and WebSocket events can race to update `_selectedPlayer` and `_currentTrack` without mutex protection.
-
----
-
-### 9. Async Method Reentrancy
-**File:** `/lib/providers/music_assistant_provider.dart:2713-2841`
-
-`selectPlayer()` is `void async` with no guard against concurrent calls. Multiple rapid player switches can interleave.
-
----
-
-### 10. Unbounded Search Cache
-**File:** `/lib/services/cache_service.dart:31-32`
-
-`_searchCache` map has no size limit or proactive TTL eviction. Grows indefinitely with user searches.
-
----
-
-### 11. Static Memory Leak
-**File:** `/lib/models/player.dart:96, 139-144`
-
-`_playerCreationTimes` static map cleanup only removes 50 of 100+ entries, allowing unbounded growth.
-
----
-
-### 12. No Database Indexes
-**File:** `/lib/database/database.dart`
-
-No secondary indexes defined. Query performance degrades as database grows.
-
----
-
-### 13. No Incremental Sync
-**File:** `/lib/services/sync_service.dart:150-165`
-
-Full library fetch (up to 4000 items) on every sync instead of delta updates.
-
----
-
-### 14. Offline Queue Not Atomic
-**File:** `/lib/services/offline_action_queue.dart:80-108`
-
-Queue persistence happens after all processing - crash during processing loses successful actions.
-
----
-
-### 15. Auth Retry Without Deduplication
-**File:** `/lib/services/sendspin_service.dart:189-209`
-
-Multiple auth messages can be sent during rapid reconnection attempts.
-
----
-
-### 16. Pending Requests Not Completed on Disconnect
-**File:** `/lib/services/music_assistant_api.dart:2911`
-
-`_pendingRequests.clear()` abandons Completers without completing them with errors.
-
----
-
-### 17. HTTP Fallback for Local IPs
-**File:** `/lib/services/auth/auth_manager.dart:51-58`
-
-HTTPS failures silently fall back to HTTP on local networks - MITM vulnerability.
-
----
-
-### 18. Certificate Validation Bypassed
-**File:** `/lib/services/auth/auth_manager.dart:210-236`
-
-HTTPS redirects explicitly refused for local IPs due to expected certificate failures.
-
----
-
-## MEDIUM SEVERITY ISSUES
-
-### 19. Double Opacity Bug
-**File:** `/lib/widgets/player/player_controls.dart:62-63, 99-100`
-
-```dart
-// BUG: .withOpacity(0.5).withOpacity(expandedElementsOpacity) compounds opacity
-color: (shuffle == true ? primaryColor : textColor.withOpacity(0.5))
-    .withOpacity(expandedElementsOpacity),
-```
-
----
-
-### 20. Mixed Async Patterns
-**Locations:** 13 instances
-
-`.then()` chains mixed with `async/await` throughout the codebase.
-
----
-
-### 21. Hardcoded Colors
-**Locations:** 55 instances
-
-`Color(0xFF604CEC)`, `Color(0xFF1a1a1a)` scattered across theme files and widgets.
-
----
-
-### 22. View Modes as Strings
-**Locations:** 80+ instances
-
-`'grid2'`, `'grid3'`, `'list'` should be enums.
-
----
-
-### 23. Fire-and-Forget Pause Commands
-**File:** `/lib/providers/music_assistant_provider.dart:3875-3894`
-
-Server pause command uses `unawaited()` - errors are silently lost.
-
----
-
-### 24. Position Tracker Anchor Timeout Missing
-**File:** `/lib/services/position_tracker.dart:24-26`
-
-No timeout on stale anchor - interpolation can drift indefinitely.
-
----
-
-### 25. PCM Buffer No Overflow Protection
-**File:** `/lib/services/pcm_audio_player.dart:68, 236-247`
-
-Audio buffer grows unbounded if data arrives faster than consumption.
-
----
-
-### 26. No Client-Side Rate Limiting
-**Location:** App-wide
-
-No throttling on API requests during rapid user interactions.
-
----
-
-### 27. Portrait-Only Lock
-**File:** `/lib/main.dart:64-68`
-
-No landscape orientation support.
-
----
-
-### 28. Touch Targets Below 48dp
-**Files:** player_controls.dart, queue_panel.dart, player_card.dart
-
-Multiple buttons at 28x28 and 44x44 instead of minimum 48x48.
-
----
-
-### 29. WCAG Contrast Not Validated
-**File:** `/lib/theme/palette_helper.dart`
-
-Uses 0.4 threshold instead of proper WCAG 4.5:1 contrast ratio calculation.
-
----
-
-### 30. StreamControllers Not Closed
-**File:** `/lib/services/hardware_volume_service.dart:18-19, 74-85`
-
-`_volumeUpController` and `_volumeDownController` never closed in dispose().
-
----
-
-## LOW SEVERITY ISSUES
-
-### 31-34. Naming Inconsistencies
-Mixed patterns: `_isLoading` vs `_isLoadingPlaylists`, various cache variable names.
-
-### 35-38. Missing TODO Implementations
-6 actionable TODOs identified (queue removal, audiobook progress sync, playlist modification).
-
-### 39-42. Dead/Unused Code
-- `@Deprecated` methods still implemented
-- `library_stats.dart` appears unused
-- `animation_debugger.dart` disabled by default
-
-### 43-44. Minor Documentation Gaps
-Missing method documentation, no architecture diagram.
-
----
-
-## Recommended Remediation Roadmap
-
-### Sprint 1 (Week 1-2): Security & Critical Fixes
-1. Migrate credentials to `flutter_secure_storage`
-2. Add logging to all silent catch blocks
-3. Store connection state subscription
-4. Fix audio session listener disposal
-5. Add basic test infrastructure (10% coverage target)
-
-### Sprint 2 (Week 3-4): Memory & Race Conditions
-6. Add mutex to player state updates
-7. Add reentrancy guard to `selectPlayer()`
-8. Implement bounded caches with LRU eviction
-9. Fix static memory leak in Player model
-10. Store and cancel all stream subscriptions
-
-### Sprint 3 (Week 5-6): Architecture Refactoring
-11. Split `MusicAssistantProvider` into 5 smaller classes
-12. Split `expandable_player.dart` into component widgets
-13. Replace GlobalKey anti-patterns with Provider
-14. Convert string constants to enums
-15. Extract hardcoded colors to constants file
-
-### Sprint 4 (Week 7-8): Accessibility & UI
-16. Add Semantics to all interactive elements
-17. Increase touch targets to 48dp minimum
-18. Implement WCAG contrast validation
-19. Fix double opacity bug
-20. Add landscape orientation support
-
-### Sprint 5 (Week 9-10): Performance & Polish
-21. Add database indexes
-22. Implement incremental sync
-23. Add client-side rate limiting
-24. Fix atomic offline queue processing
-25. Achieve 30% test coverage target
-
----
-
-## Files Requiring Most Attention
-
-| File | LOC | Issues | Priority |
-|------|-----|--------|----------|
-| `music_assistant_provider.dart` | 4,469 | 12 | CRITICAL |
-| `settings_service.dart` | 811 | 4 | CRITICAL |
-| `expandable_player.dart` | 2,485 | 6 | HIGH |
-| `music_assistant_api.dart` | 2,929 | 5 | HIGH |
-| `cache_service.dart` | 370 | 4 | HIGH |
-| `massiv_audio_handler.dart` | 296 | 2 | CRITICAL |
-| `player.dart` | 422 | 2 | HIGH |
-| `auth_manager.dart` | 300 | 3 | HIGH |
-
----
-
-## Estimated Technical Debt
-
-| Category | Effort (Dev-Days) |
-|----------|-------------------|
-| Security Fixes | 3-5 |
-| Test Infrastructure | 10-15 |
-| Architecture Refactoring | 15-20 |
-| Memory Leak Fixes | 3-5 |
-| Accessibility | 5-8 |
-| UI/UX Polish | 3-5 |
-| Performance | 5-8 |
-| **Total** | **44-66 dev-days** |
-
----
-
-## Conclusion
-
-The Ensemble app has a solid foundation with well-designed patterns for caching, audio handling, and multi-device synchronization. However, **critical security vulnerabilities** (plaintext credentials), **zero test coverage**, and a **4,469-line god class** represent significant risks that must be addressed before any production deployment.
-
-The most urgent priorities are:
-1. **Secure credential storage** - immediate security risk
-2. **Add test infrastructure** - enables safe refactoring
-3. **Split the god class** - enables maintainability
-4. **Add accessibility** - legal/compliance requirement
-
-With focused effort over 8-10 weeks, the codebase can be brought to production-quality standards.
-
----
-
-*Audit conducted using 6 parallel specialized sub-agents analyzing security, memory management, race conditions, architecture, UI/UX, and audio/networking.*

AUDIT_PROMPT.md

@@ -1,119 +0,0 @@
-# Ensemble Codebase Audit Prompt
-
-Run this prompt with Claude Code to perform a comprehensive audit of the Ensemble Flutter app.
-
----
-
-## Prompt
-
-You are performing a comprehensive code audit on the Ensemble Flutter app. This is a music/audiobook/podcast player app with 93+ Dart files.
-
-**CRITICAL RULES:**
-1. DO NOT remove or break any existing functionality
-2. All changes must be on the current branch: `audit/code-quality-review`
-3. Run `flutter analyze` after each set of changes to verify no regressions
-4. Commit changes in logical, reviewable chunks
-
-**AUDIT PHASES:**
-
-### Phase 1: Code Quality Analysis (Read-Only)
-First, analyze the codebase without making changes. Create a report covering:
-
-1. **Large File Analysis** - Review these files for refactoring opportunities:
-   - `lib/screens/new_library_screen.dart` (122KB)
-   - `lib/screens/search_screen.dart` (129KB)
-   - `lib/widgets/expandable_player.dart` (107KB)
-   - `lib/screens/album_details_screen.dart` (48KB)
-   - `lib/screens/artist_details_screen.dart` (45KB)
-
-2. **Pattern Inconsistencies** - Look for:
-   - Inconsistent naming conventions (camelCase vs snake_case)
-   - Mixed widget composition patterns
-   - Inconsistent error handling approaches
-   - Duplicate code across screens/widgets
-
-3. **Performance Red Flags** - Identify:
-   - Unnecessary rebuilds (missing const constructors)
-   - Heavy computations in build methods
-   - Missing list item caching (ListView.builder vs ListView)
-   - Inefficient state management patterns
-
-4. **Scroll Performance Issues** - Specifically audit:
-   - ScrollController usage and disposal
-   - Sliver implementations
-   - AnimatedBuilder/AnimatedWidget usage
-   - Image loading in scrollable lists
-   - Any jank-inducing patterns
-
-### Phase 2: Quick Wins (Low Risk, High Impact)
-Apply these fixes first:
-
-1. Add missing `const` constructors throughout
-2. Fix any `flutter analyze` warnings
-3. Remove dead code and unused imports
-4. Standardize formatting with `dart format`
-
-### Phase 3: Scroll Animation Optimization
-Focus on smoother scrolling:
-
-1. **Image Optimization**
-   - Ensure CachedNetworkImage is used consistently
-   - Add appropriate cacheWidth/cacheHeight
-   - Implement proper placeholder/error widgets
-
-2. **List Performance**
-   - Convert any ListView to ListView.builder where appropriate
-   - Add itemExtent where possible for fixed-height items
-   - Implement AutomaticKeepAliveClientMixin where needed
-   - Consider RepaintBoundary for complex list items
-
-3. **Animation Smoothing**
-   - Use `Curves.easeOutCubic` or similar for scroll-linked animations
-   - Ensure animations run at 60fps (avoid heavy computations during animation)
-   - Review CustomScrollView/Sliver implementations
-
-### Phase 4: Code Consistency Improvements
-
-1. **Widget Extraction**
-   - Extract repeated UI patterns into reusable widgets
-   - Ensure extracted widgets follow existing naming patterns
-
-2. **State Management**
-   - Verify Provider usage is consistent
-   - Check for proper disposal of controllers/streams
-
-3. **Error Handling**
-   - Standardize try/catch patterns
-   - Ensure consistent loading/error state UI
-
-### Phase 5: Verification
-
-After all changes:
-1. Run `flutter analyze` - must pass with 0 issues
-2. Run `flutter test` if tests exist
-3. Create a summary of all changes made
-4. List any recommendations that were NOT implemented (too risky)
-
----
-
-## Execution Instructions
-
-```bash
-# Start the audit
-cd /home/home-server/Ensemble
-git checkout audit/code-quality-review
-
-# After each phase, commit your changes
-git add -A && git commit -m "Audit Phase X: [description]"
-
-# Verify no regressions
-flutter analyze
-```
-
----
-
-## Expected Deliverables
-
-1. `AUDIT_REPORT.md` - Findings from Phase 1
-2. Multiple commits with clear messages for each phase
-3. `AUDIT_SUMMARY.md` - Final summary of all changes and remaining recommendations

AUDIT_REPORT.md

@@ -1,257 +0,0 @@
-# Ensemble Codebase Audit Report
-
-**Date**: 2026-01-14
-**Scope**: Full codebase audit (104 Dart files, 18 screens)
-**Focus Areas**: UI Continuity, Performance, Logic/Best Practices
-
----
-
-## Executive Summary
-
-The Ensemble codebase is a **mature, feature-rich Flutter application** with many good patterns already in place. However, the audit identified **significant architectural debt** that should be addressed:
-
-| Severity | Count | Key Themes |
-|----------|-------|------------|
-| **Critical** | 6 | God classes (5,443 & 4,209 lines), design token adoption, startup blocking |
-| **High** | 15 | Touch targets, batch DB operations, over-notification, code duplication |
-| **Medium** | 25+ | Inconsistencies, memory issues, missing error boundaries |
-| **Low** | 15+ | Minor polish items |
-
-**Top 3 Priorities:**
-1. **Split `MusicAssistantProvider` (5,443 lines)** - God object handling everything
-2. **Split `new_library_screen.dart` (4,209 lines)** - 10 scroll controllers, 15+ view modes
-3. **Fix startup performance** - Sequential blocking ops could save 1-8 seconds
-
----
-
-## Critical Issues
-
-### 1. God Object: MusicAssistantProvider (5,443 lines)
-**File**: `lib/providers/music_assistant_provider.dart`
-- 54 `notifyListeners()` calls
-- 30+ state variables
-- 100+ public methods
-- Handles: connection, auth, players, library, search, caching, local playback, Sendspin
-- **Fix**: Split into ConnectionManager, PlayerStateManager, LibraryStateManager, SearchStateManager
-
-### 2. God Object: NewLibraryScreen (4,209 lines)
-**File**: `lib/screens/new_library_screen.dart`
-- 10 scroll controllers
-- 15+ view mode states
-- 15+ sort order states
-- Handles: Music, Books, Podcasts, Radio tabs
-- **Fix**: Extract to ArtistsTab, AlbumsTab, TracksTab, PlaylistsTab, BooksTab, PodcastsTab, RadioTab
-
-### 3. Sequential Blocking Startup (500-1500ms wasted)
-**File**: `lib/main.dart:33-66`
-```dart
-await DatabaseService.instance.initialize();
-await ProfileService.instance.migrateFromOwnerName();
-await SettingsService.migrateToSecureStorage();
-await SyncService.instance.loadFromCache();
-audioHandler = await AudioService.init(...);
-```
-- **Fix**: Parallelize with `Future.wait()`, defer AudioService to post-first-frame
-
-### 4. Design Tokens Exist But Unused
-**File**: `lib/theme/design_tokens.dart`
-- `Spacing.*` used in only ~6 of 34+ widget files
-- `Radii.*` used in only ~5 files
-- `IconSizes.*` used in only ~4 files
-- **Fix**: Systematic replacement of hardcoded values
-
-### 5. Touch Targets Too Small (32x32)
-**File**: `lib/screens/new_library_screen.dart:1805-1867`
-- Sort, favorites, view mode buttons are 32x32
-- Material Design minimum: 48x48
-- **Fix**: Increase to 48x48 or add padding for hit area
-
-### 6. No Batch Database Inserts
-**File**: `lib/services/sync_service.dart:212-273`
-- 1000 albums = 1000 separate DB transactions
-- **Fix**: Wrap in single transaction or use Drift batch insert
-
----
-
-## High Severity Issues
-
-### Performance
-| Issue | File | Impact |
-|-------|------|--------|
-| `context.watch()` in nested tabs | new_library_screen.dart:2960 | All tabs rebuild on any provider change |
-| Consumer wrapping 800-line player | expandable_player.dart:1234 | Full rebuild on every state change |
-| Inline sorting during build | new_library_screen.dart:3647 | 5-20ms for 1000+ albums |
-| Multiple setState for author images | new_library_screen.dart:1017 | 20+ rebuilds as images load |
-| SecureStorage migration every startup | secure_storage_service.dart:103 | 100-300ms wasted |
-
-### Architecture
-| Issue | File | Impact |
-|-------|------|--------|
-| State duplication across 4 providers | providers/*.dart | Maintenance burden, sync issues |
-| 8 duplicate `_cycle*ViewMode()` methods | new_library_screen.dart:251-402 | DRY violation |
-| 60+ duplicate getter/setter pairs | settings_service.dart:500-1000 | Code bloat |
-| Global singleton NavigationProvider | navigation_provider.dart:40 | Untestable |
-| CacheService duplicated in providers | Multiple | Memory waste, inconsistency |
-
-### UI/UX
-| Issue | File | Impact |
-|-------|------|--------|
-| Hardcoded bottom spacing (140, 164, 100) | Multiple detail screens | Content obscured by player |
-| Inconsistent button sizes (44 vs 50) | Multiple screens | Visual disharmony |
-| No debounce on card taps | album_card.dart:118 | Double navigation possible |
-| Missing PopScope on AudiobookSeriesScreen | audiobook_series_screen.dart:276 | Adaptive colors not cleared |
-
-### Error Handling
-| Issue | File | Impact |
-|-------|------|--------|
-| No Flutter error boundaries | main.dart | Red error screen on build failure |
-| API returns empty list on error | music_assistant_api.dart | Can't distinguish error from empty |
-
----
-
-## Medium Severity Issues
-
-### Performance
-- PaletteGenerator on main isolate (10-30ms blocking)
-- Multiple `SharedPreferences.getInstance()` calls (132 occurrences)
-- AppStartup polling loop with fixed 250ms delay
-- SystemThemeHelper FutureBuilder recreated on every build
-
-### UI Consistency
-- Border radius varies: 8, 12, 20, 22, 25 for same element types
-- `SizedBox(height: 8)` appears 40+ times instead of `Spacing.vGap8`
-- Hardcoded colors for status (Colors.red, Colors.green)
-- Inconsistent icon sizes across screens
-
-### State Management
-- Over-notification (multiple notifyListeners in single methods)
-- Wide Consumer scope (watch instead of select)
-- Missing dispose() in some providers
-- Inconsistent async state handling (loading/error)
-
-### Navigation
-- `isQueuePanelOpen` vs `isQueuePanelTargetOpen` inconsistency
-- `popToHome()` doesn't clear adaptive colors
-- Infinite navigation loop possible (Album → Artist → Album)
-- Orphaned Hero animations in podcast_card, radio_station_card
-
-### Data/Caching
-- Unbounded `_podcastCoverCache`
-- SyncService listener not removed on error
-- Redundant API calls between providers
-- Fire-and-forget persistence race condition
-
-### Error Handling
-- No zone error handler for async exceptions
-- `retryCritical()` retries all errors including non-recoverable
-- No user notification of offline queue status
-- DisconnectedState not used consistently
-
----
-
-## Quick Wins (High Impact, Low Effort)
-
-| # | Task | File(s) | Effort |
-|---|------|---------|--------|
-| 1 | Replace hardcoded bottom spacing with `BottomSpacing.withMiniPlayer` | Detail screens | 30 min |
-| 2 | Add navigation debounce to card widgets | album_card, artist_card, etc. | 1 hr |
-| 3 | Fix touch targets to 48x48 minimum | new_library_screen.dart | 15 min |
-| 4 | Add migration skip flag for SecureStorage | secure_storage_service.dart | 30 min |
-| 5 | Add Flutter error boundary | main.dart | 30 min |
-| 6 | Use `context.select()` instead of `context.watch()` | global_player_overlay, etc. | 2 hr |
-| 7 | Cache `SharedPreferences.getInstance()` | settings_service.dart | 30 min |
-
----
-
-## Refactoring Roadmap
-
-### Phase 1: Quick Wins (1-2 days)
-- Fix touch targets
-- Fix bottom spacing
-- Add navigation debounce
-- Add error boundaries
-- Cache SharedPreferences singleton
-
-### Phase 2: Performance (3-5 days)
-- Parallelize startup operations
-- Replace `context.watch()` with `context.select()`
-- Batch database inserts
-- Add SecureStorage migration skip flag
-- Fix over-notification in provider
-
-### Phase 3: Design System (1 week)
-- Systematic design token adoption
-- Standardize button sizes (44 vs 50)
-- Standardize border radius values
-- Create StatusColors semantic tokens
-- Replace all magic numbers
-
-### Phase 4: Architecture (2-3 weeks)
-- ~~Split MusicAssistantProvider into focused managers~~ **DEFERRED** - MusicAssistantProvider has evolved with Sendspin, Cast-Sendspin ID mapping, position tracker integration. Splitting would require ~1600 lines of sync work. Code is working and tested.
-- ~~Split new_library_screen into tab widgets~~ **DEFERRED** - Tabs have tight state coupling (15+ view modes, 15+ sort orders, 10 scroll controllers). Extraction would require InheritedWidget/callbacks for all shared state. Risk outweighs benefit.
-- ✅ Extract generic helpers for SettingsService - Reduced from 1,031 to 874 lines (~15%)
-- ✅ Remove/integrate unused providers - Deleted PlayerProvider (964 lines), LibraryProvider, ConnectionProvider (651 lines total)
-- ~~Split music_assistant_api.dart by domain~~ **DEFERRED** - All methods share WebSocket connection and auth state. Clean extraction would require connection manager abstraction.
-
----
-
-## Positive Findings
-
-The codebase already demonstrates many good practices:
-
-- **Performance awareness**: `// PERF:` comments, RepaintBoundary (55 occurrences), image caching (80 memCacheWidth/Height)
-- **Caching**: Multi-tier caching with LRU eviction, proper TTLs, proper DB indexes
-- **Error handling**: DebugLogger, RetryHelper, OfflineActionQueue well-implemented
-- **Theme system**: Material You support, adaptive colors from album art
-- **Offline support**: Cache-first loading, graceful degradation
-- **Navigation**: Consistent FadeSlidePageRoute, proper Hero animations (mostly)
-
----
-
-## Files by Priority
-
-| Priority | File | Lines | Key Issues |
-|----------|------|-------|------------|
-| 1 | music_assistant_provider.dart | 5,443 | God object, over-notification |
-| 2 | new_library_screen.dart | 4,209 | God class, performance, touch targets |
-| 3 | main.dart | 549 | Startup blocking, error boundaries |
-| 4 | music_assistant_api.dart | 3,434 | Silent failures, needs splitting |
-| 5 | settings_service.dart | 1,019 | Code duplication, no caching |
-| 6 | expandable_player.dart | ~800 | Wide Consumer scope |
-| 7 | global_player_overlay.dart | ~500 | BottomSpacing source, Consumer scope |
-| 8 | All detail screens | Various | Hardcoded bottom spacing |
-| 9 | All card widgets | Various | Navigation debounce, design tokens |
-
----
-
-## Audit Methodology
-
-This audit was conducted using 9 parallel sub-agents analyzing:
-
-**UI Continuity (3 agents)**
-1. Navigation & Flow - back button, Hero animations, tab preservation
-2. Visual Consistency - design tokens, spacing, typography
-3. Component Placement - touch targets, bottom spacing, modals
-
-**Performance (3 agents)**
-4. Rendering Performance - ListView.builder, const, rebuilds
-5. Data & Caching - streams, invalidation, memory bounds
-6. Startup & Load Time - blocking operations, initialization order
-
-**Logic/Best Practices (3 agents)**
-7. State Management - Provider patterns, notification frequency
-8. Error Handling - try-catch, boundaries, resilience
-9. Code Quality - file size, duplication, SOLID principles
-
----
-
-## Conclusion
-
-The Ensemble app is well-architected at the macro level but has accumulated technical debt in its largest files. The most impactful improvements would be:
-
-1. **Splitting the two 4,000+ line files** into focused components
-2. **Adopting design tokens systematically** for visual consistency
-3. **Optimizing startup sequence** for faster app launch
-4. **Using granular state management** (select vs watch) for better performance
-
-The quick wins section provides immediate value with minimal risk, while the roadmap offers a path to sustainable improvement.

AUDIT_SUMMARY.md

@@ -1,57 +0,0 @@
-# Audit Summary
-
-**Branch:** `audit/code-quality-review`
-**Date:** January 4, 2026
-
-## Changes Applied
-
-### Phase 1: Analysis Complete
-- Created `AUDIT_REPORT.md` with comprehensive findings
-- 4 parallel subagents analyzed const constructors, scroll performance, code duplication, and dead code
-
-### Phase 2: Deprecated API Fixes (18 files)
-- Replaced all `colorScheme.background` with `colorScheme.surface` (Material 3 compliance)
-
-**Files modified:**
-- lib/screens/library_artists_screen.dart
-- lib/screens/library_albums_screen.dart
-- lib/screens/library_playlists_screen.dart
-- lib/screens/library_tracks_screen.dart
-- lib/screens/artist_details_screen.dart
-- lib/screens/new_home_screen.dart
-- lib/screens/login_screen.dart
-- lib/screens/settings_screen.dart
-- lib/screens/album_details_screen.dart
-- lib/screens/search_screen.dart
-- lib/screens/new_library_screen.dart
-
-### Phase 3: Scroll Performance Optimization
-- Added `memCacheWidth` and `memCacheHeight` to CachedNetworkImage instances
-
-**lib/screens/new_library_screen.dart:**
-- Line 1400-1401: Author list tile image (128x128 cache)
-- Line 1487-1488: Author grid card image (256x256 cache)
-- Line 1577-1578: Audiobook list tile cover (256x256 cache)
-- Line 1749-1750: Audiobook grid cover (512x512 cache)
-- Line 1970-1971: Series list tile cover (256x256 cache)
-- Line 2986-2987: Album list tile cover (256x256 cache)
-
-## Recommendations NOT Implemented (Low Priority)
-
-These were identified but NOT changed to preserve functionality:
-
-1. **View mode cycling refactor** - 8 similar functions could be consolidated
-2. **Color constant extraction** - Duplicated colors in 3 files
-3. **EdgeInsets.zero const** - 64 instances (build-time only, minimal impact)
-4. **BorderRadius.circular const** - 40+ instances
-
-## Verification
-
-Changes should be verified by:
-1. GitHub Actions build (triggered automatically)
-2. Manual UI testing of scroll smoothness
-3. Verify no visual regressions in dark/light themes
-
-## Build Trigger
-
-GitHub Actions workflow triggered on branch `audit/code-quality-review`

README.md

@@ -151,6 +151,12 @@ For access outside your home network, you'll need to expose Music Assistant thro
 - Android device (Android 5.0+)
 - Audiobookshelf provider configured in Music Assistant (for audiobook features)
 
+## Sponsors
+
+A huge thank you to my sponsors! 💖
+
+<a href="https://github.com/pcsokonay"><img src="https://github.com/pcsokonay.png" width="60px" alt="pcsokonay" /></a>
+
 ## License
 
 MIT License

android/app/src/main/kotlin/com/collotsspot/ensemble/MainActivity.kt

@@ -1,5 +1,11 @@
 package com.collotsspot.ensemble
 
+import android.content.Context
+import android.database.ContentObserver
+import android.media.AudioManager
+import android.os.Handler
+import android.os.Looper
+import android.provider.Settings
 import android.util.Log
 import android.view.KeyEvent
 import com.ryanheise.audioservice.AudioServiceActivity
@@ -14,10 +20,22 @@ class MainActivity: AudioServiceActivity() {
     private var methodChannel: MethodChannel? = null
     private var isListening = false
 
+    // Volume observer for lockscreen volume changes
+    // Watches system STREAM_MUSIC volume and mirrors changes to the MA player
+    // when a remote/group player is active
+    private var audioManager: AudioManager? = null
+    private var volumeObserver: VolumeContentObserver? = null
+    private var isObservingVolume = false
+    private var lastKnownVolume: Int = -1
+    // Guard flag to ignore volume changes triggered by our own setStreamVolume calls
+    private var ignoringVolumeChange = false
+
     override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
         super.configureFlutterEngine(flutterEngine)
         Log.d(TAG, "Configuring Flutter engine, setting up MethodChannel")
 
+        audioManager = getSystemService(Context.AUDIO_SERVICE) as AudioManager
+
         methodChannel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
         methodChannel?.setMethodCallHandler { call, result ->
             Log.d(TAG, "Received method call: ${call.method}")
@@ -32,6 +50,24 @@ class MainActivity: AudioServiceActivity() {
                     Log.d(TAG, "Volume listening DISABLED")
                     result.success(null)
                 }
+                "startVolumeObserver" -> {
+                    // Start observing system volume for lockscreen volume changes.
+                    // Optional: initialVolume (0-100) sets the system volume to match
+                    // the MA player's current volume for a consistent HUD display.
+                    val initialVolume = call.argument<Int>("initialVolume")
+                    startVolumeObserver(initialVolume)
+                    result.success(null)
+                }
+                "stopVolumeObserver" -> {
+                    stopVolumeObserver()
+                    result.success(null)
+                }
+                "syncSystemVolume" -> {
+                    // Sync system volume to match MA player volume (0-100)
+                    val volume = call.argument<Int>("volume") ?: 0
+                    syncSystemVolume(volume)
+                    result.success(null)
+                }
                 else -> {
                     Log.d(TAG, "Unknown method: ${call.method}")
                     result.notImplemented()
@@ -40,6 +76,82 @@ class MainActivity: AudioServiceActivity() {
         }
     }
 
+    /// Start observing system STREAM_MUSIC volume changes.
+    /// When a change is detected, sends an "absoluteVolumeChange" event to Flutter
+    /// with the new volume mapped to 0-100 scale.
+    private fun startVolumeObserver(initialVolume: Int?) {
+        if (isObservingVolume) return
+
+        val am = audioManager ?: return
+
+        // Optionally set system volume to match the MA player's current volume
+        if (initialVolume != null) {
+            syncSystemVolume(initialVolume)
+        }
+
+        lastKnownVolume = am.getStreamVolume(AudioManager.STREAM_MUSIC)
+
+        volumeObserver = VolumeContentObserver(Handler(Looper.getMainLooper()))
+        contentResolver.registerContentObserver(
+            Settings.System.CONTENT_URI,
+            true,
+            volumeObserver!!
+        )
+        isObservingVolume = true
+        Log.d(TAG, "Volume observer STARTED, initial system volume: $lastKnownVolume")
+    }
+
+    /// Stop observing system volume changes.
+    private fun stopVolumeObserver() {
+        if (!isObservingVolume) return
+
+        volumeObserver?.let {
+            contentResolver.unregisterContentObserver(it)
+        }
+        volumeObserver = null
+        isObservingVolume = false
+        Log.d(TAG, "Volume observer STOPPED")
+    }
+
+    /// Set the system STREAM_MUSIC volume to match an MA player volume (0-100).
+    /// Maps MA's 0-100 range to the device's 0-maxVolume range.
+    private fun syncSystemVolume(maVolume: Int) {
+        val am = audioManager ?: return
+        val maxSystemVolume = am.getStreamMaxVolume(AudioManager.STREAM_MUSIC)
+        val systemVolume = (maVolume * maxSystemVolume / 100).coerceIn(0, maxSystemVolume)
+
+        ignoringVolumeChange = true
+        am.setStreamVolume(AudioManager.STREAM_MUSIC, systemVolume, 0)
+        lastKnownVolume = systemVolume
+        ignoringVolumeChange = false
+        Log.d(TAG, "Synced system volume: MA $maVolume% -> system $systemVolume/$maxSystemVolume")
+    }
+
+    /// ContentObserver that watches for system volume changes.
+    /// When volume changes (e.g., from lockscreen hardware buttons),
+    /// maps the change to a 0-100 value and sends to Flutter.
+    inner class VolumeContentObserver(handler: Handler) : ContentObserver(handler) {
+        override fun onChange(selfChange: Boolean) {
+            super.onChange(selfChange)
+
+            if (ignoringVolumeChange) return
+
+            val am = audioManager ?: return
+            val currentVolume = am.getStreamVolume(AudioManager.STREAM_MUSIC)
+
+            if (currentVolume != lastKnownVolume) {
+                val maxVolume = am.getStreamMaxVolume(AudioManager.STREAM_MUSIC)
+                val maVolume = if (maxVolume > 0) (currentVolume * 100 / maxVolume) else 0
+
+                Log.d(TAG, "Volume observer: system $lastKnownVolume -> $currentVolume (MA: $maVolume%)")
+                lastKnownVolume = currentVolume
+
+                // Send the absolute volume (0-100) to Flutter
+                methodChannel?.invokeMethod("absoluteVolumeChange", maVolume)
+            }
+        }
+    }
+
     // Use dispatchKeyEvent instead of onKeyDown - Flutter's engine uses dispatchKeyEvent
     // and may consume events before they reach onKeyDown
     override fun dispatchKeyEvent(event: KeyEvent?): Boolean {
@@ -84,4 +196,34 @@ class MainActivity: AudioServiceActivity() {
             }
         }
     }
+
+    // Pause volume interception when app goes to background so hardware buttons
+    // only control the system volume (e.g., YouTube, phone ringer) as expected.
+    private var wasListeningBeforePause = false
+    private var wasObservingBeforePause = false
+
+    override fun onPause() {
+        wasListeningBeforePause = isListening
+        wasObservingBeforePause = isObservingVolume
+        isListening = false
+        stopVolumeObserver()
+        Log.d(TAG, "onPause: suspended volume interception (wasListening=$wasListeningBeforePause, wasObserving=$wasObservingBeforePause)")
+        super.onPause()
+    }
+
+    override fun onResume() {
+        super.onResume()
+        if (wasListeningBeforePause) {
+            isListening = true
+        }
+        if (wasObservingBeforePause) {
+            startVolumeObserver(null)
+        }
+        Log.d(TAG, "onResume: restored volume interception (listening=$isListening, observing=$isObservingVolume)")
+    }
+
+    override fun onDestroy() {
+        stopVolumeObserver()
+        super.onDestroy()
+    }
 }

android/build.gradle

@@ -2,9 +2,6 @@ buildscript {
     ext.kotlin_version = '2.1.0'
     repositories {
         google()
-        // Use Maven Central mirrors as fallback for 403 errors
-        maven { url 'https://maven.aliyun.com/repository/central' }
-        maven { url 'https://maven.aliyun.com/repository/google' }
         mavenCentral()
     }
 
@@ -17,9 +14,6 @@ buildscript {
 allprojects {
     repositories {
         google()
-        // Use Maven Central mirrors as fallback for 403 errors
-        maven { url 'https://maven.aliyun.com/repository/central' }
-        maven { url 'https://maven.aliyun.com/repository/google' }
         mavenCentral()
     }
 }

lib/main.dart

@@ -31,82 +31,85 @@ late MassivAudioHandler audioHandler;
 // Global debug logger instance
 final _logger = DebugLogger();
 
-Future<void> main() async {
-  WidgetsFlutterBinding.ensureInitialized();
-
-  // Initialize SharedPreferences cache early for performance
-  await SettingsService.initialize();
-  _logger.log('⚡ SharedPreferences cached');
-
-  // Initialize local database
-  await DatabaseService.instance.initialize();
-  _logger.log('💾 Database initialized');
-
-  // Migrate existing ownerName to profile (one-time for existing users)
-  await ProfileService.instance.migrateFromOwnerName();
-
-  // Migrate credentials to secure storage (one-time for existing users)
-  await SettingsService.migrateToSecureStorage();
-  _logger.log('🔐 Secure storage migration complete');
-
-  // Load library from cache for instant startup
-  await SyncService.instance.loadFromCache();
-  _logger.log('📦 Library cache loaded');
-
-  // Create auth manager for streaming headers
-  final authManager = AuthManager();
-
-  // 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,
-    DeviceOrientation.portraitDown,
-  ]);
-
-  // Set initial system UI overlay style based on platform brightness
-  // SystemUIWrapper will update this dynamically when theme changes
-  final platformBrightness = WidgetsBinding.instance.platformDispatcher.platformBrightness;
-  final isDark = platformBrightness == Brightness.dark;
-  SystemChrome.setSystemUIOverlayStyle(
-    SystemUiOverlayStyle(
-      statusBarColor: Colors.transparent,
-      statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
-      systemNavigationBarColor: isDark ? const Color(0xFF1a1a1a) : const Color(0xFFF5F5F5),
-      systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
-    ),
-  );
-
-  // Set up Flutter error boundary to catch and log widget build errors
-  FlutterError.onError = (FlutterErrorDetails details) {
-    _logger.error('Flutter error: ${details.exceptionAsString()}', context: 'FlutterError');
-    _logger.error('Stack trace:\n${details.stack}', context: 'FlutterError');
-    // Still report to Flutter's default handler in debug mode
-    FlutterError.presentError(details);
-  };
-
-  // Catch errors from the platform dispatcher (platform channel errors)
-  PlatformDispatcher.instance.onError = (error, stack) {
-    _logger.error('Platform error: $error', context: 'PlatformDispatcher');
-    _logger.error('Stack trace:\n$stack', context: 'PlatformDispatcher');
-    return true; // Handled
-  };
-
-  // Wrap app in zone to catch async errors
+void main() {
+  // All initialization must run inside the same zone as runApp() to avoid
+  // "Zone mismatch" errors from Flutter's binding system
   runZonedGuarded(
-    () => runApp(const MusicAssistantApp()),
+    () async {
+      WidgetsFlutterBinding.ensureInitialized();
+
+      // Initialize SharedPreferences cache early for performance
+      await SettingsService.initialize();
+      _logger.log('⚡ SharedPreferences cached');
+
+      // Initialize local database
+      await DatabaseService.instance.initialize();
+      _logger.log('💾 Database initialized');
+
+      // Migrate existing ownerName to profile (one-time for existing users)
+      await ProfileService.instance.migrateFromOwnerName();
+
+      // Migrate credentials to secure storage (one-time for existing users)
+      await SettingsService.migrateToSecureStorage();
+      _logger.log('🔐 Secure storage migration complete');
+
+      // Load library from cache for instant startup
+      await SyncService.instance.loadFromCache();
+      _logger.log('📦 Library cache loaded');
+
+      // Create auth manager for streaming headers
+      final authManager = AuthManager();
+
+      // 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,
+        DeviceOrientation.portraitDown,
+      ]);
+
+      // Set initial system UI overlay style based on platform brightness
+      // SystemUIWrapper will update this dynamically when theme changes
+      final platformBrightness = WidgetsBinding.instance.platformDispatcher.platformBrightness;
+      final isDark = platformBrightness == Brightness.dark;
+      SystemChrome.setSystemUIOverlayStyle(
+        SystemUiOverlayStyle(
+          statusBarColor: Colors.transparent,
+          statusBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+          systemNavigationBarColor: isDark ? const Color(0xFF1a1a1a) : const Color(0xFFF5F5F5),
+          systemNavigationBarIconBrightness: isDark ? Brightness.light : Brightness.dark,
+        ),
+      );
+
+      // Set up Flutter error boundary to catch and log widget build errors
+      FlutterError.onError = (FlutterErrorDetails details) {
+        _logger.error('Flutter error: ${details.exceptionAsString()}', context: 'FlutterError');
+        _logger.error('Stack trace:\n${details.stack}', context: 'FlutterError');
+        // Still report to Flutter's default handler in debug mode
+        FlutterError.presentError(details);
+      };
+
+      // Catch errors from the platform dispatcher (platform channel errors)
+      PlatformDispatcher.instance.onError = (error, stack) {
+        _logger.error('Platform error: $error', context: 'PlatformDispatcher');
+        _logger.error('Stack trace:\n$stack', context: 'PlatformDispatcher');
+        return true; // Handled
+      };
+
+      runApp(const MusicAssistantApp());
+    },
     (error, stackTrace) {
       _logger.error('Uncaught async error: $error', context: 'ZoneError');
       _logger.error('Stack trace:\n$stackTrace', context: 'ZoneError');
@@ -128,6 +131,7 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
   final _hardwareVolumeService = HardwareVolumeService();
   StreamSubscription? _volumeUpSub;
   StreamSubscription? _volumeDownSub;
+  StreamSubscription? _absoluteVolumeSub;
   String? _lastSelectedPlayerId;
   String? _builtinPlayerId;
 
@@ -158,6 +162,12 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
       _volumeDownSub = _hardwareVolumeService.onVolumeDown.listen((_) {
         _adjustVolume(-_volumeStep);
       });
+
+      // Listen for absolute volume changes from lockscreen/background
+      // (ContentObserver on system STREAM_MUSIC volume)
+      _absoluteVolumeSub = _hardwareVolumeService.onAbsoluteVolumeChange.listen((volume) {
+        _setAbsoluteVolume(volume);
+      });
     } catch (e, stack) {
       _logger.error('Hardware volume init failed', context: 'VolumeInit', error: e, stackTrace: stack);
     }
@@ -173,18 +183,41 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
   }
 
   /// Enable/disable volume button interception based on selected player.
+  /// Also manages the volume observer for lockscreen volume routing.
   Future<void> _updateVolumeInterception() async {
+    final player = _musicProvider.selectedPlayer;
     final isBuiltinPlayer = _builtinPlayerId != null &&
-        _musicProvider.selectedPlayer?.playerId == _builtinPlayerId;
+        player?.playerId == _builtinPlayerId;
     await _hardwareVolumeService.setIntercepting(!isBuiltinPlayer);
+
+    // Start/stop volume observer for lockscreen volume changes.
+    // When a remote/group player is active, observe system volume changes
+    // so lockscreen hardware buttons route to the MA player.
+    if (!isBuiltinPlayer && player != null) {
+      // Get the effective volume to sync the system volume HUD
+      final effectiveVolume = _musicProvider.groupVolumeManager.isGroupPlayer(player)
+          ? (_musicProvider.groupVolumeManager.getEffectiveVolumeLevel(
+                  player, _musicProvider.availablePlayersUnfiltered) ?? player.volume)
+          : player.volume;
+      await _hardwareVolumeService.startVolumeObserver(initialVolume: effectiveVolume);
+    } else {
+      await _hardwareVolumeService.stopVolumeObserver();
+    }
   }
 
   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) {
+    // Use effective volume for group players (player.volume returns 0
+    // because MA API returns null for group player volume_level)
+    final currentVolume = _musicProvider.groupVolumeManager.isGroupPlayer(player)
+        ? (_musicProvider.groupVolumeManager.getEffectiveVolumeLevel(
+                player, _musicProvider.availablePlayersUnfiltered) ?? player.volume)
+        : player.volume;
+
+    final newVolume = (currentVolume + delta).clamp(0, 100);
+    if (newVolume != currentVolume) {
       try {
         await _musicProvider.setVolume(player.playerId, newVolume);
       } catch (e) {
@@ -193,11 +226,29 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
     }
   }
 
+  /// Handle absolute volume change from lockscreen/background.
+  /// Called when the ContentObserver detects a system volume change
+  /// while a remote/group player is active.
+  Future<void> _setAbsoluteVolume(int volume) async {
+    final player = _musicProvider.selectedPlayer;
+    if (player == null) return;
+
+    // Don't route to builtin player - that's handled by the system directly
+    if (_builtinPlayerId != null && player.playerId == _builtinPlayerId) return;
+
+    try {
+      await _musicProvider.setVolume(player.playerId, volume.clamp(0, 100));
+    } catch (e) {
+      _logger.error('Lockscreen volume change failed', context: 'VolumeControl', error: e);
+    }
+  }
+
   @override
   void dispose() {
     _musicProvider.removeListener(_onProviderChanged);
     _volumeUpSub?.cancel();
     _volumeDownSub?.cancel();
+    _absoluteVolumeSub?.cancel();
     _hardwareVolumeService.dispose();
     WidgetsBinding.instance.removeObserver(this);
     super.dispose();
@@ -329,8 +380,17 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
                   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());
+                    // Wrap entire app with global player overlay.
+                    // Provide an Overlay ancestor so BottomNavigationBar/Tooltip can render safely.
+                    return Overlay(
+                      initialEntries: [
+                        OverlayEntry(
+                          builder: (context) => GlobalPlayerOverlay(
+                            child: child ?? const SizedBox.shrink(),
+                          ),
+                        ),
+                      ],
+                    );
                   },
                   home: const AppStartup(),
                 ),
@@ -475,6 +535,9 @@ class _AppStartupState extends State<AppStartup> {
   Future<void> _checkAndConnect() async {
     final serverUrl = await SettingsService.getServerUrl();
 
+    // DEBUG: Log where server URL is coming from
+    _logger.log('🐛 DEBUG: Server URL from SharedPreferences: $serverUrl');
+
     if (!mounted) return;
 
     setState(() {
@@ -483,6 +546,7 @@ class _AppStartupState extends State<AppStartup> {
 
     // If we have a saved server URL, attempt auto-connection
     if (serverUrl != null && serverUrl.isNotEmpty) {
+      _logger.log('🐛 DEBUG: Auto-connecting because server URL exists');
       setState(() {
         _isConnecting = true;
       });

lib/providers/music_assistant_provider.dart

@@ -22,6 +22,7 @@ import '../services/sync_service.dart';
 import '../services/local_player_service.dart';
 import '../services/metadata_service.dart';
 import '../services/position_tracker.dart';
+import '../services/group_volume_manager.dart';
 import '../services/sendspin_service.dart';
 import '../services/pcm_audio_player.dart';
 import '../services/offline_action_queue.dart';
@@ -46,6 +47,7 @@ class MusicAssistantProvider with ChangeNotifier {
   final DebugLogger _logger = DebugLogger();
   final CacheService _cacheService = CacheService();
   final PositionTracker _positionTracker = PositionTracker();
+  final GroupVolumeManager _groupVolumeManager = GroupVolumeManager();
 
   MAConnectionState _connectionState = MAConnectionState.disconnected;
   String? _serverUrl;
@@ -67,6 +69,16 @@ class MusicAssistantProvider with ChangeNotifier {
   List<Player> _availablePlayers = [];
   bool _selectPlayerInProgress = false; // Reentrancy guard for selectPlayer()
   Map<String, String> _castToSendspinIdMap = {}; // Maps regular Cast IDs to Sendspin IDs for grouping
+
+  // Pending volume cache: prevents stale API data from overwriting optimistic
+  // volume updates in _updatePlayerState() and refreshPlayers().
+  // Key: playerId, Value: volume level (0-100)
+  final Map<String, int> _pendingVolumes = {};
+  final Map<String, int> _pendingVolumeTimestamps = {}; // millisecondsSinceEpoch
+  static const int _pendingVolumeTimeoutMs = 8000; // 8s for non-group players
+  static const int _pendingVolumeTimeoutGroupMs = 30000; // 30s for group players (API returns null)
+  static const int _pendingVolumeTolerancePoints = 3; // Confirm if within ±3 points
+
   Track? _currentTrack;
   Audiobook? _currentAudiobook; // Currently playing audiobook context (with chapters)
   String? _currentPodcastName; // Currently playing podcast's name (set when playing episode)
@@ -90,6 +102,7 @@ class MusicAssistantProvider with ChangeNotifier {
 
   // Home refresh counter - increments to signal home screen to refresh all rows
   int _homeRefreshCounter = 0;
+  String? _lastConnectedUrl; // Track last successfully connected server URL
   StreamSubscription? _connectionStateSubscription;
   StreamSubscription? _localPlayerEventSubscription;
   StreamSubscription? _playerUpdatedEventSubscription;
@@ -500,6 +513,9 @@ class MusicAssistantProvider with ChangeNotifier {
   /// Raw unfiltered players list (for internal use)
   List<Player> get availablePlayersUnfiltered => _availablePlayers;
 
+  /// Group volume manager for resolving group player volumes
+  GroupVolumeManager get groupVolumeManager => _groupVolumeManager;
+
   /// Check if a player should show the "manually synced" indicator (yellow border)
   /// Returns true for BOTH the leader AND children of a manually created sync group
   /// Excludes pre-configured MA speaker groups (provider = 'player_group')
@@ -1050,16 +1066,17 @@ class MusicAssistantProvider with ChangeNotifier {
       _connectionStateSubscription?.cancel();
       _connectionStateSubscription = _api!.connectionState.listen(
         (state) async {
-          _connectionState = state;
-          notifyListeners();
-
           if (state == MAConnectionState.connected) {
             _logger.log('🔗 WebSocket connected to MA server');
 
             if (_api!.authRequired && !_api!.isAuthenticated) {
+              // Don't broadcast 'connected' yet — AppStartup watches isConnected
+              // and would transition to HomeScreen before auth completes, causing
+              // data fetches to fail with "Not authenticated".
               _logger.log('🔐 MA auth required, attempting authentication...');
               final authenticated = await _handleMaAuthentication();
               if (!authenticated) {
+                _connectionState = MAConnectionState.error;
                 _error = 'Authentication required. Please log in again.';
                 notifyListeners();
                 return;
@@ -1069,17 +1086,26 @@ class MusicAssistantProvider with ChangeNotifier {
               return;
             }
 
-            // No auth required, initialize immediately
+            // No auth required — safe to broadcast connected and initialize
+            _connectionState = state;
+            notifyListeners();
             await _initializeAfterConnection();
           } else if (state == MAConnectionState.authenticated) {
+            _connectionState = state;
+            notifyListeners();
             _logger.log('✅ MA authentication successful');
             // Now safe to initialize since we're authenticated
             await _initializeAfterConnection();
           } else if (state == MAConnectionState.disconnected) {
+            _connectionState = state;
+            notifyListeners();
             // DON'T clear players or caches on disconnect!
             // Keep showing cached data for instant UI display on reconnect
             // Player list and state will be refreshed when connection is restored
             _logger.log('📡 Disconnected - keeping cached players and data for instant resume');
+          } else {
+            _connectionState = state;
+            notifyListeners();
           }
         },
         onError: (error) {
@@ -1342,15 +1368,13 @@ class MusicAssistantProvider with ChangeNotifier {
 
       loadLibrary();
 
-      // Only invalidate home cache if it was empty (no cached recent albums = empty cache)
-      // This prevents jarring double-load when cache is already valid
-      if (_cacheService.getCachedRecentAlbums() == null) {
-        _logger.log('🔄 Home cache was empty, invalidating after auth...');
+      // Only force home refresh when connecting to a different server (or first connect).
+      // Reconnecting to the same server after backgrounding preserves cached home data.
+      if (_serverUrl != _lastConnectedUrl) {
         _cacheService.invalidateHomeCache();
         _homeRefreshCounter++;
-      } else {
-        _logger.log('✅ Home cache has valid data, skipping refresh');
       }
+      _lastConnectedUrl = _serverUrl;
 
       // Notify listeners to trigger UI refresh - home rows will re-fetch with valid authentication
       notifyListeners();
@@ -1890,6 +1914,9 @@ class MusicAssistantProvider with ChangeNotifier {
     _tracks = [];
     _currentTrack = null;
     _cacheService.clearAll();
+    _groupVolumeManager.clear();
+    _pendingVolumes.clear();
+    _pendingVolumeTimestamps.clear();
     _logger.log('🗑️ Cleared all data on logout');
     notifyListeners();
   }
@@ -2743,6 +2770,24 @@ class MusicAssistantProvider with ChangeNotifier {
         }
       }
 
+      // Update member volume in _availablePlayers for accurate group volume
+      // computation. When MA changes a group member's volume (after setVolume
+      // on the group player), it fires player_updated for each member.
+      // Without this, _availablePlayers member volumes stay stale until the
+      // next _updatePlayerState poll, which could cause the group average
+      // to be wrong during the convergence check.
+      final rawVolume = event['volume_level'];
+      final eventVolume = rawVolume is int
+          ? rawVolume
+          : (rawVolume is double ? rawVolume.round() : null);
+      if (eventVolume != null) {
+        final idx = _availablePlayers.indexWhere((p) => p.playerId == playerId);
+        if (idx != -1 && _availablePlayers[idx].volumeLevel != eventVolume) {
+          _availablePlayers[idx] =
+              _availablePlayers[idx].copyWith(volumeLevel: eventVolume);
+        }
+      }
+
       final currentMedia = event['current_media'] as Map<String, dynamic>?;
       final playerName = event['name'] as String? ?? playerId;
 
@@ -4566,6 +4611,40 @@ class MusicAssistantProvider with ChangeNotifier {
     }
   }
 
+  /// Apply volume protection for the selected player.
+  /// Injects effective volume for group players (whose API volume is null)
+  /// and protects optimistic volume updates from stale API data.
+  void _applyVolumeProtection(Player updatedPlayer, List<Player> allPlayers) {
+    if (_groupVolumeManager.isGroupPlayer(updatedPlayer)) {
+      final effectiveVolume = _groupVolumeManager.getEffectiveVolumeLevel(
+          updatedPlayer, allPlayers);
+      if (effectiveVolume != null) {
+        _selectedPlayer = _selectedPlayer!.copyWith(volumeLevel: effectiveVolume);
+      }
+    }
+
+    final pendingVol = _pendingVolumes[updatedPlayer.playerId];
+    final pendingTs = _pendingVolumeTimestamps[updatedPlayer.playerId];
+    if (pendingVol != null && pendingTs != null) {
+      final elapsed = DateTime.now().millisecondsSinceEpoch - pendingTs;
+      final isGroup = _groupVolumeManager.isGroupPlayer(updatedPlayer);
+      final timeoutMs = isGroup ? _pendingVolumeTimeoutGroupMs : _pendingVolumeTimeoutMs;
+      if (elapsed >= timeoutMs) {
+        _pendingVolumes.remove(updatedPlayer.playerId);
+        _pendingVolumeTimestamps.remove(updatedPlayer.playerId);
+      } else {
+        final currentEffective = _selectedPlayer?.volumeLevel;
+        if (currentEffective != null &&
+            (currentEffective - pendingVol).abs() <= _pendingVolumeTolerancePoints) {
+          _pendingVolumes.remove(updatedPlayer.playerId);
+          _pendingVolumeTimestamps.remove(updatedPlayer.playerId);
+        } else {
+          _selectedPlayer = _selectedPlayer!.copyWith(volumeLevel: pendingVol);
+        }
+      }
+    }
+  }
+
   Future<void> _updatePlayerState() async {
     if (_selectedPlayer == null || _api == null) return;
 
@@ -4598,6 +4677,24 @@ class MusicAssistantProvider with ChangeNotifier {
         return;
       }
 
+      // Update _availablePlayers with fresh volume/state data from API.
+      // This is critical for group volume computation: member players don't get
+      // individual _updatePlayerState() calls, so their volumes in _availablePlayers
+      // would go stale. Without this, after the pending timeout expires, the
+      // computed group average uses old member volumes and snaps back to 0.
+      for (final freshPlayer in allPlayers) {
+        final idx = _availablePlayers.indexWhere(
+            (p) => p.playerId == freshPlayer.playerId);
+        if (idx != -1) {
+          _availablePlayers[idx] = _availablePlayers[idx].copyWith(
+            volumeLevel: freshPlayer.volumeLevel,
+            state: freshPlayer.state,
+            powered: freshPlayer.powered,
+            available: freshPlayer.available,
+          );
+        }
+      }
+
       Player? rawPlayer = allPlayers.firstWhere(
         (p) => p.playerId == selectedId ||
                (translatedSendspinId != null && p.playerId == translatedSendspinId) ||
@@ -4632,6 +4729,9 @@ class MusicAssistantProvider with ChangeNotifier {
       );
 
       _selectedPlayer = updatedPlayer;
+
+      _applyVolumeProtection(updatedPlayer, allPlayers);
+
       stateChanged = true;
 
       // Handle external sources (Spotify Connect, TV optical, etc.)
@@ -4980,6 +5080,8 @@ class MusicAssistantProvider with ChangeNotifier {
         }
 
         _selectedPlayer = updatedPlayer;
+
+        _applyVolumeProtection(updatedPlayer, _availablePlayers);
       } catch (e) {
         stateChanged = true;
       }
@@ -5952,6 +6054,63 @@ class MusicAssistantProvider with ChangeNotifier {
 
   Future<void> setVolume(String playerId, int volumeLevel) async {
     try {
+      // Optimistically update the selected player's volume BEFORE any async calls.
+      // This prevents slider snapback: without this, clearing _pendingVolume on drag
+      // end causes the slider to read the stale player.volume until player_updated arrives.
+      if (_selectedPlayer != null && _selectedPlayer!.playerId == playerId) {
+        _selectedPlayer = _selectedPlayer!.copyWith(volumeLevel: volumeLevel);
+        notifyListeners();
+      }
+
+      // Cache pending volume for ALL players to protect optimistic updates
+      // from being overwritten by stale API data in _updatePlayerState()/refreshPlayers().
+      _pendingVolumes[playerId] = volumeLevel;
+      _pendingVolumeTimestamps[playerId] = DateTime.now().millisecondsSinceEpoch;
+
+      // Also cache for group players in GroupVolumeManager
+      // (MA API returns null for group player volume_level)
+      final player = _availablePlayers.where((p) => p.playerId == playerId).firstOrNull;
+      if (player != null && _groupVolumeManager.isGroupPlayer(player)) {
+        _groupVolumeManager.onVolumeSet(playerId, volumeLevel);
+      }
+
+      // Proportional volume propagation for in-app sync group leaders.
+      // When a user creates a group via long-press (players/cmd/group), the leader
+      // retains its own non-null volumeLevel and isGroupPlayer() returns false.
+      // We detect this via isGroupLeader and propagate volume changes to all
+      // members proportionally, preserving relative volume balance.
+      if (player != null &&
+          player.isGroupLeader &&
+          !_groupVolumeManager.isGroupPlayer(player)) {
+        final currentVol = player.volumeLevel;
+        final now = DateTime.now().millisecondsSinceEpoch;
+        for (final memberId in player.groupMembers!) {
+          if (memberId == playerId) continue; // Skip the leader itself
+          final idx = _availablePlayers.indexWhere((p) => p.playerId == memberId);
+          if (idx == -1) continue;
+          final member = _availablePlayers[idx];
+          if (member.volumeLevel == null) continue;
+
+          final int memberNewVol;
+          if (currentVol != null && currentVol > 0) {
+            // Ratio-based: maintain relative balance between members
+            memberNewVol = (member.volumeLevel! * volumeLevel / currentVol)
+                .round()
+                .clamp(0, 100);
+          } else {
+            // Can't ratio from 0 — set all to the new absolute value
+            memberNewVol = volumeLevel;
+          }
+
+          // Protect from snap-back and update optimistically
+          _pendingVolumes[memberId] = memberNewVol;
+          _pendingVolumeTimestamps[memberId] = now;
+          _availablePlayers[idx] = member.copyWith(volumeLevel: memberNewVol);
+          // Fire-and-forget — don't await, send in parallel
+          _api?.setVolume(memberId, memberNewVol);
+        }
+      }
+
       final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
       if (builtinPlayerId != null && playerId == builtinPlayerId) {
         _localPlayerVolume = volumeLevel;

lib/screens/album_details_screen.dart

@@ -847,7 +847,9 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
             final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
             final expandedHeight = coverSize + 70;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
         slivers: [
           SliverAppBar(
             expandedHeight: expandedHeight,
@@ -972,7 +974,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                       ),
                     ),
                   ),
-                  Spacing.vGap16,
+                  Spacing.vGap8,
                   // Album Description
                   if (_albumDescription != null && _albumDescription!.isNotEmpty) ...[
                     InkWell(
@@ -1109,7 +1111,7 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
                       ),
                     ],
                   ),
-                  const SizedBox(height: 24),
+                  const SizedBox(height: 12),
                 ],
               ),
             ),
@@ -1216,7 +1218,29 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
             ),
           SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)), // Space for bottom nav + mini player
         ],
-      );
+      ),
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.background.withOpacity(0.0),
+                            colorScheme.background,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
+            );
           },
         ),
       ),

lib/screens/artist_details_screen.dart

@@ -884,9 +884,11 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> with LibraryS
           builder: (context, constraints) {
             // Responsive cover size: 50% of screen width, clamped between 140-200 (smaller for circular artist image)
             final coverSize = (constraints.maxWidth * 0.5).clamp(140.0, 200.0);
-            final expandedHeight = coverSize + 80;
+            final expandedHeight = coverSize + 45;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
           slivers: [
             SliverAppBar(
               expandedHeight: expandedHeight,
@@ -1157,7 +1159,30 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> with LibraryS
             ],
           ],
         ],
-        );
+        ),
+                // Bottom fade gradient to mask content behind mini player
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.background.withOpacity(0.0),
+                            colorScheme.background,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
+            );
           },
         ),
       ),

lib/screens/audiobook_author_screen.dart

@@ -300,9 +300,11 @@ class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
           builder: (context, constraints) {
             // Responsive cover size: 50% of screen width, clamped between 140-200 (matches artist detail)
             final coverSize = (constraints.maxWidth * 0.5).clamp(140.0, 200.0);
-            final expandedHeight = coverSize + 60;
+            final expandedHeight = coverSize + 25;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
           slivers: [
             SliverAppBar(
               expandedHeight: expandedHeight,
@@ -370,7 +372,7 @@ class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
               child: Padding(
                 padding: const EdgeInsets.fromLTRB(24.0, 8.0, 24.0, 24.0),
                 child: Row(
-                  crossAxisAlignment: CrossAxisAlignment.start,
+                  crossAxisAlignment: CrossAxisAlignment.center,
                   children: [
                     // Author info on the left
                     Expanded(
@@ -452,6 +454,28 @@ class _AudiobookAuthorScreenState extends State<AudiobookAuthorScreen> {
             _buildAudiobookSliver(),
             SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)),
           ],
+            ),
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.surface.withOpacity(0.0),
+                            colorScheme.surface,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
             );
           },
         ),

lib/screens/audiobook_detail_screen.dart

@@ -523,7 +523,9 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
             final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
             final expandedHeight = coverSize + 70;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
           slivers: [
             SliverAppBar(
               expandedHeight: expandedHeight,
@@ -929,7 +931,29 @@ class _AudiobookDetailScreenState extends State<AudiobookDetailScreen> {
 
             SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)),
           ],
-        );
+        ),
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.surface.withOpacity(0.0),
+                            colorScheme.surface,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
+            );
           },
         ),
       ),

lib/screens/audiobook_series_screen.dart

@@ -283,7 +283,9 @@ class _AudiobookSeriesScreenState extends State<AudiobookSeriesScreen> {
           final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
           final expandedHeight = coverSize + 70;
 
-          return CustomScrollView(
+          return Stack(
+            children: [
+              CustomScrollView(
         slivers: [
           // App bar with series cover collage (matches audiobook detail screen)
           SliverAppBar(
@@ -457,7 +459,29 @@ class _AudiobookSeriesScreenState extends State<AudiobookSeriesScreen> {
             child: SizedBox(height: BottomSpacing.withMiniPlayer),
           ),
         ],
-      );
+      ),
+              Positioned(
+                left: 0,
+                right: 0,
+                bottom: 0,
+                height: BottomSpacing.withMiniPlayer,
+                child: IgnorePointer(
+                  child: DecoratedBox(
+                    decoration: BoxDecoration(
+                      gradient: LinearGradient(
+                        begin: Alignment.topCenter,
+                        end: Alignment.bottomCenter,
+                        colors: [
+                          colorScheme.surface.withOpacity(0.0),
+                          colorScheme.surface,
+                        ],
+                      ),
+                    ),
+                  ),
+                ),
+              ),
+            ],
+          );
         },
       ),
     );

lib/screens/home_screen.dart

@@ -1,8 +1,11 @@
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
+import 'package:material_symbols_icons/symbols.dart';
 import '../l10n/app_localizations.dart';
+import '../providers/music_assistant_provider.dart';
 import '../providers/navigation_provider.dart';
+import '../theme/theme_provider.dart';
 import '../widgets/global_player_overlay.dart';
 import 'new_home_screen.dart';
 import 'new_library_screen.dart';
@@ -19,6 +22,7 @@ class HomeScreen extends StatefulWidget {
 class _HomeScreenState extends State<HomeScreen> {
   final GlobalKey<SearchScreenState> _searchScreenKey = GlobalKey<SearchScreenState>();
   DateTime? _lastBackPress;
+  final _cachedNavColor = _CachedNavColor();
 
   @override
   void initState() {
@@ -105,7 +109,15 @@ class _HomeScreenState extends State<HomeScreen> {
           },
           child: Scaffold(
             backgroundColor: colorScheme.surface,
-            // No bottomNavigationBar here - it's now in GlobalPlayerOverlay
+            // extendBody: true preserves the existing layout where content fills the
+            // full screen and screens manage their own bottom padding (BottomSpacing).
+            // Without this, Scaffold would constrain the body above the nav bar,
+            // causing double bottom spacing.
+            extendBody: true,
+            // BottomNavigationBar requires an Overlay ancestor (for Tooltip);
+            // Scaffold inside Navigator provides one. Previously it was in
+            // GlobalPlayerOverlay's Stack (outside Navigator) causing crashes.
+            bottomNavigationBar: _buildBottomNavigationBar(context, colorScheme),
             body: Stack(
               children: [
                 // Home and Library use IndexedStack for state preservation
@@ -131,4 +143,162 @@ class _HomeScreenState extends State<HomeScreen> {
       },
     );
   }
+
+  /// Build the bottom navigation bar with adaptive colors and player expansion animation.
+  /// Moved here from GlobalPlayerOverlay so it has proper Overlay ancestry
+  /// (required by BottomNavigationBar's internal Tooltip widgets).
+  Widget? _buildBottomNavigationBar(BuildContext context, ColorScheme colorScheme) {
+    // Hide nav bar when not connected
+    final isConnected = context.select<MusicAssistantProvider, bool>(
+      (p) => p.isConnected,
+    );
+    if (!isConnected) return null;
+
+    return Consumer<ThemeProvider>(
+      builder: (context, themeProvider, _) {
+        final isDark = Theme.of(context).brightness == Brightness.dark;
+
+        return ValueListenableBuilder<PlayerExpansionState>(
+          valueListenable: playerExpansionNotifier,
+          builder: (context, expansionState, _) {
+            // Nav bar color logic - only use adaptive colors when:
+            // 1. Player is expanding/expanded, OR
+            // 2. On a detail screen (isOnDetailScreen)
+            // On home screen with collapsed player: always use default theme colors
+            final bool useAdaptiveColors = themeProvider.adaptiveTheme &&
+                (expansionState.progress > 0 || themeProvider.isOnDetailScreen);
+
+            // Nav bar background color
+            final Color navBgColor;
+            if (expansionState.progress > 0 && expansionState.backgroundColor != null) {
+              // Player is expanding - blend from surface to player's adaptive color
+              navBgColor = Color.lerp(colorScheme.surface, expansionState.backgroundColor, expansionState.progress)!;
+            } else if (useAdaptiveColors) {
+              // On a detail screen - use adaptive surface color for nav bar
+              final adaptiveBg = themeProvider.getAdaptiveSurfaceColorFor(Theme.of(context).brightness);
+              navBgColor = adaptiveBg ?? colorScheme.surface;
+            } else {
+              // Home screen with collapsed player - use default surface color
+              navBgColor = colorScheme.surface;
+            }
+
+            // Icon color - only use adaptive colors when appropriate
+            final Color baseSourceColor = (useAdaptiveColors && themeProvider.adaptiveColors != null)
+                ? themeProvider.adaptiveColors!.primary
+                : colorScheme.primary;
+
+            // Blend icon color with player's primary color during expansion
+            Color sourceColor = baseSourceColor;
+            if (themeProvider.adaptiveTheme && expansionState.progress > 0 && expansionState.primaryColor != null) {
+              sourceColor = Color.lerp(baseSourceColor, expansionState.primaryColor!, expansionState.progress)!;
+            }
+            final navSelectedColor = _cachedNavColor.getAdjustedColor(sourceColor, isDark);
+
+            // Fade out and slide down nav bar as player expands
+            // Use IgnorePointer when faded to prevent accidental taps
+            final navOpacity = (1.0 - expansionState.progress * 2).clamp(0.0, 1.0);
+            final navSlideDown = expansionState.progress * 20; // Slide down 20px as it fades
+
+            return IgnorePointer(
+              ignoring: navOpacity < 0.1,
+              child: Transform.translate(
+                offset: Offset(0, navSlideDown),
+                child: Opacity(
+                  opacity: navOpacity,
+                  child: Container(
+                    decoration: BoxDecoration(
+                      color: navBgColor,
+                      boxShadow: expansionState.progress < 0.5
+                          ? [
+                              BoxShadow(
+                                color: Colors.black.withOpacity(0.1),
+                                blurRadius: 10,
+                                offset: const Offset(0, -2),
+                              ),
+                            ]
+                          : null,
+                    ),
+                    child: BottomNavigationBar(
+                      currentIndex: navigationProvider.selectedIndex,
+                      onTap: (index) {
+                        if (GlobalPlayerOverlay.isPlayerExpanded) {
+                          GlobalPlayerOverlay.collapsePlayer();
+                        }
+                        navigationProvider.navigatorKey.currentState?.popUntil((route) => route.isFirst);
+                        // Clear adaptive colors when switching tabs (detail screen colors shouldn't persist)
+                        themeProvider.clearAdaptiveColors();
+                        if (index == 3) {
+                          GlobalPlayerOverlay.hidePlayer();
+                        } else if (navigationProvider.selectedIndex == 3) {
+                          GlobalPlayerOverlay.showPlayer();
+                        }
+                        navigationProvider.setSelectedIndex(index);
+                      },
+                      backgroundColor: Colors.transparent,
+                      selectedItemColor: navSelectedColor,
+                      unselectedItemColor: colorScheme.onSurface.withOpacity(0.54),
+                      elevation: 0,
+                      type: BottomNavigationBarType.fixed,
+                      selectedFontSize: 12,
+                      unselectedFontSize: 12,
+                      items: [
+                        BottomNavigationBarItem(
+                          icon: const Icon(Icons.home_outlined),
+                          activeIcon: const Icon(Icons.home_rounded),
+                          label: S.of(context)!.home,
+                        ),
+                        BottomNavigationBarItem(
+                          icon: const Icon(Symbols.book_2, fill: 0),
+                          activeIcon: const Icon(Symbols.book_2, fill: 1),
+                          label: S.of(context)!.library,
+                        ),
+                        BottomNavigationBarItem(
+                          icon: const Icon(Icons.search_rounded),
+                          activeIcon: const Icon(Icons.search_rounded),
+                          label: S.of(context)!.search,
+                        ),
+                        BottomNavigationBarItem(
+                          icon: const Icon(Icons.settings_outlined),
+                          activeIcon: const Icon(Icons.settings_rounded),
+                          label: S.of(context)!.settings,
+                        ),
+                      ],
+                    ),
+                  ),
+                ),
+              ),
+            );
+          },
+        );
+      },
+    );
+  }
+}
+
+/// Cached color with contrast adjustment for nav bar icon colors.
+/// Avoids expensive HSL conversions during scroll/animation.
+class _CachedNavColor {
+  Color? _sourceColor;
+  bool? _isDark;
+  Color? _adjustedColor;
+
+  Color getAdjustedColor(Color sourceColor, bool isDark) {
+    if (_sourceColor == sourceColor && _isDark == isDark && _adjustedColor != null) {
+      return _adjustedColor!;
+    }
+
+    var navSelectedColor = sourceColor;
+    if (isDark && navSelectedColor.computeLuminance() < 0.2) {
+      final hsl = HSLColor.fromColor(navSelectedColor);
+      navSelectedColor = hsl.withLightness((hsl.lightness + 0.3).clamp(0.0, 0.8)).toColor();
+    } else if (!isDark && navSelectedColor.computeLuminance() > 0.8) {
+      final hsl = HSLColor.fromColor(navSelectedColor);
+      navSelectedColor = hsl.withLightness((hsl.lightness - 0.3).clamp(0.2, 1.0)).toColor();
+    }
+
+    _sourceColor = sourceColor;
+    _isDark = isDark;
+    _adjustedColor = navSelectedColor;
+    return navSelectedColor;
+  }
 }

lib/screens/new_home_screen.dart

@@ -4,10 +4,12 @@ import 'package:provider/provider.dart';
 import '../l10n/app_localizations.dart';
 import '../models/recommendation_folder.dart';
 import '../providers/music_assistant_provider.dart';
+import '../providers/navigation_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/mini_player_content.dart' show MiniPlayerLayout;
 import '../widgets/player_selector.dart';
 import '../widgets/album_row.dart';
 import '../widgets/artist_row.dart';
@@ -29,9 +31,10 @@ class NewHomeScreen extends StatefulWidget {
   State<NewHomeScreen> createState() => _NewHomeScreenState();
 }
 
-class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveClientMixin, WidgetsBindingObserver {
+class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveClientMixin {
   static final _logger = DebugLogger();
-  Key _refreshKey = UniqueKey();
+  final ValueNotifier<int> _refreshSignal = ValueNotifier<int>(0);
+  double? _cachedRowHeight; // Cached to avoid size jumps when nav bar toggles
   // Main rows (default on)
   bool _showRecentAlbums = true;
   bool _showDiscoverArtists = true;
@@ -51,7 +54,6 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
   List<String> _homeRowOrder = List.from(SettingsService.defaultHomeRowOrder);
   // Discovery folders (dynamic rows from provider recommendations)
   List<RecommendationFolder> _discoveryFolders = [];
-  bool _isLoadingDiscoveryFolders = false;
   // Discovery row preferences (itemId -> enabled)
   Map<String, bool> _discoveryRowEnabled = {};
 
@@ -68,7 +70,6 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
   @override
   void initState() {
     super.initState();
-    WidgetsBinding.instance.addObserver(this);
     _loadSettings();
     // Listen to sync completion to refresh favorite rows when data becomes available
     SyncService.instance.addListener(_onSyncChanged);
@@ -80,15 +81,66 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
     _lastHomeRefreshCounter = provider.homeRefreshCounter;
     _providerListeningTo = provider;
     provider.addListener(_onProviderChanged);
+
+    // Reload settings only when switching back to home from settings tab
+    navigationProvider.addListener(_onNavigationChanged);
+  }
+
+  int _lastNavIndex = 0;
+
+  void _onNavigationChanged() {
+    final newIndex = navigationProvider.selectedIndex;
+    // Reload preferences when leaving settings tab (3) for home tab (0)
+    if (_lastNavIndex == 3 && newIndex == 0) {
+      _reloadPreferencesOnly();
+    }
+    _lastNavIndex = newIndex;
+  }
+
+  /// Reload only local preferences (no API calls). Used when switching back from settings.
+  Future<void> _reloadPreferencesOnly() 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 showFavPlaylists = await SettingsService.getShowFavoritePlaylists();
+    final showFavRadio = await SettingsService.getShowFavoriteRadioStations();
+    final showFavPodcasts = await SettingsService.getShowFavoritePodcasts();
+    final showContAudiobooks = await SettingsService.getShowContinueListeningAudiobooks();
+    final showDiscAudiobooks = await SettingsService.getShowDiscoverAudiobooks();
+    final showDiscSeries = await SettingsService.getShowDiscoverSeries();
+    final rowOrder = await SettingsService.getHomeRowOrder();
+    final discoveryRowPrefs = await SettingsService.getDiscoveryRowPreferences();
+    if (mounted) {
+      setState(() {
+        _showRecentAlbums = showRecent;
+        _showDiscoverArtists = showDiscArtists;
+        _showDiscoverAlbums = showDiscAlbums;
+        _showFavoriteAlbums = showFavAlbums;
+        _showFavoriteArtists = showFavArtists;
+        _showFavoriteTracks = showFavTracks;
+        _showFavoritePlaylists = showFavPlaylists;
+        _showFavoriteRadioStations = showFavRadio;
+        _showFavoritePodcasts = showFavPodcasts;
+        _showContinueListeningAudiobooks = showContAudiobooks;
+        _showDiscoverAudiobooks = showDiscAudiobooks;
+        _showDiscoverSeries = showDiscSeries;
+        _homeRowOrder = rowOrder;
+        _discoveryRowEnabled = discoveryRowPrefs;
+      });
+    }
   }
 
   @override
   void dispose() {
+    navigationProvider.removeListener(_onNavigationChanged);
     SyncService.instance.removeListener(_onSyncChanged);
     // Clean up provider listener
     _providerListeningTo?.removeListener(_onProviderChanged);
     _providerListeningTo = null;
-    WidgetsBinding.instance.removeObserver(this);
+    _refreshSignal.dispose();
     super.dispose();
   }
 
@@ -121,9 +173,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
     if (currentRefreshCounter != _lastHomeRefreshCounter) {
       _logger.log('🔄 Home: refresh counter changed ($_lastHomeRefreshCounter -> $currentRefreshCounter), refreshing all rows');
       _lastHomeRefreshCounter = currentRefreshCounter;
-      setState(() {
-        _refreshKey = UniqueKey();  // Forces all rows to rebuild and re-fetch data
-      });
+      _refreshSignal.value++;
       return;  // Don't process other refresh conditions in this cycle
     }
 
@@ -133,9 +183,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
       if (_lastArtistCount == 0 && currentCount > 0) {
         _logger.log('🔄 Home: artists loaded from cache ($currentCount), refreshing rows');
         _hadEmptyFavoritesOnLoad = false;
-        setState(() {
-          _refreshKey = UniqueKey();
-        });
+        _refreshSignal.value++;
       }
       _lastArtistCount = currentCount;
     }
@@ -154,21 +202,12 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
       _providerListeningTo?.removeListener(_onProviderChanged);
       _providerListeningTo = null;
       if (mounted) {
-        setState(() {
-          _refreshKey = UniqueKey();
-        });
+        _refreshSignal.value++;
       }
     }
     _lastSyncStatus = newStatus;
   }
 
-  @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();
@@ -205,21 +244,21 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
     }
 
     // Load discovery folders dynamically (after settings load)
-    // This will add enabled discovery rows to the home order
-    await _loadDiscoveryFolders(forceRefresh: false);
+    // Skip if already loaded to avoid unnecessary rebuilds on settings reload
+    if (_discoveryFolders.isEmpty) {
+      await _loadDiscoveryFolders(forceRefresh: false);
+    } else {
+      // Just re-sync the row order with current enabled state (no API call)
+      setState(() {
+        _syncDiscoveryRowOrder(_discoveryFolders);
+      });
+    }
   }
 
   Future<void> _loadDiscoveryFolders({bool forceRefresh = false}) async {
     if (!mounted) return;
     final provider = context.read<MusicAssistantProvider>();
 
-    // Set loading state if not already loaded
-    if (_discoveryFolders.isEmpty && mounted) {
-      setState(() {
-        _isLoadingDiscoveryFolders = true;
-      });
-    }
-
     try {
       var folders = await provider.getDiscoveryFoldersWithCache();
       // If cached result is empty, force a refresh to get from API/database
@@ -232,59 +271,31 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
         setState(() {
           _discoveryFolders = folders;
           _discoveryRowEnabled = discoveryRowPrefs;
-          _isLoadingDiscoveryFolders = false;
+          _syncDiscoveryRowOrder(folders);
         });
       }
-      // Add enabled discovery rows to home row order if not already present
-      if (mounted) {
-        _addDiscoveryRowsToHomeOrder(folders);
-      }
     } catch (e) {
       _logger.log('⚠️ Failed to load discovery folders: $e');
-      if (mounted) {
-        setState(() {
-          _isLoadingDiscoveryFolders = false;
-        });
-      }
     }
   }
 
-  /// Add discovery rows to the home row order (at the end, like static rows)
-  void _addDiscoveryRowsToHomeOrder(List<RecommendationFolder> folders) {
-    if (!mounted) return;
-
+  /// Sync discovery row order without calling setState. Only adds new folders, never removes.
+  /// Visibility is controlled by _discoveryRowEnabled / _isRowEnabled().
+  bool _syncDiscoveryRowOrder(List<RecommendationFolder> folders) {
     bool didModify = false;
 
-    _logger.log('🔍 Discovery: Processing ${folders.length} folders, prefs: $_discoveryRowEnabled');
-
     for (final folder in folders) {
       final discoveryRowId = 'discovery:${folder.itemId}';
-      // Check if this discovery row is enabled (default to false)
-      final isEnabled = _discoveryRowEnabled[folder.itemId] ?? false;
-
-      _logger.log('🔍 Discovery: ${folder.name} (${folder.itemId}) enabled=$isEnabled, inOrder=${_homeRowOrder.contains(discoveryRowId)}');
-
-      if (isEnabled && !_homeRowOrder.contains(discoveryRowId)) {
-        // Add at the end (consistent with static rows behavior)
+      if (!_homeRowOrder.contains(discoveryRowId)) {
         _homeRowOrder.add(discoveryRowId);
-        _logger.log('✅ Discovery: Adding $discoveryRowId to home order at end');
-        didModify = true;
-      } else if (!isEnabled && _homeRowOrder.contains(discoveryRowId)) {
-        // Remove disabled discovery row from order
-        _homeRowOrder.remove(discoveryRowId);
-        _logger.log('❌ Discovery: Removing $discoveryRowId from home order');
         didModify = true;
       }
     }
 
-    // Save the updated row order to settings and trigger rebuild
     if (didModify) {
-      _logger.log('💾 Discovery: Saving updated home row order: $_homeRowOrder');
       SettingsService.setHomeRowOrder(_homeRowOrder);
-      if (mounted) {
-        setState(() {}); // Trigger rebuild to show new row order
-      }
     }
+    return didModify;
   }
 
   Future<void> _onRefresh() async {
@@ -299,9 +310,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
     await _loadSettings();
 
     if (mounted) {
-      setState(() {
-        _refreshKey = UniqueKey();
-      });
+      _refreshSignal.value++;
     }
   }
 
@@ -438,23 +447,6 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
     for (final rowId in _homeRowOrder) {
       if (_isRowEnabled(rowId)) count++;
     }
-    // Count discovery folders that are NOT in the main row order yet (legacy support during load)
-    // This handles the brief moment between when discovery folders load and when they're added to the order
-    if (_discoveryFolders.isNotEmpty) {
-      for (final folder in _discoveryFolders) {
-        final discoveryRowId = 'discovery:${folder.itemId}';
-        if (!_homeRowOrder.contains(discoveryRowId) && (_discoveryRowEnabled[folder.itemId] ?? false)) {
-          count++;
-        }
-      }
-    } else if (_isLoadingDiscoveryFolders && _discoveryFolders.isEmpty) {
-      // Count as 1 row when loading so RefreshIndicator works
-      // Only if no discovery rows are in the main order
-      final hasDiscoveryRowsInOrder = _homeRowOrder.any((id) => id.startsWith('discovery:'));
-      if (!hasDiscoveryRowsInOrder) {
-        count += 1;
-      }
-    }
     return count;
   }
 
@@ -483,57 +475,6 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
     }
   }
 
-  /// Build a loading placeholder for discovery rows
-  Widget _buildDiscoveryLoadingPlaceholder(double rowHeight) {
-    final colorScheme = Theme.of(context).colorScheme;
-    final textTheme = Theme.of(context).textTheme;
-
-    return SizedBox(
-      height: rowHeight,
-      child: Column(
-        crossAxisAlignment: CrossAxisAlignment.start,
-        children: [
-          Padding(
-            padding: const EdgeInsets.fromLTRB(16.0, 12.0, 16.0, 8.0),
-            child: Text(
-              S.of(context)!.discoveryMixes,
-              style: textTheme.titleLarge?.copyWith(
-                fontWeight: FontWeight.bold,
-                color: colorScheme.onBackground,
-              ),
-            ),
-          ),
-          Expanded(
-            child: Center(
-              child: Column(
-                mainAxisAlignment: MainAxisAlignment.center,
-                children: [
-                  SizedBox(
-                    width: 24,
-                    height: 24,
-                    child: CircularProgressIndicator(
-                      strokeWidth: 2,
-                      valueColor: AlwaysStoppedAnimation<Color>(
-                        colorScheme.primary.withOpacity(0.7),
-                      ),
-                    ),
-                  ),
-                  const SizedBox(height: 12),
-                  Text(
-                    S.of(context)!.loading,
-                    style: textTheme.bodySmall?.copyWith(
-                      color: colorScheme.onSurface.withOpacity(0.6),
-                    ),
-                  ),
-                ],
-              ),
-            ),
-          ),
-        ],
-      ),
-    );
-  }
-
   Widget _buildConnectedView(
       BuildContext context, MusicAssistantProvider provider) {
     // Use LayoutBuilder to get available screen height
@@ -541,15 +482,30 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
       builder: (context, constraints) {
         // Each row is always 1/3 of screen height
         // 1 row = 1/3, 2 rows = 2/3, 3 rows = full screen, 4+ rows scroll
-        final availableHeight = constraints.maxHeight - BottomSpacing.withMiniPlayer;
+        // With extendBody: true, constraints include the area behind the nav bar.
+        // Only subtract mini player space (not nav bar) since nav bar is Scaffold chrome.
+        final miniPlayerSpace = MiniPlayerLayout.height + 12.0 + 22.0; // 72 + 12 + 22 = 106
+        final availableHeight = constraints.maxHeight - miniPlayerSpace;
 
-        // Account for margins between rows (2px each)
-        // Only adjust for margins when ≤3 rows (so they fit exactly without scroll)
-        // For 4+ rows, use original calculation so 4th row stays hidden (scrollable)
+        // Account for margins between rows (2px each, 2 margins for 3 rows).
+        // Always use the 3-row margin calculation so rowHeight stays stable
+        // regardless of how many rows are currently enabled (avoids jitter on reload).
         const marginSize = 2.0;
         final enabledRows = _countEnabledRows();
-        final marginsInView = enabledRows > 1 && enabledRows <= 3 ? (enabledRows - 1) * marginSize : 0.0;
-        final rowHeight = (availableHeight - marginsInView) / 3;
+        const marginsInView = 2 * marginSize; // always 2 margins for 3-row layout
+        final candidateRowHeight = (availableHeight - marginsInView) / 3;
+
+        // Cache rowHeight to prevent size jumps when the bottom nav bar toggles
+        // on connect/disconnect. The nav bar hides when disconnected, giving more
+        // vertical space and taller rows. When it reappears, rows shrink visibly.
+        // Fix: always ratchet down to the smaller (nav-bar-present) value, and
+        // only allow increases on large changes like screen rotation.
+        if (_cachedRowHeight == null || (candidateRowHeight - _cachedRowHeight!).abs() > 50) {
+          _cachedRowHeight = candidateRowHeight;
+        } else if (candidateRowHeight < _cachedRowHeight!) {
+          _cachedRowHeight = candidateRowHeight;
+        }
+        final rowHeight = _cachedRowHeight!;
 
         // Use Android 12+ stretch overscroll effect
         return NotificationListener<ScrollNotification>(
@@ -571,12 +527,15 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
             behavior: const _StretchScrollBehavior(),
             child: SingleChildScrollView(
               physics: const AlwaysScrollableScrollPhysics(),
-              padding: EdgeInsets.only(bottom: BottomSpacing.withMiniPlayer),
+              // For ≤3 rows: no padding needed (rows + miniPlayerSpace = viewport)
+              // For 4+ rows: pad by miniPlayerSpace so last row scrolls above mini player
+              padding: enabledRows >= 4
+                  ? EdgeInsets.only(bottom: miniPlayerSpace)
+                  : EdgeInsets.zero,
               child: SizedBox(
                 // Ensure minimum height for pull-to-refresh when empty
                 height: enabledRows == 0 ? availableHeight : null,
                 child: Column(
-                  key: _refreshKey,
                   crossAxisAlignment: CrossAxisAlignment.start,
                   children: _buildOrderedRows(provider, rowHeight, enabledRows == 0),
                 ),
@@ -634,9 +593,6 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
       return rows;
     }
 
-    // Track which discovery folders have been rendered (from main row order)
-    final renderedDiscoveryFolders = <String>{};
-
     for (final rowId in _homeRowOrder) {
       final widget = _buildRowWidget(rowId, provider, rowHeight);
       if (widget != null) {
@@ -645,42 +601,6 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
           rows.add(const SizedBox(height: 2.0));
         }
         rows.add(widget);
-        // Track discovery folders that were rendered from main row order
-        if (rowId.startsWith('discovery:')) {
-          renderedDiscoveryFolders.add(rowId.substring('discovery:'.length));
-        }
-      }
-    }
-
-    // Add legacy discovery folders that aren't in the main row order yet
-    // This ensures existing discovery folders still show even if not yet in _homeRowOrder
-    if (_discoveryFolders.isNotEmpty) {
-      for (final folder in _discoveryFolders) {
-        if (!renderedDiscoveryFolders.contains(folder.itemId)) {
-          final discoveryRowId = 'discovery:${folder.itemId}';
-          // Check if this specific discovery row is enabled
-          final isEnabled = _discoveryRowEnabled[folder.itemId] ?? false;
-          if (isEnabled) {
-            final widget = _buildRowWidget(discoveryRowId, provider, rowHeight);
-            if (widget != null) {
-              // Add spacing between rows
-              if (rows.isNotEmpty) {
-                rows.add(const SizedBox(height: 2.0));
-              }
-              rows.add(widget);
-            }
-          }
-        }
-      }
-    } else if (_isLoadingDiscoveryFolders && _discoveryFolders.isEmpty) {
-      // Show loading placeholder when discovery folders are loading
-      // Only if no discovery rows are in the main order
-      final hasDiscoveryRowsInOrder = _homeRowOrder.any((id) => id.startsWith('discovery:'));
-      if (!hasDiscoveryRowsInOrder) {
-        if (rows.isNotEmpty) {
-          rows.add(const SizedBox(height: 2.0));
-        }
-        rows.add(_buildDiscoveryLoadingPlaceholder(rowHeight));
       }
     }
 
@@ -697,6 +617,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
           title: S.of(context)!.recentlyPlayed,
           loadAlbums: () => provider.getRecentAlbumsWithCache(),
           getCachedAlbums: () => provider.getCachedRecentAlbums(),
+          refreshSignal: _refreshSignal,
           rowHeight: rowHeight,
         );
       case 'discover-artists':
@@ -706,6 +627,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
           title: S.of(context)!.discoverArtists,
           loadArtists: () => provider.getDiscoverArtistsWithCache(),
           getCachedArtists: () => provider.getCachedDiscoverArtists(),
+          refreshSignal: _refreshSignal,
           rowHeight: rowHeight,
         );
       case 'discover-albums':
@@ -715,6 +637,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
           title: S.of(context)!.discoverAlbums,
           loadAlbums: () => provider.getDiscoverAlbumsWithCache(),
           getCachedAlbums: () => provider.getCachedDiscoverAlbums(),
+          refreshSignal: _refreshSignal,
           rowHeight: rowHeight,
         );
       case 'continue-listening':
@@ -750,6 +673,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
           key: const ValueKey('favorite-albums'),
           title: S.of(context)!.favoriteAlbums,
           loadAlbums: () => provider.getFavoriteAlbums(),
+          refreshSignal: _refreshSignal,
           rowHeight: rowHeight,
         );
       case 'favorite-artists':
@@ -758,6 +682,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
           key: const ValueKey('favorite-artists'),
           title: S.of(context)!.favoriteArtists,
           loadArtists: () => provider.getFavoriteArtists(),
+          refreshSignal: _refreshSignal,
           rowHeight: rowHeight,
         );
       case 'favorite-tracks':

lib/screens/new_library_screen.dart

@@ -3410,7 +3410,17 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
   }
 
   // ============ PODCASTS TAB ============
+  // Consumer wrapper avoids using context.select inside PageView.builder's
+  // sliver context, which would rebuild the entire list instead of individual items.
   Widget _buildPodcastsTab(BuildContext context, S l10n) {
+    return Consumer<MusicAssistantProvider>(
+      builder: (context, maProvider, _) {
+        return _buildPodcastsTabContent(context, l10n, maProvider);
+      },
+    );
+  }
+
+  Widget _buildPodcastsTabContent(BuildContext context, S l10n, MusicAssistantProvider maProvider) {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
     // PERF: Use select() to only rebuild when podcasts, loading state, or enabled providers changes
@@ -3714,7 +3724,17 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
   }
 
   // ============ RADIO TAB ============
+  // Consumer wrapper avoids using context.select inside PageView.builder's
+  // sliver context, which would rebuild the entire list instead of individual items.
   Widget _buildRadioStationsTab(BuildContext context, S l10n) {
+    return Consumer<MusicAssistantProvider>(
+      builder: (context, maProvider, _) {
+        return _buildRadioTabContent(context, l10n, maProvider);
+      },
+    );
+  }
+
+  Widget _buildRadioTabContent(BuildContext context, S l10n, MusicAssistantProvider maProvider) {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
     // PERF: Use select() to only rebuild when radio stations, loading state, or enabled providers changes
@@ -3964,7 +3984,17 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
   }
 
   // ============ ARTISTS TAB ============
+  // Consumer wrapper avoids using context.select inside PageView.builder's
+  // sliver context, which would rebuild the entire list instead of individual items.
   Widget _buildArtistsTab(BuildContext context, S l10n) {
+    return Consumer<MusicAssistantProvider>(
+      builder: (context, maProvider, _) {
+        return _buildArtistsTabContent(context, l10n, maProvider);
+      },
+    );
+  }
+
+  Widget _buildArtistsTabContent(BuildContext context, S l10n, MusicAssistantProvider maProvider) {
     // Use select to only rebuild when specific fields change
     // SyncService changes are handled by _onSyncServiceChanged listener
     final (isLoading, enabledProviders) = context.select<MusicAssistantProvider, (bool, Set<String>)>(
@@ -4201,7 +4231,17 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
   }
 
   // ============ ALBUMS TAB ============
+  // Consumer wrapper avoids using context.select inside PageView.builder's
+  // sliver context, which would rebuild the entire list instead of individual items.
   Widget _buildAlbumsTab(BuildContext context, S l10n) {
+    return Consumer<MusicAssistantProvider>(
+      builder: (context, maProvider, _) {
+        return _buildAlbumsTabContent(context, l10n, maProvider);
+      },
+    );
+  }
+
+  Widget _buildAlbumsTabContent(BuildContext context, S l10n, MusicAssistantProvider maProvider) {
     // Use select to only rebuild when specific fields change
     // SyncService changes are handled by _onSyncServiceChanged listener
     final (isLoading, enabledProviders) = context.select<MusicAssistantProvider, (bool, Set<String>)>(

lib/screens/playlist_details_screen.dart

@@ -797,7 +797,9 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> with Sing
             final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
             final expandedHeight = coverSize + 70;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
               slivers: [
                 SliverAppBar(
                   expandedHeight: expandedHeight,
@@ -1052,12 +1054,13 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> with Sing
                             );
                           },
                           child: ListTile(
+                            contentPadding: const EdgeInsets.only(left: 12, right: 20),
                             leading: Row(
                               mainAxisSize: MainAxisSize.min,
                               children: [
                                 // Track number
                                 SizedBox(
-                                  width: 28,
+                                  width: 24,
                                   child: Text(
                                     '${index + 1}',
                                     style: textTheme.bodyMedium?.copyWith(
@@ -1066,7 +1069,7 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> with Sing
                                     textAlign: TextAlign.right,
                                   ),
                                 ),
-                                const SizedBox(width: 12),
+                                const SizedBox(width: 16),
                                 // Track artwork
                                 ClipRRect(
                                   borderRadius: BorderRadius.circular(4),
@@ -1115,25 +1118,28 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> with Sing
                               maxLines: 1,
                               overflow: TextOverflow.ellipsis,
                             ),
-                            trailing: Row(
-                              mainAxisSize: MainAxisSize.min,
-                              children: [
-                                if (HiResBadge.getTooltip(track) != null) ...[
-                                  HiResBadge.fromTrack(track, primaryColor: colorScheme.primary)!,
-                                  const SizedBox(width: 12),
-                                ],
-                                if (track.duration != null)
-                                  SizedBox(
-                                    width: 40,
-                                    child: Text(
-                                      _formatDuration(track.duration!),
-                                      style: textTheme.bodySmall?.copyWith(
-                                        color: colorScheme.onSurface.withOpacity(0.5),
+                            trailing: Padding(
+                              padding: const EdgeInsets.only(right: 4),
+                              child: Row(
+                                mainAxisSize: MainAxisSize.min,
+                                children: [
+                                  if (HiResBadge.getTooltip(track) != null) ...[
+                                    HiResBadge.fromTrack(track, primaryColor: colorScheme.primary)!,
+                                    const SizedBox(width: 12),
+                                  ],
+                                  if (track.duration != null)
+                                    SizedBox(
+                                      width: 40,
+                                      child: Text(
+                                        _formatDuration(track.duration!),
+                                        style: textTheme.bodySmall?.copyWith(
+                                          color: colorScheme.onSurface.withOpacity(0.5),
+                                        ),
+                                        textAlign: TextAlign.right,
                                       ),
-                                      textAlign: TextAlign.right,
                                     ),
-                                  ),
-                              ],
+                                ],
+                              ),
                             ),
                             onTap: () => _playTrack(index),
                           ),
@@ -1144,6 +1150,28 @@ class _PlaylistDetailsScreenState extends State<PlaylistDetailsScreen> with Sing
                   ),
                 SliverToBoxAdapter(child: SizedBox(height: BottomSpacing.withMiniPlayer)), // Space for bottom nav + mini player
               ],
+            ),
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.surface.withOpacity(0.0),
+                            colorScheme.surface,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
             );
           },
         ),

lib/screens/podcast_detail_screen.dart

@@ -654,7 +654,9 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
             final coverSize = (constraints.maxWidth * 0.7).clamp(200.0, 320.0);
             final expandedHeight = coverSize + 70;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
               slivers: [
                 SliverAppBar(
                   expandedHeight: expandedHeight,
@@ -1109,6 +1111,28 @@ class _PodcastDetailScreenState extends State<PodcastDetailScreen> {
                   child: SizedBox(height: BottomSpacing.withMiniPlayer),
                 ),
               ],
+            ),
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.surface.withOpacity(0.0),
+                            colorScheme.surface,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
             );
           },
         ),

lib/screens/podcast_episode_detail_screen.dart

@@ -255,7 +255,9 @@ class _PodcastEpisodeDetailScreenState extends State<PodcastEpisodeDetailScreen>
             final coverSize = (constraints.maxWidth * 0.6).clamp(180.0, 280.0);
             final expandedHeight = coverSize + 70;
 
-            return CustomScrollView(
+            return Stack(
+              children: [
+                CustomScrollView(
               slivers: [
                 SliverAppBar(
                   expandedHeight: expandedHeight,
@@ -495,6 +497,28 @@ class _PodcastEpisodeDetailScreenState extends State<PodcastEpisodeDetailScreen>
                   child: SizedBox(height: BottomSpacing.withMiniPlayer),
                 ),
               ],
+            ),
+                Positioned(
+                  left: 0,
+                  right: 0,
+                  bottom: 0,
+                  height: BottomSpacing.withMiniPlayer,
+                  child: IgnorePointer(
+                    child: DecoratedBox(
+                      decoration: BoxDecoration(
+                        gradient: LinearGradient(
+                          begin: Alignment.topCenter,
+                          end: Alignment.bottomCenter,
+                          colors: [
+                            colorScheme.surface.withOpacity(0.0),
+                            colorScheme.surface,
+                          ],
+                        ),
+                      ),
+                    ),
+                  ),
+                ),
+              ],
             );
           },
         ),

lib/screens/search_screen.dart

@@ -598,35 +598,47 @@ class SearchScreenState extends State<SearchScreen> {
                     ),
                     const SizedBox(width: 8),
                     // Library-only toggle with circle background
-                    Tooltip(
-                      message: S.of(context)!.libraryOnly,
-                      child: SizedBox(
-                        width: 44,
-                        height: 44,
-                        child: Material(
-                          color: colorScheme.surfaceContainerHighest.withOpacity(0.6),
-                          shape: const CircleBorder(),
-                          child: InkWell(
-                            onTap: () {
-                              setState(() {
-                                _libraryOnly = !_libraryOnly;
-                              });
-                              if (_searchController.text.isNotEmpty) {
-                                _performSearch(_searchController.text);
-                              }
-                            },
-                            customBorder: const CircleBorder(),
-                            child: Icon(
-                              Symbols.book_2,
-                              fill: _libraryOnly ? 1 : 0,
-                              size: 22,
-                              color: _libraryOnly
-                                  ? colorScheme.primary
-                                  : colorScheme.onSurface,
+                    LayoutBuilder(
+                      builder: (context, constraints) {
+                        final control = SizedBox(
+                          width: 44,
+                          height: 44,
+                          child: Material(
+                            color: colorScheme.surfaceContainerHighest.withOpacity(0.6),
+                            shape: const CircleBorder(),
+                            child: InkWell(
+                              onTap: () {
+                                setState(() {
+                                  _libraryOnly = !_libraryOnly;
+                                });
+                                if (_searchController.text.isNotEmpty) {
+                                  _performSearch(_searchController.text);
+                                }
+                              },
+                              customBorder: const CircleBorder(),
+                              child: Icon(
+                                Symbols.book_2,
+                                fill: _libraryOnly ? 1 : 0,
+                                size: 22,
+                                color: _libraryOnly
+                                    ? colorScheme.primary
+                                    : colorScheme.onSurface,
+                              ),
                             ),
                           ),
-                        ),
-                      ),
+                        );
+
+                        // Only use Tooltip if an Overlay ancestor exists
+                        final hasOverlay = Overlay.maybeOf(context) != null;
+                        if (!hasOverlay) {
+                          return control;
+                        }
+
+                        return Tooltip(
+                          message: S.of(context)!.libraryOnly,
+                          child: control,
+                        );
+                      },
                     ),
                   ],
                 ),

lib/screens/settings_screen.dart

@@ -12,6 +12,7 @@ import '../services/settings_service.dart';
 import '../theme/theme_provider.dart';
 import '../theme/app_theme.dart';
 import '../utils/page_transitions.dart';
+import '../providers/navigation_provider.dart';
 import '../widgets/global_player_overlay.dart';
 import 'debug_log_screen.dart';
 import 'login_screen.dart';
@@ -24,6 +25,7 @@ class SettingsScreen extends StatefulWidget {
 }
 
 class _SettingsScreenState extends State<SettingsScreen> {
+  final _scrollController = ScrollController();
   final _lastFmApiKeyController = TextEditingController();
   final _audioDbApiKeyController = TextEditingController();
   String _appVersion = '';
@@ -56,18 +58,42 @@ class _SettingsScreenState extends State<SettingsScreen> {
   Map<String, bool> _discoveryRowEnabled = {};
   bool _isLoadingDiscoveryFolders = false;
 
-  /// Filtered row order for the draggable list (excludes discovery-mixes)
-  /// Shows rows in home order, plus any discovery rows from provider that aren't in home order yet
+  /// All available static home screen rows (that can be toggled on/off)
+  static const List<String> _allAvailableRows = [
+    'recent-albums',
+    'discover-artists',
+    'discover-albums',
+    'discovery-mixes',
+    'continue-listening',
+    'discover-audiobooks',
+    'discover-series',
+    'favorite-albums',
+    'favorite-artists',
+    'favorite-tracks',
+    'favorite-playlists',
+    'favorite-radio-stations',
+    'favorite-podcasts',
+  ];
+
+  /// Filtered row order for the draggable list
+  /// Shows all available rows (in home order + discovery rows), regardless of enabled state
   List<String> get _filteredRowOrder {
     final rows = <String>[];
 
-    // First, add all rows from home order (excluding discovery-mixes)
+    // First, add all static rows in their current home order
     for (final rowId in _homeRowOrder) {
       if (rowId == 'discovery-mixes') continue;
       rows.add(rowId);
     }
 
-    // Then, add any discovery rows from provider that aren't in home order yet
+    // Then, add any static rows that aren't in home order yet (so users can enable them)
+    for (final rowId in _allAvailableRows) {
+      if (!_homeRowOrder.contains(rowId) && rowId != 'discovery-mixes') {
+        rows.add(rowId);
+      }
+    }
+
+    // Finally, add any discovery rows from provider that aren't in home order yet
     for (final folder in _discoveryFolders) {
       final discoveryRowId = 'discovery:${folder.itemId}';
       if (!_homeRowOrder.contains(discoveryRowId)) {
@@ -166,6 +192,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
 
   @override
   void dispose() {
+    _scrollController.dispose();
     _lastFmApiKeyController.dispose();
     _audioDbApiKeyController.dispose();
     super.dispose();
@@ -326,9 +353,15 @@ class _SettingsScreenState extends State<SettingsScreen> {
         final itemId = rowId.substring('discovery:'.length);
         _discoveryRowEnabled[itemId] = value;
         SettingsService.setDiscoveryRowPreference(itemId, value);
+        // Always add to home row order for position tracking
+        if (!_homeRowOrder.contains(rowId)) {
+          _homeRowOrder.add(rowId);
+          SettingsService.setHomeRowOrder(_homeRowOrder);
+        }
         return;
       }
 
+      // Save the setting
       switch (rowId) {
         case 'recent-albums':
           _showRecentAlbums = value;
@@ -378,6 +411,14 @@ class _SettingsScreenState extends State<SettingsScreen> {
           _showFavoritePodcasts = value;
           SettingsService.setShowFavoritePodcasts(value);
           break;
+        default:
+          break;
+      }
+
+      // When enabling a row, add it to home row order if not already present
+      if (value && !_homeRowOrder.contains(rowId)) {
+        _homeRowOrder.add(rowId);
+        SettingsService.setHomeRowOrder(_homeRowOrder);
       }
     });
   }
@@ -412,7 +453,13 @@ class _SettingsScreenState extends State<SettingsScreen> {
         elevation: 0,
         leading: IconButton(
           icon: const Icon(Icons.arrow_back_rounded),
-          onPressed: () => Navigator.pop(context),
+          onPressed: () {
+            // Settings is rendered conditionally in HomeScreen (not pushed as a route),
+            // so Navigator.pop would pop the entire HomeScreen causing a black screen.
+            // Instead, switch tab back to Home and restore the mini player.
+            GlobalPlayerOverlay.showPlayer();
+            navigationProvider.setSelectedIndex(0);
+          },
           color: colorScheme.onBackground,
         ),
         title: Text(
@@ -438,6 +485,7 @@ class _SettingsScreenState extends State<SettingsScreen> {
         ],
       ),
       body: SingleChildScrollView(
+        controller: _scrollController,
         padding: const EdgeInsets.all(24.0),
         child: Column(
           crossAxisAlignment: CrossAxisAlignment.center,
@@ -1003,21 +1051,8 @@ class _SettingsScreenState extends State<SettingsScreen> {
                   displayRows.insert(newIndex, item);
 
                   setState(() {
-                    // Update _homeRowOrder with the new order
-                    _homeRowOrder.clear();
-
-                    // Add discovery rows that are enabled
-                    for (final rowId in displayRows) {
-                      if (rowId.startsWith('discovery:')) {
-                        // Only add enabled discovery rows to home order
-                        final itemId = rowId.substring('discovery:'.length);
-                        if (_discoveryRowEnabled[itemId] ?? false) {
-                          _homeRowOrder.add(rowId);
-                        }
-                      } else {
-                        _homeRowOrder.add(rowId);
-                      }
-                    }
+                    // Update _homeRowOrder with the new order (all rows, including discovery)
+                    _homeRowOrder = displayRows;
                   });
                   SettingsService.setHomeRowOrder(_homeRowOrder);
                 },

lib/services/group_volume_manager.dart

@@ -0,0 +1,175 @@
+import '../models/player.dart';
+import 'debug_logger.dart';
+
+/// Manages volume state for group players where the MA API returns null volume.
+///
+/// Both pre-configured speaker groups (provider == 'player_group') and dynamic
+/// sync groups (ID typically starts with 'syncgroup_') don't have their own
+/// volume_level in the MA API. This manager computes an effective volume from
+/// group members and caches recently-set volumes to prevent slider snap-back.
+class GroupVolumeManager {
+  final _logger = DebugLogger();
+
+  // Cache of last-set volume per group player ID.
+  // Prevents slider snap-back between setVolume() and next player_updated event.
+  final Map<String, int> _pendingVolumes = {};
+
+  // Timestamps for pending volumes - used to expire stale entries
+  final Map<String, DateTime> _pendingTimestamps = {};
+
+  // How long to trust a pending volume before falling back to computed average.
+  // For group players the API never returns a volume, so we keep the pending
+  // value until the computed member average converges (within tolerance) or
+  // until a generous timeout to avoid leaking state forever.
+  static const Duration _pendingTimeout = Duration(seconds: 30);
+
+  // If the computed member average is within this many points of the pending
+  // value, we consider the server to have confirmed it and clear the pending.
+  static const int _confirmationTolerance = 3;
+
+  /// Check if a player is a group player that needs computed volume.
+  ///
+  /// Detects both:
+  /// - Pre-configured MA speaker groups (provider == 'player_group')
+  /// - Dynamic sync groups (have group members but API returns null volume)
+  bool isGroupPlayer(Player player) {
+    // Pre-configured MA speaker groups
+    if (player.provider == 'player_group') return true;
+    // Dynamic sync groups: have multiple group members but MA returns null volume
+    if (player.groupMembers != null &&
+        player.groupMembers!.length > 1 &&
+        player.volumeLevel == null) {
+      return true;
+    }
+    return false;
+  }
+
+  /// Get the effective volume for a player.
+  ///
+  /// For non-group players: returns player.volumeLevel (unchanged behavior).
+  /// For group players: returns cached pending volume if recent, otherwise
+  /// computes average from group members.
+  ///
+  /// [player] - The player to get volume for.
+  /// [allPlayers] - All available players (needed to look up group members).
+  ///
+  /// Returns volume as int 0-100, or null if no volume can be determined.
+  int? getEffectiveVolumeLevel(Player player, List<Player> allPlayers) {
+    if (!isGroupPlayer(player)) {
+      return player.volumeLevel;
+    }
+
+    // Check for a pending (just-set) volume
+    final pending = _pendingVolumes[player.playerId];
+    if (pending != null) {
+      final timestamp = _pendingTimestamps[player.playerId];
+      if (timestamp != null &&
+          DateTime.now().difference(timestamp) < _pendingTimeout) {
+        // Compute member average to see if server has converged
+        final memberAvg = _computeGroupVolume(player, allPlayers);
+        if (memberAvg != null && (memberAvg - pending).abs() <= _confirmationTolerance) {
+          // Server confirmed — member average matches what we set
+          _pendingVolumes.remove(player.playerId);
+          _pendingTimestamps.remove(player.playerId);
+          _logger.debug(
+              'GroupVolume: Convergence confirmed for ${player.name}: '
+              'pending=$pending, memberAvg=$memberAvg',
+              context: 'GroupVolumeManager');
+          return memberAvg;
+        }
+        // Not yet confirmed — keep showing the pending value
+        _logger.debug(
+            'GroupVolume: Pending protection active for ${player.name}: '
+            'pending=$pending, memberAvg=$memberAvg, '
+            'elapsed=${DateTime.now().difference(timestamp).inSeconds}s',
+            context: 'GroupVolumeManager');
+        return pending;
+      }
+      // Expired after generous timeout — remove it
+      _logger.debug(
+          'GroupVolume: Pending expired for ${player.name} after ${_pendingTimeout.inSeconds}s, '
+          'falling back to computed average',
+          context: 'GroupVolumeManager');
+      _pendingVolumes.remove(player.playerId);
+      _pendingTimestamps.remove(player.playerId);
+    }
+
+    // Compute average from group members
+    return _computeGroupVolume(player, allPlayers);
+  }
+
+  /// Compute the average volume across all group members.
+  /// Recursively resolves nested group members (MA sometimes makes the first
+  /// member of a group also a group player, which returns null for volumeLevel).
+  /// Returns null if no members have a valid volume.
+  int? _computeGroupVolume(Player groupPlayer, List<Player> allPlayers,
+      {int depth = 0}) {
+    // Prevent infinite recursion from circular group references
+    if (depth > 3) return null;
+
+    final memberIds = groupPlayer.groupMembers;
+    if (memberIds == null || memberIds.isEmpty) {
+      _logger.debug('GroupVolume: No group members for ${groupPlayer.name}',
+          context: 'GroupVolumeManager');
+      return null;
+    }
+
+    int totalVolume = 0;
+    int count = 0;
+
+    for (final memberId in memberIds) {
+      // Skip self-references (groupMembers can include the group's own ID)
+      if (memberId == groupPlayer.playerId) continue;
+
+      final member =
+          allPlayers.where((p) => p.playerId == memberId).firstOrNull;
+      if (member == null) continue;
+
+      if (member.volumeLevel != null) {
+        totalVolume += member.volumeLevel!;
+        count++;
+      } else if (isGroupPlayer(member)) {
+        // Nested group player — MA returns null volumeLevel for these.
+        // Recursively compute from the nested group's own members.
+        final subVolume =
+            _computeGroupVolume(member, allPlayers, depth: depth + 1);
+        if (subVolume != null) {
+          totalVolume += subVolume;
+          count++;
+          _logger.debug(
+              'GroupVolume: Resolved nested group ${member.name} → volume $subVolume',
+              context: 'GroupVolumeManager');
+        }
+      }
+    }
+
+    if (count == 0) {
+      _logger.debug(
+          'GroupVolume: No members with volume for ${groupPlayer.name} '
+          '(${memberIds.length} members checked, depth=$depth)',
+          context: 'GroupVolumeManager');
+      return null;
+    }
+
+    final avg = (totalVolume / count).round();
+    _logger.debug(
+        'GroupVolume: ${groupPlayer.name} average=$avg from $count members '
+        '(total=$totalVolume, depth=$depth)',
+        context: 'GroupVolumeManager');
+    return avg;
+  }
+
+  /// Record that a volume was just set on a group player.
+  /// This prevents the slider from snapping back to 0 before the
+  /// MA server processes the volume change on all members.
+  void onVolumeSet(String playerId, int volumeLevel) {
+    _pendingVolumes[playerId] = volumeLevel;
+    _pendingTimestamps[playerId] = DateTime.now();
+  }
+
+  /// Clear all cached state (e.g., on disconnect)
+  void clear() {
+    _pendingVolumes.clear();
+    _pendingTimestamps.clear();
+  }
+}

lib/services/hardware_volume_service.dart

@@ -7,6 +7,11 @@ import 'debug_logger.dart';
 ///
 /// For MA players: intercept buttons and send volume commands via API
 /// For builtin player: let native volume work (don't intercept)
+///
+/// Also provides a volume observer for lockscreen volume changes.
+/// When the app is in the background/lockscreen, dispatchKeyEvent doesn't fire,
+/// so the observer watches system STREAM_MUSIC volume changes and sends
+/// absolute volume values to Flutter for routing to the MA player.
 class HardwareVolumeService {
   static final HardwareVolumeService _instance = HardwareVolumeService._internal();
   factory HardwareVolumeService() => _instance;
@@ -17,16 +22,25 @@ class HardwareVolumeService {
 
   final _volumeUpController = StreamController<void>.broadcast();
   final _volumeDownController = StreamController<void>.broadcast();
+  final _absoluteVolumeController = StreamController<int>.broadcast();
 
   Stream<void> get onVolumeUp => _volumeUpController.stream;
   Stream<void> get onVolumeDown => _volumeDownController.stream;
 
+  /// Stream of absolute volume values (0-100) from lockscreen hardware buttons.
+  /// Fires when the system STREAM_MUSIC volume changes while the volume
+  /// observer is active (remote/group player selected, app in background).
+  Stream<int> get onAbsoluteVolumeChange => _absoluteVolumeController.stream;
+
   bool _isListening = false;
   bool get isListening => _isListening;
 
   bool _isIntercepting = false;
   bool get isIntercepting => _isIntercepting;
 
+  bool _isObservingVolume = false;
+  bool get isObservingVolume => _isObservingVolume;
+
   /// Initialize the service and start listening for volume button events
   Future<void> init() async {
     if (_isListening) return;
@@ -39,6 +53,11 @@ class HardwareVolumeService {
         case 'volumeDown':
           _volumeDownController.add(null);
           break;
+        case 'absoluteVolumeChange':
+          // Volume changed from lockscreen/background via ContentObserver
+          final volume = call.arguments as int? ?? 0;
+          _absoluteVolumeController.add(volume);
+          break;
       }
     });
 
@@ -70,8 +89,53 @@ class HardwareVolumeService {
     }
   }
 
+  /// Start the volume observer for lockscreen/background volume changes.
+  /// When active, system STREAM_MUSIC volume changes are detected and sent
+  /// to Flutter via [onAbsoluteVolumeChange]. Optionally sets the system
+  /// volume to [initialVolume] (0-100) to match the MA player's current volume.
+  Future<void> startVolumeObserver({int? initialVolume}) async {
+    if (_isObservingVolume) return;
+
+    try {
+      await _channel.invokeMethod('startVolumeObserver', {
+        if (initialVolume != null) 'initialVolume': initialVolume,
+      });
+      _isObservingVolume = true;
+      _logger.info('Volume observer started', context: 'VolumeService');
+    } catch (e) {
+      _logger.error('Failed to start volume observer', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Stop the volume observer.
+  Future<void> stopVolumeObserver() async {
+    if (!_isObservingVolume) return;
+
+    try {
+      await _channel.invokeMethod('stopVolumeObserver');
+      _isObservingVolume = false;
+      _logger.info('Volume observer stopped', context: 'VolumeService');
+    } catch (e) {
+      _logger.error('Failed to stop volume observer', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Sync the system volume to match the MA player volume (0-100).
+  /// Used to keep the system volume HUD in sync with the MA player.
+  Future<void> syncSystemVolume(int maVolume) async {
+    try {
+      await _channel.invokeMethod('syncSystemVolume', {'volume': maVolume});
+    } catch (e) {
+      _logger.error('Failed to sync system volume', context: 'VolumeService', error: e);
+    }
+  }
+
   /// Stop listening for volume button events
   Future<void> dispose() async {
+    if (_isObservingVolume) {
+      await stopVolumeObserver();
+    }
+
     if (!_isListening) return;
 
     try {
@@ -86,5 +150,6 @@ class HardwareVolumeService {
     // Close StreamControllers to prevent memory leaks
     await _volumeUpController.close();
     await _volumeDownController.close();
+    await _absoluteVolumeController.close();
   }
 }

lib/services/music_assistant_api.dart

@@ -1466,9 +1466,10 @@ class MusicAssistantAPI {
         final futures = batch.map((uri) => _sendCommand(
           'music/item_by_uri',
           args: {'uri': uri},
-        ).timeout(const Duration(seconds: 5), onTimeout: () => <String, dynamic>{'result': null}));
+        ).timeout(const Duration(seconds: 5), onTimeout: () => <String, dynamic>{'result': null})
+         .catchError((_) => <String, dynamic>{'result': null}));
 
-        final results = await Future.wait(futures, eagerError: false);
+        final results = await Future.wait(futures);
 
         for (final trackResponse in results) {
           if (albumUris.length >= limit) break;
@@ -1505,9 +1506,10 @@ class MusicAssistantAPI {
         final futures = batch.map((uri) => _sendCommand(
           'music/item_by_uri',
           args: {'uri': uri},
-        ).timeout(const Duration(seconds: 5), onTimeout: () => <String, dynamic>{'result': null}));
+        ).timeout(const Duration(seconds: 5), onTimeout: () => <String, dynamic>{'result': null})
+         .catchError((_) => <String, dynamic>{'result': null}));
 
-        final results = await Future.wait(futures, eagerError: false);
+        final results = await Future.wait(futures);
 
         for (final albumResponse in results) {
           try {

lib/services/sync_service.dart

@@ -173,7 +173,9 @@ class SyncService with ChangeNotifier {
     }
 
     // Check if sync is needed (default: every 5 minutes)
-    if (!force) {
+    // Always sync if cache is empty (no albums AND no artists loaded)
+    final cacheEmpty = _cachedAlbums.isEmpty && _cachedArtists.isEmpty;
+    if (!force && !cacheEmpty) {
       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));

lib/widgets/album_card.dart

@@ -59,15 +59,20 @@ class _AlbumCardState extends State<AlbumCard> with LibraryStatusMixin {
   @override
   void initState() {
     super.initState();
-    // Initialize status in centralized service from widget data
-    final service = LibraryStatusService.instance;
-    final key = libraryItemKey;
-    if (!service.isInLibrary(key) && widget.album.inLibrary) {
-      service.setLibraryStatus(key, true);
-    }
-    if (!service.isFavorite(key) && (widget.album.favorite ?? false)) {
-      service.setFavoriteStatus(key, true);
-    }
+    // Defer status initialization to after the build frame completes.
+    // setLibraryStatus() calls notifyListeners() synchronously, which triggers
+    // setState() in listening widgets — illegal during the build phase.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      final service = LibraryStatusService.instance;
+      final key = libraryItemKey;
+      if (!service.isInLibrary(key) && widget.album.inLibrary) {
+        service.setLibraryStatus(key, true);
+      }
+      if (!service.isFavorite(key) && (widget.album.favorite ?? false)) {
+        service.setFavoriteStatus(key, true);
+      }
+    });
     _initFallbackImage();
   }
 

lib/widgets/album_row.dart

@@ -14,6 +14,8 @@ class AlbumRow extends StatefulWidget {
   final double? rowHeight;
   /// Optional: synchronous getter for cached data (for instant display)
   final List<Album>? Function()? getCachedAlbums;
+  /// Optional: signal to trigger in-place reload without destroying the widget
+  final ValueNotifier<int>? refreshSignal;
 
   const AlbumRow({
     super.key,
@@ -22,6 +24,7 @@ class AlbumRow extends StatefulWidget {
     this.heroTagSuffix,
     this.rowHeight,
     this.getCachedAlbums,
+    this.refreshSignal,
   });
 
   @override
@@ -46,6 +49,19 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
       _isLoading = false;
     }
     _loadAlbums();
+    widget.refreshSignal?.addListener(_onRefreshSignal);
+  }
+
+  void _onRefreshSignal() {
+    if (!mounted) return;
+    _hasLoaded = false;
+    _loadAlbums();
+  }
+
+  @override
+  void dispose() {
+    widget.refreshSignal?.removeListener(_onRefreshSignal);
+    super.dispose();
   }
 
   Future<void> _loadAlbums() async {

lib/widgets/artist_card.dart

@@ -59,15 +59,20 @@ class _ArtistCardState extends State<ArtistCard> with LibraryStatusMixin {
   @override
   void initState() {
     super.initState();
-    // Initialize status in centralized service from widget data
-    final service = LibraryStatusService.instance;
-    final key = libraryItemKey;
-    if (!service.isInLibrary(key) && widget.artist.inLibrary) {
-      service.setLibraryStatus(key, true);
-    }
-    if (!service.isFavorite(key) && (widget.artist.favorite ?? false)) {
-      service.setFavoriteStatus(key, true);
-    }
+    // Defer status initialization to after the build frame completes.
+    // setLibraryStatus() calls notifyListeners() synchronously, which triggers
+    // setState() in listening widgets — illegal during the build phase.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      final service = LibraryStatusService.instance;
+      final key = libraryItemKey;
+      if (!service.isInLibrary(key) && widget.artist.inLibrary) {
+        service.setLibraryStatus(key, true);
+      }
+      if (!service.isFavorite(key) && (widget.artist.favorite ?? false)) {
+        service.setFavoriteStatus(key, true);
+      }
+    });
     // Fetch fallback image once in initState, not during build
     _initFallbackImage();
   }

lib/widgets/artist_row.dart

@@ -14,6 +14,8 @@ class ArtistRow extends StatefulWidget {
   final double? rowHeight;
   /// Optional: synchronous getter for cached data (for instant display)
   final List<Artist>? Function()? getCachedArtists;
+  /// Optional: signal to trigger in-place reload without destroying the widget
+  final ValueNotifier<int>? refreshSignal;
 
   const ArtistRow({
     super.key,
@@ -22,6 +24,7 @@ class ArtistRow extends StatefulWidget {
     this.heroTagSuffix,
     this.rowHeight,
     this.getCachedArtists,
+    this.refreshSignal,
   });
 
   @override
@@ -46,6 +49,19 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
       _isLoading = false;
     }
     _loadArtists();
+    widget.refreshSignal?.addListener(_onRefreshSignal);
+  }
+
+  void _onRefreshSignal() {
+    if (!mounted) return;
+    _hasLoaded = false;
+    _loadArtists();
+  }
+
+  @override
+  void dispose() {
+    widget.refreshSignal?.removeListener(_onRefreshSignal);
+    super.dispose();
   }
 
   Future<void> _loadArtists() async {

lib/widgets/expandable_player.dart

@@ -140,6 +140,10 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
   static const double _collapsedBorderRadius = 16.0;
   static double get _collapsedArtSize => MiniPlayerLayout.artSize;
   static const double _bottomNavHeight = 56.0;
+
+  // Animation for hiding bottom nav offset on detail screens
+  late AnimationController _detailScreenController;
+  bool _lastIsOnDetailScreen = false;
   static const double _edgeDeadZone = 40.0; // Dead zone for Android back gesture
 
   // Pastel yellow for grouped players (matches PlayerCard.groupBorderColor)
@@ -318,6 +322,13 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     // Track lyrics scroll position for swipe-to-close (only allowed at top)
     _lyricsScrollController.addListener(_onLyricsScroll);
 
+    // Animation for transitioning mini player when entering/leaving detail screens
+    _detailScreenController = AnimationController(
+      duration: const Duration(milliseconds: 150),
+      vsync: this,
+    );
+    _detailScreenController.addListener(_onDetailScreenAnimation);
+
     // Slide animation for device switching - used for snap/spring animations
     _slideController = AnimationController(
       duration: const Duration(milliseconds: 250),
@@ -356,6 +367,10 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     _loadVolumePrecisionModeSetting();
   }
 
+  void _onDetailScreenAnimation() {
+    if (mounted) setState(() {});
+  }
+
   Future<void> _loadVolumePrecisionModeSetting() async {
     final enabled = await SettingsService.getVolumePrecisionMode();
     if (mounted) {
@@ -415,6 +430,7 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     // (Controllers remove listeners on dispose, but explicit removal is clearer)
     _controller.removeListener(_notifyExpansionProgress);
     _controller.removeListener(_recordAnimationFrame);
+    _detailScreenController.removeListener(_onDetailScreenAnimation);
     _lyricsScrollController.removeListener(_onLyricsScroll);
 
     _controller.dispose();
@@ -422,6 +438,7 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     _sleepTimerPanelController.dispose();
     _lyricsPanelController.dispose();
     _slideController.dispose();
+    _detailScreenController.dispose();
     _slideOffsetNotifier.dispose();
     _positionSubscription?.cancel();
     _queueItemsSubscription?.cancel();
@@ -1794,9 +1811,23 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
   Widget build(BuildContext context) {
     // PERF: Use select() to only rebuild when adaptive theme setting changes
     final adaptiveTheme = context.select<ThemeProvider, bool>((p) => p.adaptiveTheme);
+    // Watch detail screen state to animate mini player position
+    final isOnDetailScreen = context.select<ThemeProvider, bool>((p) => p.isOnDetailScreen);
     // Get full themeProvider for methods that need adaptive color schemes
     final themeProvider = context.read<ThemeProvider>();
 
+    // Animate bottom nav offset when entering/leaving detail screens
+    if (isOnDetailScreen != _lastIsOnDetailScreen) {
+      _lastIsOnDetailScreen = isOnDetailScreen;
+      if (isOnDetailScreen) {
+        _detailScreenController.duration = const Duration(milliseconds: 100);
+        _detailScreenController.forward();
+      } else {
+        _detailScreenController.duration = const Duration(milliseconds: 80);
+        _detailScreenController.reverse();
+      }
+    }
+
     return Consumer<MusicAssistantProvider>(
       builder: (context, maProvider, child) {
         final selectedPlayer = maProvider.selectedPlayer;
@@ -1925,7 +1956,8 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
         ? adaptiveScheme.onPrimaryContainer
         : colorScheme.onPrimaryContainer;
 
-    final bottomNavSpace = _bottomNavHeight + bottomPadding;
+    final effectiveNavHeight = _bottomNavHeight * (1.0 - _detailScreenController.value);
+    final bottomNavSpace = effectiveNavHeight + bottomPadding;
     final bottomOffset = bottomNavSpace + _collapsedMargin;
     final width = screenSize.width - (_collapsedMargin * 2);
 
@@ -2074,9 +2106,10 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     final textAlignment = Alignment.lerp(Alignment.centerLeft, Alignment.center, t)!;
     final titleFontWeight = FontWeight.lerp(MiniPlayerLayout.primaryFontWeight, FontWeight.w600, t);
 
-    // Collapsed: position above bottom nav bar
+    // Collapsed: position above bottom nav bar (or at bottom edge on detail screens)
     // Expanded: extend to very bottom (behind system nav bar) for seamless edge-to-edge
-    final bottomNavSpace = _bottomNavHeight + bottomPadding;
+    final effectiveNavHeight = _bottomNavHeight * (1.0 - _detailScreenController.value);
+    final bottomNavSpace = effectiveNavHeight + bottomPadding;
     final collapsedBottomOffset = bottomNavSpace + _collapsedMargin;
     final expandedBottomOffset = 0.0; // Extend behind system nav bar
     final expandedHeight = screenSize.height; // Full screen height for edge-to-edge
@@ -2250,6 +2283,10 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
     // Smoothly fade out horizontal slide offset (for device switching) as animation progresses
     final miniPlayerSlideOffset = _slideOffset * collapsedWidth * offsetFade;
 
+    // Extend gesture hit area above mini player for easier swipe-down,
+    // especially on detail screens where the player sits closer to screen edge.
+    const _gestureExtension = 20.0;
+
     return Positioned(
       left: horizontalMargin,
       right: horizontalMargin,
@@ -2475,7 +2512,12 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
             });
           }
         },
-        child: Container(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            // Invisible gesture extension area above mini player
+            if (!isExpanded) const SizedBox(height: _gestureExtension),
+            Container(
           // PERF Phase 4: Only show shadow when meaningfully visible (t < 0.5)
           // This avoids BoxDecoration allocation for majority of animation frames
           // Shadow fades out quickly during first half of expansion
@@ -3415,6 +3457,8 @@ class ExpandablePlayerState extends State<ExpandablePlayer>
           ),
         ),
         ),
+          ],
+        ),
       ),
     );
   }

lib/widgets/global_player_overlay.dart

@@ -3,51 +3,16 @@ import 'dart:ui';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
-import 'package:material_symbols_icons/symbols.dart';
 import '../l10n/app_localizations.dart';
 import '../providers/music_assistant_provider.dart';
 import '../providers/navigation_provider.dart';
-import '../services/settings_service.dart';
 import '../theme/theme_provider.dart';
+import '../services/settings_service.dart';
 
 import 'expandable_player.dart';
 import 'player/mini_player_content.dart' show MiniPlayerLayout;
 import 'player/player_reveal_overlay.dart';
 
-/// Cached color with contrast adjustment
-/// Avoids expensive HSL conversions during scroll
-class _CachedNavColor {
-  Color? _sourceColor;
-  bool? _isDark;
-  Color? _adjustedColor;
-
-  Color getAdjustedColor(Color sourceColor, bool isDark) {
-    // Return cached value if inputs haven't changed
-    if (_sourceColor == sourceColor && _isDark == isDark && _adjustedColor != null) {
-      return _adjustedColor!;
-    }
-
-    // Compute new adjusted color
-    var navSelectedColor = sourceColor;
-    if (isDark && navSelectedColor.computeLuminance() < 0.2) {
-      final hsl = HSLColor.fromColor(navSelectedColor);
-      navSelectedColor = hsl.withLightness((hsl.lightness + 0.3).clamp(0.0, 0.8)).toColor();
-    } else if (!isDark && navSelectedColor.computeLuminance() > 0.8) {
-      final hsl = HSLColor.fromColor(navSelectedColor);
-      navSelectedColor = hsl.withLightness((hsl.lightness - 0.3).clamp(0.2, 1.0)).toColor();
-    }
-
-    // Cache the result
-    _sourceColor = sourceColor;
-    _isDark = isDark;
-    _adjustedColor = navSelectedColor;
-
-    return navSelectedColor;
-  }
-}
-
-final _cachedNavColor = _CachedNavColor();
-
 /// A global key to access the player state from anywhere in the app
 final globalPlayerKey = GlobalKey<ExpandablePlayerState>();
 
@@ -197,6 +162,7 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
   // State for player reveal overlay
   bool _isRevealVisible = false;
 
+
   // State for interactive hint mode (blur backdrop + wait for user action)
   bool _isHintModeActive = false;
   Timer? _hintBounceTimer;
@@ -530,138 +496,9 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
           padding: const EdgeInsets.only(bottom: 0), // Content manages its own padding
           child: widget.child,
         ),
-        // Global persistent bottom navigation bar - positioned at bottom
-        // Hide when: not connected OR showing welcome screen
-        // Always show when connected so users can access Settings/Library even without a player
-        if (isConnected && !shouldShowWelcomeBackdrop)
-          Positioned(
-            left: 0,
-            right: 0,
-            bottom: 0,
-            child: ListenableBuilder(
-              listenable: navigationProvider,
-              builder: (context, _) {
-                return Consumer<ThemeProvider>(
-                builder: (context, themeProvider, _) {
-                  final isDark = Theme.of(context).brightness == Brightness.dark;
+        // BottomNavigationBar is now in HomeScreen's Scaffold.bottomNavigationBar
+        // for proper Navigator/Overlay ancestry
 
-                  return ValueListenableBuilder<PlayerExpansionState>(
-                    valueListenable: playerExpansionNotifier,
-                    builder: (context, expansionState, _) {
-                      // Nav bar color logic - only use adaptive colors when:
-                      // 1. Player is expanding/expanded, OR
-                      // 2. On a detail screen (isOnDetailScreen)
-                      // On home screen with collapsed player: always use default theme colors
-                      final bool useAdaptiveColors = themeProvider.adaptiveTheme &&
-                          (expansionState.progress > 0 || themeProvider.isOnDetailScreen);
-
-                      // Nav bar background color
-                      final Color navBgColor;
-                      if (expansionState.progress > 0 && expansionState.backgroundColor != null) {
-                        // Player is expanding - blend from surface to player's adaptive color
-                        navBgColor = Color.lerp(colorScheme.surface, expansionState.backgroundColor, expansionState.progress)!;
-                      } else if (useAdaptiveColors) {
-                        // On a detail screen - use adaptive surface color for nav bar
-                        final adaptiveBg = themeProvider.getAdaptiveSurfaceColorFor(Theme.of(context).brightness);
-                        navBgColor = adaptiveBg ?? colorScheme.surface;
-                      } else {
-                        // Home screen with collapsed player - use default surface color
-                        navBgColor = colorScheme.surface;
-                      }
-
-                      // Icon color - only use adaptive colors when appropriate
-                      final Color baseSourceColor = (useAdaptiveColors && themeProvider.adaptiveColors != null)
-                          ? themeProvider.adaptiveColors!.primary
-                          : colorScheme.primary;
-
-                      // Blend icon color with player's primary color during expansion
-                      Color sourceColor = baseSourceColor;
-                      if (themeProvider.adaptiveTheme && expansionState.progress > 0 && expansionState.primaryColor != null) {
-                        sourceColor = Color.lerp(baseSourceColor, expansionState.primaryColor!, expansionState.progress)!;
-                      }
-                      final navSelectedColor = _cachedNavColor.getAdjustedColor(sourceColor, isDark);
-
-                      // Fade out and slide down nav bar as player expands
-                      // Use IgnorePointer when faded to prevent accidental taps
-                      final navOpacity = (1.0 - expansionState.progress * 2).clamp(0.0, 1.0);
-                      final navSlideDown = expansionState.progress * 20; // Slide down 20px as it fades
-
-                      return IgnorePointer(
-                        ignoring: navOpacity < 0.1,
-                        child: Transform.translate(
-                          offset: Offset(0, navSlideDown),
-                          child: Opacity(
-                            opacity: navOpacity,
-                            child: Container(
-                              decoration: BoxDecoration(
-                                color: navBgColor,
-                                boxShadow: expansionState.progress < 0.5
-                                    ? [
-                                        BoxShadow(
-                                          color: Colors.black.withOpacity(0.1),
-                                          blurRadius: 10,
-                                          offset: const Offset(0, -2),
-                                        ),
-                                      ]
-                                    : null,
-                              ),
-                              child: BottomNavigationBar(
-                                currentIndex: navigationProvider.selectedIndex,
-                                onTap: (index) {
-                                  if (GlobalPlayerOverlay.isPlayerExpanded) {
-                                    GlobalPlayerOverlay.collapsePlayer();
-                                  }
-                                  navigationProvider.navigatorKey.currentState?.popUntil((route) => route.isFirst);
-                                  // Clear adaptive colors when switching tabs (detail screen colors shouldn't persist)
-                                  themeProvider.clearAdaptiveColors();
-                                  if (index == 3) {
-                                    GlobalPlayerOverlay.hidePlayer();
-                                  } else if (navigationProvider.selectedIndex == 3) {
-                                    GlobalPlayerOverlay.showPlayer();
-                                  }
-                                  navigationProvider.setSelectedIndex(index);
-                                },
-                                backgroundColor: Colors.transparent,
-                                selectedItemColor: navSelectedColor,
-                                unselectedItemColor: colorScheme.onSurface.withOpacity(0.54),
-                                elevation: 0,
-                                type: BottomNavigationBarType.fixed,
-                                selectedFontSize: 12,
-                                unselectedFontSize: 12,
-                                items: [
-                                  BottomNavigationBarItem(
-                                    icon: const Icon(Icons.home_outlined),
-                                    activeIcon: const Icon(Icons.home_rounded),
-                                    label: S.of(context)!.home,
-                                  ),
-                                  BottomNavigationBarItem(
-                                    icon: const Icon(Symbols.book_2, fill: 0),
-                                    activeIcon: const Icon(Symbols.book_2, fill: 1),
-                                    label: S.of(context)!.library,
-                                  ),
-                                  BottomNavigationBarItem(
-                                    icon: const Icon(Icons.search_rounded),
-                                    activeIcon: const Icon(Icons.search_rounded),
-                                    label: S.of(context)!.search,
-                                  ),
-                                  BottomNavigationBarItem(
-                                    icon: const Icon(Icons.settings_outlined),
-                                    activeIcon: const Icon(Icons.settings_rounded),
-                                    label: S.of(context)!.settings,
-                                  ),
-                                ],
-                              ),
-                            ),
-                          ),
-                        ),
-                      );
-                    },
-                  );
-                },
-              );
-              },
-            ),
-          ),
         // Blur backdrop for device selector (reveal mode) - static, no animation
         if (_isRevealVisible && !_isHintModeActive)
           Positioned.fill(
@@ -788,8 +625,9 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
           PlayerRevealOverlay(
             key: _revealKey,
             onDismiss: _hidePlayerReveal,
-            // Use viewPadding to match BottomNavigationBar's height calculation
-            miniPlayerBottom: BottomSpacing.navBarHeight + MediaQuery.of(context).viewPadding.bottom + 12,
+            // Use viewPadding to match BottomNavigationBar's height calculation.
+            // On detail screens the nav bar is hidden so exclude its height.
+            miniPlayerBottom: (context.read<ThemeProvider>().isOnDetailScreen ? 0.0 : BottomSpacing.navBarHeight) + MediaQuery.of(context).viewPadding.bottom + 12,
             miniPlayerHeight: 64,
             showOnboardingHints: _isOnboardingReveal,
             // Pass pending action parameters for "Play On" functionality

lib/widgets/hires_badge.dart

@@ -69,46 +69,54 @@ class HiResBadge extends StatelessWidget {
     final baseColor = primaryColor ?? colorScheme.primary;
     final color = Color.lerp(baseColor, Colors.white, 0.5)!;
 
-    return Tooltip(
-      message: tooltip ?? 'Hi-Res Audio',
-      child: Container(
-        padding: const EdgeInsets.all(2),
-        decoration: BoxDecoration(
-          border: Border.all(color: color, width: 1.5),
-          borderRadius: BorderRadius.circular(4),
-        ),
-        child: Column(
-          mainAxisSize: MainAxisSize.min,
-          children: [
-            Text(
-              'Hi-Res',
+    final content = Container(
+      padding: const EdgeInsets.all(2),
+      decoration: BoxDecoration(
+        border: Border.all(color: color, width: 1.5),
+        borderRadius: BorderRadius.circular(4),
+      ),
+      child: Column(
+        mainAxisSize: MainAxisSize.min,
+        children: [
+          Text(
+            'Hi-Res',
+            style: TextStyle(
+              color: color,
+              fontSize: 9,
+              fontWeight: FontWeight.w500,
+              height: 1.1,
+            ),
+          ),
+          Container(
+            margin: const EdgeInsets.only(top: 1),
+            padding: const EdgeInsets.symmetric(horizontal: 3, vertical: 1),
+            decoration: BoxDecoration(
+              color: color,
+              borderRadius: BorderRadius.circular(2),
+            ),
+            child: Text(
+              'AUDIO',
               style: TextStyle(
-                color: color,
-                fontSize: 9,
-                fontWeight: FontWeight.w500,
+                color: colorScheme.surface,
+                fontSize: 8,
+                fontWeight: FontWeight.bold,
                 height: 1.1,
               ),
             ),
-            Container(
-              margin: const EdgeInsets.only(top: 1),
-              padding: const EdgeInsets.symmetric(horizontal: 3, vertical: 1),
-              decoration: BoxDecoration(
-                color: color,
-                borderRadius: BorderRadius.circular(2),
-              ),
-              child: Text(
-                'AUDIO',
-                style: TextStyle(
-                  color: colorScheme.surface,
-                  fontSize: 8,
-                  fontWeight: FontWeight.bold,
-                  height: 1.1,
-                ),
-              ),
-            ),
-          ],
-        ),
+          ),
+        ],
       ),
     );
+
+    // Only use Tooltip if an Overlay ancestor exists
+    final hasOverlay = Overlay.maybeOf(context) != null;
+    if (!hasOverlay) {
+      return content;
+    }
+
+    return Tooltip(
+      message: tooltip ?? 'Hi-Res Audio',
+      child: content,
+    );
   }
 }

lib/widgets/library_status_builder.dart

@@ -1,4 +1,5 @@
 import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
 import '../services/library_status_service.dart';
 
 /// A widget that rebuilds when the library/favorite status of an item changes.
@@ -123,9 +124,16 @@ mixin LibraryStatusMixin<T extends StatefulWidget> on State<T> {
 
   void _onLibraryStatusChanged() {
     // Trigger rebuild to pick up new status values
-    if (mounted) {
-      setState(() {});
-    }
+    // Defer setState to avoid calling it during build phase
+    if (!mounted) return;
+
+    // Use Future.microtask to defer setState until after the current build phase
+    // This prevents "setState during build" errors while avoiding Overlay issues
+    Future.microtask(() {
+      if (mounted) {
+        setState(() {});
+      }
+    });
   }
 
   /// Set library status optimistically and return previous value for rollback

lib/widgets/player/player_reveal_overlay.dart

@@ -100,12 +100,12 @@ class PlayerRevealOverlayState extends State<PlayerRevealOverlay>
       curve: const Interval(0.0, 0.4, curve: Curves.easeOut),
     );
 
-    // Preload all player track info and extract colors
-    _preloadColorsForPlayers();
-
-    // Start reveal animation
+    // Start reveal animation first, then load colors after it settles
+    // (color extraction triggers setState which causes jitter during animation)
     _revealController.duration = const Duration(milliseconds: 200);
-    _revealController.forward();
+    _revealController.forward().then((_) {
+      if (mounted) _preloadColorsForPlayers();
+    });
 
     // Auto-refresh player data
     _refreshTimer = Timer.periodic(Timings.playerPollingInterval, (_) {
@@ -266,15 +266,23 @@ class PlayerRevealOverlayState extends State<PlayerRevealOverlay>
     final hintColor = colorScheme.onSurface.withOpacity(0.7);
 
     // Back gesture is handled at GlobalPlayerOverlay level
-    return Consumer<MusicAssistantProvider>(
-      builder: (context, maProvider, child) {
-        final allPlayers = maProvider.availablePlayers;
+    // Use Selector to only rebuild when the player list actually changes,
+    // not on every provider notification (prevents jitter during animation)
+    return Selector<MusicAssistantProvider, ({List<dynamic> players, String? selectedId, int playerCount})>(
+      selector: (_, p) => (
+        players: p.availablePlayers,
+        selectedId: p.selectedPlayer?.playerId,
+        playerCount: p.availablePlayers.length,
+      ),
+      shouldRebuild: (prev, next) => prev.playerCount != next.playerCount || prev.selectedId != next.selectedId,
+      builder: (context, data, child) {
+        final maProvider = context.read<MusicAssistantProvider>();
+        final allPlayers = data.players;
         final selectedPlayer = maProvider.selectedPlayer;
-        final currentTrack = maProvider.currentTrack;
 
         // Filter out the selected player - it's already shown in the mini player
         final players = allPlayers
-            .where((p) => p.playerId != selectedPlayer?.playerId)
+            .where((p) => p.playerId != data.selectedId)
             .toList();
 
         // Default card colors - used when player doesn't have extracted colors

lib/widgets/player/queue_panel.dart

@@ -806,14 +806,12 @@ class _QueuePanelState extends State<QueuePanel> with SingleTickerProviderStateM
                         ),
                         onPressed: () => _handleTransferQueue(context),
                         padding: Spacing.paddingAll12,
-                        tooltip: S.of(context)!.transferQueueToPlayer,
                       ),
                       // Clear queue button
                       IconButton(
                         icon: Icon(Icons.delete_sweep_rounded, color: widget.textColor.withOpacity(0.7), size: IconSizes.sm),
                         onPressed: _handleClearQueue,
                         padding: Spacing.paddingAll12,
-                        tooltip: S.of(context)!.clearQueue,
                       ),
                     ],
                   ),

notes.txt

@@ -0,0 +1,260 @@
+# Pull Request: Group Volume Management, Hardware Volume Integration, and Bugfixes
+
+## Summary
+
+This PR represents a testing and debugging cycle following v3.0.2. Initial work on sync group volume management uncovered multiple UI bugs that required fixes. The final result addresses:
+
+1. **Fix: Group Player Volume Management** - Two distinct volume control issues for Music Assistant sync groups
+2. **Feature: Hardware Volume Button Integration** - Phone volume buttons now control Music Assistant player volume from lockscreen / shade widget / app minimised
+3. **UI Bug Fixes** - Five UI issues discovered during sync group testing, which had to be fixed to get the sync groups to work without crashes
+4. **Fix: Cold Start Homepage Race Condition** - Intermittent empty homepage on app cold start - surfaced once sync group volume calculations were introduced.
+5. **Code Quality: Cleanup and Optimization** - Removes dead code and eliminates duplicate logic - mine, not yours, I tried to not to touch your code as much as possible
+
+All changes have been tested and verified with `dart analyze` showing no new issues.
+
+---
+
+## Group Volume Management Fixes
+
+### 1. Group Player Volume Management
+
+**Issue:** Volume control for Music Assistant sync groups had two distinct problems depending on how the group was created:
+
+1. **Server-side groups**: Volume slider would snap back to 0 immediately after release
+2. **In-app created groups**: Adjusting the leader's volume only changed that one player, not all members proportionally
+
+#### Part A: Server-Side Groups (Null Volume Snap-back)
+
+**Root Cause:** The Music Assistant API returns `volume_level: null` for certain group players (pre-configured speaker groups with `provider == 'player_group'` and some server-side sync groups). The app had no logic to handle this case, so the null volume was interpreted as 0.
+
+**Solution:** Implemented `GroupVolumeManager` service with dual-tier volume protection:
+
+- **Tier 1 (GroupVolumeManager):** Computes effective volume from group members (detects groups, resolves nested, averages volumes, caches pending for 30s, confirms with ±3 tolerance).
+- **Tier 2 (Provider-level):** Optimistic update protection (caches for 8s/30s, prevents stale overwrites).
+
+#### Part B: In-App Created Groups (Proportional Volume Propagation)
+
+**Root Cause:** For in-app groups, leader has non-null volume, so `setVolume()` only affects leader, not members.
+
+**Expected behavior:** Leader adjustment changes all members proportionally; individual adjustments affect only that member.
+
+**Solution:** In `setVolume()`, for group leaders with non-null volume:
+1. Calculate proportional: `memberNewVol = (memberCurrentVol * newVol / leaderCurrentVol).round()` (handle zero case with absolute).
+2. Cache pending, update optimistically, fire parallel API calls.
+
+**Files Changed:**
+- `lib/services/group_volume_manager.dart` (NEW - 162 lines)
+- `lib/providers/music_assistant_provider.dart` (added manager, helper, updated events/state/volume methods)
+
+---
+
+## Features
+
+### 2. Hardware Volume Button Integration (Convenience Feature)
+
+**Feature:** Phone hardware volume buttons (including lockscreen) control MA player volume, with system HUD mirroring.
+
+**Implementation:**
+- **Android Native:** `MainActivity.kt` (~120 lines) - VolumeContentObserver, MethodChannel commands, lifecycle.
+- **Flutter Service:** `hardware_volume_service.dart` (~65 lines) - streams, observer methods, sync.
+- **Integration:** `main.dart` (~35 lines) - adjust/set/update methods, subscription.
+
+**Why This Matters:** Seamless remote control from lockscreen/tray/buttons.
+
+---
+
+## UI Bug Fixes
+
+During sync group testing, fixed these UI bugs:
+
+### 3A. Zone Mismatch Warning
+
+**File:** `lib/main.dart`
+
+**Issue:** Console warnings during init.
+
+**Root Cause:** Init code outside `runZonedGuarded()`.
+
+**Fix:** Move init inside `runZonedGuarded()`.
+
+---
+
+### 3B. BottomNavigationBar "No Overlay" Crash
+
+**Files:** `lib/screens/home_screen.dart`, `lib/widgets/global_player_overlay.dart`
+
+**Issue:** Crash on nav interaction.
+
+**Root Cause:** Nav in Stack without Overlay.
+
+**Fix:** Move nav to Scaffold.bottomNavigationBar, add extendBody: true.
+
+---
+
+### 3C. setState During Build Warning (Artist/Album Cards)
+
+**Files:** `lib/widgets/artist_card.dart`, `lib/widgets/album_card.dart`
+
+**Issue:** Warnings causing corruption.
+
+**Root Cause:** Service calls in initState trigger setState during build.
+
+**Fix:** Defer with addPostFrameCallback, add mounted guard.
+
+---
+
+### 3D. context.select Inside SliverList Crash
+
+**File:** `lib/screens/new_library_screen.dart`
+
+**Issue:** Crash on library tabs.
+
+**Root Cause:** context.select in sliver context.
+
+**Fix:** Use Consumer wrappers for tabs.
+
+---
+
+### 3E. QueuePanel Tooltip "No Overlay" Error
+
+**File:** `lib/widgets/player/queue_panel.dart`
+
+**Issue:** Crash on long-press buttons.
+
+**Root Cause:** Tooltips require Overlay, but in Stack.
+
+**Fix:** Remove tooltip properties.
+
+---
+
+### 3F. Settings Back Button Crash
+
+**File:** `lib/screens/settings_screen.dart`
+
+**Issue:** Back button crashes to black screen.
+
+**Root Cause:** Navigator.pop pops home screen.
+
+**Fix:** Use showPlayer + setSelectedIndex(0).
+
+---
+
+## Cold Start Homepage Race Condition Fix
+
+### 4. Cold Start Homepage Empty/No Refresh
+
+**Issue:** Intermittent empty homepage on cold start.
+
+**Root Cause:** isConnected true before auth complete, leading to failed fetches.
+
+**Solution:** Delay broadcasting 'connected' state until auth if required (`music_assistant_provider.dart:1058-1101`).
+
+---
+
+## Technical Implementation Details
+
+### GroupVolumeManager Architecture
+
+The `GroupVolumeManager` is a stateful service that handles **server-side groups with null volume**:
+
+1. **Detects group players:**
+   ```dart
+   bool isGroupPlayer(Player player) {
+     // Pre-configured MA speaker groups
+     if (player.provider == 'player_group') return true;
+     // Dynamic sync groups: have multiple members but MA returns null volume
+     if (player.groupMembers != null &&
+         player.groupMembers!.length > 1 &&
+         player.volumeLevel == null) {
+       return true;
+     }
+     return false;
+   }
+   ```
+
+2. **Computes effective volume:**
+   - Recursively resolves nested groups (max depth 3)
+   - Averages volumes across all leaf members
+   - Skips self-references in `groupMembers`
+   - Returns `null` if no members have valid volumes
+
+3. **Caches pending volumes:**
+   - When user sets volume: stored with timestamp
+   - Returns cached value if within 30s timeout
+   - Clears cache when member average converges (±3 tolerance)
+   - Falls back to computed average after timeout
+
+4. **Integrates with provider:**
+   - Called from `_applyVolumeProtection()` in provider
+   - Receives fresh `allPlayers` list for accurate member volumes
+   - Injects effective volume into `_selectedPlayer` via `copyWith()`
+
+### Proportional Volume Propagation (In-App Groups)
+
+For **in-app created groups with non-null leader volume**, proportional propagation works as follows:
+
+1. **Detection:** `setVolume()` checks if `player.isGroupLeader && !isGroupPlayer(player)`
+   - Leader has `groupMembers` with 2+ entries
+   - Leader has its own non-null `volumeLevel`
+   - NOT detected as a group player (GroupVolumeManager handles those)
+
+2. **Calculation:** For each member in `groupMembers` (excluding leader itself):
+   ```dart
+   if (leaderCurrentVol > 0) {
+     memberNewVol = (memberVol * newVol / leaderCurrentVol).round().clamp(0, 100)
+   } else {
+     memberNewVol = newVol  // Can't ratio from zero
+   }
+   ```
+
+3. **Execution:**
+   - Cache `_pendingVolumes[memberId]` and `_pendingVolumeTimestamps[memberId]`
+   - Update `_availablePlayers[idx]` optimistically
+   - Fire `_api?.setVolume(memberId, memberNewVol)` without awaiting
+   - Continue to send leader's own `volume_set` command
+
+4. **Result:** All member volumes scale proportionally with the leader, preserving relative balance.
+
+### Connection State Flow (After Fix)
+
+```
+WebSocket connects → MAConnectionState.connected
+                    ↓
+         Auth required?
+        ↙              ↘
+      YES              NO
+       ↓                ↓
+  Don't notify    Set state + notify
+  Try auth              ↓
+       ↓          Initialize
+   Success?
+  ↙        ↘
+YES        NO
+ ↓          ↓
+auth     error state
+event     + notify
+ ↓
+Set state
++ notify
+ ↓
+Initialize
+```
+
+**Key:** Listeners only see `isConnected = true` after auth completes (or immediately if no auth required).
+
+
+## Files Modified
+android/.../MainActivity.kt                      |  120 + (NEW - ContentObserver)
+lib/main.dart                                    |  207 ±
+lib/providers/music_assistant_provider.dart      |  165 ±
+lib/screens/home_screen.dart                     |  172 ± (BottomNav moved here)
+lib/screens/new_library_screen.dart              |   70 ± (Consumer wrappers)
+lib/screens/settings_screen.dart                 |    9 ± (back button fix)
+lib/services/group_volume_manager.dart           |  162 + (NEW)
+lib/services/hardware_volume_service.dart        |   65 + (NEW)
+lib/widgets/album_card.dart                      |   23 ± (postFrameCallback)
+lib/widgets/artist_card.dart                     |   23 ± (postFrameCallback)
+lib/widgets/global_player_overlay.dart           |  171 - (BottomNav moved out)
+lib/widgets/player/queue_panel.dart              |    2 - (tooltip removed)
+
+**Total:** ~650 added, ~300 removed/refactored.

pubspec.yaml

@@ -1,7 +1,7 @@
 name: ensemble
 description: A minimalistic Music Assistant client built with Flutter
 publish_to: 'none'
-version: 3.0.2+54
+version: 3.0.3+55
 
 environment:
   sdk: '>=3.0.0 <4.0.0'