Merge feature/hardware-volume-control: Hardware volume button support

- Add dynamic volume interception toggling based on selected player
- MA player selected: intercept hardware buttons, control via API
- Builtin player selected: disable interception, let native volume work
- Use FlutterVolumeController for builtin player UI slider and MA commands

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

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

README.md

@@ -11,7 +11,7 @@
 
 ## Disclaimer
 
-I am not a developer. This application was created using **Claude Code** and **Gemini CLI**.
+This application was built with AI-assisted development using **Claude Code** and **Gemini CLI**.
 
 ---
 
@@ -28,9 +28,18 @@ I am not a developer. This application was created using **Claude Code** and **G
 - **Full Playback Controls** - Play, pause, skip, seek, and adjust volume
 - **Queue Management** - View and manage the playback queue
 
+### Home Screen
+- **Customizable Rows** - Toggle Recently Played, Discover Artists, and Discover Albums
+- **Favorites Rows** - Optional rows for Favorite Albums, Artists, and Tracks
+- **Adaptive Layout** - Rows scale properly for different screen sizes and aspect ratios
+- **Pull to Refresh** - Refresh content with a simple pull gesture
+
 ### Library Browsing
-- **Browse Your Collection** - Artists, albums, and tracks from all your music sources
+- **Browse Your Collection** - Artists, albums, playlists, and tracks from all your music sources
+- **Favorites Filter** - Toggle to show only your favorite items
 - **Album Details** - View track listings with artwork
+- **Artist Details** - View artist albums and top tracks
+- **Playlist Support** - Browse and play your playlists
 - **Search** - Find music across your entire library
 
 ### Smart Features

android/app/src/main/AndroidManifest.xml

@@ -14,7 +14,7 @@
         android:usesCleartextTraffic="true"
         android:networkSecurityConfig="@xml/network_security_config">
         <activity
-            android:name="com.ryanheise.audioservice.AudioServiceActivity"
+            android:name=".MainActivity"
             android:exported="true"
             android:launchMode="singleTop"
             android:theme="@style/LaunchTheme"

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

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

lib/main.dart

@@ -1,3 +1,4 @@
+import 'dart:async';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
 import 'package:provider/provider.dart';
@@ -10,6 +11,7 @@ import 'services/settings_service.dart';
 import 'services/audio/massiv_audio_handler.dart';
 import 'services/auth/auth_manager.dart';
 import 'services/debug_logger.dart';
+import 'services/hardware_volume_service.dart';
 import 'services/music_assistant_api.dart' show MAConnectionState;
 import 'theme/theme_provider.dart';
 import 'theme/app_theme.dart';
