Merge pull request 'release v2026.05.13.3: full-player seed + MediaSession expansion (Wear)' (#46) from dev into main

External media controllers (Android Wear, Auto, Bluetooth dashes,
lock-screen widgets) consume the audio_service MediaSession and
silently no-op on any action that isn't in the handler's
systemActions set. Several handler methods were already implemented
but never advertised, plus stop() defaulted to a no-op — which
matched user reports of "media controller on the watch sometimes
works but doesn't play nice with Minstrel."

This patch lines the advertised surface up with what the handler
actually implements + wires a native heart-rating button.

**Expanded controls + systemActions:**
- Added MediaControl.stop to the expanded controls list.
- systemActions now also enumerates stop, skipToQueueItem (override
  shipped in v2026.05.13.1), setShuffleMode, setRepeatMode, and
  setRating. Without these in the set, Android 13+ drops the
  corresponding callbacks from external surfaces.

**stop() override:** halts _player and dismisses the foreground
notification via super.stop(). Default just flipped processingState
to idle without releasing the audio session — external surfaces
treated that as "paused forever".

**setRating wiring (native heart-button protocol):** new LikeBridge
adapter passes through configure() carrying toggleTrackLike +
isTrackLiked closures over LikesController and likedIdsProvider.
- setRating override flips the like through the bridge and re-emits
  mediaItem so the watch's heart icon updates immediately.
- _toMediaItem populates MediaItem.rating on every track change so
  the right filled/outlined heart shows on track-A → track-B.
- PlayerActions ref.listen on likedIdsProvider calls
  refreshCurrentRating so toggling a like from TrackRow / kebab /
  another device (SSE) also keeps the watch icon in sync.

**artUri seed on first broadcast:** AlbumCoverCache.peekCached
returns the file path synchronously when the cover is already on
disk. _toMediaItem uses this so warm-cache tracks broadcast with
artUri populated from the first frame — external controllers see
the cover immediately instead of waiting for the later async
_loadArtForCurrentItem path. Cold-cache tracks fall through to that
path unchanged.

flutter_client/lib/cache/adapters.dart

@@ -17,10 +17,21 @@ import '../models/track.dart';
 import 'db.dart';
 
 extension CachedArtistAdapter on CachedArtist {
-  ArtistRef toRef() => ArtistRef(
+  /// `coverAlbumId` lets the caller pass a representative album id so
+  /// the ArtistRef carries a reconstructed `/api/albums/<id>/cover`
+  /// URL. cached_artists doesn't store this directly — the server
+  /// derives it from the most-recent album at query time — so drift
+  /// readers that want the cover URL join cached_albums and pass the
+  /// first album's id through. Empty string yields empty coverUrl,
+  /// matching the server's behavior for endpoints that don't carry
+  /// the lookup (artist detail, search, raw cached_artists row reads).
+  ArtistRef toRef({String coverAlbumId = ''}) => ArtistRef(
         id: id,
         name: name,
         sortName: sortName,
+        coverUrl: coverAlbumId.isNotEmpty
+            ? '/api/albums/$coverAlbumId/cover'
+            : '',
       );
 }
 

flutter_client/lib/cache/tile_providers.dart

@@ -18,6 +18,7 @@
 // subscriptions; drift handles this fine in practice but worth
 // measuring if a future surface scales to hundreds.
 
+import 'package:drift/drift.dart' as drift show OrderingTerm;
 import 'package:drift/drift.dart' show leftOuterJoin;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
@@ -63,6 +64,12 @@ final albumTileProvider =
 
 /// Watches the cached_artists row for [id]. Triggers background
 /// hydration on miss; yields the row once it lands.
+///
+/// LEFT JOIN cached_albums ordered by sort_title so the first row per
+/// artist carries a representative album id; toRef() reconstructs
+/// `/api/albums/<id>/cover` from it. Without this join the ArtistRef
+/// has an empty coverUrl and tiles fall back to the music-notes
+/// placeholder even though the server has the cover available.
 final artistTileProvider =
     StreamProvider.family<ArtistRef?, String>((ref, id) async* {
   if (id.isEmpty) {
@@ -70,7 +77,12 @@ final artistTileProvider =
     return;
   }
   final db = ref.watch(appDbProvider);
-  final query = db.select(db.cachedArtists)..where((t) => t.id.equals(id));
+  final query = (db.select(db.cachedArtists)..where((t) => t.id.equals(id)))
+      .join([
+    leftOuterJoin(db.cachedAlbums,
+        db.cachedAlbums.artistId.equalsExp(db.cachedArtists.id)),
+  ])
+    ..orderBy([drift.OrderingTerm.asc(db.cachedAlbums.sortTitle)]);
   var enqueued = false;
   await for (final rows in query.watch()) {
     if (rows.isEmpty) {
@@ -83,7 +95,12 @@ final artistTileProvider =
       yield null;
       continue;
     }
-    yield rows.first.toRef();
+    // First row has the alphabetically-first album (or null if artist
+    // has no albums in drift yet — yields a coverless ArtistRef which
+    // the UI falls back to the placeholder icon for).
+    final artist = rows.first.readTable(db.cachedArtists);
+    final firstAlbum = rows.first.readTableOrNull(db.cachedAlbums);
+    yield artist.toRef(coverAlbumId: firstAlbum?.id ?? '');
   }
 });
 

flutter_client/lib/library/library_providers.dart

@@ -233,17 +233,28 @@ Map<String, dynamic> _trackToJson(TrackRef t) => {
 final artistProvider =
     StreamProvider.family<ArtistRef, String>((ref, id) {
   final db = ref.watch(appDbProvider);
-  return cacheFirst<CachedArtist, ArtistRef>(
-    driftStream: (db.select(db.cachedArtists)..where((t) => t.id.equals(id)))
-        .watch(),
+  // LEFT JOIN cached_albums for cover-URL reconstruction (see
+  // CachedArtistAdapter.toRef). First row carries the alphabetically-
+  // first album.
+  final query = (db.select(db.cachedArtists)..where((t) => t.id.equals(id)))
+      .join([
+    drift.leftOuterJoin(db.cachedAlbums,
+        db.cachedAlbums.artistId.equalsExp(db.cachedArtists.id)),
+  ])
+    ..orderBy([drift.OrderingTerm.asc(db.cachedAlbums.sortTitle)]);
+  return cacheFirst<drift.TypedResult, ArtistRef>(
+    driftStream: query.watch(),
     fetchAndPopulate: () async {
       final api = await ref.read(libraryApiProvider.future);
       final fresh = await api.getArtist(id);
       await db.into(db.cachedArtists).insertOnConflictUpdate(fresh.toDrift());
     },
-    toResult: (rows) => rows.isEmpty
-        ? const ArtistRef(id: '', name: '')
-        : rows.first.toRef(),
+    toResult: (rows) {
+      if (rows.isEmpty) return const ArtistRef(id: '', name: '');
+      final artist = rows.first.readTable(db.cachedArtists);
+      final firstAlbum = rows.first.readTableOrNull(db.cachedAlbums);
+      return artist.toRef(coverAlbumId: firstAlbum?.id ?? '');
+    },
     isOnline: () async => (await ref
         .read(connectivityProvider.future)
         .timeout(const Duration(seconds: 3), onTimeout: () => true)),

flutter_client/lib/library/library_screen.dart

@@ -62,9 +62,19 @@ final _meApiProvider = FutureProvider<MeApi>((ref) async {
 /// via /api/library/sync.
 final _libraryArtistsProvider = StreamProvider<List<ArtistRef>>((ref) {
   final db = ref.watch(appDbProvider);
-  final query = db.select(db.cachedArtists)
-    ..orderBy([(t) => drift.OrderingTerm.asc(t.sortName)]);
-  return cacheFirst<CachedArtist, List<ArtistRef>>(
+  // LEFT JOIN cached_albums so each artist row carries a representative
+  // album id for cover-URL reconstruction. Sorted by artist sortName
+  // then album sortTitle: the first row per artist gets the
+  // alphabetically-first album. Dedup happens in toResult.
+  final query = db.select(db.cachedArtists).join([
+    drift.leftOuterJoin(db.cachedAlbums,
+        db.cachedAlbums.artistId.equalsExp(db.cachedArtists.id)),
+  ])
+    ..orderBy([
+      drift.OrderingTerm.asc(db.cachedArtists.sortName),
+      drift.OrderingTerm.asc(db.cachedAlbums.sortTitle),
+    ]);
+  return cacheFirst<drift.TypedResult, List<ArtistRef>>(
     driftStream: query.watch(),
     fetchAndPopulate: () async {
       // Cold-cache fallback: sync should have populated drift already,
@@ -80,7 +90,23 @@ final _libraryArtistsProvider = StreamProvider<List<ArtistRef>>((ref) {
         );
       });
     },
-    toResult: (rows) => rows.map((r) => r.toRef()).toList(),
+    toResult: (rows) {
+      // The join multiplies rows by album count; dedup by artist id
+      // keeping the first occurrence so we get one ArtistRef per
+      // artist with the alphabetically-first album's id for the
+      // cover-URL projection. Artists with no albums in drift yet
+      // come through as a single row with null cachedAlbums and an
+      // empty coverUrl — UI falls back to the placeholder icon.
+      final seen = <String>{};
+      final out = <ArtistRef>[];
+      for (final r in rows) {
+        final a = r.readTable(db.cachedArtists);
+        if (!seen.add(a.id)) continue;
+        final album = r.readTableOrNull(db.cachedAlbums);
+        out.add(a.toRef(coverAlbumId: album?.id ?? ''));
+      }
+      return out;
+    },
     isOnline: () async => (await ref
         .read(connectivityProvider.future)
         .timeout(const Duration(seconds: 3), onTimeout: () => true)),

flutter_client/lib/player/album_cover_cache.dart

@@ -27,6 +27,32 @@ class AlbumCoverCache {
   /// same album dedupe to one fetch.
   final Map<String, Future<String?>> _inflight = {};
 
+  /// Cached covers directory path resolved once on the first
+  /// async cacheDir call, then reused for sync existsSync() checks
+  /// in [peekCached]. Without this every "is the cover already on
+  /// disk?" check would have to await path_provider, blocking the
+  /// MediaItem broadcast on every track change.
+  String? _coversDirPath;
+
+  /// Returns the local file path for [albumId]'s cover if it's
+  /// already cached on disk, or null otherwise. Synchronous — uses
+  /// File.existsSync() against a path computed from the directory
+  /// resolved by an earlier async [getOrFetch] call. Returns null
+  /// until at least one getOrFetch has populated _coversDirPath.
+  ///
+  /// The audio handler uses this to seed MediaItem.artUri on the
+  /// initial broadcast so external media controllers (Wear, Android
+  /// Auto, Bluetooth) see the cover on the first frame for warm-cache
+  /// tracks. Cold-cache tracks still fall back to the async
+  /// _loadArtForCurrentItem path.
+  String? peekCached(String albumId) {
+    if (albumId.isEmpty) return null;
+    final dir = _coversDirPath;
+    if (dir == null) return null;
+    final path = '$dir/$albumId.jpg';
+    return File(path).existsSync() ? path : null;
+  }
+
   /// Returns local file path to the album cover, or null on any
   /// failure (network, 4xx/5xx, disk full, empty albumId).
   Future<String?> getOrFetch(String albumId) {
@@ -44,6 +70,9 @@ class AlbumCoverCache {
       final dir = await _cacheDirFactory();
       final coversDir = Directory('${dir.path}/album_covers');
       await coversDir.create(recursive: true);
+      // Cache the resolved directory so [peekCached] can do its
+      // existsSync() check without re-awaiting path_provider.
+      _coversDirPath = coversDir.path;
       final filePath = '${coversDir.path}/$albumId.jpg';
       final file = File(filePath);
       if (await file.exists()) return filePath;

flutter_client/lib/player/audio_handler.dart

@@ -40,6 +40,7 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
   String? _token;
   AlbumCoverCache? _coverCache;
   AudioCacheManager? _audioCacheManager;
+  LikeBridge? _likeBridge;
 
   /// Trackers to dedupe registration — once we've inserted an index row
   /// for a trackId, don't repeat the work on every buffered-position
@@ -94,10 +95,12 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
     required String? token,
     AlbumCoverCache? coverCache,
     AudioCacheManager? audioCacheManager,
+    LikeBridge? likeBridge,
   }) {
     _baseUrl = baseUrl;
     _token = token;
     if (coverCache != null) _coverCache = coverCache;
+    if (likeBridge != null) _likeBridge = likeBridge;
     if (audioCacheManager != null) _audioCacheManager = audioCacheManager;
   }
 
@@ -301,12 +304,30 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
     final extras = <String, dynamic>{};
     if (t.albumId.isNotEmpty) extras['album_id'] = t.albumId;
     if (t.artistId.isNotEmpty) extras['artist_id'] = t.artistId;
+    // Sync-peek the album cover cache so warm-cache tracks broadcast
+    // with artUri populated on the first frame. External media
+    // controllers (Android Wear, Bluetooth dashes, Auto, lock screen)
+    // can only render the cover bytes that audio_service hands them
+    // at MediaItem broadcast time; the later async _loadArtForCurrent
+    // Item path repopulates for cold-cache tracks. Without this seed,
+    // every track change starts with a generic icon on the watch and
+    // only gets the real cover after one or two seconds.
+    final coverPath = (t.albumId.isNotEmpty && _coverCache != null)
+        ? _coverCache!.peekCached(t.albumId)
+        : null;
+    // MediaItem.rating reflects the user's like state on this track
+    // so external surfaces (Wear's heart button, lock-screen
+    // favorites) render the right filled/outlined icon. Updated on
+    // every track change via _likeBridge.isTrackLiked.
+    final liked = _likeBridge?.isTrackLiked(t.id) ?? false;
     return MediaItem(
       id: t.id,
       title: t.title,
       artist: t.artistName,
       album: t.albumTitle,
       duration: Duration(seconds: t.durationSec),
+      artUri: coverPath != null ? Uri.file(coverPath) : null,
+      rating: Rating.newHeartRating(liked),
       extras: extras.isEmpty ? null : extras,
     );
   }
@@ -391,6 +412,58 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
   @override
   Future<void> skipToPrevious() => _player.seekToPrevious();
 
+  /// Stops playback and dismisses the system notification. BaseAudio
+  /// Handler's default just sets the processing state to idle without
+  /// touching the player, so the just_audio engine kept its audio
+  /// session and external surfaces (Wear, Auto, BT) saw a "paused
+  /// forever" rather than a clean stop. Halting the player releases
+  /// the session and lets super.stop() tear down the foreground
+  /// notification.
+  @override
+  Future<void> stop() async {
+    await _player.stop();
+    await super.stop();
+  }
+
+  /// Heart rating from external surfaces (Wear's favorite button,
+  /// lock-screen like) → LikesController.toggle(track). We only
+  /// route through the bridge when the rating actually flips relative
+  /// to the current state, so repeated taps from a flaky controller
+  /// don't ping-pong the like.
+  @override
+  Future<void> setRating(Rating rating, [Map<String, dynamic>? extras]) async {
+    final media = mediaItem.value;
+    final bridge = _likeBridge;
+    if (media == null || bridge == null) return;
+    final currentlyLiked = bridge.isTrackLiked(media.id);
+    final wantLiked = rating.hasHeart();
+    if (currentlyLiked == wantLiked) return;
+    try {
+      await bridge.toggleTrackLike(media.id);
+    } catch (_) {
+      // LikesController already rolls back on REST failure; nothing
+      // to do here beyond letting the broadcast skip.
+      return;
+    }
+    // Re-emit so the watch's heart icon updates immediately.
+    mediaItem.add(media.copyWith(rating: Rating.newHeartRating(wantLiked)));
+  }
+
+  /// Re-emits the current mediaItem with a fresh rating pulled from
+  /// the LikeBridge. Called by PlayerActions on likedIdsProvider
+  /// changes so the watch / lock-screen heart icon updates when the
+  /// user toggles a like from TrackRow, the kebab menu, or another
+  /// device's playback (SSE-routed). No-op if no track is playing
+  /// or the like state didn't change.
+  void refreshCurrentRating() {
+    final media = mediaItem.value;
+    final bridge = _likeBridge;
+    if (media == null || bridge == null) return;
+    final liked = bridge.isTrackLiked(media.id);
+    if (media.rating?.hasHeart() == liked) return;
+    mediaItem.add(media.copyWith(rating: Rating.newHeartRating(liked)));
+  }
+
   @override
   Future<void> setShuffleMode(AudioServiceShuffleMode shuffleMode) async {
     await _player
@@ -425,20 +498,33 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
         MediaControl.skipToPrevious,
         if (playing) MediaControl.pause else MediaControl.play,
         MediaControl.skipToNext,
+        MediaControl.stop,
       ],
       // androidCompactActionIndices tells the system which controls
       // appear in the collapsed/lock-screen view. Without this, some
       // Android versions render the player without working buttons.
+      // Keep this at 3 actions (prev/play-pause/next) — stop lives
+      // in the expanded view only.
       androidCompactActionIndices: const [0, 1, 2],
       // systemActions enumerates which actions the system can invoke
-      // on us — without play/pause/skip in here, taps on lock-screen
-      // controls don't route back to the handler on Android 13+.
+      // on us. Anything not listed here doesn't route back to the
+      // handler from external surfaces (Wear, Auto, Bluetooth, lock
+      // screen) — Android 13+ silently drops those events. Keep this
+      // in sync with the override methods so each implemented action
+      // is actually advertised.
       systemActions: const {
         MediaAction.play,
         MediaAction.pause,
+        MediaAction.stop,
         MediaAction.skipToNext,
         MediaAction.skipToPrevious,
+        MediaAction.skipToQueueItem,
         MediaAction.seek,
+        MediaAction.setShuffleMode,
+        MediaAction.setRepeatMode,
+        // Heart rating — Wear and lock screen render this as a like
+        // button. Routed to LikesController via _likeBridge.
+        MediaAction.setRating,
       },
       processingState: switch (_player.processingState) {
         ProcessingState.idle => AudioProcessingState.idle,
@@ -463,3 +549,27 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
     ));
   }
 }
+
+/// Adapter that lets the audio handler call into the app's
+/// LikesController without depending on Riverpod directly. Constructed
+/// in PlayerActions where ref is available; consumed inside the audio
+/// handler's setRating override and MediaItem builder to keep external
+/// media controllers (Wear, lock screen, Auto) in sync with the
+/// likedIds drift cache.
+class LikeBridge {
+  const LikeBridge({
+    required this.toggleTrackLike,
+    required this.isTrackLiked,
+  });
+
+  /// Flip the like state for [trackId]. Returns a Future that resolves
+  /// once the underlying LikesController has both updated drift
+  /// optimistically and rolled the change through the REST API
+  /// (errors result in drift rollback inside LikesController).
+  final Future<void> Function(String trackId) toggleTrackLike;
+
+  /// Read the current like state for [trackId] from the drift-backed
+  /// likedIdsProvider. Synchronous because the audio handler needs
+  /// to populate MediaItem.rating on the broadcast hot path.
+  final bool Function(String trackId) isTrackLiked;
+}

flutter_client/lib/player/now_playing_screen.dart

@@ -45,16 +45,105 @@ class _NowPlayingScreenState extends ConsumerState<NowPlayingScreen> {
   // dismiss. Reset on each drag start.
   double _dragOffset = 0;
 
-  /// Last resolved dominant color. Held across track changes so the
-  /// gradient backdrop tweens smoothly from the previous album's color
-  /// to the next, instead of dropping through fs.obsidian during the
-  /// brief moment albumColorProvider for the new id is still loading.
-  Color? _lastDominant;
+  /// The MediaItem currently displayed on the screen. Held separately
+  /// from the live mediaItemProvider so we can preload the new track's
+  /// cover bytes + dominant color BEFORE flipping the visible state.
+  /// Without this gate the full-player UI swapped to the new track's
+  /// title/cover slot immediately while the image was still decoding,
+  /// producing a visible "pop in" once the bytes arrived.
+  MediaItem? _displayedMedia;
 
-  /// Dedupe key for the cover precache side-effect. Without this we'd
-  /// fire precacheImage on every MediaItem rebroadcast (twice per track
-  /// change, once on artUri arrival).
-  String? _precachedArtUri;
+  /// Dominant color of [_displayedMedia]'s cover. Tweened by the
+  /// backdrop AnimatedContainer when it changes.
+  Color? _displayedDominant;
+
+  /// The id of the most-recent track we kicked a preload for. Used to
+  /// drop stale preload completions when the user skips rapidly past
+  /// a track whose cover hadn't finished decoding yet.
+  String? _pendingPreloadId;
+
+  @override
+  void initState() {
+    super.initState();
+    // Seed displayed state from the current mediaItem if a track is
+    // already playing when the full player is opened. ref.listen
+    // below only fires on CHANGES after subscription, so without
+    // this seed the screen sits on "Nothing playing." even though
+    // the mini bar shows a live track — the listener never gets a
+    // mediaItem emission because the stream's current value hasn't
+    // changed.
+    final current = ref.read(mediaItemProvider).value;
+    if (current == null) return;
+    _displayedMedia = current;
+    // Best-effort synchronous color seed: if albumColorProvider has
+    // already extracted this album's dominant color earlier in the
+    // session, pull it now so the backdrop renders correctly on
+    // first frame. Otherwise the post-frame _scheduleSwap below
+    // resolves it asynchronously and AnimatedContainer tweens.
+    final albumId = current.extras?['album_id'] as String?;
+    if (albumId != null && albumId.isNotEmpty) {
+      _displayedDominant =
+          ref.read(albumColorProvider(albumId)).asData?.value;
+    }
+    // Kick the preload pipeline post-frame so the cover bytes are
+    // decoded + the dominant color is resolved even when the user
+    // opens the player to a track that hasn't yet flowed through
+    // ref.listen.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      if (!mounted) return;
+      _scheduleSwap(current);
+    });
+  }
+
+  /// Preload the new track's cover bytes + dominant color, then
+  /// atomically flip _displayedMedia / _displayedDominant. Until both
+  /// resolve, the screen continues to render the previous track —
+  /// the new title/cover/gradient appear together in one frame.
+  ///
+  /// Concurrency: if a second track change arrives while the first
+  /// preload is still in flight, the older preload's
+  /// _pendingPreloadId check fails and its completion is dropped.
+  Future<void> _scheduleSwap(MediaItem newMedia) async {
+    _pendingPreloadId = newMedia.id;
+
+    // 1. Precache the cover image bytes so when _AlbumArt mounts with
+    //    the new media, FileImage paints synchronously. Non-file
+    //    artUris fall through to ServerImage which handles its own
+    //    network load + 120ms fade — they won't snap.
+    final artUri = newMedia.artUri;
+    if (artUri != null && artUri.isScheme('file') && context.mounted) {
+      try {
+        await precacheImage(FileImage(File.fromUri(artUri)), context);
+      } catch (_) {
+        // Decode failed (missing file, corrupt bytes) — proceed
+        // anyway; _AlbumArt's errorBuilder shows the slate fallback.
+      }
+    }
+
+    // 2. Wait for the dominant-color extraction so the gradient is
+    //    populated when we swap. PaletteGenerator runs against the
+    //    same FileImage, typically resolving within ~50ms once the
+    //    decode completes.
+    Color? newDominant;
+    final albumId = newMedia.extras?['album_id'] as String?;
+    if (albumId != null && albumId.isNotEmpty) {
+      try {
+        newDominant = await ref.read(albumColorProvider(albumId).future);
+      } catch (_) {
+        // Color extraction failed — keep the previous dominant so the
+        // backdrop doesn't drop to obsidian on the swap.
+      }
+    }
+
+    // 3. Atomic flip. Bail if a newer swap superseded us, or the
+    //    screen was disposed mid-preload.
+    if (!mounted) return;
+    if (_pendingPreloadId != newMedia.id) return;
+    setState(() {
+      _displayedMedia = newMedia;
+      if (newDominant != null) _displayedDominant = newDominant;
+    });
+  }
 
   void _onDragStart(DragStartDetails _) {
     _dragOffset = 0;
@@ -78,10 +167,61 @@ class _NowPlayingScreenState extends ConsumerState<NowPlayingScreen> {
   @override
   Widget build(BuildContext context) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
-    final media = ref.watch(mediaItemProvider).value;
-    final playback = ref.watch(playbackStateProvider).value;
 
-    if (media == null) {
+    // Listen for mediaItem changes and schedule a preload-then-swap.
+    // Build renders _displayedMedia / _displayedDominant; the live
+    // mediaItemProvider only drives the swap pipeline.
+    //
+    // Decision process:
+    //   - On the first non-null mediaItem after mount, seed
+    //     _displayedMedia immediately so the screen has something to
+    //     paint.
+    //   - On a track id change, kick off a preload. The new track's
+    //     cover bytes + dominant color must both resolve before we
+    //     flip the displayed state. The user sees the previous track
+    //     in full until the new one is fully ready, then a clean
+    //     atomic swap (no fade, no placeholder flash).
+    //   - On the same track id but the artUri-bearing rebroadcast
+    //     (audio_handler sends MediaItem twice on track change),
+    //     refresh through the same preload pipeline so the displayed
+    //     cover reflects the freshly-written AlbumCoverCache file.
+    ref.listen<AsyncValue<MediaItem?>>(mediaItemProvider, (prev, next) {
+      final newMedia = next.asData?.value;
+      if (newMedia == null) {
+        if (_displayedMedia != null) {
+          setState(() {
+            _displayedMedia = null;
+            _displayedDominant = null;
+            _pendingPreloadId = null;
+          });
+        }
+        return;
+      }
+      if (_displayedMedia == null) {
+        // First mount with a track playing — seed immediately, then
+        // kick the preload pipeline to update the dominant color and
+        // ensure the cover is decoded.
+        setState(() => _displayedMedia = newMedia);
+        _scheduleSwap(newMedia);
+        return;
+      }
+      final isNewTrack = newMedia.id != _displayedMedia!.id;
+      final coverGotPopulated =
+          newMedia.id == _displayedMedia!.id &&
+              newMedia.artUri != null &&
+              _displayedMedia!.artUri == null;
+      if (isNewTrack || coverGotPopulated) {
+        _scheduleSwap(newMedia);
+      }
+    });
+
+    final playback = ref.watch(playbackStateProvider).value;
+    final displayedMedia = _displayedMedia;
+
+    if (displayedMedia == null) {
+      // Either nothing playing, or the very first mount before a
+      // mediaItem has been emitted. The ref.listen above will seed
+      // _displayedMedia as soon as a non-null MediaItem arrives.
       return const Scaffold(body: Center(child: Text('Nothing playing.')));
     }
 
@@ -90,53 +230,22 @@ class _NowPlayingScreenState extends ConsumerState<NowPlayingScreen> {
     // only fires on state transitions and would leave the bar frozen
     // between them.
     final pos = ref.watch(positionProvider).value ?? Duration.zero;
-    final dur = media.duration ?? Duration.zero;
+    final dur = displayedMedia.duration ?? Duration.zero;
     final isPlaying = playback?.playing == true;
     final shuffleOn = playback?.shuffleMode == AudioServiceShuffleMode.all;
     final repeatMode = playback?.repeatMode ?? AudioServiceRepeatMode.none;
     final actions = ref.read(playerActionsProvider);
-    final albumId = (media.extras?['album_id'] as String?) ?? '';
+    final albumId = (displayedMedia.extras?['album_id'] as String?) ?? '';
 
-    // Dominant-color gradient backdrop seeded from the current track's
-    // album cover. Tweens to the new color on track change via
-    // AnimatedContainer.
-    //
-    // We hold _lastDominant across builds so a track change doesn't
-    // briefly tween to fs.obsidian while albumColorProvider for the
-    // new id is loading — that brief stop produced the "background
-    // coloring snaps in" effect users saw. With a held color, the
-    // gradient stays on the previous album's color until the new
-    // extraction resolves, then animates straight to it.
-    final dominantAsync = ref.watch(albumColorProvider(albumId));
-    final resolved = dominantAsync.asData?.value;
-    if (resolved != null) _lastDominant = resolved;
-    final dominant = _lastDominant ?? fs.obsidian;
-    // 0.55 alpha keeps the color present without overwhelming contrast
-    // on the title / artist text below. The lower half of the screen
-    // stays obsidian for control legibility.
+    // Backdrop color: render the dominant we've already committed to
+    // _displayedDominant. AnimatedContainer tweens between successive
+    // values, so the only color changes the user sees are the
+    // atomic-with-cover swaps from _scheduleSwap. 0.55 alpha keeps
+    // the gradient present without overwhelming the title/artist
+    // text below.
+    final dominant = _displayedDominant ?? fs.obsidian;
     final gradientTop = dominant.withValues(alpha: 0.55);
 
-    // Precache the cover image bytes the moment a new MediaItem (with
-    // a file:// artUri) is broadcast. Without this, AnimatedSwitcher's
-    // cross-fade for the cover would complete before FileImage finished
-    // decoding the bytes — visible as a "snap in" of the album art
-    // after the fade. precacheImage decodes in the background; by the
-    // time the new _AlbumArt mounts inside the switcher, the bytes are
-    // ready and the cover paints synchronously.
-    //
-    // Non-file artUris (the rare moment before AlbumCoverCache has
-    // written the file) fall back to ServerImage / CachedNetworkImage
-    // which has its own 120ms fade — no precache benefit there.
-    final artUri = media.artUri;
-    final artKey = artUri?.toString();
-    if (artUri != null &&
-        artUri.isScheme('file') &&
-        artKey != _precachedArtUri) {
-      _precachedArtUri = artKey;
-      // ignore: unawaited_futures
-      precacheImage(FileImage(File.fromUri(artUri)), context);
-    }
-
     return Scaffold(
       backgroundColor: fs.obsidian,
       // The whole screen accepts vertical drag for dismissal. Buttons
@@ -167,46 +276,36 @@ class _NowPlayingScreenState extends ConsumerState<NowPlayingScreen> {
                   child: Column(
                     children: [
                       const Spacer(),
-                      AnimatedSwitcher(
-                        duration: _trackChangeDuration,
-                        child: KeyedSubtree(
-                          key: ValueKey('cover-${media.id}'),
-                          child: _AlbumArt(
-                              media: media, albumId: albumId, fs: fs),
-                        ),
-                      ),
+                      // No AnimatedSwitcher: _displayedMedia only
+                      // advances after the preload pipeline has the
+                      // new cover + color ready, so a track change
+                      // is an atomic swap. Fading would just smear a
+                      // transition the user explicitly asked us not
+                      // to add.
+                      _AlbumArt(
+                          media: displayedMedia, albumId: albumId, fs: fs),
                       const SizedBox(height: 28),
-                      AnimatedSwitcher(
-                        duration: _trackChangeDuration,
-                        child: KeyedSubtree(
-                          key: ValueKey('title-${media.id}'),
-                          child: _TitleRow(media: media, fs: fs),
-                        ),
-                      ),
+                      _TitleRow(media: displayedMedia, fs: fs),
                       const SizedBox(height: 4),
-                      AnimatedSwitcher(
-                        duration: _trackChangeDuration,
-                        child: Column(
-                          key: ValueKey('artist-album-${media.id}'),
-                          mainAxisSize: MainAxisSize.min,
-                          children: [
+                      Column(
+                        mainAxisSize: MainAxisSize.min,
+                        children: [
+                          Text(
+                            displayedMedia.artist ?? '',
+                            style: TextStyle(color: fs.ash, fontSize: 14),
+                            maxLines: 1,
+                            overflow: TextOverflow.ellipsis,
+                          ),
+                          if ((displayedMedia.album ?? '').isNotEmpty) ...[
+                            const SizedBox(height: 2),
                             Text(
-                              media.artist ?? '',
-                              style: TextStyle(color: fs.ash, fontSize: 14),
+                              displayedMedia.album!,
+                              style: TextStyle(color: fs.ash, fontSize: 12),
                               maxLines: 1,
                               overflow: TextOverflow.ellipsis,
                             ),
-                            if ((media.album ?? '').isNotEmpty) ...[
-                              const SizedBox(height: 2),
-                              Text(
-                                media.album!,
-                                style: TextStyle(color: fs.ash, fontSize: 12),
-                                maxLines: 1,
-                                overflow: TextOverflow.ellipsis,
-                              ),
-                            ],
                           ],
-                        ),
+                        ],
                       ),
                       const SizedBox(height: 24),
                       _SecondaryControls(
@@ -214,7 +313,7 @@ class _NowPlayingScreenState extends ConsumerState<NowPlayingScreen> {
                         actions: actions,
                         shuffleOn: shuffleOn,
                         repeatMode: repeatMode,
-                        media: media,
+                        media: displayedMedia,
                       ),
                       const SizedBox(height: 8),
                       _SeekRow(position: pos, duration: dur, fs: fs, ref: ref),

flutter_client/lib/player/player_bar.dart

@@ -28,16 +28,37 @@ import 'player_provider.dart';
 /// Tap anywhere on the bar (including art/title) ascends to the full
 /// player. A vertical drag upward also ascends, so the gesture mirrors
 /// the drag-down dismissal on the full screen.
-class PlayerBar extends ConsumerWidget {
+class PlayerBar extends ConsumerStatefulWidget {
   const PlayerBar({super.key});
 
   @override
-  Widget build(BuildContext context, WidgetRef ref) {
+  ConsumerState<PlayerBar> createState() => _PlayerBarState();
+}
+
+class _PlayerBarState extends ConsumerState<PlayerBar> {
+  /// Last non-null artUri we've seen from the mediaItem stream. Held
+  /// across the audio_handler's two-broadcast track-change pattern
+  /// (bare MediaItem first, then with artUri once AlbumCoverCache
+  /// resolves) so the mini bar keeps showing the previous track's
+  /// cover until the new one is known. Without this hold the bar
+  /// flickered to the slate placeholder for ~100ms on every track
+  /// change.
+  Uri? _lastArtUri;
+
+  @override
+  Widget build(BuildContext context) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     final media = ref.watch(mediaItemProvider).value;
     final playback = ref.watch(playbackStateProvider).value;
     if (media == null) return const SizedBox.shrink();
 
+    // Capture the latest non-null artUri so _TrackInfo's cover stays
+    // continuous across track changes.
+    if (media.artUri != null) _lastArtUri = media.artUri;
+    final displayMedia = media.artUri == null && _lastArtUri != null
+        ? media.copyWith(artUri: _lastArtUri)
+        : media;
+
     // positionProvider is just_audio's positionStream (~200ms cadence)
     // so the mini bar's seek crawls forward smoothly. PlaybackState
     // only updates on event transitions and would leave it frozen.
@@ -65,7 +86,7 @@ class PlayerBar extends ConsumerWidget {
                 child: Row(
                   crossAxisAlignment: CrossAxisAlignment.center,
                   children: [
-                    Expanded(child: _TrackInfo(media: media)),
+                    Expanded(child: _TrackInfo(media: displayMedia)),
                     const SizedBox(width: 8),
                     _PlayControls(playback: playback, ref: ref),
                   ],
@@ -96,27 +117,27 @@ class _TrackInfo extends StatelessWidget {
     // than fade-cutting. Tag is stable per-route (not keyed by media.id)
     // so the transition works regardless of what's playing.
     //
-    // AnimatedSwitcher around the cover smooths the artUri null→file://
-    // swap that fires on every track change: audio_handler broadcasts
-    // the new MediaItem without artUri immediately, then re-broadcasts
-    // with artUri once AlbumCoverCache resolves the path. Without the
-    // crossfade the cover snaps from the previous track's image to a
-    // slate placeholder to the new image — visible as a flicker.
-    final Widget coverChild;
-    if (media.artUri != null) {
+    // Why no transition / placeholder handling: the audio_handler
+    // broadcasts MediaItem twice on track change — once with artUri
+    // null (the new track's bare metadata), then with artUri set once
+    // AlbumCoverCache resolves. The widget tree above hands us the
+    // most-recent non-null artUri (`displayArtUri`), so the previous
+    // track's cover stays visible across that null gap and the new
+    // cover snaps in the moment its artUri arrives. Rapid change is
+    // fine here per operator preference; AnimatedSwitcher previously
+    // smeared the swap and made the slate placeholder visible.
+    final displayArtUri = media.artUri;
+    final Widget cover;
+    if (displayArtUri != null) {
       // CachedNetworkImageProvider for HTTPS art URIs so the mini bar
       // hits the same disk cache the rest of the UI uses (ServerImage,
       // discover thumbnails). FileImage stays for the file:// branch
       // populated by AlbumCoverCache — bytes are already on disk and a
       // second cache layer would only burn duplicate space.
-      coverChild = Image(
-        // Key includes the artUri so AnimatedSwitcher detects a swap;
-        // without this it treats successive Image widgets as the same
-        // tree node and skips the transition.
-        key: ValueKey('art-${media.artUri}'),
-        image: media.artUri!.isScheme('file')
-            ? FileImage(File.fromUri(media.artUri!)) as ImageProvider
-            : CachedNetworkImageProvider(media.artUri.toString()),
+      cover = Image(
+        image: displayArtUri.isScheme('file')
+            ? FileImage(File.fromUri(displayArtUri)) as ImageProvider
+            : CachedNetworkImageProvider(displayArtUri.toString()),
         width: 48,
         height: 48,
         // Without a fit, Image paints the source at its intrinsic
@@ -128,19 +149,8 @@ class _TrackInfo extends StatelessWidget {
             Container(width: 48, height: 48, color: fs.slate),
       );
     } else {
-      coverChild = Container(
-        key: const ValueKey('art-placeholder'),
-        width: 48,
-        height: 48,
-        color: fs.slate,
-      );
+      cover = Container(width: 48, height: 48, color: fs.slate);
     }
-    final cover = AnimatedSwitcher(
-      duration: const Duration(milliseconds: 180),
-      switchInCurve: Curves.easeOut,
-      switchOutCurve: Curves.easeOut,
-      child: coverChild,
-    );
     return Row(
       // Default centering vertically aligns the like/kebab buttons
       // against the album art (48dp) — visually they span the title +

flutter_client/lib/player/player_provider.dart

@@ -1,10 +1,12 @@
 import 'package:audio_service/audio_service.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
+import '../api/endpoints/likes.dart' show LikeKind;
 import '../api/endpoints/radio.dart';
 import '../auth/auth_provider.dart';
 import '../cache/audio_cache_manager.dart';
 import '../library/library_providers.dart' show dioProvider;
+import '../likes/likes_provider.dart';
 import '../models/track.dart';
 import 'album_cover_cache.dart';
 import 'audio_handler.dart';
@@ -49,7 +51,18 @@ final positionProvider = StreamProvider<Duration>(
 );
 
 class PlayerActions {
-  PlayerActions(this._ref);
+  PlayerActions(this._ref) {
+    // Keep MediaItem.rating in sync with the drift-backed likedIds
+    // cache so external media surfaces (Wear's heart button, lock-
+    // screen favorite, Auto's like icon) reflect the current state
+    // even when the user toggles a like from somewhere other than
+    // the watch itself — e.g. tapping the heart on a TrackRow, the
+    // kebab menu, or another logged-in device propagating via SSE.
+    _ref.listen<AsyncValue<LikedIds>>(likedIdsProvider, (_, next) {
+      if (next.value == null) return;
+      _ref.read(audioHandlerProvider).refreshCurrentRating();
+    });
+  }
   final Ref _ref;
 
   Future<void> playTracks(List<TrackRef> tracks, {int initialIndex = 0}) async {
@@ -63,11 +76,28 @@ class PlayerActions {
         token: token,
         coverCache: cache,
         audioCacheManager: audioCache,
+        likeBridge: _buildLikeBridge(),
       );
     await h.setQueueFromTracks(tracks, initialIndex: initialIndex);
     await h.play();
   }
 
+  /// Builds the adapter the audio handler uses to read + flip the
+  /// current track's like state in response to external media-
+  /// controller events (Wear's heart button, lock-screen favorite).
+  /// Constructed here because the audio handler is initialized in
+  /// main.dart before the ProviderScope exists; passing the bridge
+  /// in via configure() keeps the handler Riverpod-agnostic while
+  /// still letting it call into LikesController + likedIdsProvider.
+  LikeBridge _buildLikeBridge() {
+    return LikeBridge(
+      toggleTrackLike: (id) =>
+          _ref.read(likesControllerProvider).toggle(LikeKind.track, id),
+      isTrackLiked: (id) =>
+          _ref.read(likedIdsProvider).value?.has(LikeKind.track, id) ?? false,
+    );
+  }
+
   Future<void> playNext(TrackRef track) async {
     final h = _ref.read(audioHandlerProvider);
     await h.playNext(track);

flutter_client/pubspec.yaml

@@ -1,7 +1,7 @@
 name: minstrel
 description: Minstrel mobile client
 publish_to: 'none'
-version: 2026.5.13+2
+version: 2026.5.13+4
 
 environment:
   sdk: '>=3.5.0 <4.0.0'