@@ -71,6 +73,14 @@ class MusicAssistantApp extends StatefulWidget {
 class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindingObserver {
   late MusicAssistantProvider _musicProvider;
   late ThemeProvider _themeProvider;
+  final _hardwareVolumeService = HardwareVolumeService();
+  StreamSubscription? _volumeUpSub;
+  StreamSubscription? _volumeDownSub;
+  String? _lastSelectedPlayerId;
+  String? _builtinPlayerId;
+
+  // Volume step size (percentage points per button press)
+  static const int _volumeStep = 5;
 
   @override
   void initState() {
@@ -78,10 +88,92 @@ class _MusicAssistantAppState extends State<MusicAssistantApp> with WidgetsBindi
     _musicProvider = MusicAssistantProvider();
     _themeProvider = ThemeProvider();
     WidgetsBinding.instance.addObserver(this);
+    _initHardwareVolumeControl();
+    // Listen to player selection changes to toggle volume interception
+    _musicProvider.addListener(_onProviderChanged);
+  }
+
+  Future<void> _initHardwareVolumeControl() async {
+    try {
+      _logger.log('🔊 [1/5] Starting hardware volume control initialization...');
+
+      // Get builtin player ID for detecting when to disable interception
+      _builtinPlayerId = await SettingsService.getBuiltinPlayerId();
+      _logger.log('🔊 [2/5] Builtin player ID: $_builtinPlayerId');
+
+      _logger.log('🔊 [3/5] Calling HardwareVolumeService.init()...');
+      await _hardwareVolumeService.init();
+      _logger.log('🔊 [4/5] HardwareVolumeService.init() completed, isListening=${_hardwareVolumeService.isListening}');
+
+      _volumeUpSub = _hardwareVolumeService.onVolumeUp.listen((_) {
+        _logger.log('🔊 Volume UP event received in main.dart');
+        _adjustVolume(_volumeStep);
+      });
+
+      _volumeDownSub = _hardwareVolumeService.onVolumeDown.listen((_) {
+        _logger.log('🔊 Volume DOWN event received in main.dart');
+        _adjustVolume(-_volumeStep);
+      });
+
+      _logger.log('🔊 [5/5] Hardware volume control fully initialized');
+    } catch (e, stack) {
+      _logger.error('Hardware volume control initialization FAILED', context: 'VolumeInit', error: e, stackTrace: stack);
+    }
+  }
+
+  /// Called when provider state changes - check if selected player changed
+  void _onProviderChanged() {
+    final currentPlayerId = _musicProvider.selectedPlayer?.playerId;
+    if (currentPlayerId != _lastSelectedPlayerId) {
+      _lastSelectedPlayerId = currentPlayerId;
+      _updateVolumeInterception();
+    }
+  }
+
+  /// Enable/disable volume button interception based on selected player.
+  /// For builtin player: disable interception so native volume works
+  /// For MA players: enable interception to control player via API
+  Future<void> _updateVolumeInterception() async {
+    final isBuiltinPlayer = _builtinPlayerId != null &&
+        _musicProvider.selectedPlayer?.playerId == _builtinPlayerId;
+
+    if (isBuiltinPlayer) {
+      _logger.log('🔊 Builtin player selected - disabling volume interception');
+      await _hardwareVolumeService.setIntercepting(false);
+    } else {
+      _logger.log('🔊 MA player selected - enabling volume interception');
+      await _hardwareVolumeService.setIntercepting(true);
+    }
+  }
+
+  Future<void> _adjustVolume(int delta) async {
+    final player = _musicProvider.selectedPlayer;
+    if (player == null) {
+      _logger.log('🔊 Hardware volume button pressed but no player selected');
+      return;
+    }
+
+    _logger.log('🔊 Hardware volume: player=${player.name}, current=${player.volume}, delta=$delta');
+
+    final newVolume = (player.volume + delta).clamp(0, 100);
+    if (newVolume != player.volume) {
+      try {
+        await _musicProvider.setVolume(player.playerId, newVolume);
+        _logger.log('🔊 Hardware volume adjusted: ${player.volume} -> $newVolume for ${player.name}');
+      } catch (e) {
+        _logger.error('Hardware volume adjustment failed', context: 'VolumeControl', error: e);
+      }
+    } else {
+      _logger.log('🔊 Hardware volume: already at limit ($newVolume)');
+    }
   }
 
   @override
   void dispose() {
+    _musicProvider.removeListener(_onProviderChanged);
+    _volumeUpSub?.cancel();
+    _volumeDownSub?.cancel();
+    _hardwareVolumeService.dispose();
     WidgetsBinding.instance.removeObserver(this);
     super.dispose();
   }

lib/providers/music_assistant_provider.dart

@@ -2,6 +2,7 @@ import 'dart:async';
 import 'package:flutter/foundation.dart';
 import 'package:flutter/painting.dart';
 import 'package:cached_network_image/cached_network_image.dart';
+import 'package:flutter_volume_controller/flutter_volume_controller.dart';
 import '../models/media_item.dart';
 import '../models/player.dart';
 import '../services/music_assistant_api.dart';
@@ -50,6 +51,7 @@ class MusicAssistantProvider with ChangeNotifier {
 
   // Local player state
   bool _isLocalPlayerPowered = true;
+  int _localPlayerVolume = 100; // Tracked MA volume for builtin player (0-100)
   bool _builtinPlayerAvailable = true; // False on MA 2.7.0b20+ (uses Sendspin instead)
   StreamSubscription? _localPlayerEventSubscription;
   StreamSubscription? _playerUpdatedEventSubscription;
@@ -491,7 +493,9 @@ class MusicAssistantProvider with ChangeNotifier {
 
     final isPlaying = _localPlayer.isPlaying;
     final position = _localPlayer.position.inSeconds;
-    final volume = (_localPlayer.volume * 100).round();
+    // Use tracked MA volume instead of just_audio player volume
+    // just_audio volume is for local playback, MA volume is for server sync
+    final volume = _localPlayerVolume;
     final isPaused = !isPlaying && position > 0;
 
     await _api!.updateBuiltinPlayerState(
@@ -501,7 +505,7 @@ class MusicAssistantProvider with ChangeNotifier {
       paused: isPaused,
       position: position,
       volume: volume,
-      muted: _localPlayer.volume == 0.0,
+      muted: _localPlayerVolume == 0,
     );
   }
 
@@ -590,9 +594,14 @@ class MusicAssistantProvider with ChangeNotifier {
           break;
 
         case 'volume_set':
-          final volume = event['volume_level'] as int?;
+        case 'set_volume':
+          // MA sends 'set_volume' in event type but 'volume' in data
+          final volume = event['volume_level'] as int? ?? event['volume'] as int?;
           if (volume != null) {
-            await _localPlayer.setVolume(volume / 100.0);
+            _localPlayerVolume = volume; // Track MA volume
+            // Use device media volume (FlutterVolumeController), NOT just_audio software volume
+            await FlutterVolumeController.setVolume(volume / 100.0);
+            _logger.log('🔊 Builtin player DEVICE volume set to ${(volume / 100.0).toStringAsFixed(2)} from server event');
           }
           break;
 
@@ -834,6 +843,28 @@ class MusicAssistantProvider with ChangeNotifier {
     _cacheService.invalidateHomeCache();
   }
 
+  // ============================================================================
+  // FAVORITES FOR HOME SCREEN
+  // ============================================================================
+
+  /// Get favorite albums from the library
+  Future<List<Album>> getFavoriteAlbums() async {
+    // Filter from loaded library - favorites are already loaded
+    return _albums.where((a) => a.favorite == true).toList();
+  }
+
+  /// Get favorite artists from the library
+  Future<List<Artist>> getFavoriteArtists() async {
+    // Filter from loaded library - favorites are already loaded
+    return _artists.where((a) => a.favorite == true).toList();
+  }
+
+  /// Get favorite tracks from the library
+  Future<List<Track>> getFavoriteTracks() async {
+    // Filter from loaded library - favorites are already loaded
+    return _tracks.where((t) => t.favorite == true).toList();
+  }
+
   // ============================================================================
   // DETAIL SCREEN CACHING
   // ============================================================================
@@ -1678,7 +1709,19 @@ class MusicAssistantProvider with ChangeNotifier {
 
   Future<void> setVolume(String playerId, int volumeLevel) async {
     try {
+      // Check if this is the builtin player
+      final builtinPlayerId = await SettingsService.getBuiltinPlayerId();
+      if (builtinPlayerId != null && playerId == builtinPlayerId) {
+        // For builtin player, control device media volume directly
+        _localPlayerVolume = volumeLevel;
+        await FlutterVolumeController.setVolume(volumeLevel / 100.0);
+        _logger.log('🔊 Builtin player DEVICE volume set to $volumeLevel%');
+        // Also notify MA server about the volume change
         await _api?.setVolume(playerId, volumeLevel);
+      } else {
+        // For MA players, just send to MA server
+        await _api?.setVolume(playerId, volumeLevel);
+      }
     } catch (e) {
       ErrorHandler.logError('Set volume', e);
       rethrow;

lib/screens/album_details_screen.dart

@@ -500,10 +500,16 @@ class _AlbumDetailsScreenState extends State<AlbumDetailsScreen> with SingleTick
   void _navigateToArtist() {
     // Navigate to the first artist if available
     if (widget.album.artists != null && widget.album.artists!.isNotEmpty) {
+      final artist = widget.album.artists!.first;
+      final maProvider = context.read<MusicAssistantProvider>();
+      final imageUrl = maProvider.getImageUrl(artist, size: 256);
       Navigator.push(
         context,
         MaterialPageRoute(
-          builder: (context) => ArtistDetailsScreen(artist: widget.album.artists!.first),
+          builder: (context) => ArtistDetailsScreen(
+            artist: artist,
+            initialImageUrl: imageUrl,
+          ),
         ),
       );
     }

lib/screens/artist_details_screen.dart

@@ -15,11 +15,13 @@ import '../utils/page_transitions.dart';
 class ArtistDetailsScreen extends StatefulWidget {
   final Artist artist;
   final String? heroTagSuffix;
+  final String? initialImageUrl;
 
   const ArtistDetailsScreen({
     super.key,
     required this.artist,
     this.heroTagSuffix,
+    this.initialImageUrl,
   });
 
   @override
@@ -44,12 +46,14 @@ class _ArtistDetailsScreenState extends State<ArtistDetailsScreen> {
   void initState() {
     super.initState();
     _isFavorite = widget.artist.favorite ?? false;
+    // Use initial image URL immediately for smooth hero animation
+    _artistImageUrl = widget.initialImageUrl;
     _loadArtistAlbums();
     _loadArtistDescription();
     _refreshFavoriteStatus();
 
-    // CRITICAL FIX: Defer image loading and color extraction until after transition
-    // This prevents expensive operations during hero animation
+    // Defer higher-res image loading and color extraction until after transition
+    // But hero animation now works because we have initialImageUrl
     WidgetsBinding.instance.addPostFrameCallback((_) {
       Future.delayed(const Duration(milliseconds: 350), () {
         if (mounted) {

lib/screens/debug_log_screen.dart

@@ -433,6 +433,8 @@ class _DebugLogScreenState extends State<DebugLogScreen> {
 
   Color _getLevelColor(LogLevel level) {
     switch (level) {
+      case LogLevel.perf:
+        return Colors.purple;
       case LogLevel.debug:
         return Colors.grey;
       case LogLevel.info:

lib/screens/library_albums_screen.dart

@@ -67,6 +67,8 @@ class LibraryAlbumsScreen extends StatelessWidget {
       child: GridView.builder(
         key: const PageStorageKey<String>('library_albums_full_grid'),
         cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Cards have their own keep-alive
+        addRepaintBoundaries: false, // Cards have RepaintBoundary
         gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
           crossAxisCount: 2,
           childAspectRatio: 0.75,

lib/screens/library_artists_screen.dart

@@ -69,6 +69,8 @@ class LibraryArtistsScreen extends StatelessWidget {
       child: ListView.builder(
         key: const PageStorageKey<String>('library_artists_full_list'),
         cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Tiles have their own keep-alive
+        addRepaintBoundaries: false, // Tiles have RepaintBoundary
         itemCount: artists.length,
         padding: const EdgeInsets.all(8),
         itemBuilder: (context, index) {
@@ -90,6 +92,9 @@ class LibraryArtistsScreen extends StatelessWidget {
   }) {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
+    final maProvider = context.read<MusicAssistantProvider>();
+    // Get image URL for hero animation
+    final imageUrl = maProvider.getImageUrl(artist, size: 256);
 
     // RepaintBoundary isolates repaints to individual tiles
     return RepaintBoundary(
@@ -116,6 +121,7 @@ class LibraryArtistsScreen extends StatelessWidget {
               child: ArtistDetailsScreen(
                 artist: artist,
                 heroTagSuffix: 'library',
+                initialImageUrl: imageUrl,
               ),
             ),
           );

lib/screens/library_playlists_screen.dart

@@ -91,6 +91,9 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
       child: ListView.builder(
         itemCount: _playlists.length,
         padding: const EdgeInsets.all(8),
+        cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+        addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
         itemBuilder: (context, index) {
           final playlist = _playlists[index];
           return _buildPlaylistTile(context, playlist, provider);
@@ -104,8 +107,9 @@ class _LibraryPlaylistsScreenState extends State<LibraryPlaylistsScreen> {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
 
-    return Builder(
-      builder: (context) => ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(playlist.itemId),
         leading: Container(
           width: 48,
           height: 48,

lib/screens/library_tracks_screen.dart

@@ -54,6 +54,9 @@ class LibraryTracksScreen extends StatelessWidget {
     return ListView.builder(
       itemCount: provider.tracks.length,
       padding: const EdgeInsets.all(8),
+      cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+      addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+      addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
       itemBuilder: (context, index) {
         final track = provider.tracks[index];
         return _buildTrackTile(context, track, provider, index);
@@ -73,7 +76,9 @@ class LibraryTracksScreen extends StatelessWidget {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
 
-    return ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(track.uri ?? track.itemId),
         leading: Container(
           width: 48,
           height: 48,
@@ -110,6 +115,7 @@ class LibraryTracksScreen extends StatelessWidget {
               )
             : null,
         onTap: () => _playTrack(context, maProvider, index),
+      ),
     );
   }
 

lib/screens/new_home_screen.dart

@@ -1,10 +1,14 @@
 import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
 import 'package:provider/provider.dart';
 import '../providers/music_assistant_provider.dart';
+import '../services/settings_service.dart';
+import '../services/debug_logger.dart';
 import '../widgets/global_player_overlay.dart';
 import '../widgets/player_selector.dart';
 import '../widgets/album_row.dart';
 import '../widgets/artist_row.dart';
+import '../widgets/track_row.dart';
 import '../widgets/common/disconnected_state.dart';
 import 'settings_screen.dart';
 import 'search_screen.dart';
@@ -16,17 +20,73 @@ class NewHomeScreen extends StatefulWidget {
   State<NewHomeScreen> createState() => _NewHomeScreenState();
 }
 
-class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveClientMixin {
+class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveClientMixin, WidgetsBindingObserver {
+  static final _logger = DebugLogger();
   Key _refreshKey = UniqueKey();
+  // Main rows (default on)
+  bool _showRecentAlbums = true;
+  bool _showDiscoverArtists = true;
+  bool _showDiscoverAlbums = true;
+  // Favorites rows (default off)
+  bool _showFavoriteAlbums = false;
+  bool _showFavoriteArtists = false;
+  bool _showFavoriteTracks = false;
+  // Random order for favorites (generated once per session)
+  late List<int> _favoritesOrder;
 
   @override
   bool get wantKeepAlive => true;
 
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addObserver(this);
+    // Generate random order for favorites rows (0, 1, 2 shuffled)
+    _favoritesOrder = [0, 1, 2]..shuffle();
+    _loadSettings();
+  }
+
+  @override
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    super.dispose();
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    // Reload settings when app resumes (coming back from settings)
+    if (state == AppLifecycleState.resumed) {
+      _loadSettings();
+    }
+  }
+
+  Future<void> _loadSettings() async {
+    final showRecent = await SettingsService.getShowRecentAlbums();
+    final showDiscArtists = await SettingsService.getShowDiscoverArtists();
+    final showDiscAlbums = await SettingsService.getShowDiscoverAlbums();
+    final showFavAlbums = await SettingsService.getShowFavoriteAlbums();
+    final showFavArtists = await SettingsService.getShowFavoriteArtists();
+    final showFavTracks = await SettingsService.getShowFavoriteTracks();
+    if (mounted) {
+      setState(() {
+        _showRecentAlbums = showRecent;
+        _showDiscoverArtists = showDiscArtists;
+        _showDiscoverAlbums = showDiscAlbums;
+        _showFavoriteAlbums = showFavAlbums;
+        _showFavoriteArtists = showFavArtists;
+        _showFavoriteTracks = showFavTracks;
+      });
+    }
+  }
+
   Future<void> _onRefresh() async {
     // Invalidate cache to force fresh data on pull-to-refresh
     final provider = context.read<MusicAssistantProvider>();
     provider.invalidateHomeCache();
 
+    // Reload settings in case they changed
+    await _loadSettings();
+
     if (mounted) {
       setState(() {
         _refreshKey = UniqueKey();
@@ -37,6 +97,7 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
   @override
   Widget build(BuildContext context) {
     super.build(context); // Required for AutomaticKeepAliveClientMixin
+    // Settings are loaded in initState and didChangeAppLifecycleState - no need to reload on every build
     final colorScheme = Theme.of(context).colorScheme;
 
     return Scaffold(
@@ -96,43 +157,125 @@ class _NewHomeScreenState extends State<NewHomeScreen> with AutomaticKeepAliveCl
 
   Widget _buildConnectedView(
       BuildContext context, MusicAssistantProvider provider) {
+    // Use LayoutBuilder to get available screen height
+    return LayoutBuilder(
+      builder: (context, constraints) {
+        // Simple calculation: available height divided by 3 rows
+        // Each row includes its title, artwork, and info
+        final availableHeight = constraints.maxHeight - BottomSpacing.withMiniPlayer;
+        final rowHeight = availableHeight / 3;
+
+        // Build favorites rows in random order
+        final favoritesWidgets = _buildFavoritesRows(provider, rowHeight);
+
         // Use Android 12+ stretch overscroll effect
-    return ScrollConfiguration(
+        return NotificationListener<ScrollNotification>(
+          onNotification: (notification) {
+            if (notification is ScrollStartNotification) {
+              _logger.resetFrameStats();
+              _logger.perf('SCROLL START', context: 'HomeScreen');
+            } else if (notification is ScrollUpdateNotification) {
+              _logger.startFrame();
+              SchedulerBinding.instance.addPostFrameCallback((_) {
+                _logger.endFrame();
+              });
+            } else if (notification is ScrollEndNotification) {
+              _logger.perf('SCROLL END', context: 'HomeScreen');
+            }
+            return false;
+          },
+          child: ScrollConfiguration(
             behavior: const _StretchScrollBehavior(),
             child: SingleChildScrollView(
               physics: const AlwaysScrollableScrollPhysics(),
+              padding: EdgeInsets.only(bottom: BottomSpacing.withMiniPlayer),
               child: Column(
                 key: _refreshKey,
                 crossAxisAlignment: CrossAxisAlignment.start,
                 children: [
-          // Recently played albums (with caching)
-          // Stable keys prevent widget recreation on parent rebuilds
+                  // Recently played albums (optional)
+                  if (_showRecentAlbums)
                     AlbumRow(
                       key: const ValueKey('recent-albums'),
                       title: 'Recently Played',
                       loadAlbums: () => provider.getRecentAlbumsWithCache(),
+                      rowHeight: rowHeight,
                     ),
-          const SizedBox(height: 21),
 
-          // Discover Artists (with caching)
+                  // Discover Artists (optional)
+                  if (_showDiscoverArtists)
                     ArtistRow(
                       key: const ValueKey('discover-artists'),
                       title: 'Discover Artists',
                       loadArtists: () => provider.getDiscoverArtistsWithCache(),
+                      rowHeight: rowHeight,
                     ),
-          const SizedBox(height: 3),
 
-          // Discover Albums (with caching)
+                  // Discover Albums (optional)
+                  if (_showDiscoverAlbums)
                     AlbumRow(
                       key: const ValueKey('discover-albums'),
                       title: 'Discover Albums',
                       loadAlbums: () => provider.getDiscoverAlbumsWithCache(),
+                      rowHeight: rowHeight,
                     ),
-          SizedBox(height: BottomSpacing.withMiniPlayer), // Space for bottom nav + mini player
+
+                  // Favorites rows in random order
+                  ...favoritesWidgets,
                 ],
               ),
             ),
+          ),
         );
+      },
+    );
+  }
+
+  /// Build favorites rows in random order (order set once per session)
+  List<Widget> _buildFavoritesRows(MusicAssistantProvider provider, double rowHeight) {
+    // Create list of enabled favorites with their order index
+    final enabledFavorites = <MapEntry<int, Widget>>[];
+
+    if (_showFavoriteAlbums) {
+      enabledFavorites.add(MapEntry(
+        _favoritesOrder[0],
+        AlbumRow(
+          key: const ValueKey('favorite-albums'),
+          title: 'Favorite Albums',
+          loadAlbums: () => provider.getFavoriteAlbums(),
+          rowHeight: rowHeight,
+        ),
+      ));
+    }
+
+    if (_showFavoriteArtists) {
+      enabledFavorites.add(MapEntry(
+        _favoritesOrder[1],
+        ArtistRow(
+          key: const ValueKey('favorite-artists'),
+          title: 'Favorite Artists',
+          loadArtists: () => provider.getFavoriteArtists(),
+          rowHeight: rowHeight,
+        ),
+      ));
+    }
+
+    if (_showFavoriteTracks) {
+      enabledFavorites.add(MapEntry(
+        _favoritesOrder[2],
+        TrackRow(
+          key: const ValueKey('favorite-tracks'),
+          title: 'Favorite Tracks',
+          loadTracks: () => provider.getFavoriteTracks(),
+          rowHeight: rowHeight,
+        ),
+      ));
+    }
+
+    // Sort by the random order index
+    enabledFavorites.sort((a, b) => a.key.compareTo(b.key));
+
+    return enabledFavorites.map((e) => e.value).toList();
   }
 }
 

lib/screens/new_library_screen.dart

@@ -289,6 +289,8 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
           child: ListView.builder(
             key: PageStorageKey<String>('library_artists_list_${_showFavoritesOnly ? 'fav' : 'all'}'),
             cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+            addAutomaticKeepAlives: false, // Tiles have their own keep-alive
+            addRepaintBoundaries: false, // Tiles have RepaintBoundary
             itemCount: artists.length,
             padding: EdgeInsets.only(left: 8, right: 8, top: 8, bottom: BottomSpacing.navBarOnly),
             itemBuilder: (context, index) {
@@ -312,7 +314,10 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
   }) {
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
+    final maProvider = context.read<MusicAssistantProvider>();
     final suffix = '_library';
+    // Get image URL for hero animation
+    final imageUrl = maProvider.getImageUrl(artist, size: 256);
 
     return RepaintBoundary(
       child: ListTile(
@@ -322,9 +327,6 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
           radius: 24,
           imageSize: 128,
           heroTag: HeroTags.artistImage + (artist.uri ?? artist.itemId) + suffix,
-          onImageLoaded: (imageUrl) {
-            // Store for adaptive colors on tap
-          },
         ),
       title: Hero(
         tag: HeroTags.artistName + (artist.uri ?? artist.itemId) + suffix,
@@ -348,6 +350,7 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
               child: ArtistDetailsScreen(
                 artist: artist,
                 heroTagSuffix: 'library',
+                initialImageUrl: imageUrl,
               ),
             ),
           );
@@ -394,6 +397,8 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
           child: GridView.builder(
             key: PageStorageKey<String>('library_albums_grid_${_showFavoritesOnly ? 'fav' : 'all'}'),
             cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+            addAutomaticKeepAlives: false, // Cards have their own keep-alive
+            addRepaintBoundaries: false, // Cards have RepaintBoundary
             padding: EdgeInsets.only(left: 16, right: 16, top: 16, bottom: BottomSpacing.navBarOnly),
             gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
               crossAxisCount: 2,
@@ -442,6 +447,8 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
       child: ListView.builder(
         key: PageStorageKey<String>('library_playlists_list_${_showFavoritesOnly ? 'fav' : 'all'}'),
         cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+        addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+        addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
         itemCount: _playlists.length,
         padding: EdgeInsets.only(left: 8, right: 8, top: 8, bottom: BottomSpacing.navBarOnly),
         itemBuilder: (context, index) {
@@ -458,7 +465,9 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
 
-    return ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(playlist.itemId),
         leading: Container(
         width: 48,
         height: 48,
@@ -505,6 +514,7 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
             ),
           );
         },
+      ),
     );
   }
 
@@ -539,6 +549,8 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
       child: ListView.builder(
         key: const PageStorageKey<String>('library_tracks_list'),
         cacheExtent: 500,
+        addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+        addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
         padding: EdgeInsets.only(left: 8, right: 8, top: 8, bottom: BottomSpacing.navBarOnly),
         itemCount: sortedTracks.length,
         itemBuilder: (context, index) {
@@ -557,7 +569,9 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
     // Get image URL from track itself
     final imageUrl = maProvider.api?.getImageUrl(track, size: 128);
 
-    return ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(track.uri ?? track.itemId),
         contentPadding: const EdgeInsets.symmetric(horizontal: 16, vertical: 4),
         leading: Container(
         width: 48,
@@ -618,6 +632,7 @@ class _NewLibraryScreenState extends State<NewLibraryScreen>
           }
         }
       },
+      ),
     );
   }
 }

lib/screens/search_screen.dart

@@ -299,6 +299,9 @@ class SearchScreenState extends State<SearchScreen> {
               final listItems = _buildListItems(artists, albums, tracks);
               return ListView.builder(
                 padding: EdgeInsets.fromLTRB(16, 8, 16, BottomSpacing.navBarOnly),
+                cacheExtent: 500, // Prebuild items off-screen for smoother scrolling
+                addAutomaticKeepAlives: false, // Tiles don't need individual keep-alive
+                addRepaintBoundaries: false, // We add RepaintBoundary manually to tiles
                 itemCount: listItems.length,
                 itemBuilder: (context, index) {
                   final item = listItems[index];
@@ -404,8 +407,12 @@ class SearchScreenState extends State<SearchScreen> {
 
   Widget _buildArtistTile(Artist artist) {
     final colorScheme = Theme.of(context).colorScheme;
+    final maProvider = context.read<MusicAssistantProvider>();
+    final imageUrl = maProvider.getImageUrl(artist, size: 256);
 
-    return ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(artist.uri ?? artist.itemId),
       leading: ArtistAvatar(
         artist: artist,
         radius: 24,
@@ -428,10 +435,14 @@ class SearchScreenState extends State<SearchScreen> {
           Navigator.push(
             context,
             MaterialPageRoute(
-            builder: (context) => ArtistDetailsScreen(artist: artist),
+              builder: (context) => ArtistDetailsScreen(
+                artist: artist,
+                initialImageUrl: imageUrl,
+              ),
             ),
           );
         },
+      ),
     );
   }
 
@@ -440,7 +451,9 @@ class SearchScreenState extends State<SearchScreen> {
     final imageUrl = maProvider.getImageUrl(album, size: 128);
     final colorScheme = Theme.of(context).colorScheme;
 
-    return ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(album.uri ?? album.itemId),
         leading: Container(
         width: 48,
         height: 48,
@@ -481,6 +494,7 @@ class SearchScreenState extends State<SearchScreen> {
             ),
           );
         },
+      ),
     );
   }
 
@@ -491,7 +505,9 @@ class SearchScreenState extends State<SearchScreen> {
         : null;
     final colorScheme = Theme.of(context).colorScheme;
 
-    return ListTile(
+    return RepaintBoundary(
+      child: ListTile(
+        key: ValueKey(track.uri ?? track.itemId),
         leading: Container(
         width: 48,
         height: 48,
@@ -531,6 +547,7 @@ class SearchScreenState extends State<SearchScreen> {
               )
             : null,
         onTap: () => _playTrack(track),
+      ),
     );
   }
 

lib/screens/settings_screen.dart

@@ -18,6 +18,14 @@ class SettingsScreen extends StatefulWidget {
 class _SettingsScreenState extends State<SettingsScreen> {
   final _lastFmApiKeyController = TextEditingController();
   final _audioDbApiKeyController = TextEditingController();
+  // Main rows (default on)
+  bool _showRecentAlbums = true;
+  bool _showDiscoverArtists = true;
+  bool _showDiscoverAlbums = true;
+  // Favorites rows (default off)
+  bool _showFavoriteAlbums = false;
+  bool _showFavoriteArtists = false;
+  bool _showFavoriteTracks = false;
 
   @override
   void initState() {
@@ -35,6 +43,24 @@ class _SettingsScreenState extends State<SettingsScreen> {
     if (audioDbKey != null) {
       _audioDbApiKeyController.text = audioDbKey;
     }
+
+    // Load home screen settings
+    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();
+    if (mounted) {
+      setState(() {
+        _showRecentAlbums = showRecent;
+        _showDiscoverArtists = showDiscArtists;
+        _showDiscoverAlbums = showDiscAlbums;
+        _showFavoriteAlbums = showFavAlbums;
+        _showFavoriteArtists = showFavArtists;
+        _showFavoriteTracks = showFavTracks;
+      });
+    }
   }
 
   @override
@@ -308,6 +334,167 @@ class _SettingsScreenState extends State<SettingsScreen> {
 
             const SizedBox(height: 32),
 
+            // Home Screen section
+            Text(
+              'Home Screen',
+              style: textTheme.titleMedium?.copyWith(
+                color: colorScheme.onBackground,
+                fontWeight: FontWeight.bold,
+              ),
+            ),
+            const SizedBox(height: 8),
+            Text(
+              'Choose which rows to display on the home screen',
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.onBackground.withOpacity(0.6),
+              ),
+            ),
+            const SizedBox(height: 16),
+
+            // Main rows section
+            Container(
+              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+              decoration: BoxDecoration(
+                color: colorScheme.surfaceVariant.withOpacity(0.3),
+                borderRadius: BorderRadius.circular(12),
+              ),
+              child: Column(
+                children: [
+                  SwitchListTile(
+                    title: Text(
+                      'Recently Played',
+                      style: TextStyle(color: colorScheme.onSurface),
+                    ),
+                    subtitle: Text(
+                      'Show recently played albums',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    ),
+                    value: _showRecentAlbums,
+                    onChanged: (value) {
+                      setState(() => _showRecentAlbums = value);
+                      SettingsService.setShowRecentAlbums(value);
+                    },
+                    activeColor: colorScheme.primary,
+                    contentPadding: EdgeInsets.zero,
+                  ),
+                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
+                  SwitchListTile(
+                    title: Text(
+                      'Discover Artists',
+                      style: TextStyle(color: colorScheme.onSurface),
+                    ),
+                    subtitle: Text(
+                      'Show random artists to discover',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    ),
+                    value: _showDiscoverArtists,
+                    onChanged: (value) {
+                      setState(() => _showDiscoverArtists = value);
+                      SettingsService.setShowDiscoverArtists(value);
+                    },
+                    activeColor: colorScheme.primary,
+                    contentPadding: EdgeInsets.zero,
+                  ),
+                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
+                  SwitchListTile(
+                    title: Text(
+                      'Discover Albums',
+                      style: TextStyle(color: colorScheme.onSurface),
+                    ),
+                    subtitle: Text(
+                      'Show random albums to discover',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    ),
+                    value: _showDiscoverAlbums,
+                    onChanged: (value) {
+                      setState(() => _showDiscoverAlbums = value);
+                      SettingsService.setShowDiscoverAlbums(value);
+                    },
+                    activeColor: colorScheme.primary,
+                    contentPadding: EdgeInsets.zero,
+                  ),
+                ],
+              ),
+            ),
+
+            const SizedBox(height: 16),
+
+            Text(
+              'Favorites',
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.onBackground.withOpacity(0.6),
+              ),
+            ),
+            const SizedBox(height: 8),
+
+            // Favorites rows section
+            Container(
+              padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+              decoration: BoxDecoration(
+                color: colorScheme.surfaceVariant.withOpacity(0.3),
+                borderRadius: BorderRadius.circular(12),
+              ),
+              child: Column(
+                children: [
+                  SwitchListTile(
+                    title: Text(
+                      'Favorite Albums',
+                      style: TextStyle(color: colorScheme.onSurface),
+                    ),
+                    subtitle: Text(
+                      'Show a row of your favorite albums',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    ),
+                    value: _showFavoriteAlbums,
+                    onChanged: (value) {
+                      setState(() => _showFavoriteAlbums = value);
+                      SettingsService.setShowFavoriteAlbums(value);
+                    },
+                    activeColor: colorScheme.primary,
+                    contentPadding: EdgeInsets.zero,
+                  ),
+                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
+                  SwitchListTile(
+                    title: Text(
+                      'Favorite Artists',
+                      style: TextStyle(color: colorScheme.onSurface),
+                    ),
+                    subtitle: Text(
+                      'Show a row of your favorite artists',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    ),
+                    value: _showFavoriteArtists,
+                    onChanged: (value) {
+                      setState(() => _showFavoriteArtists = value);
+                      SettingsService.setShowFavoriteArtists(value);
+                    },
+                    activeColor: colorScheme.primary,
+                    contentPadding: EdgeInsets.zero,
+                  ),
+                  Divider(color: colorScheme.outline.withOpacity(0.2), height: 1),
+                  SwitchListTile(
+                    title: Text(
+                      'Favorite Tracks',
+                      style: TextStyle(color: colorScheme.onSurface),
+                    ),
+                    subtitle: Text(
+                      'Show a row of your favorite tracks',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.6), fontSize: 12),
+                    ),
+                    value: _showFavoriteTracks,
+                    onChanged: (value) {
+                      setState(() => _showFavoriteTracks = value);
+                      SettingsService.setShowFavoriteTracks(value);
+                    },
+                    activeColor: colorScheme.primary,
+                    contentPadding: EdgeInsets.zero,
+                  ),
+                ],
+              ),
+            ),
+
+            const SizedBox(height: 32),
+
             Text(
               'Metadata APIs (Optional)',
               style: textTheme.titleMedium?.copyWith(

lib/services/debug_logger.dart

@@ -5,6 +5,7 @@ import 'package:device_info_plus/device_info_plus.dart';
 
 /// Log levels for filtering and display
 enum LogLevel {
+  perf,   // Performance timing (for FPS diagnosis)
   debug,  // Verbose debugging info (hidden by default)
   info,   // General information
   warning, // Potential issues
@@ -48,7 +49,16 @@ class DebugLogger {
   /// Legacy getter for backward compatibility
   List<String> get logs => _entries.map((e) => e.formatted).toList();
 
+  // Set to true to only log perf entries (for FPS diagnosis)
+  // Set to false for normal operation with full logging for user bug reports
+  static const bool _perfOnlyMode = false;
+
   void _addEntry(LogLevel level, String message, {String? context}) {
+    // In perf-only mode, skip all non-perf logs
+    if (_perfOnlyMode && level != LogLevel.perf) {
+      return;
+    }
+
     final entry = LogEntry(
       timestamp: DateTime.now(),
       level: level,
@@ -100,6 +110,54 @@ class DebugLogger {
     _addEntry(LogLevel.info, message);
   }
 
+  /// Performance logging - always prints to console for real-time monitoring
+  void perf(String message, {String? context}) {
+    _addEntry(LogLevel.perf, message, context: context);
+  }
+
+  /// Track build time of a widget
+  final Map<String, Stopwatch> _buildTimers = {};
+
+  void startBuild(String widgetName) {
+    _buildTimers[widgetName] = Stopwatch()..start();
+  }
+
+  void endBuild(String widgetName) {
+    final sw = _buildTimers.remove(widgetName);
+    if (sw != null) {
+      sw.stop();
+      if (sw.elapsedMilliseconds > 4) { // Only log if > 4ms (slow for 60fps)
+        perf('BUILD ${sw.elapsedMilliseconds}ms', context: widgetName);
+      }
+    }
+  }
+
+  /// Track frame times during scroll
+  Stopwatch? _frameTimer;
+  int _slowFrameCount = 0;
+  int _totalFrameCount = 0;
+
+  void startFrame() {
+    _frameTimer = Stopwatch()..start();
+  }
+
+  void endFrame() {
+    if (_frameTimer != null) {
+      _frameTimer!.stop();
+      _totalFrameCount++;
+      final ms = _frameTimer!.elapsedMilliseconds;
+      if (ms > 16) { // > 16ms means dropped frame at 60fps
+        _slowFrameCount++;
+        perf('SLOW FRAME ${ms}ms (${_slowFrameCount}/${_totalFrameCount} slow)', context: 'Scroll');
+      }
+    }
+  }
+
+  void resetFrameStats() {
+    _slowFrameCount = 0;
+    _totalFrameCount = 0;
+  }
+
   void clear() {
     _entries.clear();
   }

lib/services/hardware_volume_service.dart

@@ -0,0 +1,110 @@
+import 'dart:async';
+import 'package:flutter/services.dart';
+import 'debug_logger.dart';
+
+/// Service to intercept hardware volume button presses
+/// and route them to the selected Music Assistant player.
+///
+/// For MA players: intercept buttons and send volume commands via API
+/// For builtin player: let native volume work (don't intercept)
+class HardwareVolumeService {
+  static final HardwareVolumeService _instance = HardwareVolumeService._internal();
+  factory HardwareVolumeService() => _instance;
+  HardwareVolumeService._internal();
+
+  static const _channel = MethodChannel('com.musicassistant.music_assistant/volume_buttons');
+  final _logger = DebugLogger();
+
+  final _volumeUpController = StreamController<void>.broadcast();
+  final _volumeDownController = StreamController<void>.broadcast();
+
+  Stream<void> get onVolumeUp => _volumeUpController.stream;
+  Stream<void> get onVolumeDown => _volumeDownController.stream;
+
+  bool _isListening = false;
+  bool get isListening => _isListening;
+
+  bool _isIntercepting = false;
+  bool get isIntercepting => _isIntercepting;
+
+  /// Initialize the service and start listening for volume button events
+  Future<void> init() async {
+    _logger.log('🔊 HardwareVolumeService.init() called, _isListening=$_isListening');
+
+    if (_isListening) {
+      _logger.log('🔊 HardwareVolumeService.init() - already listening, returning early');
+      return;
+    }
+
+    _logger.log('🔊 Setting up MethodChannel handler for volume events...');
+    _channel.setMethodCallHandler((call) async {
+      _logger.log('🔊 MethodChannel received call: ${call.method}');
+      switch (call.method) {
+        case 'volumeUp':
+          _logger.log('🔊 Hardware VOLUME UP pressed - broadcasting event');
+          _volumeUpController.add(null);
+          break;
+        case 'volumeDown':
+          _logger.log('🔊 Hardware VOLUME DOWN pressed - broadcasting event');
+          _volumeDownController.add(null);
+          break;
+        default:
+          _logger.log('🔊 Unknown method call: ${call.method}');
+      }
+    });
+    _logger.log('🔊 MethodChannel handler set up');
+
+    try {
+      _logger.log('🔊 Invoking startListening on native channel...');
+      await _channel.invokeMethod('startListening');
+      _isListening = true;
+      _isIntercepting = true;
+      _logger.log('🔊 Native startListening succeeded, _isListening=$_isListening');
+    } catch (e) {
+      _logger.error('Failed to start volume button listening', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Enable or disable volume button interception.
+  /// When disabled, hardware volume buttons control device volume normally.
+  /// When enabled, volume button events are sent to Flutter for MA player control.
+  Future<void> setIntercepting(bool intercept) async {
+    if (!_isListening) {
+      _logger.log('🔊 setIntercepting($intercept) called but not listening yet');
+      return;
+    }
+
+    if (_isIntercepting == intercept) {
+      _logger.log('🔊 setIntercepting($intercept) - already in that state');
+      return;
+    }
+
+    try {
+      if (intercept) {
+        await _channel.invokeMethod('startListening');
+        _isIntercepting = true;
+        _logger.log('🔊 Volume interception ENABLED - will capture buttons for MA players');
+      } else {
+        await _channel.invokeMethod('stopListening');
+        _isIntercepting = false;
+        _logger.log('🔊 Volume interception DISABLED - native volume buttons work normally');
+      }
+    } catch (e) {
+      _logger.error('Failed to set volume interception to $intercept', context: 'VolumeService', error: e);
+    }
+  }
+
+  /// Stop listening for volume button events
+  Future<void> dispose() async {
+    if (!_isListening) return;
+
+    try {
+      await _channel.invokeMethod('stopListening');
+      _isListening = false;
+      _isIntercepting = false;
+      _logger.info('Hardware volume button listening stopped', context: 'VolumeService');
+    } catch (e) {
+      _logger.error('Failed to stop volume button listening', context: 'VolumeService', error: e);
+    }
+  }
+}

lib/services/settings_service.dart

@@ -21,6 +21,12 @@ class SettingsService {
   static const String _keyLocalPlayerName = 'local_player_name';
   static const String _keyOwnerName = 'owner_name';
   static const String _keyLastSelectedPlayerId = 'last_selected_player_id';
+  static const String _keyShowRecentAlbums = 'show_recent_albums';
+  static const String _keyShowDiscoverArtists = 'show_discover_artists';
+  static const String _keyShowDiscoverAlbums = 'show_discover_albums';
+  static const String _keyShowFavoriteAlbums = 'show_favorite_albums';
+  static const String _keyShowFavoriteArtists = 'show_favorite_artists';
+  static const String _keyShowFavoriteTracks = 'show_favorite_tracks';
 
   static Future<String?> getServerUrl() async {
     final prefs = await SharedPreferences.getInstance();
@@ -313,4 +319,66 @@ class SettingsService {
     final prefs = await SharedPreferences.getInstance();
     await prefs.clear();
   }
+
+  // Home Screen Row Settings (Main rows - default on)
+  static Future<bool> getShowRecentAlbums() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowRecentAlbums) ?? true;
+  }
+
+  static Future<void> setShowRecentAlbums(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowRecentAlbums, show);
+  }
+
+  static Future<bool> getShowDiscoverArtists() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowDiscoverArtists) ?? true;
+  }
+
+  static Future<void> setShowDiscoverArtists(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowDiscoverArtists, show);
+  }
+
+  static Future<bool> getShowDiscoverAlbums() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowDiscoverAlbums) ?? true;
+  }
+
+  static Future<void> setShowDiscoverAlbums(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowDiscoverAlbums, show);
+  }
+
+  // Home Screen Favorites Settings (default off)
+  static Future<bool> getShowFavoriteAlbums() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowFavoriteAlbums) ?? false;
+  }
+
+  static Future<void> setShowFavoriteAlbums(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowFavoriteAlbums, show);
+  }
+
+  static Future<bool> getShowFavoriteArtists() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowFavoriteArtists) ?? false;
+  }
+
+  static Future<void> setShowFavoriteArtists(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowFavoriteArtists, show);
+  }
+
+  static Future<bool> getShowFavoriteTracks() async {
+    final prefs = await SharedPreferences.getInstance();
+    return prefs.getBool(_keyShowFavoriteTracks) ?? false;
+  }
+
+  static Future<void> setShowFavoriteTracks(bool show) async {
+    final prefs = await SharedPreferences.getInstance();
+    await prefs.setBool(_keyShowFavoriteTracks, show);
+  }
 }

lib/widgets/album_row.dart

@@ -2,18 +2,21 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
+import '../services/debug_logger.dart';
 import 'album_card.dart';
 
 class AlbumRow extends StatefulWidget {
   final String title;
   final Future<List<Album>> Function() loadAlbums;
   final String? heroTagSuffix;
+  final double? rowHeight;
 
   const AlbumRow({
     super.key,
     required this.title,
     required this.loadAlbums,
     this.heroTagSuffix,
+    this.rowHeight,
   });
 
   @override
@@ -44,17 +47,28 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
     }
   }
 
+  static final _logger = DebugLogger();
+
   @override
   Widget build(BuildContext context) {
+    _logger.startBuild('AlbumRow:${widget.title}');
     super.build(context); // Required for AutomaticKeepAliveClientMixin
     final textTheme = Theme.of(context).textTheme;
     final colorScheme = Theme.of(context).colorScheme;
 
-    return Column(
+    // Total row height includes title + content
+    final totalHeight = widget.rowHeight ?? 237.0; // Default: 44 title + 193 content
+    const titleHeight = 44.0; // 12 top padding + ~24 text + 8 bottom padding
+    final contentHeight = totalHeight - titleHeight;
+
+    final result = RepaintBoundary(
+      child: SizedBox(
+        height: totalHeight,
+        child: Column(
         crossAxisAlignment: CrossAxisAlignment.start,
         children: [
           Padding(
-          padding: const EdgeInsets.symmetric(horizontal: 16.0, vertical: 8.0),
+            padding: const EdgeInsets.fromLTRB(16.0, 12.0, 16.0, 8.0),
             child: Text(
               widget.title,
               style: textTheme.titleLarge?.copyWith(
@@ -63,8 +77,7 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
               ),
             ),
           ),
-        SizedBox(
-          height: 193,
+          Expanded(
             child: FutureBuilder<List<Album>>(
               future: _albumsFuture,
               builder: (context, snapshot) {
@@ -91,18 +104,28 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
                   );
                 }
 
+                // Card layout: square artwork + text below
+                // Text area: 8px gap + ~18px title + ~18px artist = ~44px
+                const textAreaHeight = 44.0;
+                final artworkSize = contentHeight - textAreaHeight;
+                final cardWidth = artworkSize; // Card width = artwork width (square)
+                final itemExtent = cardWidth + 12; // width + horizontal margins
+
                 return ScrollConfiguration(
                   behavior: const _StretchScrollBehavior(),
                   child: ListView.builder(
                     scrollDirection: Axis.horizontal,
                     padding: const EdgeInsets.symmetric(horizontal: 12.0),
                     itemCount: albums.length,
-                  itemExtent: 162, // 150px width + 12px horizontal margins
+                    itemExtent: itemExtent,
+                    cacheExtent: 500, // Preload ~3 items ahead for smoother scrolling
+                    addAutomaticKeepAlives: false, // Row already uses AutomaticKeepAliveClientMixin
+                    addRepaintBoundaries: false, // Cards already have RepaintBoundary
                     itemBuilder: (context, index) {
                       final album = albums[index];
                       return Container(
                         key: ValueKey(album.uri ?? album.itemId),
-                      width: 150,
+                        width: cardWidth,
                         margin: const EdgeInsets.symmetric(horizontal: 6.0),
                         child: AlbumCard(
                           album: album,
@@ -116,7 +139,11 @@ class _AlbumRowState extends State<AlbumRow> with AutomaticKeepAliveClientMixin
             ),
           ),
           ],
+        ),
+      ),
     );
+    _logger.endBuild('AlbumRow:${widget.title}');
+    return result;
   }
 }
 

lib/widgets/artist_card.dart

@@ -1,5 +1,6 @@
 import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
+import 'package:cached_network_image/cached_network_image.dart';
 import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
 import '../screens/artist_details_screen.dart';
@@ -13,12 +14,14 @@ class ArtistCard extends StatefulWidget {
   final Artist artist;
   final VoidCallback? onTap;
   final String? heroTagSuffix;
+  final double? imageSize;
 
   const ArtistCard({
     super.key,
     required this.artist,
     this.onTap,
     this.heroTagSuffix,
+    this.imageSize,
   });
 
   @override
@@ -29,11 +32,36 @@ class _ArtistCardState extends State<ArtistCard> {
   static final _logger = DebugLogger();
   String? _fallbackImageUrl;
   bool _triedFallback = false;
+  String? _cachedMaImageUrl;
+
+  @override
+  void initState() {
+    super.initState();
+    // Fetch fallback image once in initState, not during build
+    _initFallbackImage();
+  }
+
+  void _initFallbackImage() {
+    // We'll check if MA has an image after first build, then fetch fallback if needed
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      final maProvider = context.read<MusicAssistantProvider>();
+      final maImageUrl = maProvider.api?.getImageUrl(widget.artist, size: 256);
+      _cachedMaImageUrl = maImageUrl;
+
+      if (maImageUrl == null && !_triedFallback) {
+        _triedFallback = true;
+        _logger.debug('No MA image for "${widget.artist.name}", trying fallback', context: 'ArtistCard');
+        _fetchFallbackImage();
+      }
+    });
+  }
 
   @override
   Widget build(BuildContext context) {
     final maProvider = context.read<MusicAssistantProvider>();
-    final maImageUrl = maProvider.api?.getImageUrl(widget.artist, size: 256);
+    // Use cached URL if available, otherwise get fresh (but don't trigger fetches during build)
+    final maImageUrl = _cachedMaImageUrl ?? maProvider.api?.getImageUrl(widget.artist, size: 256);
     final colorScheme = Theme.of(context).colorScheme;
     final textTheme = Theme.of(context).textTheme;
 
@@ -42,13 +70,6 @@ class _ArtistCardState extends State<ArtistCard> {
     // Use MA image if available, otherwise try fallback
     final imageUrl = maImageUrl ?? _fallbackImageUrl;
 
-    // Try to fetch fallback image if MA doesn't have one and we haven't tried yet
-    if (maImageUrl == null && !_triedFallback) {
-      _triedFallback = true;
-      _logger.debug('No MA image for "${widget.artist.name}", trying fallback', context: 'ArtistCard');
-      _fetchFallbackImage();
-    }
-
     return RepaintBoundary(
       child: GestureDetector(
         onTap: widget.onTap ?? () {
@@ -60,6 +81,7 @@ class _ArtistCardState extends State<ArtistCard> {
               child: ArtistDetailsScreen(
                 artist: widget.artist,
                 heroTagSuffix: widget.heroTagSuffix,
+                initialImageUrl: imageUrl,
               ),
             ),
           );
@@ -67,33 +89,49 @@ class _ArtistCardState extends State<ArtistCard> {
         child: Column(
           crossAxisAlignment: CrossAxisAlignment.center,
           children: [
-            // Artist image - circular
-            Hero(
+            // Artist image - circular, constrained to be a proper circle
+            Expanded(
+              child: Center(
+                child: LayoutBuilder(
+                  builder: (context, constraints) {
+                    // Use the smaller dimension to ensure a circle
+                    final size = constraints.maxWidth < constraints.maxHeight
+                        ? constraints.maxWidth
+                        : constraints.maxHeight;
+                    return Hero(
                       tag: HeroTags.artistImage + (widget.artist.uri ?? widget.artist.itemId) + suffix,
                       child: ClipOval(
                         child: Container(
-                  width: 110,
-                  height: 110,
+                          width: size,
+                          height: size,
                           color: colorScheme.surfaceVariant,
                           child: imageUrl != null
-                      ? Image.network(
-                          imageUrl,
+                              ? CachedNetworkImage(
+                                  imageUrl: imageUrl,
                                   fit: BoxFit.cover,
-                          cacheWidth: 256,
-                          cacheHeight: 256,
-                          errorBuilder: (_, __, ___) => Icon(
+                                  memCacheWidth: 256,
+                                  memCacheHeight: 256,
+                                  fadeInDuration: const Duration(milliseconds: 150),
+                                  placeholder: (context, url) => const SizedBox(),
+                                  errorWidget: (context, url, error) => Icon(
                                     Icons.person_rounded,
-                            size: 60,
+                                    size: size * 0.55,
                                     color: colorScheme.onSurfaceVariant,
                                   ),
                                 )
-                      : Icon(Icons.person_rounded, size: 60, color: colorScheme.onSurfaceVariant),
+                              : Icon(Icons.person_rounded, size: size * 0.55, color: colorScheme.onSurfaceVariant),
+                        ),
+                      ),
+                    );
+                  },
                 ),
               ),
             ),
-          const SizedBox(height: 12),
-          // Artist name
-          Hero(
+          const SizedBox(height: 8),
+          // Artist name - fixed height container so image size is consistent
+          SizedBox(
+            height: 36, // Fixed height for 2 lines of text
+            child: Hero(
               tag: HeroTags.artistName + (widget.artist.uri ?? widget.artist.itemId) + suffix,
               child: Material(
                 color: Colors.transparent,
@@ -109,6 +147,7 @@ class _ArtistCardState extends State<ArtistCard> {
                 ),
               ),
             ),
+          ),
           ],
         ),
       ),

lib/widgets/artist_row.dart

@@ -2,18 +2,21 @@ import 'package:flutter/material.dart';
 import 'package:provider/provider.dart';
 import '../models/media_item.dart';
 import '../providers/music_assistant_provider.dart';
+import '../services/debug_logger.dart';
 import 'artist_card.dart';
 
 class ArtistRow extends StatefulWidget {
   final String title;
   final Future<List<Artist>> Function() loadArtists;
   final String? heroTagSuffix;
+  final double? rowHeight;
 
   const ArtistRow({
     super.key,
     required this.title,
     required this.loadArtists,
     this.heroTagSuffix,
+    this.rowHeight,
   });
 
   @override
@@ -44,17 +47,28 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
     }
   }
 
+  static final _logger = DebugLogger();
+
   @override
   Widget build(BuildContext context) {
+    _logger.startBuild('ArtistRow:${widget.title}');
     super.build(context); // Required for AutomaticKeepAliveClientMixin
     final textTheme = Theme.of(context).textTheme;
     final colorScheme = Theme.of(context).colorScheme;
 
-    return Column(
+    // Total row height includes title + content
+    final totalHeight = widget.rowHeight ?? 207.0; // Default: 44 title + 163 content
+    const titleHeight = 44.0; // 12 top padding + ~24 text + 8 bottom padding
+    final contentHeight = totalHeight - titleHeight;
+
+    final result = RepaintBoundary(
+      child: SizedBox(
+        height: totalHeight,
+        child: Column(
           crossAxisAlignment: CrossAxisAlignment.start,
           children: [
             Padding(
-          padding: const EdgeInsets.symmetric(horizontal: 16.0, vertical: 8.0),
+              padding: const EdgeInsets.fromLTRB(16.0, 12.0, 16.0, 8.0),
               child: Text(
                 widget.title,
                 style: textTheme.titleLarge?.copyWith(
@@ -63,8 +77,7 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
               ),
             ),
           ),
-        SizedBox(
-          height: 163,
+          Expanded(
             child: FutureBuilder<List<Artist>>(
               future: _artistsFuture,
               builder: (context, snapshot) {
@@ -91,18 +104,28 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
                   );
                 }
 
+                // Card layout: circle image + name below
+                // Text area: 8px gap + ~36px for 2-line name = ~44px
+                const textAreaHeight = 44.0;
+                final imageSize = contentHeight - textAreaHeight;
+                final cardWidth = imageSize; // Card width = image width (circle)
+                final itemExtent = cardWidth + 16; // width + horizontal margins
+
                 return ScrollConfiguration(
                   behavior: const _StretchScrollBehavior(),
                   child: ListView.builder(
                     scrollDirection: Axis.horizontal,
                     padding: const EdgeInsets.symmetric(horizontal: 12.0),
                     itemCount: artists.length,
-                  itemExtent: 136, // 120px width + 16px horizontal margins
+                    itemExtent: itemExtent,
+                    cacheExtent: 500, // Preload ~3 items ahead for smoother scrolling
+                    addAutomaticKeepAlives: false, // Row already uses AutomaticKeepAliveClientMixin
+                    addRepaintBoundaries: false, // Cards already have RepaintBoundary
                     itemBuilder: (context, index) {
                       final artist = artists[index];
                       return Container(
                         key: ValueKey(artist.uri ?? artist.itemId),
-                      width: 120,
+                        width: cardWidth,
                         margin: const EdgeInsets.symmetric(horizontal: 8.0),
                         child: ArtistCard(
                           artist: artist,
@@ -116,7 +139,11 @@ class _ArtistRowState extends State<ArtistRow> with AutomaticKeepAliveClientMixi
             ),
           ),
           ],
+        ),
+      ),
     );
+    _logger.endBuild('ArtistRow:${widget.title}');
+    return result;
   }
 }
 

lib/widgets/global_player_overlay.dart

@@ -5,6 +5,40 @@ import '../providers/navigation_provider.dart';
 import '../theme/theme_provider.dart';
 import 'expandable_player.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>();
 
@@ -23,7 +57,7 @@ class BottomSpacing {
   static const double navBarOnly = navBarHeight + 16.0;
 
   /// Space needed when mini player is also visible
-  static const double withMiniPlayer = navBarHeight + miniPlayerHeight + 14.0;
+  static const double withMiniPlayer = navBarHeight + miniPlayerHeight + 22.0;
 }
 
 /// ValueNotifier for player expansion progress (0.0 to 1.0) and background color
@@ -135,19 +169,13 @@ class _GlobalPlayerOverlayState extends State<GlobalPlayerOverlay>
               return Consumer<ThemeProvider>(
                 builder: (context, themeProvider, _) {
                   // Use adaptive primary color for bottom nav when adaptive theme is enabled
-                  var navSelectedColor = themeProvider.adaptiveTheme
+                  final sourceColor = themeProvider.adaptiveTheme
                       ? themeProvider.adaptivePrimaryColor
                       : colorScheme.primary;
 
-                  // Ensure nav color has sufficient contrast against the surface background
+                  // Use cached color computation to avoid expensive HSL operations during scroll
                   final isDark = Theme.of(context).brightness == Brightness.dark;
-                  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();
-                  }
+                  final navSelectedColor = _cachedNavColor.getAdjustedColor(sourceColor, isDark);
 
                   // Base background: use adaptive surface color if available, otherwise default surface
                   final baseBgColor = (themeProvider.adaptiveTheme && themeProvider.adaptiveSurfaceColor != null)

lib/widgets/player/queue_panel.dart

@@ -89,6 +89,8 @@ class QueuePanel extends StatelessWidget {
     return ListView.builder(
       padding: Spacing.paddingH8,
       cacheExtent: 500,
+      addAutomaticKeepAlives: false, // Items don't need individual keep-alive
+      addRepaintBoundaries: false, // We add RepaintBoundary manually
       itemCount: items.length,
       itemBuilder: (context, index) {
         final item = items[index];
@@ -96,7 +98,8 @@ class QueuePanel extends StatelessWidget {
         final isPastItem = index < currentIndex;
         final imageUrl = maProvider.api?.getImageUrl(item.track, size: 80);
 
-        return Opacity(
+        return RepaintBoundary(
+          child: Opacity(
           opacity: isPastItem ? 0.5 : 1.0,
           child: Container(
             margin: EdgeInsets.symmetric(vertical: Spacing.xxs),
@@ -162,6 +165,7 @@ class QueuePanel extends StatelessWidget {
               },
             ),
           ),
+          ),
         );
       },
     );

lib/widgets/track_row.dart

@@ -0,0 +1,260 @@
+import 'package:flutter/material.dart';
+import 'package:provider/provider.dart';
+import 'package:cached_network_image/cached_network_image.dart';
+import '../models/media_item.dart';
+import '../providers/music_assistant_provider.dart';
+import '../services/debug_logger.dart';
+
+class TrackRow extends StatefulWidget {
+  final String title;
+  final Future<List<Track>> Function() loadTracks;
+  final double? rowHeight;
+
+  const TrackRow({
+    super.key,
+    required this.title,
+    required this.loadTracks,
+    this.rowHeight,
+  });
+
+  @override
+  State<TrackRow> createState() => _TrackRowState();
+}
+
+class _TrackRowState extends State<TrackRow> with AutomaticKeepAliveClientMixin {
+  late Future<List<Track>> _tracksFuture;
+  List<Track>? _cachedTracks;
+  bool _hasLoaded = false;
+
+  @override
+  bool get wantKeepAlive => true;
+
+  @override
+  void initState() {
+    super.initState();
+    _loadTracksOnce();
+  }
+
+  void _loadTracksOnce() {
+    if (!_hasLoaded) {
+      _tracksFuture = widget.loadTracks().then((tracks) {
+        _cachedTracks = tracks;
+        return tracks;
+      });
+      _hasLoaded = true;
+    }
+  }
+
+  static final _logger = DebugLogger();
+
+  @override
+  Widget build(BuildContext context) {
+    _logger.startBuild('TrackRow:${widget.title}');
+    super.build(context);
+    final textTheme = Theme.of(context).textTheme;
+    final colorScheme = Theme.of(context).colorScheme;
+
+    // Total row height includes title + content
+    final totalHeight = widget.rowHeight ?? 224.0; // Default: 44 title + 180 content
+    const titleHeight = 44.0; // 12 top padding + ~24 text + 8 bottom padding
+    final contentHeight = totalHeight - titleHeight;
+
+    final result = RepaintBoundary(
+      child: SizedBox(
+        height: totalHeight,
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Padding(
+              padding: const EdgeInsets.fromLTRB(16.0, 12.0, 16.0, 8.0),
+              child: Text(
+                widget.title,
+                style: textTheme.titleLarge?.copyWith(
+                fontWeight: FontWeight.bold,
+                color: colorScheme.onBackground,
+              ),
+            ),
+          ),
+          Expanded(
+            child: FutureBuilder<List<Track>>(
+              future: _tracksFuture,
+              builder: (context, snapshot) {
+                final tracks = snapshot.data ?? _cachedTracks;
+
+                if (tracks == null && snapshot.connectionState == ConnectionState.waiting) {
+                  return const Center(child: CircularProgressIndicator());
+                }
+
+                if (snapshot.hasError && tracks == null) {
+                  return Center(
+                    child: Text('Error: ${snapshot.error}'),
+                  );
+                }
+
+                if (tracks == null || tracks.isEmpty) {
+                  return Center(
+                    child: Text(
+                      'No tracks found',
+                      style: TextStyle(color: colorScheme.onSurface.withOpacity(0.5)),
+                    ),
+                  );
+                }
+
+                // Card layout: square artwork + text below
+                // Text area: 8px gap + ~18px title + ~18px artist = ~44px
+                const textAreaHeight = 44.0;
+                final artworkSize = contentHeight - textAreaHeight;
+                final cardWidth = artworkSize; // Card width = artwork width (square)
+                final itemExtent = cardWidth + 12;
+
+                return ScrollConfiguration(
+                  behavior: const _StretchScrollBehavior(),
+                  child: ListView.builder(
+                    scrollDirection: Axis.horizontal,
+                    padding: const EdgeInsets.symmetric(horizontal: 12.0),
+                    itemCount: tracks.length,
+                    itemExtent: itemExtent,
+                    cacheExtent: 500, // Preload ~3 items ahead for smoother scrolling
+                    addAutomaticKeepAlives: false, // Row already uses AutomaticKeepAliveClientMixin
+                    addRepaintBoundaries: false, // Cards already have RepaintBoundary
+                    itemBuilder: (context, index) {
+                      final track = tracks[index];
+                      return Container(
+                        key: ValueKey(track.uri ?? track.itemId),
+                        width: cardWidth,
+                        margin: const EdgeInsets.symmetric(horizontal: 6.0),
+                        child: _TrackCard(
+                          track: track,
+                          tracks: tracks,
+                          index: index,
+                        ),
+                      );
+                    },
+                  ),
+                );
+              },
+            ),
+          ),
+          ],
+        ),
+      ),
+    );
+    _logger.endBuild('TrackRow:${widget.title}');
+    return result;
+  }
+}
+
+class _TrackCard extends StatelessWidget {
+  final Track track;
+  final List<Track> tracks;
+  final int index;
+
+  const _TrackCard({
+    required this.track,
+    required this.tracks,
+    required this.index,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    final maProvider = context.read<MusicAssistantProvider>();
+    // Try track image first, then album image
+    final trackImageUrl = maProvider.getImageUrl(track, size: 256);
+    final albumImageUrl = track.album != null
+        ? maProvider.getImageUrl(track.album!, size: 256)
+        : null;
+    final imageUrl = trackImageUrl ?? albumImageUrl;
+    final colorScheme = Theme.of(context).colorScheme;
+    final textTheme = Theme.of(context).textTheme;
+
+    return RepaintBoundary(
+      child: GestureDetector(
+        onTap: () => _playTrack(context, maProvider),
+        child: Column(
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            // Album artwork
+            AspectRatio(
+              aspectRatio: 1.0,
+              child: ClipRRect(
+                borderRadius: BorderRadius.circular(12.0),
+                child: Container(
+                  color: colorScheme.surfaceVariant,
+                  child: imageUrl != null
+                      ? CachedNetworkImage(
+                          imageUrl: imageUrl,
+                          fit: BoxFit.cover,
+                          memCacheWidth: 256,
+                          memCacheHeight: 256,
+                          fadeInDuration: const Duration(milliseconds: 150),
+                          placeholder: (context, url) => const SizedBox(),
+                          errorWidget: (context, url, error) => Icon(
+                            Icons.music_note_rounded,
+                            size: 64,
+                            color: colorScheme.onSurfaceVariant,
+                          ),
+                        )
+                      : Center(
+                          child: Icon(
+                            Icons.music_note_rounded,
+                            size: 64,
+                            color: colorScheme.onSurfaceVariant,
+                          ),
+                        ),
+                ),
+              ),
+            ),
+            const SizedBox(height: 8),
+            // Track title
+            Text(
+              track.name,
+              maxLines: 1,
+              overflow: TextOverflow.ellipsis,
+              style: textTheme.titleSmall?.copyWith(
+                color: colorScheme.onSurface,
+                fontWeight: FontWeight.w500,
+              ),
+            ),
+            // Artist name
+            Text(
+              track.artistsString,
+              maxLines: 1,
+              overflow: TextOverflow.ellipsis,
+              style: textTheme.bodySmall?.copyWith(
+                color: colorScheme.onSurface.withOpacity(0.7),
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+
+  Future<void> _playTrack(BuildContext context, MusicAssistantProvider maProvider) async {
+    if (maProvider.selectedPlayer == null) {
+      ScaffoldMessenger.of(context).showSnackBar(
+        const SnackBar(content: Text('No player selected')),
+      );
+      return;
+    }
+
+    await maProvider.playTracks(
+      maProvider.selectedPlayer!.playerId,
+      tracks,
+      startIndex: index,
+    );
+  }
+}
+
+class _StretchScrollBehavior extends ScrollBehavior {
+  const _StretchScrollBehavior();
+
+  @override
+  Widget buildOverscrollIndicator(
+      BuildContext context, Widget child, ScrollableDetails details) {
+    return StretchingOverscrollIndicator(
+      axisDirection: details.direction,
+      child: child,
+    );
+  }
+}