Merge pull request 'Hotfix v2026.05.15.1 — allow discovery-mix variants in playlists CHECK constraints' (#49) from dev into main

HOTFIX for v2026.05.15.0. R3 added deep_cuts/rediscover/new_for_you/
on_this_day/first_listens producers + registry entries but not their
system_variant values to the playlists_kind_variant_consistent /
playlists_seed_consistent CHECK constraints (0021's whitelist).
insertSystemPlaylist for any new mix → SQLSTATE 23514, and since
BuildSystemPlaylists is one all-or-nothing txn that aborts the
ENTIRE build — For-You/Discover refresh 500s and the daily lazy
build fails too. System playlists are fully broken in prod.

Migration 0028 drops + re-adds both constraints with all five new
seedless variants (mirrors the 0021 drop-and-readd pattern).
CHECK-only — sqlc/dbq unaffected (regen produced no drift).

Bumps to 2026.5.15+7 for the v2026.05.15.1 patch release.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.forgejo/workflows/flutter.yml

@@ -1,9 +1,13 @@
 name: flutter
 
-# Analyze + test + build the Flutter mobile client. Only runs when the
-# diff touches flutter_client/ or one of the shared web inputs the
-# sync_shared.sh script copies. Other pushes skip — this workflow is
-# independent from the Go/web test.yml and release.yml.
+# Analyze + test the Flutter mobile client; build an APK only where
+# it's actually consumed. dev pushes: analyze+test+codegen only
+# (~3min) — the operator dev-tests via a local Android Studio build,
+# not the CI artifact. main pushes: also build a debug APK as the
+# native-build safety net (Gradle/manifest/plugin breakage that
+# analyze+test can't catch) before any release tag. tags: signed
+# release APK. Only runs when the diff touches flutter_client/ or a
+# shared web input sync_shared.sh copies.
 
 on:
   push:
@@ -56,6 +60,12 @@ jobs:
       - name: Pub get
         run: flutter pub get
 
+      - name: Codegen (drift, etc.)
+        # build_runner generates *.g.dart files (drift schemas, etc.)
+        # which are gitignored. Must run before analyze + test so the
+        # generated symbols exist.
+        run: dart run build_runner build --delete-conflicting-outputs
+
       - name: Analyze
         run: flutter analyze --fatal-infos
 
@@ -63,15 +73,52 @@ jobs:
         run: flutter test --reporter compact
 
       - name: Build debug APK
-        if: github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')
+        # main-only: native-build safety net before release tags.
+        # dev skips this (~7min) — operator dev-tests locally.
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: flutter build apk --debug
 
+      - name: Decode signing keystore
+        if: startsWith(github.ref, 'refs/tags/v')
+        # Reconstructs the release keystore from a base64-encoded
+        # CI secret so every tagged build is signed with the same
+        # key. Without this, each CI runner would generate its own
+        # debug keystore and Android would refuse to upgrade an
+        # existing install (signature mismatch).
+        shell: bash
+        env:
+          ANDROID_KEYSTORE_B64: ${{ secrets.ANDROID_KEYSTORE_B64 }}
+        run: |
+          if [ -z "${ANDROID_KEYSTORE_B64}" ]; then
+            echo "::error::ANDROID_KEYSTORE_B64 secret is missing — release builds need a consistent signing key"
+            exit 1
+          fi
+          KEYSTORE_PATH="${RUNNER_TEMP}/minstrel-release.keystore"
+          echo "${ANDROID_KEYSTORE_B64}" | base64 -d > "${KEYSTORE_PATH}"
+          echo "ANDROID_KEYSTORE_PATH=${KEYSTORE_PATH}" >> "${GITHUB_ENV}"
+
       - name: Build release APK
         if: startsWith(github.ref, 'refs/tags/v')
-        run: flutter build apk --release
+        # Inject the tag (sans leading 'v') as the build's --build-name
+        # so PackageInfo.version matches what /api/client/version
+        # reports — otherwise the in-app update banner would always
+        # think the user is behind because pubspec.yaml's static
+        # version drifts from the actual release tag.
+        #
+        # ANDROID_KEYSTORE_PATH is set by the previous step;
+        # build.gradle.kts picks it up and signs the release APK with
+        # the operator's persistent keystore.
+        shell: bash
+        env:
+          ANDROID_STORE_PASSWORD: ${{ secrets.ANDROID_STORE_PASSWORD }}
+          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
+          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          flutter build apk --release --build-name="${TAG}"
 
       - name: Upload debug APK artifact
-        if: github.event_name == 'push' && !startsWith(github.ref, 'refs/tags/')
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: forgejo/upload-artifact@v3
         with:
           name: minstrel-debug-${{ github.sha }}
@@ -81,14 +128,15 @@ jobs:
         if: startsWith(github.ref, 'refs/tags/v')
         shell: bash
         env:
-          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          CI_TOKEN: ${{ secrets.CI_TOKEN }}
         run: |
           TAG="${GITHUB_REF#refs/tags/}"
           REPO="${GITHUB_REPOSITORY}"
-          # Look up the release ID for this tag (release must exist already;
-          # release.yml creates it as part of the server-side release flow).
+          # Look up the release ID for this tag. The release object must
+          # exist already — operator creates it (or release.yml will, in
+          # a future enhancement) before pushing the tag.
           RELEASE_ID=$(curl -fsSL \
-            -H "Authorization: token ${RELEASE_TOKEN}" \
+            -H "Authorization: token ${CI_TOKEN}" \
             "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/tags/${TAG}" \
             | grep -oP '"id":\s*\K[0-9]+' | head -1)
           if [ -z "${RELEASE_ID}" ]; then
@@ -96,6 +144,6 @@ jobs:
             exit 1
           fi
           curl -fsSL \
-            -H "Authorization: token ${RELEASE_TOKEN}" \
+            -H "Authorization: token ${CI_TOKEN}" \
             -F "attachment=@build/app/outputs/flutter-apk/app-release.apk" \
             "https://git.fabledsword.com/api/v1/repos/${REPO}/releases/${RELEASE_ID}/assets?name=minstrel-${TAG}.apk"

.forgejo/workflows/release.yml

@@ -50,9 +50,11 @@ jobs:
           if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
             VERSION="${GITHUB_REF#refs/tags/}"
             echo "args=-t ${IMAGE}:${VERSION} -t ${IMAGE}:latest" >> "$GITHUB_OUTPUT"
+            echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
             echo "::notice::Release build: ${VERSION} + latest"
           else
             echo "args=-t ${IMAGE}:main" >> "$GITHUB_OUTPUT"
+            echo "version=main" >> "$GITHUB_OUTPUT"
             echo "::notice::Main-branch build: :main"
           fi
 
@@ -60,9 +62,40 @@ jobs:
         if: steps.guard.outputs.ready == 'true'
         shell: bash
         run: |
-          echo "${{ secrets.REGISTRY_TOKEN }}" \
+          echo "${{ secrets.CI_TOKEN }}" \
             | docker login git.fabledsword.com -u "${{ github.actor }}" --password-stdin
 
+      # In-app update flow (#397): on tag pushes only, fetch the APK
+      # that flutter.yml is attaching to this same release. flutter.yml
+      # runs in parallel; poll up to 15 min for the asset to appear.
+      # On main pushes (or if the APK never lands), client/ stays empty
+      # and the endpoints return 404 — graceful degradation.
+      - name: Fetch APK for bundled in-app update channel
+        if: steps.guard.outputs.ready == 'true' && startsWith(github.ref, 'refs/tags/v')
+        shell: bash
+        env:
+          CI_TOKEN: ${{ secrets.CI_TOKEN }}
+        run: |
+          TAG="${GITHUB_REF#refs/tags/}"
+          REPO="${GITHUB_REPOSITORY}"
+          APK_URL="https://git.fabledsword.com/${REPO}/releases/download/${TAG}/minstrel-${TAG}.apk"
+          echo "Polling ${APK_URL} (up to 15 min for flutter.yml to attach)..."
+          for i in $(seq 1 30); do
+            if curl -fsSL -H "Authorization: token ${CI_TOKEN}" \
+                -o client/minstrel.apk "$APK_URL"; then
+              echo "Got APK on attempt $i"
+              echo "${TAG}" > client/minstrel.apk.version
+              ls -lh client/
+              exit 0
+            fi
+            echo "APK not ready yet (attempt $i/30), sleeping 30s..."
+            sleep 30
+          done
+          echo "::warning::APK never appeared at ${APK_URL} after 15 min — image will ship without bundled update channel"
+
       - name: Build and push
         if: steps.guard.outputs.ready == 'true'
-        run: docker buildx build --push ${{ steps.tags.outputs.args }} .
+        run: |
+          docker buildx build \
+            --build-arg MINSTREL_VERSION="${{ steps.tags.outputs.version }}" \
+            --push ${{ steps.tags.outputs.args }} .

.gitignore

@@ -12,6 +12,11 @@
 # Test binary, built with `go test -c`
 *.test
 
+# Bundled Android APK + version sidecar (#397). Populated by CI for
+# tag releases; never committed. README in client/ explains the flow.
+client/minstrel.apk
+client/minstrel.apk.version
+
 # Output of the go coverage tool, specifically when used with LiteIDE
 *.out
 

Dockerfile

@@ -15,7 +15,13 @@ COPY . .
 # Overwrite the committed placeholder with the freshly-built SPA assets.
 COPY --from=web /web/build ./web/build
 ENV CGO_ENABLED=0
-RUN go build -trimpath -ldflags="-s -w" -o /out/minstrel ./cmd/minstrel
+# Version stamping: release.yml passes the git tag via MINSTREL_VERSION
+# build-arg; local `docker build` falls back to "dev". Surfaced at
+# /healthz for operator-side image-version verification.
+ARG MINSTREL_VERSION=dev
+RUN go build -trimpath \
+    -ldflags="-s -w -X 'git.fabledsword.com/bvandeusen/minstrel/internal/server.ServerVersion=${MINSTREL_VERSION}'" \
+    -o /out/minstrel ./cmd/minstrel
 
 FROM debian:bookworm-slim
 RUN apt-get update \
@@ -33,9 +39,15 @@ COPY config.example.yaml /etc/smartmusic/config.yaml
 # A non-writable path at this location silently breaks every downstream
 # cache, so we create + chown it once at image build. Operators mount a
 # named volume on top to persist across container recreates.
-RUN mkdir -p /app/data && chown -R minstrel:minstrel /app
+RUN mkdir -p /app/data /app/client && chown -R minstrel:minstrel /app
 WORKDIR /app
 
+# In-app update channel (#397). client/ in the build context holds
+# minstrel.apk + minstrel.apk.version (populated by release.yml on tag
+# pushes; .gitkeep + README otherwise). Endpoints return 404 when the
+# APK files aren't present, so non-tag images degrade gracefully.
+COPY --chown=minstrel:minstrel client/ /app/client/
+
 USER minstrel
 EXPOSE 4533
 ENV MINSTREL_STORAGE_DATA_DIR=/app/data

client/README.md

@@ -0,0 +1,35 @@
+# Bundled client assets
+
+Holds the Android APK (`minstrel.apk` + `minstrel.apk.version`) that the
+server serves via `/api/client/version` and `/api/client/apk` for the
+in-app update flow (#397).
+
+## Production
+
+CI populates this directory on tag releases:
+1. `flutter.yml` builds `app-release.apk` and attaches it to the
+   Forgejo release as `minstrel-<TAG>.apk`.
+2. `release.yml` waits for that asset to appear, downloads it into
+   this directory as `minstrel.apk`, writes the tag string to
+   `minstrel.apk.version`, and `docker buildx build` includes both
+   via `COPY client/ /app/client/`.
+
+## Development
+
+Empty directory works fine — the endpoints return 404 and the Flutter
+update banner stays hidden ("no update channel" graceful degradation).
+
+To smoke-test the update flow locally, drop a real APK + a version
+file into this directory:
+
+```sh
+cp /path/to/app-release.apk client/minstrel.apk
+echo "v0.2.0" > client/minstrel.apk.version
+```
+
+## Why a directory and not embed.FS?
+
+The APK is 30-60 MB. Embedding bloats the Go binary and slows
+`go build` for everyone, even when the APK isn't being changed.
+File-on-disk also lets operators override at runtime via volume
+mount on `/app/client/` if they want to ship their own build.

cmd/minstrel/main.go

@@ -14,6 +14,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/config"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/coverart"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/db"
+	"git.fabledsword.com/bvandeusen/minstrel/internal/eventbus"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/library"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrconfig"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/lidarrrequests"
@@ -24,6 +25,7 @@ import (
 	"git.fabledsword.com/bvandeusen/minstrel/internal/server"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/similarity"
 	"git.fabledsword.com/bvandeusen/minstrel/internal/subsonic"
+	syncpkg "git.fabledsword.com/bvandeusen/minstrel/internal/sync"
 )
 
 func main() {
@@ -146,9 +148,38 @@ func run() error {
 	// import requests and reconciles them against the library. Short-circuits
 	// to no-op when lidarr_config.enabled = false.
 	lidarrCfg := lidarrconfig.New(pool)
-	lidarrReconciler := lidarrrequests.NewReconciler(pool, lidarrCfg, logger.With("component", "lidarr"))
+	// Live-event bus shared between SSE subscribers (api.Mount) and
+	// background workers that publish (reconciler today; scanner later).
+	// Constructed before any service that publishes so they all share the
+	// same instance.
+	bus := eventbus.New()
+	// Scan-run lifecycle events use a package-level setter rather than
+	// threading the bus through RunScan + TryStartScan + the Scheduler
+	// + every test caller. Per-process singleton, set once at startup.
+	library.SetEventBus(bus)
+	lidarrReconciler := lidarrrequests.NewReconciler(pool, lidarrCfg, logger.With("component", "lidarr"), bus)
 	go lidarrReconciler.Run(ctx)
 
+	// library_changes compactor (#357 follow-up). Daily tick; deletes
+	// rows older than the configured retention so the change-log table
+	// doesn't grow unbounded. Clients that drop offline longer than
+	// retention hit the /api/library/sync 410 fallback and resync.
+	libraryChangesCompactor := syncpkg.NewCompactor(pool, logger.With("component", "library_changes_compactor"))
+	go libraryChangesCompactor.Run(ctx)
+
+	// Per-user system-playlist scheduler (#392 Half B). Fires each
+	// active user's daily build at 03:00 in their stored timezone.
+	// Replaces the 24h-anchored cron loop (removed in the next commit
+	// of this arc).
+	playlistScheduler, err := playlists.NewScheduler(pool, logger.With("component", "playlist_scheduler"), cfg.Storage.DataDir)
+	if err != nil {
+		return fmt.Errorf("init playlist scheduler: %w", err)
+	}
+	if err := playlistScheduler.Start(ctx); err != nil {
+		return fmt.Errorf("start playlist scheduler: %w", err)
+	}
+	defer playlistScheduler.Stop()
+
 	// Ensure DataDir exists before any service tries to write into it.
 	// Fatal on failure: a non-writable data_dir silently breaks every
 	// downstream cache (playlist covers, artist art, album-cover fallback)
@@ -173,7 +204,8 @@ func run() error {
 	srv := server.New(logger, pool, scanner, subsonic.Config{
 		AllowPlaintextPassword: cfg.Subsonic.AllowPlaintextPassword,
 	}, cfg.Events, cfg.Recommendation, cfg.Storage.DataDir, cfg.Branding, coverEnricher, cfg.Library.CoverArtBackfillCap, coverSettings, scanner, scanCfg, scheduler)
-	playlists.StartSystemPlaylistCron(ctx, pool, logger.With("component", "system_playlist_cron"), cfg.Storage.DataDir)
+	srv.Bus = bus
+	srv.PlaylistScheduler = playlistScheduler
 	httpServer := &http.Server{
 		Addr:              cfg.Server.Address,
 		Handler:           srv.Router(),

flutter_client/.gitignore

@@ -43,3 +43,7 @@ app.*.map.json
 /android/app/debug
 /android/app/profile
 /android/app/release
+
+# drift codegen output (regenerated by build_runner; CI runs build_runner)
+*.g.dart
+

flutter_client/android/app/build.gradle.kts

@@ -30,11 +30,38 @@ android {
         versionName = flutter.versionName
     }
 
+    // Real release signing config — populated only when CI exports
+    // ANDROID_KEYSTORE_PATH (decoded from a base64 secret) plus the
+    // matching password/alias env vars. Without these (local
+    // `flutter build apk --release` runs), the release build falls
+    // through to the debug keystore so local builds still work.
+    //
+    // Why this matters: Flutter's default `flutter run --release` and
+    // CI's earlier setup both signed with the per-machine debug
+    // keystore (~/.android/debug.keystore). Every CI runner generated
+    // its own debug key, so consecutive release APKs had different
+    // signatures and Android refused to upgrade an existing install.
+    val keystorePath: String? = System.getenv("ANDROID_KEYSTORE_PATH")
+    if (keystorePath != null && keystorePath.isNotEmpty()) {
+        signingConfigs {
+            create("release") {
+                storeFile = file(keystorePath)
+                storePassword = System.getenv("ANDROID_STORE_PASSWORD")
+                keyAlias = System.getenv("ANDROID_KEY_ALIAS")
+                keyPassword = System.getenv("ANDROID_KEY_PASSWORD")
+            }
+        }
+    }
+
     buildTypes {
         release {
-            // TODO: Add your own signing config for the release build.
-            // Signing with the debug keys for now, so `flutter run --release` works.
-            signingConfig = signingConfigs.getByName("debug")
+            signingConfig = if (keystorePath != null && keystorePath.isNotEmpty()) {
+                signingConfigs.getByName("release")
+            } else {
+                // Local-only fallback so `flutter run --release` works
+                // without the keystore. CI must export ANDROID_KEYSTORE_PATH.
+                signingConfigs.getByName("debug")
+            }
         }
     }
 }

flutter_client/android/app/src/main/AndroidManifest.xml

@@ -1,12 +1,23 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- Used in all build flavours (debug / profile / release). -->
     <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
     <uses-permission android:name="android.permission.WAKE_LOCK" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
     <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <!-- Android 13+ requires this to be declared AND prompted at runtime
+         for the media notification (now-playing tile) to appear. Audio
+         playback works without it; only the system-tray surface breaks. -->
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <!-- In-app update flow (#397). First update attempt prompts the
+         user to enable "Install unknown apps" for Minstrel in
+         Settings → Apps → Special access. One-time grant; persists. -->
+    <uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
     <application
         android:label="minstrel"
         android:name="${applicationName}"
-        android:icon="@mipmap/ic_launcher">
+        android:icon="@mipmap/ic_launcher"
+        android:networkSecurityConfig="@xml/network_security_config">
         <activity
             android:name=".MainActivity"
             android:exported="true"
@@ -49,6 +60,20 @@
                 <action android:name="android.intent.action.MEDIA_BUTTON" />
             </intent-filter>
         </receiver>
+        <!-- FileProvider for the in-app update flow (#397). Maps the
+             cache directory (where dio.download writes the APK) to a
+             content:// URI so the PackageInstaller intent can read it
+             across the process boundary. file:// URIs are blocked
+             since Android 7. -->
+        <provider
+            android:name="androidx.core.content.FileProvider"
+            android:authorities="${applicationId}.fileprovider"
+            android:exported="false"
+            android:grantUriPermissions="true">
+            <meta-data
+                android:name="android.support.FILE_PROVIDER_PATHS"
+                android:resource="@xml/file_paths" />
+        </provider>
     </application>
     <!-- Required to query activities that can process text, see:
          https://developer.android.com/training/package-visibility and

flutter_client/android/app/src/main/kotlin/com/fabledsword/minstrel/MainActivity.kt

@@ -1,5 +1,70 @@
 package com.fabledsword.minstrel
 
-import io.flutter.embedding.android.FlutterActivity
+import android.content.Intent
+import androidx.core.content.FileProvider
+import com.ryanheise.audioservice.AudioServiceActivity
+import io.flutter.embedding.engine.FlutterEngine
+import io.flutter.plugin.common.MethodChannel
+import java.io.File
 
-class MainActivity : FlutterActivity()
+// Must extend AudioServiceActivity (not FlutterActivity) so the
+// audio_service plugin can wire its FlutterEngine through. Without this
+// the platform call from AudioService.init() throws PlatformException
+// "The Activity class declared in your AndroidManifest.xml is wrong",
+// which on first start cascades into a flutter_cache_manager sqlite
+// EXCLUSIVE-lock crash because the engine partially re-initialises.
+class MainActivity : AudioServiceActivity() {
+
+    companion object {
+        private const val INSTALLER_CHANNEL = "com.fabledsword.minstrel/installer"
+    }
+
+    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
+        super.configureFlutterEngine(flutterEngine)
+
+        // In-app update channel (#397). Dart calls install(path) with
+        // the cache-dir APK path; we hand it to Android's
+        // PackageInstaller via FileProvider + ACTION_VIEW.
+        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, INSTALLER_CHANNEL)
+            .setMethodCallHandler { call, result ->
+                when (call.method) {
+                    "install" -> {
+                        val path = call.argument<String>("path")
+                        if (path == null) {
+                            result.error("missing_path", "path argument required", null)
+                            return@setMethodCallHandler
+                        }
+                        try {
+                            installApk(path)
+                            result.success(null)
+                        } catch (e: Exception) {
+                            result.error("install_failed", e.message, null)
+                        }
+                    }
+                    else -> result.notImplemented()
+                }
+            }
+    }
+
+    private fun installApk(path: String) {
+        val file = File(path)
+        if (!file.exists()) {
+            throw IllegalStateException("apk not found at $path")
+        }
+        val uri = FileProvider.getUriForFile(
+            this,
+            "${packageName}.fileprovider",
+            file
+        )
+        val intent = Intent(Intent.ACTION_VIEW).apply {
+            setDataAndType(uri, "application/vnd.android.package-archive")
+            // NEW_TASK: PackageInstaller runs in its own task.
+            // GRANT_READ_URI_PERMISSION: hands the content:// URI to
+            // the installer process, which lacks our app's read perms
+            // by default.
+            flags = Intent.FLAG_ACTIVITY_NEW_TASK or
+                Intent.FLAG_GRANT_READ_URI_PERMISSION
+        }
+        startActivity(intent)
+    }
+}

flutter_client/android/app/src/main/res/xml/file_paths.xml

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  FileProvider mappings for the in-app update flow (#397).
+  - cache-path/. exposes the app's getCacheDir() so the downloaded
+    APK at <cache>/minstrel-update.apk can be read by the
+    PackageInstaller via the content:// URI built in MainActivity.kt.
+-->
+<paths xmlns:android="http://schemas.android.com/apk/res/android">
+    <cache-path name="updates" path="." />
+</paths>

flutter_client/android/app/src/main/res/xml/network_security_config.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+  Permits cleartext HTTP to 127.0.0.1 ONLY. Required because just_audio +
+  audio_service spin up a local HTTP proxy on loopback to inject the
+  Authorization header (Android's MediaSession API can't pass headers down
+  to ExoPlayer directly). Without this exemption, ExoPlayer hits Android's
+  cleartext block when connecting to the local proxy and audio playback
+  fails with "Cleartext HTTP traffic to 127.0.0.1 not permitted".
+
+  All other hosts inherit cleartextTrafficPermitted="false" — actual
+  remote traffic (to your Minstrel server) must still be HTTPS.
+
+  Loopback traffic doesn't leave the device, so this exemption doesn't
+  reduce security for real network endpoints.
+-->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">127.0.0.1</domain>
+    </domain-config>
+</network-security-config>

flutter_client/lib/admin/admin_quarantine_screen.dart

@@ -1,6 +1,7 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
+import '../shared/live_events_provider.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
 import '../theme/theme_extension.dart';
 import 'admin_providers.dart';
@@ -12,6 +13,15 @@ class AdminQuarantineScreen extends ConsumerWidget {
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // #402 wire-up: any quarantine event (flag from a user / admin
+    // resolve / file delete / lidarr delete) refreshes the admin queue.
+    ref.listen<AsyncValue<LiveEvent>>(liveEventsProvider, (_, next) {
+      final e = next.asData?.value;
+      if (e == null) return;
+      if (e.kind.startsWith('quarantine.')) {
+        ref.invalidate(adminQuarantineProvider);
+      }
+    });
     final items = ref.watch(adminQuarantineProvider);
     return Scaffold(
       backgroundColor: fs.obsidian,

flutter_client/lib/admin/admin_requests_screen.dart

@@ -2,6 +2,7 @@ import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../models/admin_user.dart';
+import '../shared/live_events_provider.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
 import '../theme/theme_extension.dart';
 import 'admin_providers.dart';
@@ -13,6 +14,15 @@ class AdminRequestsScreen extends ConsumerWidget {
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // #402 wire-up: invalidate the admin requests list when a user
+    // creates/cancels/admin approves/rejects/reconciler completes —
+    // request.status_changed covers all of them.
+    ref.listen<AsyncValue<LiveEvent>>(liveEventsProvider, (_, next) {
+      final e = next.asData?.value;
+      if (e?.kind == 'request.status_changed') {
+        ref.invalidate(adminRequestsProvider);
+      }
+    });
     final requests = ref.watch(adminRequestsProvider);
     // Best-effort lookup for requester usernames. If the users provider
     // hasn't loaded yet, valueOrNull is null and rows fall back to the

flutter_client/lib/api/endpoints/events.dart

@@ -0,0 +1,91 @@
+import 'package:dio/dio.dart';
+
+/// Thin client for POST /api/events — the play-event lifecycle the
+/// server uses for history, recommendation scoring, ListenBrainz
+/// scrobbles, and (since #415) system-playlist rotation.
+///
+/// Mirrors the web events dispatcher's three calls. Best-effort by
+/// contract: callers swallow errors — a missed event is acceptable
+/// per the server spec's v1 stance, and the server's
+/// auto-close-prior-open keeps history sane even if an ended/skipped
+/// is lost.
+class EventsApi {
+  EventsApi(this._dio);
+  final Dio _dio;
+
+  /// POST play_started. Returns the server's play_event_id (used to
+  /// close the row later), or null if the call failed / response was
+  /// malformed. `source` tags the originating system playlist
+  /// ('for_you' | 'discover') so the server advances that rotation;
+  /// omit for library / user-playlist / radio plays.
+  Future<String?> playStarted({
+    required String trackId,
+    required String clientId,
+    String? source,
+  }) async {
+    final r = await _dio.post<Map<String, dynamic>>(
+      '/api/events',
+      data: {
+        'type': 'play_started',
+        'track_id': trackId,
+        'client_id': clientId,
+        if (source != null && source.isNotEmpty) 'source': source,
+      },
+    );
+    return (r.data ?? const {})['play_event_id'] as String?;
+  }
+
+  Future<void> playEnded({
+    required String playEventId,
+    required int durationPlayedMs,
+  }) async {
+    await _dio.post<void>(
+      '/api/events',
+      data: {
+        'type': 'play_ended',
+        'play_event_id': playEventId,
+        'duration_played_ms': durationPlayedMs,
+      },
+    );
+  }
+
+  Future<void> playSkipped({
+    required String playEventId,
+    required int positionMs,
+  }) async {
+    await _dio.post<void>(
+      '/api/events',
+      data: {
+        'type': 'play_skipped',
+        'play_event_id': playEventId,
+        'position_ms': positionMs,
+      },
+    );
+  }
+
+  /// Replays a complete play that happened offline / on a flaky
+  /// connection (#426 part B). One call: the server records start+end
+  /// from `atIso` (the original play-start time) + durationPlayedMs,
+  /// applies the canonical skip rule, and advances #415 rotation when
+  /// source is a system playlist. Driven by the offline mutation
+  /// queue, never the live path.
+  Future<void> playOffline({
+    required String trackId,
+    required String clientId,
+    required String atIso,
+    required int durationPlayedMs,
+    String? source,
+  }) async {
+    await _dio.post<void>(
+      '/api/events',
+      data: {
+        'type': 'play_offline',
+        'track_id': trackId,
+        'client_id': clientId,
+        'at': atIso,
+        'duration_played_ms': durationPlayedMs,
+        if (source != null && source.isNotEmpty) 'source': source,
+      },
+    );
+  }
+}

flutter_client/lib/api/endpoints/library.dart

@@ -3,6 +3,7 @@ import 'package:dio/dio.dart';
 import '../../models/album.dart';
 import '../../models/artist.dart';
 import '../../models/home_data.dart';
+import '../../models/home_index.dart';
 import '../../models/track.dart';
 
 /// LibraryApi wraps the server's native /api/* library surface.
@@ -27,6 +28,24 @@ class LibraryApi {
     return HomeData.fromJson(r.data ?? const {});
   }
 
+  /// GET /api/home/index — per-item rendering variant. Returns just IDs
+  /// per section; client hydrates each tile via the per-entity
+  /// endpoints. ~10× smaller than /api/home on populated libraries so
+  /// the cold-visit round-trip is correspondingly short.
+  Future<HomeIndex> getHomeIndex() async {
+    final r = await _dio.get<Map<String, dynamic>>('/api/home/index');
+    return HomeIndex.fromJson(r.data ?? const {});
+  }
+
+  /// GET /api/tracks/{id}. Returns the canonical TrackRef. Used by
+  /// the HydrationQueue to populate cached_tracks on a per-tile miss
+  /// — the existing endpoint already joins album + artist so the
+  /// response carries everything TrackRef needs.
+  Future<TrackRef> getTrack(String id) async {
+    final r = await _dio.get<Map<String, dynamic>>('/api/tracks/$id');
+    return TrackRef.fromJson(r.data ?? const {});
+  }
+
   /// GET /api/artists/{id}. Server returns ArtistDetail which embeds
   /// ArtistRef inline; ArtistRef.fromJson already reads only the fields
   /// it cares about, so passing the whole body is correct.
@@ -35,6 +54,24 @@ class LibraryApi {
     return ArtistRef.fromJson(r.data ?? const {});
   }
 
+  /// GET /api/artists/{id} — full response with the ArtistRef AND the
+  /// embedded album list, both parsed. Single round-trip variant used
+  /// by CacheFiller and other callers that want to populate both
+  /// cached_artists and cached_albums in one shot. The existing
+  /// getArtist / getArtistAlbums keep working for callers that only
+  /// need one half — they hit the same URL but the per-id Riverpod
+  /// caching layer dedupes.
+  Future<({ArtistRef artist, List<AlbumRef> albums})> getArtistDetail(
+      String id) async {
+    final r = await _dio.get<Map<String, dynamic>>('/api/artists/$id');
+    final body = r.data ?? const <String, dynamic>{};
+    final artist = ArtistRef.fromJson(body);
+    final albums = ((body['albums'] as List?) ?? const [])
+        .map((e) => AlbumRef.fromJson((e as Map).cast<String, dynamic>()))
+        .toList(growable: false);
+    return (artist: artist, albums: albums);
+  }
+
   /// Pulls the "albums" array out of the same ArtistDetail body. Callers
   /// that need both the artist and its albums should issue two provider
   /// reads (artistProvider + artistAlbumsProvider) — both hit the same
@@ -48,6 +85,19 @@ class LibraryApi {
         .toList(growable: false);
   }
 
+  /// GET /api/library/shuffle?limit=N (#427 S4). N random library
+  /// tracks — the online source for "Shuffle all". Bare JSON array.
+  Future<List<TrackRef>> shuffle({int limit = 100}) async {
+    final r = await _dio.get<List<dynamic>>(
+      '/api/library/shuffle',
+      queryParameters: {'limit': limit},
+    );
+    final raw = r.data ?? const [];
+    return raw
+        .map((e) => TrackRef.fromJson((e as Map).cast<String, dynamic>()))
+        .toList(growable: false);
+  }
+
   /// GET /api/artists/{id}/tracks. Server emits a bare JSON array, so we
   /// type the response as `List<dynamic>` rather than a Map envelope.
   Future<List<TrackRef>> getArtistTracks(String id) async {

flutter_client/lib/api/endpoints/library_lists.dart

@@ -12,9 +12,16 @@ class LibraryListsApi {
   final Dio _dio;
 
   Future<Paged<ArtistRef>> listArtists({int limit = 50, int offset = 0}) async {
+    // Server mounts the artists list at /api/artists (handleListArtists),
+    // not /api/library/artists. Albums use /api/library/albums for
+    // historical reasons; the paths aren't symmetric.
     final r = await _dio.get<Map<String, dynamic>>(
-      '/api/library/artists',
-      queryParameters: {'limit': limit, 'offset': offset},
+      '/api/artists',
+      queryParameters: {
+        'limit': limit,
+        'offset': offset,
+        'sort': 'alpha',
+      },
     );
     return Paged.fromJson(r.data ?? const {}, ArtistRef.fromJson);
   }

flutter_client/lib/api/endpoints/me.dart

@@ -2,6 +2,7 @@ import 'package:dio/dio.dart';
 
 import '../../models/history_event.dart';
 import '../../models/quarantine_mine.dart';
+import '../../models/system_playlists_status.dart';
 
 /// /api/me/* endpoints — caller-scoped data (history, profile, etc.).
 class MeApi {
@@ -27,4 +28,22 @@ class MeApi {
             QuarantineMineRow.fromJson((e as Map).cast<String, dynamic>()))
         .toList(growable: false);
   }
+
+  /// GET /api/me/system-playlists-status. Returns the caller's most
+  /// recent system-playlist build state. Used by the home Playlists
+  /// row to choose between real and placeholder cards.
+  Future<SystemPlaylistsStatus> systemPlaylistsStatus() async {
+    final r = await _dio.get<Map<String, dynamic>>(
+      '/api/me/system-playlists-status',
+    );
+    return SystemPlaylistsStatus.fromJson(r.data ?? const {});
+  }
+
+  /// PUT /api/me/timezone — submit the device's IANA timezone. The
+  /// scheduler uses this to fire the user's daily playlist build at
+  /// 03:00 in their local time. See AuthController._sendTimezoneIfStale
+  /// for the weekly cadence trigger.
+  Future<void> putTimezone(String timezone) async {
+    await _dio.put<void>('/api/me/timezone', data: {'timezone': timezone});
+  }
 }

flutter_client/lib/api/endpoints/playlists.dart

@@ -2,27 +2,79 @@ import 'package:dio/dio.dart';
 
 import '../../models/playlist.dart';
 
+/// Wire shape for GET /api/playlists. Server splits owned vs. public so
+/// the UI can present them as different sections; we preserve that split
+/// to give the integrations page room to grow.
+class PlaylistsList {
+  const PlaylistsList({required this.owned, required this.public});
+  final List<Playlist> owned;
+  final List<Playlist> public;
+
+  factory PlaylistsList.empty() =>
+      const PlaylistsList(owned: [], public: []);
+
+  /// Concatenated view for callers that don't care about the split.
+  List<Playlist> get all => [...owned, ...public];
+}
+
 class PlaylistsApi {
   PlaylistsApi(this._dio);
   final Dio _dio;
 
-  /// GET /api/playlists?kind=user|system|all. The server's default kind
-  /// is "user" — passing "all" returns user playlists + system mixes.
-  /// "system" returns just for-you / discover. The mobile UI defaults
-  /// to "all" so users see their generated mixes alongside their own.
-  Future<List<Playlist>> list({String kind = 'all'}) async {
-    final r = await _dio.get<List<dynamic>>(
+  /// GET /api/playlists?kind=user|system|all. Server returns
+  /// `{"owned": [...], "public": [...]}`. Owned is the caller's own
+  /// playlists, filtered by the kind param (default "user"). Public
+  /// is other users' shared playlists; not filtered by kind.
+  Future<PlaylistsList> list({String kind = 'user'}) async {
+    final r = await _dio.get<Map<String, dynamic>>(
       '/api/playlists',
       queryParameters: {'kind': kind},
     );
-    final raw = r.data ?? const [];
-    return raw
-        .map((e) => Playlist.fromJson((e as Map).cast<String, dynamic>()))
-        .toList(growable: false);
+    final body = r.data ?? const <String, dynamic>{};
+    List<Playlist> parse(String key) {
+      final raw = (body[key] as List?) ?? const [];
+      return raw
+          .map((e) => Playlist.fromJson((e as Map).cast<String, dynamic>()))
+          .toList(growable: false);
+    }
+    return PlaylistsList(owned: parse('owned'), public: parse('public'));
   }
 
   Future<PlaylistDetail> get(String id) async {
     final r = await _dio.get<Map<String, dynamic>>('/api/playlists/$id');
     return PlaylistDetail.fromJson(r.data ?? const {});
   }
+
+  /// GET /api/playlists/system/{kind}/shuffle (#415 / #411 R2).
+  /// Same shape as get() but tracks are server-ordered rotation-aware
+  /// (unplayed-this-rotation first; resets when exhausted). {kind} is
+  /// the raw system_variant. Intentionally uncached — varies per play.
+  Future<PlaylistDetail> systemShuffle(String variant) async {
+    final r = await _dio.get<Map<String, dynamic>>(
+      '/api/playlists/system/$variant/shuffle',
+    );
+    return PlaylistDetail.fromJson(r.data ?? const {});
+  }
+
+  /// POST /api/playlists/{id}/tracks. Owner only; server returns the
+  /// playlist detail with the new rows.
+  Future<void> appendTracks(String playlistId, List<String> trackIds) async {
+    await _dio.post<void>(
+      '/api/playlists/$playlistId/tracks',
+      data: {'track_ids': trackIds},
+    );
+  }
+
+  /// POST /api/playlists/system/{kind}/refresh (#411 R2). Rebuilds
+  /// the caller's system playlists and returns the named kind's new
+  /// playlist id, or null when the library is empty. {kind} is the
+  /// raw system_variant — the server routes generically off the
+  /// kind registry, no hyphen mapping.
+  Future<String?> refreshSystem(String variant) async {
+    final r = await _dio.post<Map<String, dynamic>>(
+      '/api/playlists/system/$variant/refresh',
+      data: const <String, dynamic>{},
+    );
+    return (r.data ?? const {})['playlist_id'] as String?;
+  }
 }

flutter_client/lib/api/endpoints/quarantine.dart

@@ -0,0 +1,25 @@
+import 'package:dio/dio.dart';
+
+/// /api/quarantine — flag a track (with reason + optional notes) and
+/// unflag it. Both endpoints are user-scoped: callers can only flag
+/// their own quarantine entries; admins use a separate /admin/quarantine
+/// surface.
+class QuarantineApi {
+  QuarantineApi(this._dio);
+  final Dio _dio;
+
+  /// POST /api/quarantine. Server returns 201 with the row.
+  /// Reason values: bad_rip | wrong_file | wrong_tags | duplicate | other.
+  Future<void> flag(String trackId, String reason, {String notes = ''}) async {
+    await _dio.post<void>('/api/quarantine', data: {
+      'track_id': trackId,
+      'reason': reason,
+      'notes': notes,
+    });
+  }
+
+  /// DELETE /api/quarantine/{track_id}. Server returns 204.
+  Future<void> unflag(String trackId) async {
+    await _dio.delete<void>('/api/quarantine/$trackId');
+  }
+}

flutter_client/lib/api/endpoints/radio.dart

@@ -0,0 +1,27 @@
+import 'package:dio/dio.dart';
+
+import '../../models/track.dart';
+
+/// `GET /api/radio?seed_track=<uuid>&limit=<int>`. Returns the seed
+/// at index 0 followed by up to `limit-1` weighted-shuffle picks
+/// scored by the server's recommendation engine. The shape matches
+/// what `playerActions.playTracks` expects, so a radio start is just
+/// one fetch + one playTracks call.
+class RadioApi {
+  RadioApi(this._dio);
+  final Dio _dio;
+
+  Future<List<TrackRef>> seedTrack(String trackId, {int? limit}) async {
+    final r = await _dio.get<Map<String, dynamic>>(
+      '/api/radio',
+      queryParameters: {
+        'seed_track': trackId,
+        if (limit != null) 'limit': limit,
+      },
+    );
+    final raw = (r.data?['tracks'] as List?) ?? const [];
+    return raw
+        .map((e) => TrackRef.fromJson((e as Map).cast<String, dynamic>()))
+        .toList(growable: false);
+  }
+}

flutter_client/lib/api/endpoints/requests.dart

@@ -0,0 +1,31 @@
+import 'package:dio/dio.dart';
+
+import '../../models/admin_request.dart';
+
+/// User-side requests API — `/api/requests`. Server scopes results to
+/// the caller; admins see only their own here, not all users'. The
+/// admin-cross-user view lives in `/api/admin/requests` (AdminRequestsApi).
+///
+/// Wire shape is identical to the admin endpoint, so the same
+/// AdminRequest model is reused.
+class RequestsApi {
+  RequestsApi(this._dio);
+  final Dio _dio;
+
+  /// GET /api/requests — caller's own requests, all statuses.
+  Future<List<AdminRequest>> listMine() async {
+    final r = await _dio.get<List<dynamic>>('/api/requests');
+    final raw = r.data ?? const [];
+    return raw
+        .map((e) => AdminRequest.fromJson((e as Map).cast<String, dynamic>()))
+        .toList(growable: false);
+  }
+
+  /// DELETE /api/requests/{id} — cancel a pending request. Server
+  /// returns the cancelled row body (not 204) so the caller can patch
+  /// local state without a refetch.
+  Future<AdminRequest> cancel(String id) async {
+    final r = await _dio.delete<Map<String, dynamic>>('/api/requests/$id');
+    return AdminRequest.fromJson(r.data ?? const {});
+  }
+}

flutter_client/lib/app.dart

@@ -1,18 +1,83 @@
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
+import 'cache/cache_filler.dart';
+import 'cache/metadata_prefetcher.dart';
+import 'cache/offline_provider.dart';
+import 'cache/mutation_queue.dart';
+import 'cache/prefetcher.dart';
+import 'cache/sync_controller.dart';
+import 'player/play_events_reporter.dart';
+import 'shared/live_events_dispatcher.dart';
 import 'shared/routing.dart';
 import 'theme/theme_data.dart';
+import 'theme/theme_mode_provider.dart';
 
-class MinstrelApp extends ConsumerWidget {
+class MinstrelApp extends ConsumerStatefulWidget {
   const MinstrelApp({super.key});
 
   @override
-  Widget build(BuildContext context, WidgetRef ref) {
+  ConsumerState<MinstrelApp> createState() => _MinstrelAppState();
+}
+
+class _MinstrelAppState extends ConsumerState<MinstrelApp> {
+  @override
+  void initState() {
+    super.initState();
+    // Activate offline-mode infrastructure once the first frame ships.
+    // SyncController.sync() is connectivity-aware (no-ops on no auth /
+    // no server URL), so calling it unconditionally is safe.
+    // Reading prefetcherProvider runs its constructor, which wires the
+    // queue + settings listeners.
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      // ignore: unawaited_futures
+      ref.read(syncControllerProvider.notifier).sync();
+      ref.read(prefetcherProvider);
+      // Metadata prefetcher: when /api/home returns, fire background
+      // albumProvider/artistProvider reads for the top-N items in
+      // each section so subsequent taps are drift hits, not network
+      // round trips.
+      ref.read(metadataPrefetcherProvider);
+      // Live events (#392): subscribes to /api/events/stream and
+      // invalidates publicly-scoped providers when relevant events
+      // arrive. Also installs an AppLifecycleState observer for
+      // resume-time defensive invalidation.
+      ref.read(liveEventsDispatcherProvider);
+      // Cache filler: background sweeper that walks cached_artists
+      // / cached_albums for missing relations and fetches the
+      // per-entity detail so tapping an artist surfaces albums
+      // immediately (drift hit, no /api/artists/:id round-trip at
+      // tap time). First sweep 10s after launch; every 5 minutes
+      // thereafter. Throttled 200ms between requests so it never
+      // competes with user activity.
+      ref.read(cacheFillerProvider);
+      // Mutation replayer: drains the cached_mutations queue when
+      // connectivity comes back. Controllers (LikesController,
+      // MyQuarantineController, the add-to-playlist + request flows)
+      // enqueue on REST failure so user intent persists across
+      // network loss instead of getting rolled back.
+      ref.read(mutationReplayerProvider);
+      // Play-events reporter (#415): the Flutter client otherwise
+      // reports no plays at all — this feeds history, recommendation
+      // scoring, scrobbles, and system-playlist rotation, and is the
+      // path that carries the `source` tag for #415.
+      ref.read(playEventsReporterProvider);
+      // Offline marker (#427 S1): periodic /healthz reachability
+      // probe → offlineProvider. Read here to start the poller; S4
+      // gates system-playlist play + Shuffle-all on it.
+      ref.read(offlineProvider);
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
     final router = ref.watch(routerProvider);
+    final mode = ref.watch(themeModeProvider).value ?? AppThemeMode.system;
     return MaterialApp.router(
       title: 'Minstrel',
-      theme: buildThemeData(),
+      theme: buildLightTheme(),
+      darkTheme: buildDarkTheme(),
+      themeMode: mode.materialMode,
       routerConfig: router,
     );
   }

flutter_client/lib/auth/auth_provider.dart

@@ -2,12 +2,17 @@ import 'dart:convert';
 
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:flutter_timezone/flutter_timezone.dart';
 
+import '../api/endpoints/me.dart';
+import '../library/library_providers.dart' show dioProvider;
 import '../models/user.dart';
 
-const _kServerUrl    = 'server_url';
-const _kSessionToken = 'session_token';
-const _kCurrentUser  = 'current_user';
+const _kServerUrl       = 'server_url';
+const _kSessionToken    = 'session_token';
+const _kCurrentUser     = 'current_user';
+const _kTzLastSentAt    = 'tz_last_sent_at';
+const _weeklyMs         = 7 * 24 * 60 * 60 * 1000;
 
 final secureStorageProvider = Provider<FlutterSecureStorage>(
   (ref) => const FlutterSecureStorage(),
@@ -29,7 +34,12 @@ class AuthController extends AsyncNotifier<User?> {
     _storage = ref.watch(secureStorageProvider);
     final raw = await _storage.read(key: _kCurrentUser);
     if (raw == null) return null;
-    return User.fromJson(jsonDecode(raw) as Map<String, dynamic>);
+    final user = User.fromJson(jsonDecode(raw) as Map<String, dynamic>);
+    // Fire-and-forget timezone send on app start with an existing
+    // session — no-op when last_sent_at is fresh.
+    // ignore: unawaited_futures
+    _sendTimezoneIfStale();
+    return user;
   }
 
   Future<void> setServerUrl(String url) async {
@@ -42,6 +52,8 @@ class AuthController extends AsyncNotifier<User?> {
     await _storage.write(key: _kCurrentUser,  value: userJson);
     ref.invalidate(sessionTokenProvider);
     state = AsyncData(User.fromJson(jsonDecode(userJson) as Map<String, dynamic>));
+    // ignore: unawaited_futures
+    _sendTimezoneIfStale();
   }
 
   Future<void> clearSession() async {
@@ -50,6 +62,27 @@ class AuthController extends AsyncNotifier<User?> {
     ref.invalidate(sessionTokenProvider);
     state = const AsyncData(null);
   }
+
+  /// Sends the device's current IANA timezone to PUT /api/me/timezone
+  /// when the last successful send was >7 days ago (or never).
+  /// Cadence persists in flutter_secure_storage so it survives app
+  /// restarts. Failures are swallowed: the server keeps its previous
+  /// value (or 'UTC' default) until the next attempt.
+  Future<void> _sendTimezoneIfStale() async {
+    try {
+      final lastStr = await _storage.read(key: _kTzLastSentAt);
+      final lastMs = lastStr == null ? 0 : int.tryParse(lastStr) ?? 0;
+      final nowMs = DateTime.now().millisecondsSinceEpoch;
+      if (nowMs - lastMs < _weeklyMs) return;
+      final tz = await FlutterTimezone.getLocalTimezone();
+      if (tz.isEmpty) return;
+      final dio = await ref.read(dioProvider.future);
+      await MeApi(dio).putTimezone(tz);
+      await _storage.write(key: _kTzLastSentAt, value: nowMs.toString());
+    } catch (_) {
+      // Non-fatal — server falls back to UTC or last-known value.
+    }
+  }
 }
 
 final authControllerProvider =

flutter_client/lib/cache/adapters.dart

@@ -0,0 +1,133 @@
+// Drift row → model adapters and reverse-write adapters for populating
+// drift from REST responses (#357 plan C).
+//
+// The cache loses some server-derived fields:
+//   - ArtistRef.coverUrl (server computes from most-recent album)
+//   - AlbumRef.coverUrl (server-emitted derived path)
+//   - TrackRef.streamUrl (could be reconstructed but kept empty for clarity)
+// UI already handles empty coverUrl/streamUrl gracefully. REST cold-cache
+// fallback briefly shows the real values before drift takes over.
+
+import 'package:drift/drift.dart' as drift;
+
+import '../models/album.dart';
+import '../models/artist.dart';
+import '../models/playlist.dart';
+import '../models/track.dart';
+import 'db.dart';
+
+extension CachedArtistAdapter on CachedArtist {
+  /// `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'
+            : '',
+      );
+}
+
+extension ArtistRefDriftWrite on ArtistRef {
+  CachedArtistsCompanion toDrift() => CachedArtistsCompanion.insert(
+        id: id,
+        name: name,
+        sortName: sortName.isNotEmpty ? sortName : name,
+      );
+}
+
+extension CachedAlbumAdapter on CachedAlbum {
+  /// `artistName` is supplied by the joined CachedArtists row at query time.
+  /// `coverUrl` is reconstructed deterministically from the album id —
+  /// the server emits the same shape (see internal/api/convert.go:69).
+  /// We don't need to persist it, so AlbumRef.coverUrl is non-empty
+  /// even when the row was populated from a sync that didn't carry the
+  /// derived URL.
+  AlbumRef toRef({String artistName = ''}) => AlbumRef(
+        id: id,
+        title: title,
+        sortTitle: sortTitle,
+        artistId: artistId,
+        artistName: artistName,
+        coverUrl: '/api/albums/$id/cover',
+      );
+}
+
+extension AlbumRefDriftWrite on AlbumRef {
+  CachedAlbumsCompanion toDrift() => CachedAlbumsCompanion.insert(
+        id: id,
+        artistId: artistId,
+        title: title,
+        sortTitle: sortTitle.isNotEmpty ? sortTitle : title,
+      );
+}
+
+extension CachedTrackAdapter on CachedTrack {
+  /// `artistName` and `albumTitle` come from joined rows.
+  TrackRef toRef({String artistName = '', String albumTitle = ''}) => TrackRef(
+        id: id,
+        title: title,
+        albumId: albumId,
+        albumTitle: albumTitle,
+        artistId: artistId,
+        artistName: artistName,
+        trackNumber: trackNumber,
+        discNumber: discNumber,
+        durationSec: durationMs ~/ 1000,
+      );
+}
+
+extension TrackRefDriftWrite on TrackRef {
+  CachedTracksCompanion toDrift() => CachedTracksCompanion.insert(
+        id: id,
+        albumId: albumId,
+        artistId: artistId,
+        title: title,
+        durationMs: drift.Value(durationSec * 1000),
+        trackNumber: drift.Value(trackNumber),
+        discNumber: drift.Value(discNumber),
+      );
+}
+
+extension CachedPlaylistAdapter on CachedPlaylist {
+  /// `ownerUsername` is server-derived; cache stores the userId only.
+  /// Pass empty unless a join supplies it.
+  /// `coverUrl` is reconstructed deterministically from the playlist
+  /// id — the server serves the cached collage at this path
+  /// (handleGetPlaylistCover). Mirrors the album-cover trick. When
+  /// the server hasn't built a collage yet (system playlists with no
+  /// tracks at build time), the endpoint 404s and PlaylistCard's
+  /// ServerImage falls back to its slate placeholder.
+  Playlist toRef({String ownerUsername = ''}) => Playlist(
+        id: id,
+        userId: userId,
+        name: name,
+        description: description,
+        isPublic: isPublic,
+        systemVariant: systemVariant,
+        trackCount: trackCount,
+        coverUrl: '/api/playlists/$id/cover',
+        ownerUsername: ownerUsername,
+        createdAt: '',
+        updatedAt: '',
+      );
+}
+
+extension PlaylistDriftWrite on Playlist {
+  CachedPlaylistsCompanion toDrift() => CachedPlaylistsCompanion.insert(
+        id: id,
+        userId: userId,
+        name: name,
+        description: drift.Value(description),
+        isPublic: drift.Value(isPublic),
+        trackCount: drift.Value(trackCount),
+        systemVariant: drift.Value(systemVariant),
+      );
+}

flutter_client/lib/cache/audio_cache_manager.dart

@@ -0,0 +1,296 @@
+import 'dart:io';
+
+import 'package:dio/dio.dart';
+import 'package:drift/drift.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:path_provider/path_provider.dart';
+
+import '../library/library_providers.dart' show dioProvider;
+import 'db.dart';
+
+/// Per-bucket cache usage (#427 S2). Rolling includes orphan files —
+/// partials written by LockCachingAudioSource that were never indexed
+/// (skip-before-fully-buffered) — so the rolling cap actually bounds
+/// disk.
+typedef BucketUsage = ({int liked, int rolling});
+
+/// Owns the audio cache directory + drift index.
+///
+/// #427 S2: two storage buckets keyed by liked-ness, not by
+/// CacheSource. A cached track currently in the user's liked set is
+/// charged to (and evicted under) the Liked budget; everything else
+/// is Rolling. This dedup is storage/eviction-only — it never filters
+/// what the offline surfaces can play (S4). `CacheSource` is retained
+/// on the API for callers but is now informational.
+class AudioCacheManager {
+  AudioCacheManager({
+    required AppDb db,
+    required Future<Dio> Function() dioFactory,
+    Future<Directory> Function()? cacheDirFactory,
+  })  : _db = db,
+        _dioFactory = dioFactory,
+        _cacheDirFactory = cacheDirFactory ?? getApplicationCacheDirectory;
+
+  final AppDb _db;
+  final Future<Dio> Function() _dioFactory;
+  final Future<Directory> Function() _cacheDirFactory;
+
+  Future<String> _tracksDir() async {
+    final base = await _cacheDirFactory();
+    final d = Directory('${base.path}/audio_cache');
+    if (!await d.exists()) await d.create(recursive: true);
+    return d.path;
+  }
+
+  Future<bool> isCached(String trackId) async {
+    final row = await (_db.select(_db.audioCacheIndex)
+          ..where((t) => t.trackId.equals(trackId)))
+        .getSingleOrNull();
+    if (row == null) return false;
+    return File(row.path).existsSync();
+  }
+
+  Future<String?> pathFor(String trackId) async {
+    final row = await (_db.select(_db.audioCacheIndex)
+          ..where((t) => t.trackId.equals(trackId)))
+        .getSingleOrNull();
+    if (row == null) return null;
+    return File(row.path).existsSync() ? row.path : null;
+  }
+
+  /// Downloads the track's stream to disk and indexes it. Idempotent.
+  /// lastPlayedAt is set now — pinning is play-intent.
+  Future<String?> pin(String trackId, {required CacheSource source}) async {
+    final existing = await pathFor(trackId);
+    if (existing != null) {
+      await touch(trackId);
+      return existing;
+    }
+    final dir = await _tracksDir();
+    final path = '$dir/$trackId.mp3';
+    final dio = await _dioFactory();
+    try {
+      await dio.download('/api/tracks/$trackId/stream', path);
+    } catch (_) {
+      final f = File(path);
+      if (f.existsSync()) await f.delete();
+      return null;
+    }
+    final size = await File(path).length();
+    await _db.into(_db.audioCacheIndex).insertOnConflictUpdate(
+          AudioCacheIndexCompanion.insert(
+            trackId: trackId,
+            path: path,
+            sizeBytes: size,
+            source: source,
+            lastPlayedAt: Value(DateTime.now()),
+          ),
+        );
+    return path;
+  }
+
+  /// Registers a file LockCachingAudioSource wrote itself. Called
+  /// once a track is fully buffered; it's being played, so stamp
+  /// lastPlayedAt.
+  Future<void> registerStreamCache(
+    String trackId,
+    String path,
+    int sizeBytes, {
+    CacheSource source = CacheSource.incidental,
+  }) async {
+    await _db.into(_db.audioCacheIndex).insertOnConflictUpdate(
+          AudioCacheIndexCompanion.insert(
+            trackId: trackId,
+            path: path,
+            sizeBytes: sizeBytes,
+            source: source,
+            lastPlayedAt: Value(DateTime.now()),
+          ),
+        );
+  }
+
+  /// Bumps lastPlayedAt for an already-indexed track so the rolling
+  /// LRU + the offline "Recently played" view reflect real plays
+  /// (not just download time). No-op if not indexed.
+  Future<void> touch(String trackId) async {
+    await (_db.update(_db.audioCacheIndex)
+          ..where((t) => t.trackId.equals(trackId)))
+        .write(AudioCacheIndexCompanion(lastPlayedAt: Value(DateTime.now())));
+  }
+
+  Future<void> unpin(String trackId) async {
+    final row = await (_db.select(_db.audioCacheIndex)
+          ..where((t) => t.trackId.equals(trackId)))
+        .getSingleOrNull();
+    if (row == null) return;
+    final f = File(row.path);
+    if (f.existsSync()) await f.delete();
+    await (_db.delete(_db.audioCacheIndex)
+          ..where((t) => t.trackId.equals(trackId)))
+        .go();
+  }
+
+  /// Total bytes on disk (directory walk — authoritative; catches
+  /// orphan partials the index misses).
+  Future<int> usageBytes() async {
+    final dir = Directory(await _tracksDir());
+    if (!await dir.exists()) return 0;
+    var total = 0;
+    await for (final e in dir.list(followLinks: false)) {
+      if (e is File) {
+        try {
+          total += await e.length();
+        } catch (_) {}
+      }
+    }
+    return total;
+  }
+
+  /// Bytes per bucket. Indexed rows split by liked-ness; on-disk
+  /// files with no index row (orphan partials) count as Rolling so
+  /// the rolling cap genuinely bounds disk.
+  Future<BucketUsage> bucketUsage(Set<String> liked) async {
+    final rows = await _db.select(_db.audioCacheIndex).get();
+    final indexed = <String>{};
+    var likedB = 0;
+    var rollingB = 0;
+    for (final r in rows) {
+      indexed.add(r.trackId);
+      if (liked.contains(r.trackId)) {
+        likedB += r.sizeBytes;
+      } else {
+        rollingB += r.sizeBytes;
+      }
+    }
+    final dir = Directory(await _tracksDir());
+    if (await dir.exists()) {
+      await for (final e in dir.list(followLinks: false)) {
+        if (e is! File) continue;
+        final name = e.uri.pathSegments.last;
+        final id = name.endsWith('.mp3')
+            ? name.substring(0, name.length - 4)
+            : name;
+        if (indexed.contains(id)) continue;
+        try {
+          rollingB += await e.length();
+        } catch (_) {}
+      }
+    }
+    return (liked: likedB, rolling: rollingB);
+  }
+
+  /// Enforces both budgets independently (0 = unlimited).
+  ///
+  /// Rolling: evict non-liked indexed rows LRU (oldest lastPlayedAt
+  /// /cachedAt first), then sweep orphan files oldest-by-mtime, until
+  /// rolling usage ≤ rollingCap. Liked: evict liked indexed rows LRU
+  /// until ≤ likedCap. Liked is only ever touched by its own (large)
+  /// cap, so normal use never evicts the user's liked library.
+  Future<void> evictBuckets({
+    required int likedCap,
+    required int rollingCap,
+    required Set<String> liked,
+  }) async {
+    final usage = await bucketUsage(liked);
+
+    if (rollingCap > 0 && usage.rolling > rollingCap) {
+      var over = usage.rolling - rollingCap;
+      final rolling = await (_db.select(_db.audioCacheIndex)
+            ..where((t) => t.trackId.isNotIn(liked.toList()))
+            ..orderBy([
+              (t) => OrderingTerm.asc(t.lastPlayedAt),
+              (t) => OrderingTerm.asc(t.cachedAt),
+            ]))
+          .get();
+      for (final r in rolling) {
+        if (over <= 0) break;
+        final f = File(r.path);
+        if (f.existsSync()) await f.delete();
+        await (_db.delete(_db.audioCacheIndex)
+              ..where((t) => t.trackId.equals(r.trackId)))
+            .go();
+        over -= r.sizeBytes;
+      }
+      if (over > 0) await _sweepOrphans(over);
+    }
+
+    if (likedCap > 0 && usage.liked > likedCap) {
+      var over = usage.liked - likedCap;
+      final likedRows = await (_db.select(_db.audioCacheIndex)
+            ..where((t) => t.trackId.isIn(liked.toList()))
+            ..orderBy([
+              (t) => OrderingTerm.asc(t.lastPlayedAt),
+              (t) => OrderingTerm.asc(t.cachedAt),
+            ]))
+          .get();
+      for (final r in likedRows) {
+        if (over <= 0) break;
+        final f = File(r.path);
+        if (f.existsSync()) await f.delete();
+        await (_db.delete(_db.audioCacheIndex)
+              ..where((t) => t.trackId.equals(r.trackId)))
+            .go();
+        over -= r.sizeBytes;
+      }
+    }
+  }
+
+  /// Deletes orphan files (on disk, no index row) oldest-mtime-first
+  /// until `over` bytes are reclaimed. These are unindexed partials,
+  /// always Rolling, always evict-first.
+  Future<void> _sweepOrphans(int over) async {
+    final indexed = {
+      for (final r in await _db.select(_db.audioCacheIndex).get()) r.trackId
+    };
+    final dir = Directory(await _tracksDir());
+    if (!await dir.exists()) return;
+    final orphans = <({File f, int size, DateTime mtime})>[];
+    await for (final e in dir.list(followLinks: false)) {
+      if (e is! File) continue;
+      final name = e.uri.pathSegments.last;
+      final id =
+          name.endsWith('.mp3') ? name.substring(0, name.length - 4) : name;
+      if (indexed.contains(id)) continue;
+      try {
+        final st = e.statSync();
+        orphans.add((f: e, size: st.size, mtime: st.modified));
+      } catch (_) {}
+    }
+    orphans.sort((a, b) => a.mtime.compareTo(b.mtime));
+    var remaining = over;
+    for (final o in orphans) {
+      if (remaining <= 0) break;
+      try {
+        await o.f.delete();
+        remaining -= o.size;
+      } catch (_) {}
+    }
+  }
+
+  /// Clears EVERY row + EVERY file. Wired to "Clear cache".
+  Future<void> clearAll() async {
+    final dir = await _tracksDir();
+    final d = Directory(dir);
+    if (d.existsSync()) {
+      for (final e in d.listSync()) {
+        if (e is File) await e.delete();
+      }
+    }
+    await _db.delete(_db.audioCacheIndex).go();
+  }
+}
+
+/// AppDb singleton. One per app run; ref.onDispose closes it.
+final appDbProvider = Provider<AppDb>((ref) {
+  final db = AppDb();
+  ref.onDispose(db.close);
+  return db;
+});
+
+final audioCacheManagerProvider = Provider<AudioCacheManager>((ref) {
+  final db = ref.watch(appDbProvider);
+  return AudioCacheManager(
+    db: db,
+    dioFactory: () async => ref.read(dioProvider.future),
+  );
+});

flutter_client/lib/cache/cache_filler.dart

@@ -0,0 +1,235 @@
+// Background metadata sweeper that walks the drift cache for missing
+// relations and fills them via /api/artists/:id + /api/albums/:id.
+// Cover bytes for newly-filled albums are pre-warmed too so the
+// per-tile display path doesn't have to wait on network.
+//
+// Why this layer on top of SyncController and HydrationQueue:
+//   - SyncController.sync only ingests entities the server emitted
+//     into the library_changes delta for this user. For a fresh
+//     install, that's everything; for an existing user, only recent
+//     changes. The per-artist album list and per-album track list
+//     are NOT in those deltas — they're derived at query time.
+//   - HydrationQueue fills these lazily on tile render. CacheFiller
+//     fills them proactively on a slow schedule so tapping an artist
+//     surfaces albums immediately instead of triggering a fresh
+//     /api/artists/:id at tap time.
+//
+// Pacing is conservative — 200ms between requests, max 200 entities
+// per sweep, 5-minute interval. Designed to never compete with user
+// activity. Wall time on a 1000-artist library: ~3-4 minutes spread
+// over multiple sweeps.
+
+import 'dart:async';
+
+import 'package:drift/drift.dart' show Variable;
+import 'package:flutter/foundation.dart' show debugPrint;
+import 'package:flutter_cache_manager/flutter_cache_manager.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../auth/auth_provider.dart'
+    show serverUrlProvider, sessionTokenProvider;
+import '../cache/adapters.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../cache/connectivity_provider.dart';
+import '../library/library_providers.dart' show libraryApiProvider;
+
+class CacheFiller {
+  CacheFiller(this._ref);
+  final Ref _ref;
+
+  Timer? _initialTimer;
+  Timer? _intervalTimer;
+  bool _running = false;
+  bool _disposed = false;
+
+  /// Delay between launch and the first sweep. Long enough for
+  /// SyncController to land its initial /api/library/sync so the
+  /// CacheFiller's "unfilled relations" query has meaningful work.
+  static const _initialDelay = Duration(seconds: 10);
+
+  /// Cadence between sweeps. Once a sweep finds nothing to do (steady
+  /// state) the interval becomes a cheap drift query + early exit.
+  static const _interval = Duration(minutes: 5);
+
+  /// Throttle between per-entity REST requests so the filler doesn't
+  /// saturate the server or compete with user-initiated playback.
+  static const _requestThrottle = Duration(milliseconds: 200);
+
+  /// Per-sweep cap. Without this, a fresh install with thousands of
+  /// artists would tie up the network for many minutes in one go.
+  /// The next sweep continues where this one left off (the WHERE
+  /// NOT EXISTS query naturally skips already-filled rows).
+  static const _maxIdsPerSweep = 200;
+
+  void start() {
+    _initialTimer = Timer(_initialDelay, _sweep);
+    _intervalTimer = Timer.periodic(_interval, (_) => _sweep());
+  }
+
+  Future<void> _sweep() async {
+    if (_disposed || _running) return;
+    final online = await _ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true);
+    if (!online) return;
+    _running = true;
+    try {
+      await _fillArtists();
+      if (_disposed) return;
+      await _fillAlbums();
+    } catch (e, st) {
+      debugPrint('cache_filler: sweep failed: $e\n$st');
+    } finally {
+      _running = false;
+    }
+  }
+
+  /// Find artists with no albums in cache and fetch /api/artists/:id
+  /// for each (single round-trip yields artist + albums via the new
+  /// getArtistDetail API method). Newly-discovered album covers
+  /// land in flutter_cache_manager's disk cache too so the next
+  /// visit to the artist's albums grid paints from disk.
+  Future<void> _fillArtists() async {
+    final db = _ref.read(appDbProvider);
+    final rows = await db.customSelect(
+      '''
+      SELECT a.id FROM cached_artists a
+      WHERE NOT EXISTS (
+        SELECT 1 FROM cached_albums b WHERE b.artist_id = a.id
+      )
+      LIMIT ?
+      ''',
+      variables: [Variable.withInt(_maxIdsPerSweep)],
+    ).get();
+    final ids = rows.map((r) => r.read<String>('id')).toList();
+    if (ids.isEmpty) return;
+
+    final api = await _ref.read(libraryApiProvider.future);
+    final newAlbumIds = <String>[];
+
+    for (final id in ids) {
+      if (_disposed) return;
+      try {
+        final detail = await api.getArtistDetail(id);
+        await db.transaction(() async {
+          await db
+              .into(db.cachedArtists)
+              .insertOnConflictUpdate(detail.artist.toDrift());
+          if (detail.albums.isNotEmpty) {
+            await db.batch((b) {
+              b.insertAllOnConflictUpdate(
+                db.cachedAlbums,
+                detail.albums.map((a) => a.toDrift()).toList(),
+              );
+            });
+            newAlbumIds.addAll(detail.albums.map((a) => a.id));
+          }
+        });
+      } catch (e) {
+        debugPrint('cache_filler: fillArtist($id) failed: $e');
+      }
+      await Future.delayed(_requestThrottle);
+    }
+
+    if (newAlbumIds.isNotEmpty) {
+      await _prewarmCovers(newAlbumIds);
+    }
+  }
+
+  /// Find albums with no tracks in cache and fetch /api/albums/:id
+  /// for each. The bulk response carries the album's track list which
+  /// we persist into cached_tracks for instant album detail render
+  /// on the next visit.
+  Future<void> _fillAlbums() async {
+    final db = _ref.read(appDbProvider);
+    final rows = await db.customSelect(
+      '''
+      SELECT a.id FROM cached_albums a
+      WHERE NOT EXISTS (
+        SELECT 1 FROM cached_tracks t WHERE t.album_id = a.id
+      )
+      LIMIT ?
+      ''',
+      variables: [Variable.withInt(_maxIdsPerSweep)],
+    ).get();
+    final ids = rows.map((r) => r.read<String>('id')).toList();
+    if (ids.isEmpty) return;
+
+    final api = await _ref.read(libraryApiProvider.future);
+    for (final id in ids) {
+      if (_disposed) return;
+      try {
+        final result = await api.getAlbum(id);
+        if (result.tracks.isNotEmpty) {
+          await db.batch((b) {
+            b.insertAllOnConflictUpdate(
+              db.cachedTracks,
+              result.tracks.map((t) => t.toDrift()).toList(),
+            );
+          });
+        }
+      } catch (e) {
+        debugPrint('cache_filler: fillAlbum($id) failed: $e');
+      }
+      await Future.delayed(_requestThrottle);
+    }
+  }
+
+  /// Pre-warm album cover bytes via flutter_cache_manager so the
+  /// per-tile ServerImage / CachedNetworkImage paints from disk on
+  /// the user's first visit. Mirrors SyncController's prewarm
+  /// helper — duplicated here intentionally to keep this file self-
+  /// contained; a shared helper can come out of #357 follow-up if
+  /// the duplication grows.
+  Future<void> _prewarmCovers(List<String> albumIds) async {
+    final baseUrl = await _ref.read(serverUrlProvider.future);
+    if (baseUrl == null || baseUrl.isEmpty) return;
+    final token = await _ref.read(sessionTokenProvider.future);
+    final headers = (token != null && token.isNotEmpty)
+        ? {'Authorization': 'Bearer $token'}
+        : <String, String>{};
+    final base = baseUrl.endsWith('/')
+        ? baseUrl.substring(0, baseUrl.length - 1)
+        : baseUrl;
+    final mgr = DefaultCacheManager();
+
+    var idx = 0;
+    Future<void> worker() async {
+      while (idx < albumIds.length) {
+        if (_disposed) return;
+        final i = idx++;
+        try {
+          await mgr.downloadFile(
+            '$base/api/albums/${albumIds[i]}/cover',
+            authHeaders: headers,
+          );
+        } catch (_) {
+          // Best-effort prewarm — 404 (missing collage) and 401
+          // (token refresh races) shouldn't abort the rest.
+        }
+      }
+    }
+
+    // Concurrency 3 — same as SyncController's prewarm. Covers are
+    // small enough that more parallelism doesn't help much and
+    // burns radio.
+    await Future.wait(List.generate(3, (_) => worker()));
+  }
+
+  void dispose() {
+    _disposed = true;
+    _initialTimer?.cancel();
+    _intervalTimer?.cancel();
+  }
+}
+
+/// Read once at app start (from app.dart's postFrameCallback) to
+/// activate the filler. Disposed via ref.onDispose when the provider
+/// scope tears down; in practice the scope lives for the app's
+/// lifetime so dispose only fires on uninstall / process death.
+final cacheFillerProvider = Provider<CacheFiller>((ref) {
+  final filler = CacheFiller(ref);
+  ref.onDispose(filler.dispose);
+  filler.start();
+  return filler;
+});

flutter_client/lib/cache/cache_first.dart

@@ -0,0 +1,115 @@
+// Drift-first reactive read pattern with REST cold-cache fallback (#357 plan C).
+//
+// Subscribes to a drift watch() stream. On each emission:
+//   - non-empty → map to result type T and yield
+//   - empty + online → fetch via REST, populate drift, await re-emission
+//   - empty + offline → yield mapped empty result (UI shows empty state)
+//
+// With `alwaysRefresh: true`, also kicks off a one-shot REST refresh
+// in the background after the first non-empty emission. Use for
+// aggregate lists (playlists, etc.) where the server may have rows
+// the local sync didn't pick up — yields cache immediately, refreshes
+// silently, and drift watch() re-emits with whatever new rows landed.
+//
+// The pattern lets every read provider trust drift as the source of
+// truth. SyncController keeps drift fresh in the background; widget
+// rebuilds happen automatically as drift writes propagate via watch().
+
+import 'dart:async';
+
+import 'package:flutter/foundation.dart' show debugPrint;
+
+// `tag` parameter is preserved for future ad-hoc instrumentation.
+// Normal operation only logs failure paths so the per-screen log
+// noise stays low.
+
+/// Wraps the watch + cold-cache fallback pattern. Generic over:
+///   D — the drift row type (or TypedResult for joins)
+///   T — the result type the caller wants (e.g. `List<ArtistRef>`)
+///
+/// `fetchAndPopulate` is invoked when drift is empty AND `isOnline()`
+/// returns true. It must populate drift via its own side-effect; the
+/// drift watch() stream will re-emit and this helper yields the
+/// populated rows on the next iteration.
+///
+/// REST failures are swallowed — the helper falls through to yielding
+/// the empty result. Caller is responsible for surfacing errors via
+/// toast etc.
+Stream<T> cacheFirst<D, T>({
+  required Stream<List<D>> driftStream,
+  required Future<void> Function() fetchAndPopulate,
+  required T Function(List<D>) toResult,
+  required Future<bool> Function() isOnline,
+  bool alwaysRefresh = false,
+  String? tag,
+}) async* {
+  // Tracks whether we've already kicked off a stale-while-revalidate
+  // refresh for this stream subscription, so we don't fire one on every
+  // drift re-emission (otherwise the populate cycles forever).
+  var revalidated = false;
+
+  // Tracks whether we've already tried a cold-cache fetch on this
+  // subscription. Without this, providers can spin forever in the
+  // rows-empty branch when fetchAndPopulate writes rows that don't
+  // match THIS filter — e.g. three liked-tab streams sharing one
+  // populate: the track populate writes track-typed rows, drift
+  // watch fires for the cached_likes table, the album stream
+  // re-emits with rows-empty (no album likes), the rows-empty
+  // branch re-fires populate, repeats forever. Setting this guard
+  // makes the first fetch attempt also the last for any given
+  // subscription.
+  var coldFetchAttempted = false;
+
+  await for (final rows in driftStream) {
+    if (rows.isNotEmpty) {
+      yield toResult(rows);
+      coldFetchAttempted = true;
+      // Stale-while-revalidate: yield cache immediately, then kick off
+      // a REST refresh in the background. Drift watch() picks up the
+      // resulting writes and re-emits via this same stream loop.
+      // Useful for aggregate lists (e.g. playlists) where the server
+      // may have rows the local sync didn't pick up.
+      if (alwaysRefresh && !revalidated && await isOnline()) {
+        revalidated = true;
+        unawaited(_safeFetch(fetchAndPopulate));
+      }
+      continue;
+    }
+    // rows is empty. If we've already attempted a cold fetch and
+    // drift is still empty for this filter, yield empty so the UI
+    // shows the no-content state instead of spinning forever.
+    if (coldFetchAttempted) {
+      yield toResult(rows);
+      continue;
+    }
+    coldFetchAttempted = true;
+    if (await isOnline()) {
+      try {
+        await fetchAndPopulate();
+        // Yield the current (still-empty) rows so the UI moves past
+        // loading even if populate was a no-op for this filter
+        // (server returned nothing matching, or all rows were
+        // already in drift via sync). If populate DID write rows
+        // matching this filter, the drift watch's next emission
+        // yields them via the rows.isNotEmpty branch — UI briefly
+        // shows empty then populates, instead of spinning.
+        yield toResult(rows);
+      } catch (e, st) {
+        if (tag != null) {
+          debugPrint('cacheFirst[$tag]: fetchAndPopulate failed: $e\n$st');
+        }
+        yield toResult(rows); // empty result; caller surfaces error
+      }
+    } else {
+      yield toResult(rows); // empty result; offline
+    }
+  }
+}
+
+Future<void> _safeFetch(Future<void> Function() fn) async {
+  try {
+    await fn();
+  } catch (_) {
+    // Background revalidate — swallow; UI already showed cached state.
+  }
+}

flutter_client/lib/cache/cache_settings_provider.dart

@@ -0,0 +1,114 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+
+import '../auth/auth_provider.dart' show secureStorageProvider;
+
+/// Operator-tunable cache settings. Persisted via
+/// flutter_secure_storage on the same device.
+///
+/// #427 S2: the single `capBytes` is replaced by two independent
+/// budgets — Liked and Rolling-recent — each defaulting to 5GB.
+/// Bucketing is by liked-ness (a cached track currently in the
+/// user's liked set is charged to Liked; everything else to
+/// Rolling), so the dedup is storage-only and never filters
+/// playback. The old `cache_cap_bytes` key is intentionally not
+/// migrated; defaults reapply (a one-time re-tune, not data loss).
+class CacheSettings {
+  const CacheSettings({
+    required this.likedCapBytes,
+    required this.rollingCapBytes,
+    required this.prefetchWindow,
+    required this.cacheLikedTracks,
+  });
+
+  /// Liked-bucket budget. 0 = unlimited.
+  final int likedCapBytes;
+
+  /// Rolling (recently-played) budget. 0 = unlimited.
+  final int rollingCapBytes;
+
+  /// 1..10. Number of next-tracks the prefetcher pre-downloads.
+  final int prefetchWindow;
+
+  /// When true, every like_track event triggers a pin with source autoLiked.
+  final bool cacheLikedTracks;
+
+  CacheSettings copyWith({
+    int? likedCapBytes,
+    int? rollingCapBytes,
+    int? prefetchWindow,
+    bool? cacheLikedTracks,
+  }) =>
+      CacheSettings(
+        likedCapBytes: likedCapBytes ?? this.likedCapBytes,
+        rollingCapBytes: rollingCapBytes ?? this.rollingCapBytes,
+        prefetchWindow: prefetchWindow ?? this.prefetchWindow,
+        cacheLikedTracks: cacheLikedTracks ?? this.cacheLikedTracks,
+      );
+
+  static const _fiveGiB = 5 * 1024 * 1024 * 1024;
+
+  static const defaults = CacheSettings(
+    likedCapBytes: _fiveGiB,
+    rollingCapBytes: _fiveGiB,
+    prefetchWindow: 5,
+    cacheLikedTracks: true,
+  );
+}
+
+class CacheSettingsController extends AsyncNotifier<CacheSettings> {
+  static const _kLikedCap = 'cache_liked_cap_bytes';
+  static const _kRollingCap = 'cache_rolling_cap_bytes';
+  static const _kPrefetch = 'cache_prefetch_window';
+  static const _kCacheLiked = 'cache_liked_tracks';
+
+  late FlutterSecureStorage _storage;
+
+  @override
+  Future<CacheSettings> build() async {
+    _storage = ref.read(secureStorageProvider);
+    final likedCap = await _storage.read(key: _kLikedCap);
+    final rollingCap = await _storage.read(key: _kRollingCap);
+    final pre = await _storage.read(key: _kPrefetch);
+    final liked = await _storage.read(key: _kCacheLiked);
+    return CacheSettings(
+      likedCapBytes: likedCap == null
+          ? CacheSettings.defaults.likedCapBytes
+          : int.tryParse(likedCap) ?? CacheSettings.defaults.likedCapBytes,
+      rollingCapBytes: rollingCap == null
+          ? CacheSettings.defaults.rollingCapBytes
+          : int.tryParse(rollingCap) ?? CacheSettings.defaults.rollingCapBytes,
+      prefetchWindow: pre == null
+          ? CacheSettings.defaults.prefetchWindow
+          : (int.tryParse(pre) ?? 5).clamp(1, 10),
+      cacheLikedTracks: liked == null
+          ? CacheSettings.defaults.cacheLikedTracks
+          : liked == 'true',
+    );
+  }
+
+  Future<void> setLikedCapBytes(int bytes) async {
+    await _storage.write(key: _kLikedCap, value: bytes.toString());
+    state = AsyncData(state.value!.copyWith(likedCapBytes: bytes));
+  }
+
+  Future<void> setRollingCapBytes(int bytes) async {
+    await _storage.write(key: _kRollingCap, value: bytes.toString());
+    state = AsyncData(state.value!.copyWith(rollingCapBytes: bytes));
+  }
+
+  Future<void> setPrefetchWindow(int n) async {
+    final clamped = n.clamp(1, 10);
+    await _storage.write(key: _kPrefetch, value: clamped.toString());
+    state = AsyncData(state.value!.copyWith(prefetchWindow: clamped));
+  }
+
+  Future<void> setCacheLikedTracks(bool on) async {
+    await _storage.write(key: _kCacheLiked, value: on.toString());
+    state = AsyncData(state.value!.copyWith(cacheLikedTracks: on));
+  }
+}
+
+final cacheSettingsProvider =
+    AsyncNotifierProvider<CacheSettingsController, CacheSettings>(
+        CacheSettingsController.new);

flutter_client/lib/cache/connectivity_provider.dart

@@ -0,0 +1,35 @@
+import 'package:connectivity_plus/connectivity_plus.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+/// Online if at least one connectivity result is non-none.
+/// connectivity_plus reports the union (wifi, mobile, vpn, etc.) — operator
+/// chose "no Wi-Fi gate" for #357, so any connection means "go ahead and
+/// pull/cache".
+///
+/// IMPORTANT: onConnectivityChanged only emits on *changes*, not on
+/// subscription. Without seeding an initial value via checkConnectivity(),
+/// any consumer using `ref.read(connectivityProvider.future)` would
+/// block until the OS happened to report a connectivity flip — which
+/// is exactly what made album/artist/playlist detail screens spin
+/// forever for tiles tapped before the first event landed.
+final connectivityProvider = StreamProvider<bool>((ref) async* {
+  final c = Connectivity();
+  bool isOnline(List<ConnectivityResult> rs) =>
+      rs.any((r) => r != ConnectivityResult.none);
+
+  // checkConnectivity() goes over a platform channel and on some
+  // Android builds it can stall. Fall back to "assume online" after
+  // 2s so consumers waiting on .future never block forever — being
+  // wrong about connectivity costs at most one failed request, but
+  // being stuck spins the UI indefinitely.
+  try {
+    final initial = await c.checkConnectivity().timeout(
+          const Duration(seconds: 2),
+          onTimeout: () => const [ConnectivityResult.wifi],
+        );
+    yield isOnline(initial);
+  } catch (_) {
+    yield true;
+  }
+  yield* c.onConnectivityChanged.map(isOnline);
+});

flutter_client/lib/cache/db.dart

@@ -0,0 +1,321 @@
+// Drift database for Minstrel's offline cache (#357 plan B).
+//
+// Two cache layers in one database:
+//   - Metadata cache (CachedArtists, CachedAlbums, CachedTracks,
+//     CachedLikes, CachedPlaylists, CachedPlaylistTracks) — populated
+//     by SyncController via /api/library/sync
+//   - Audio cache index (AudioCacheIndex) — owned by AudioCacheManager
+//
+// Plus SyncMetadata holding the latest sync cursor.
+//
+// All entity ids are TEXT (server-side UUIDs serialized as strings).
+// build_runner generates db.g.dart from this file; it's gitignored and
+// regenerated in CI.
+
+import 'package:drift/drift.dart';
+import 'package:drift_flutter/drift_flutter.dart';
+
+part 'db.g.dart';
+
+class CachedArtists extends Table {
+  TextColumn get id => text()();
+  TextColumn get name => text()();
+  TextColumn get sortName => text()();
+  TextColumn get mbid => text().nullable()();
+  TextColumn get artistThumbPath => text().nullable()();
+  TextColumn get artistFanartPath => text().nullable()();
+  DateTimeColumn get fetchedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+class CachedAlbums extends Table {
+  TextColumn get id => text()();
+  TextColumn get artistId => text()();
+  TextColumn get title => text()();
+  TextColumn get sortTitle => text()();
+  TextColumn get releaseDate => text().nullable()();
+  TextColumn get coverPath => text().nullable()();
+  TextColumn get mbid => text().nullable()();
+  DateTimeColumn get fetchedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+class CachedTracks extends Table {
+  TextColumn get id => text()();
+  TextColumn get albumId => text()();
+  TextColumn get artistId => text()();
+  TextColumn get title => text()();
+  IntColumn get durationMs => integer().withDefault(const Constant(0))();
+  IntColumn get trackNumber => integer().nullable()();
+  IntColumn get discNumber => integer().nullable()();
+  TextColumn get filePath => text().nullable()();
+  TextColumn get fileFormat => text().nullable()();
+  TextColumn get genre => text().nullable()();
+  DateTimeColumn get fetchedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+class CachedLikes extends Table {
+  TextColumn get userId => text()();
+  TextColumn get entityType => text()(); // 'track' | 'album' | 'artist'
+  TextColumn get entityId => text()();
+  DateTimeColumn get likedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {userId, entityType, entityId};
+}
+
+class CachedPlaylists extends Table {
+  TextColumn get id => text()();
+  TextColumn get userId => text()();
+  TextColumn get name => text()();
+  TextColumn get description => text().withDefault(const Constant(''))();
+  BoolColumn get isPublic => boolean().withDefault(const Constant(false))();
+  TextColumn get coverPath => text().nullable()();
+  IntColumn get trackCount => integer().withDefault(const Constant(0))();
+  IntColumn get durationSec => integer().withDefault(const Constant(0))();
+  /// Server's system_variant: null for user playlists, "for_you" /
+  /// "songs_like_artist" / "discover" for system-generated mixes.
+  /// Added in schemaVersion 2 to let the add-to-playlist sheet filter
+  /// out system playlists locally without a REST round-trip.
+  TextColumn get systemVariant => text().nullable()();
+  DateTimeColumn get fetchedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+class CachedPlaylistTracks extends Table {
+  TextColumn get playlistId => text()();
+  TextColumn get trackId => text()();
+  IntColumn get position => integer().withDefault(const Constant(0))();
+  @override
+  Set<Column> get primaryKey => {playlistId, trackId};
+}
+
+/// One row per fully-downloaded audio file. `source` drives tiered LRU
+/// eviction; `incidental` evicts first, `manual` last.
+class AudioCacheIndex extends Table {
+  TextColumn get trackId => text()();
+  TextColumn get path => text()();
+  IntColumn get sizeBytes => integer()();
+  DateTimeColumn get cachedAt => dateTime().withDefault(currentDateAndTime)();
+  /// When the track was last played. Drives the offline "Recently
+  /// played" ordering and rolling-bucket LRU eviction. Distinct from
+  /// cachedAt (download time). Nullable for pre-schema-9 rows until
+  /// the next play touches them (migration backfills to cachedAt).
+  DateTimeColumn get lastPlayedAt => dateTime().nullable()();
+  TextColumn get source => textEnum<CacheSource>()();
+  @override
+  Set<Column> get primaryKey => {trackId};
+}
+
+/// Single-row table holding the latest sync cursor.
+class SyncMetadata extends Table {
+  IntColumn get id => integer().withDefault(const Constant(1))();
+  IntColumn get cursor => integer().withDefault(const Constant(0))();
+  DateTimeColumn get lastSyncAt => dateTime().nullable()();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Single-row cache of the /api/home response (#357 follow-up). The
+/// home screen is the first thing the user sees on app open; storing
+/// the last successful HomeData as JSON lets us yield it immediately
+/// before the REST round-trip resolves, eliminating the cold-start
+/// blank on slow / remote connections. Schema 3+.
+class CachedHomeSnapshot extends Table {
+  IntColumn get id => integer().withDefault(const Constant(1))();
+  TextColumn get json => text()();
+  DateTimeColumn get updatedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Single-row cache of the /api/me/history response. Mirrors the
+/// CachedHomeSnapshot pattern: opening the History tab in the Library
+/// screen yields the last-known page immediately while a fresh REST
+/// pull lands underneath via SWR. Also makes basic offline scrollback
+/// possible — the last fetched page survives both app restart and
+/// loss of connectivity. Schema 4+.
+class CachedHistorySnapshot extends Table {
+  IntColumn get id => integer().withDefault(const Constant(1))();
+  TextColumn get json => text()();
+  DateTimeColumn get updatedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Single-row cache of the /api/me/system-playlists-status response.
+/// The home Playlists row reads this every render to pick between
+/// real cards and placeholder cards for For-You / Discover / Songs-
+/// like slots, so a fresh-mount cold fetch produces a visible
+/// "building / pending / failed" flicker. Storing the last result
+/// as a JSON blob means the home renders with the prior status
+/// instantly, then SWR refreshes underneath. Schema 7+.
+class CachedSystemPlaylistsStatus extends Table {
+  IntColumn get id => integer().withDefault(const Constant(1))();
+  TextColumn get json => text()();
+  DateTimeColumn get updatedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {id};
+}
+
+/// Section→position→entity-id index for the home screen, populated
+/// from the per-item discovery endpoint `/api/home/index`. Each row
+/// pins one tile slot to an entity; the actual entity data lives in
+/// cached_albums / cached_artists / cached_tracks. The home screen
+/// reads this table to know the layout, then hydrates each tile
+/// against the entity tables (per-item rendering). Schema 6+.
+class CachedHomeIndex extends Table {
+  /// One of: 'recently_added_albums', 'rediscover_albums',
+  /// 'rediscover_artists', 'most_played_tracks', 'last_played_artists'.
+  /// Mirrors the keys /api/home and /api/home/index emit.
+  TextColumn get section => text()();
+  IntColumn get position => integer()();
+  /// One of: 'album', 'artist', 'track'. Used to dispatch hydration
+  /// to the right per-entity endpoint.
+  TextColumn get entityType => text()();
+  TextColumn get entityId => text()();
+  DateTimeColumn get fetchedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {section, position};
+}
+
+/// Outbound mutation queue for offline-resilient REST calls. Likes,
+/// quarantine flag/unflag, playlist appendTracks, Lidarr request
+/// create/cancel all enqueue here on REST failure so the user's
+/// intent persists across network loss. MutationReplayer drains on
+/// connectivity transitions and a 1-minute periodic tick; entries
+/// with attempts >= 5 are skipped (the server treats them as
+/// permanent failures and library_changes sync will correct any
+/// resulting drift drift on next sync). Schema 8+.
+class CachedMutations extends Table {
+  IntColumn get id => integer().autoIncrement()();
+  /// Stable kind string (see mutation_queue.dart constants). The
+  /// replayer looks up the handler in a kind→Function map; unknown
+  /// kinds are dropped to avoid getting stuck.
+  TextColumn get kind => text()();
+  /// JSON-encoded payload — args needed to replay the REST call.
+  /// Shape depends on kind; see mutation_queue.dart.
+  TextColumn get payload => text()();
+  DateTimeColumn get createdAt => dateTime().withDefault(currentDateAndTime)();
+  /// When the last drain attempt fired against this row. Null until
+  /// the first attempt. Useful for diagnostic queries.
+  DateTimeColumn get lastAttemptAt => dateTime().nullable()();
+  IntColumn get attempts => integer().withDefault(const Constant(0))();
+}
+
+/// Caller-scoped quarantine ("hidden") rows. Mirrors the wire shape of
+/// /api/quarantine/mine — fully denormalized (track + album + artist
+/// fields inline) because the Hidden tab renders straight from this row
+/// without joining other tables. Columnar (vs JSON blob) so flag/unflag
+/// can do row-level INSERT/DELETE; the drift watch() emission feeds
+/// MyQuarantineController state directly. Schema 5+.
+class CachedQuarantineMine extends Table {
+  TextColumn get trackId => text()();
+  TextColumn get reason => text()();
+  TextColumn get notes => text().nullable()();
+  TextColumn get createdAt => text()();
+  TextColumn get trackTitle => text()();
+  IntColumn get trackDurationMs => integer().withDefault(const Constant(0))();
+  TextColumn get albumId => text()();
+  TextColumn get albumTitle => text()();
+  TextColumn get albumCoverArtPath => text().nullable()();
+  TextColumn get artistId => text()();
+  TextColumn get artistName => text()();
+  DateTimeColumn get fetchedAt => dateTime().withDefault(currentDateAndTime)();
+  @override
+  Set<Column> get primaryKey => {trackId};
+}
+
+enum CacheSource { manual, autoLiked, autoPlaylist, autoPrefetch, incidental }
+
+@DriftDatabase(tables: [
+  CachedArtists,
+  CachedAlbums,
+  CachedTracks,
+  CachedLikes,
+  CachedPlaylists,
+  CachedPlaylistTracks,
+  AudioCacheIndex,
+  SyncMetadata,
+  CachedHomeSnapshot,
+  CachedHistorySnapshot,
+  CachedQuarantineMine,
+  CachedHomeIndex,
+  CachedSystemPlaylistsStatus,
+  CachedMutations,
+])
+class AppDb extends _$AppDb {
+  AppDb([QueryExecutor? e]) : super(e ?? driftDatabase(name: 'minstrel_cache'));
+
+  @override
+  int get schemaVersion => 9;
+
+  @override
+  MigrationStrategy get migration => MigrationStrategy(
+        onCreate: (m) => m.createAll(),
+        onUpgrade: (m, from, to) async {
+          if (from < 2) {
+            // Schema 2: add CachedPlaylists.systemVariant. Existing
+            // rows get null and the next sync rebuilds them with the
+            // server's system_variant value.
+            await m.addColumn(cachedPlaylists, cachedPlaylists.systemVariant);
+            // Reset cursor so the next /api/library/sync re-emits all
+            // playlists; otherwise the new column would stay null on
+            // pre-existing rows until they happen to change server-side.
+            await customStatement('UPDATE sync_metadata SET cursor = 0');
+          }
+          if (from < 3) {
+            // Schema 3: cached_home_snapshot for #357 drift-first
+            // home page. No existing rows to migrate — table starts
+            // empty; the first /api/home fetch populates it.
+            await m.createTable(cachedHomeSnapshot);
+          }
+          if (from < 4) {
+            // Schema 4: cached_history_snapshot for drift-first
+            // History tab. Same pattern as cached_home_snapshot —
+            // empty on upgrade; first /api/me/history fetch populates.
+            await m.createTable(cachedHistorySnapshot);
+          }
+          if (from < 5) {
+            // Schema 5: cached_quarantine_mine for drift-first Hidden
+            // tab. Empty on upgrade; first /api/quarantine/mine fetch
+            // populates. Optimistic flag/unflag also writes here.
+            await m.createTable(cachedQuarantineMine);
+          }
+          if (from < 6) {
+            // Schema 6: cached_home_index for per-item rendering.
+            // Empty on upgrade; first /api/home/index fetch populates.
+            // cached_home_snapshot stays in place for now — older
+            // builds still read from it as a fallback path.
+            await m.createTable(cachedHomeIndex);
+          }
+          if (from < 7) {
+            // Schema 7: cached_system_playlists_status. Single-row
+            // snapshot of /api/me/system-playlists-status used by the
+            // home Playlists row. Empty on upgrade; first fetch
+            // populates.
+            await m.createTable(cachedSystemPlaylistsStatus);
+          }
+          if (from < 8) {
+            // Schema 8: cached_mutations outbound queue. Empty on
+            // upgrade; populated by controllers when REST calls fail.
+            await m.createTable(cachedMutations);
+          }
+          if (from < 9) {
+            // Schema 9 (#427 S2): two-bucket cache. lastPlayedAt
+            // gives the offline "Recently played" view a real
+            // recency signal (cachedAt is download time, not play
+            // time). Nullable — backfilled to cachedAt so existing
+            // rows order sensibly until next play touches them.
+            await m.addColumn(audioCacheIndex, audioCacheIndex.lastPlayedAt);
+            await customStatement(
+              'UPDATE audio_cache_index SET last_played_at = cached_at',
+            );
+          }
+        },
+      );
+}

flutter_client/lib/cache/hydration_queue.dart

@@ -0,0 +1,139 @@
+// Per-item hydration coordinator for the home/playlist/liked surfaces.
+//
+// Tile widgets are reactive to their per-entity drift row. On first
+// build, if drift has no row for the requested id, the tile asks this
+// queue to hydrate it. The queue dispatches one /api/<type>/:id
+// request, writes the result to drift, and the drift watch() on the
+// tile re-emits with the populated row.
+//
+// Concurrency cap: HydrationQueue limits the number of in-flight
+// requests so a 50-tile home screen doesn't fire 50 parallel /api/
+// calls and stall the auth-token-bound dio pool. In-flight dedup
+// (keyed by `<type>:<id>`) ensures a single hydration when multiple
+// tiles share an entity (rare on home, common when several screens
+// reference the same album).
+//
+// Failures are swallowed — a single failed hydration leaves the tile
+// in skeleton state. A future retry-on-visit pass can layer on top
+// without changing the queue's contract.
+
+import 'dart:async';
+import 'dart:collection';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../cache/adapters.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../library/library_providers.dart' show libraryApiProvider;
+
+/// Bounded-concurrency request queue for per-entity hydration. One
+/// instance per Riverpod scope (provider singleton below).
+class HydrationQueue {
+  HydrationQueue(this._ref);
+  final Ref _ref;
+
+  /// Concurrent slot count. 4 keeps the dio token pool from saturating
+  /// while still pulling tiles down faster than a serial loop. Bump
+  /// if profiling shows the queue idle while the network is healthy.
+  static const _maxConcurrent = 4;
+
+  final Queue<_HydrationRequest> _pending = Queue();
+  final Set<String> _inFlightKeys = {};
+  int _inFlight = 0;
+
+  /// Request hydration for (entityType, entityId). Idempotent — second
+  /// call for the same key while the first is queued or in flight is
+  /// dropped, so multiple tile rebuilds during a fast scroll don't
+  /// inflate the queue.
+  void enqueue({required String entityType, required String entityId}) {
+    if (entityId.isEmpty) return;
+    final key = '$entityType:$entityId';
+    if (_inFlightKeys.contains(key)) return;
+    if (_pending.any((r) => r.key == key)) return;
+    _pending.add(_HydrationRequest(
+        entityType: entityType, entityId: entityId, key: key));
+    _pump();
+  }
+
+  void _pump() {
+    while (_inFlight < _maxConcurrent && _pending.isNotEmpty) {
+      final req = _pending.removeFirst();
+      _inFlightKeys.add(req.key);
+      _inFlight++;
+      // Unawaited on purpose — _pump returns immediately so further
+      // enqueues can fill remaining slots while this one runs.
+      unawaited(_execute(req).whenComplete(() {
+        _inFlight--;
+        _inFlightKeys.remove(req.key);
+        _pump();
+      }));
+    }
+  }
+
+  Future<void> _execute(_HydrationRequest req) async {
+    try {
+      switch (req.entityType) {
+        case 'album':
+          await _hydrateAlbum(req.entityId);
+        case 'artist':
+          await _hydrateArtist(req.entityId);
+        case 'track':
+          await _hydrateTrack(req.entityId);
+      }
+    } catch (_) {
+      // Swallow — tile stays in skeleton. A retry-on-visit pass can
+      // layer on top later without changing this contract.
+    }
+  }
+
+  Future<void> _hydrateAlbum(String id) async {
+    final api = await _ref.read(libraryApiProvider.future);
+    final result = await api.getAlbum(id);
+    final db = _ref.read(appDbProvider);
+    // Album + tracks come bundled in the same response; persist both
+    // so opening the album detail later is also a drift hit.
+    await db.transaction(() async {
+      await db
+          .into(db.cachedAlbums)
+          .insertOnConflictUpdate(result.album.toDrift());
+      if (result.tracks.isNotEmpty) {
+        await db.batch((b) {
+          b.insertAllOnConflictUpdate(
+              db.cachedTracks, result.tracks.map((t) => t.toDrift()).toList());
+        });
+      }
+    });
+  }
+
+  Future<void> _hydrateArtist(String id) async {
+    final api = await _ref.read(libraryApiProvider.future);
+    final fresh = await api.getArtist(id);
+    final db = _ref.read(appDbProvider);
+    await db.into(db.cachedArtists).insertOnConflictUpdate(fresh.toDrift());
+  }
+
+  Future<void> _hydrateTrack(String id) async {
+    final api = await _ref.read(libraryApiProvider.future);
+    final fresh = await api.getTrack(id);
+    final db = _ref.read(appDbProvider);
+    await db.into(db.cachedTracks).insertOnConflictUpdate(fresh.toDrift());
+  }
+}
+
+class _HydrationRequest {
+  _HydrationRequest({
+    required this.entityType,
+    required this.entityId,
+    required this.key,
+  });
+  final String entityType;
+  final String entityId;
+  final String key;
+}
+
+/// Singleton queue scoped to the Riverpod container. Kept as a plain
+/// Provider (not StateProvider) since the queue's internal state is
+/// pump-driven, not reactively observed.
+final hydrationQueueProvider = Provider<HydrationQueue>((ref) {
+  return HydrationQueue(ref);
+});

flutter_client/lib/cache/metadata_prefetcher.dart

@@ -0,0 +1,74 @@
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../library/library_providers.dart';
+import '../models/home_data.dart';
+
+/// Pre-warms the drift cache for likely-tap targets. Conservative on
+/// purpose: only warms artistProvider rows (single row, single round
+/// trip per id) and only ever fires once per id per session. Album
+/// detail is NOT prewarmed — the albumProvider auto-fetches its track
+/// list when missing, and pre-warming N albums fans out N parallel
+/// "fetch tracks" round trips that compete with the user's actual
+/// playback request for bandwidth.
+class MetadataPrefetcher {
+  MetadataPrefetcher(this._ref) {
+    _ref.listen<AsyncValue<HomeData>>(homeProvider, (_, next) {
+      next.whenData(_warmHome);
+    });
+  }
+
+  final Ref _ref;
+
+  /// Per-session dedupe so re-rendering a screen (every UI rebuild
+  /// fires the data: callback) doesn't trigger N more fetches for
+  /// ids we've already warmed.
+  final Set<String> _warmedArtists = {};
+
+  /// Cap per section. Covers what fits on screen without scrolling.
+  static const _topN = 8;
+
+  /// Pre-warm artists. Albums are intentionally not pre-warmed —
+  /// see class comment.
+  void warmArtists(Iterable<String> ids) {
+    var n = 0;
+    for (final id in ids) {
+      if (id.isEmpty) continue;
+      if (!_warmedArtists.add(id)) continue; // already warmed
+      if (n++ >= _topN) break;
+      _swallow(_ref.read(artistProvider(id).future));
+    }
+  }
+
+  void _warmHome(HomeData h) {
+    final artistIds = <String>{};
+    for (final a in h.recentlyAddedAlbums.take(_topN)) {
+      if (a.artistId.isNotEmpty) artistIds.add(a.artistId);
+    }
+    for (final a in h.rediscoverAlbums.take(_topN)) {
+      if (a.artistId.isNotEmpty) artistIds.add(a.artistId);
+    }
+    for (final ar in h.rediscoverArtists.take(_topN)) {
+      if (ar.id.isNotEmpty) artistIds.add(ar.id);
+    }
+    for (final ar in h.lastPlayedArtists.take(_topN)) {
+      if (ar.id.isNotEmpty) artistIds.add(ar.id);
+    }
+    for (final t in h.mostPlayedTracks.take(_topN)) {
+      if (t.artistId.isNotEmpty) artistIds.add(t.artistId);
+    }
+    warmArtists(artistIds);
+  }
+
+  /// Discards the return value and any error from a fire-and-forget
+  /// provider read. We don't care about the value here — we only want
+  /// the side effect of writing drift.
+  void _swallow(Future<Object?> f) {
+    f.then<void>((_) {}).onError((_, __) {});
+  }
+}
+
+/// Read once at app start to activate the prefetcher (e.g. wire it
+/// from a top-level Consumer or main.dart container override).
+final metadataPrefetcherProvider = Provider<MetadataPrefetcher>((ref) {
+  return MetadataPrefetcher(ref);
+});

flutter_client/lib/cache/mutation_queue.dart

@@ -0,0 +1,311 @@
+// Outbound mutation queue for offline-resilient REST calls.
+//
+// Controllers (LikesController, MyQuarantineController, the add-to-
+// playlist sheet, the Discover request flow, the Requests cancel
+// action) write their optimistic local state to drift first and try
+// the corresponding REST call. On failure they enqueue here. The
+// replayer drains the queue when connectivity comes back; the user's
+// intent persists across network loss without rolling back their
+// visible action.
+//
+// Why this is separate from SyncController: sync ingests AUTHORITATIVE
+// SERVER state into drift. The mutation queue carries USER INTENT
+// outbound to the server. They flow in opposite directions and
+// shouldn't be conflated — sync wins on conflict (server is the
+// source of truth), and a mutation that fails forever (5 attempts)
+// is dropped on the trust that next sync will reconcile drift to
+// match the server's actual state.
+//
+// Drop semantics: 5 attempts then drop. The drop is intentional —
+// holding onto a forever-failing mutation just delays sync's
+// reconciliation. The user's optimistic drift state will diverge
+// from server, and the next library_changes delta corrects it.
+
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:dio/dio.dart' show DioException, DioExceptionType;
+import 'package:drift/drift.dart';
+import 'package:flutter/foundation.dart' show debugPrint;
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../api/endpoints/discover.dart';
+import '../api/endpoints/events.dart';
+import '../api/endpoints/likes.dart';
+import '../library/library_providers.dart' show dioProvider;
+import '../likes/likes_provider.dart' show likesApiProvider;
+import '../models/lidarr.dart' show LidarrRequestKind;
+import '../playlists/playlists_provider.dart' show playlistsApiProvider;
+import '../quarantine/quarantine_provider.dart' show quarantineApiProvider;
+import '../requests/requests_provider.dart' show requestsApiProvider;
+import 'audio_cache_manager.dart' show appDbProvider;
+import 'connectivity_provider.dart';
+import 'db.dart';
+
+/// Stable kind constants. Each controller emits one of these via
+/// MutationQueue.enqueue; the replayer dispatches by kind.
+class MutationKinds {
+  MutationKinds._();
+  static const likeAdd = 'like.add';
+  static const likeRemove = 'like.remove';
+  static const quarantineFlag = 'quarantine.flag';
+  static const quarantineUnflag = 'quarantine.unflag';
+  static const playlistAppend = 'playlist.append';
+  static const requestCreate = 'request.create';
+  static const requestCancel = 'request.cancel';
+  static const playOffline = 'play.offline';
+}
+
+class MutationQueue {
+  MutationQueue(this._ref);
+  final Ref _ref;
+
+  /// Persist a mutation for replay. Caller has already done the
+  /// optimistic local mutation (drift write, in-memory state update)
+  /// — this only records the REST call that needs to fire eventually.
+  Future<void> enqueue(String kind, Map<String, dynamic> payload) async {
+    final db = _ref.read(appDbProvider);
+    await db.into(db.cachedMutations).insert(
+          CachedMutationsCompanion.insert(
+            kind: kind,
+            payload: jsonEncode(payload),
+          ),
+        );
+    // Nudge the replayer in case we're online right now.
+    unawaited(_ref.read(mutationReplayerProvider).drain());
+  }
+
+  /// Count of pending mutations (attempts < 5). Diagnostic / future
+  /// UI surface for a "syncing N pending changes" indicator.
+  Future<int> pendingCount() async {
+    final db = _ref.read(appDbProvider);
+    final rows = await db.customSelect(
+      'SELECT COUNT(*) AS c FROM cached_mutations WHERE attempts < 5',
+    ).get();
+    return rows.first.read<int>('c');
+  }
+}
+
+final mutationQueueProvider =
+    Provider<MutationQueue>((ref) => MutationQueue(ref));
+
+class MutationReplayer {
+  MutationReplayer(this._ref);
+  final Ref _ref;
+
+  Timer? _initialTimer;
+  Timer? _intervalTimer;
+  bool _running = false;
+  bool _disposed = false;
+
+  /// Periodic poll cadence. The connectivity listener catches most
+  /// transitions; this is the belt-and-suspenders for cases where
+  /// connectivity_plus misses a state change (e.g. flaky Wi-Fi).
+  static const _interval = Duration(minutes: 1);
+
+  /// Max replay attempts before we drop a mutation. 5 is enough to
+  /// span a few reconnection cycles without holding onto a forever-
+  /// broken request. See file header for the drop rationale.
+  static const _maxAttempts = 5;
+
+  void start() {
+    // Drain shortly after launch in case there are queued mutations
+    // from a prior session that died offline. 3s lets the auth +
+    // server-url + dio providers finish their async warmup.
+    _initialTimer = Timer(const Duration(seconds: 3), drain);
+    // Periodic ticker is the only reconnect signal. We previously had
+    // a ref.listen(connectivityProvider, …) edge trigger here, but
+    // subscribing at start-time eagerly mounted the connectivity
+    // StreamProvider and leaked its initial-timeout Timer through
+    // tests that never reach the auth state. The drain() loop itself
+    // gates on connectivity via the .future read below.
+    _intervalTimer = Timer.periodic(_interval, (_) => drain());
+  }
+
+  /// Walk the queue oldest-first, replaying each mutation. Stops on
+  /// any transient network error (we'll retry on the next tick); a
+  /// permanent error (404 etc.) increments the attempt counter and
+  /// moves on to the next mutation. This is public so MutationQueue.
+  /// enqueue can trigger an immediate attempt after writing.
+  Future<void> drain() async {
+    if (_disposed || _running) return;
+    final online = await _ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true);
+    if (!online) return;
+    _running = true;
+    try {
+      while (!_disposed) {
+        final db = _ref.read(appDbProvider);
+        final next = await (db.select(db.cachedMutations)
+              ..where((t) => t.attempts.isSmallerThanValue(_maxAttempts))
+              ..orderBy([(t) => OrderingTerm.asc(t.createdAt)])
+              ..limit(1))
+            .getSingleOrNull();
+        if (next == null) break;
+
+        final handler = _handlers[next.kind];
+        if (handler == null) {
+          debugPrint('mutation_replayer: unknown kind ${next.kind}, dropping');
+          await (db.delete(db.cachedMutations)
+                ..where((t) => t.id.equals(next.id)))
+              .go();
+          continue;
+        }
+
+        Map<String, dynamic> payload;
+        try {
+          payload = jsonDecode(next.payload) as Map<String, dynamic>;
+        } catch (e) {
+          debugPrint('mutation_replayer: bad payload for ${next.kind}: $e');
+          await (db.delete(db.cachedMutations)
+                ..where((t) => t.id.equals(next.id)))
+              .go();
+          continue;
+        }
+
+        try {
+          await handler(_ref, payload);
+          await (db.delete(db.cachedMutations)
+                ..where((t) => t.id.equals(next.id)))
+              .go();
+        } on DioException catch (e) {
+          await (db.update(db.cachedMutations)
+                ..where((t) => t.id.equals(next.id)))
+              .write(CachedMutationsCompanion(
+            attempts: Value(next.attempts + 1),
+            lastAttemptAt: Value(DateTime.now()),
+          ));
+          if (_isTransient(e)) {
+            // Network is flaky again — bail and try the whole queue
+            // later. The current mutation will be retried next tick.
+            break;
+          }
+          // Permanent failure (4xx/5xx with a real response). Leave
+          // the row with bumped attempts and move on to the next so
+          // one bad mutation doesn't block the others.
+        } catch (e, st) {
+          debugPrint('mutation_replayer: unexpected error: $e\n$st');
+          await (db.update(db.cachedMutations)
+                ..where((t) => t.id.equals(next.id)))
+              .write(CachedMutationsCompanion(
+            attempts: Value(next.attempts + 1),
+            lastAttemptAt: Value(DateTime.now()),
+          ));
+        }
+      }
+    } finally {
+      _running = false;
+    }
+  }
+
+  bool _isTransient(DioException e) {
+    switch (e.type) {
+      case DioExceptionType.connectionError:
+      case DioExceptionType.connectionTimeout:
+      case DioExceptionType.sendTimeout:
+      case DioExceptionType.receiveTimeout:
+        return true;
+      default:
+        return false;
+    }
+  }
+
+  void dispose() {
+    _disposed = true;
+    _initialTimer?.cancel();
+    _intervalTimer?.cancel();
+  }
+}
+
+final mutationReplayerProvider = Provider<MutationReplayer>((ref) {
+  final r = MutationReplayer(ref);
+  ref.onDispose(r.dispose);
+  r.start();
+  return r;
+});
+
+/// Type signature for kind-specific replay handlers.
+typedef _Handler = Future<void> Function(Ref, Map<String, dynamic>);
+
+/// Kind → handler dispatch. Each handler decodes its payload and
+/// re-fires the original REST call. Throws on failure (caught by the
+/// replayer's drain loop above).
+///
+/// Payload shapes (see also enqueue call sites for the writer side):
+/// * like.add / like.remove: {'kind': 'track'|'album'|'artist', 'id': uuid}
+/// * quarantine.flag: {'trackId': uuid, 'reason': str, 'notes': str}
+/// * quarantine.unflag: {'trackId': uuid}
+/// * playlist.append: {'playlistId': uuid, 'trackIds': [uuid, …]}
+/// * request.create: {full createRequest args; see DiscoverApi}
+/// * request.cancel: {'id': uuid}
+/// * play.offline: {'trackId': uuid, 'clientId': str, 'at': iso8601,
+///   'durationPlayedMs': int, 'source'?: 'for_you'|'discover'}
+final Map<String, _Handler> _handlers = {
+  MutationKinds.likeAdd: (ref, p) async {
+    final api = await ref.read(likesApiProvider.future);
+    await api.like(_likeKindFromString(p['kind'] as String), p['id'] as String);
+  },
+  MutationKinds.likeRemove: (ref, p) async {
+    final api = await ref.read(likesApiProvider.future);
+    await api.unlike(
+        _likeKindFromString(p['kind'] as String), p['id'] as String);
+  },
+  MutationKinds.quarantineFlag: (ref, p) async {
+    final api = await ref.read(quarantineApiProvider.future);
+    await api.flag(
+      p['trackId'] as String,
+      p['reason'] as String,
+      notes: (p['notes'] as String?) ?? '',
+    );
+  },
+  MutationKinds.quarantineUnflag: (ref, p) async {
+    final api = await ref.read(quarantineApiProvider.future);
+    await api.unflag(p['trackId'] as String);
+  },
+  MutationKinds.playlistAppend: (ref, p) async {
+    final api = await ref.read(playlistsApiProvider.future);
+    final ids = (p['trackIds'] as List).cast<String>();
+    await api.appendTracks(p['playlistId'] as String, ids);
+  },
+  MutationKinds.requestCreate: (ref, p) async {
+    final dio = await ref.read(dioProvider.future);
+    final api = DiscoverApi(dio);
+    await api.createRequest(
+      kind: _lidarrKindFromString(p['kind'] as String),
+      artistMbid: p['artistMbid'] as String,
+      artistName: p['artistName'] as String,
+      albumMbid: p['albumMbid'] as String?,
+      albumTitle: p['albumTitle'] as String?,
+      trackMbid: p['trackMbid'] as String?,
+      trackTitle: p['trackTitle'] as String?,
+    );
+  },
+  MutationKinds.requestCancel: (ref, p) async {
+    final api = await ref.read(requestsApiProvider.future);
+    await api.cancel(p['id'] as String);
+  },
+  MutationKinds.playOffline: (ref, p) async {
+    final dio = await ref.read(dioProvider.future);
+    final api = EventsApi(dio);
+    await api.playOffline(
+      trackId: p['trackId'] as String,
+      clientId: p['clientId'] as String,
+      atIso: p['at'] as String,
+      durationPlayedMs: (p['durationPlayedMs'] as num).toInt(),
+      source: p['source'] as String?,
+    );
+  },
+};
+
+LikeKind _likeKindFromString(String s) => switch (s) {
+      'album' => LikeKind.album,
+      'artist' => LikeKind.artist,
+      _ => LikeKind.track,
+    };
+
+LidarrRequestKind _lidarrKindFromString(String s) => switch (s) {
+      'album' => LidarrRequestKind.album,
+      'track' => LidarrRequestKind.track,
+      _ => LidarrRequestKind.artist,
+    };

flutter_client/lib/cache/offline_provider.dart

@@ -0,0 +1,105 @@
+// Reachability-based offline marker (#427 S1).
+//
+// `connectivityProvider` only knows whether a network *interface* is
+// up — not whether the Minstrel server is actually reachable (captive
+// portals, server down, DNS, VPN-only routes all read "online"). This
+// is the single source of truth other features gate on: offline =
+// the server failed its /healthz probe N times in a row; recovery on
+// the first success.
+//
+// Deliberately NOT coupled to connectivityProvider: subscribing to
+// that StreamProvider eagerly mounts its 2s checkConnectivity timeout
+// and leaks a pending Timer through widget tests that never reach the
+// auth state (the bug fixed for MutationReplayer). /healthz failing
+// already covers interface-down — it just fails the probe.
+//
+// Optimistic: assume online until proven offline, so a cold launch
+// behaves normally and only flips after sustained unreachability.
+
+import 'dart:async';
+
+import 'package:dio/dio.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../api/endpoints/health.dart';
+import '../library/library_providers.dart' show dioProvider;
+
+class OfflineMonitor extends Notifier<bool> {
+  Timer? _initial;
+  Timer? _periodic;
+  int _consecutiveFails = 0;
+
+  /// Consecutive failed probes before we declare offline. Small
+  /// enough to react within ~half a minute, large enough that a
+  /// single dropped request doesn't flip the whole UI.
+  static const _threshold = 3;
+
+  /// Probe cadence. Slower when believed-online (cheap heartbeat);
+  /// faster when offline so recovery is noticed quickly.
+  static const _onlineInterval = Duration(seconds: 30);
+  static const _offlineInterval = Duration(seconds: 10);
+
+  /// Let auth + server-url + dio providers finish async warmup
+  /// before the first probe so a cold start doesn't false-positive.
+  static const _initialDelay = Duration(seconds: 5);
+
+  @override
+  bool build() {
+    ref.onDispose(() {
+      _initial?.cancel();
+      _periodic?.cancel();
+    });
+    _initial = Timer(_initialDelay, () {
+      _check();
+      _arm();
+    });
+    return false; // optimistic until a probe says otherwise
+  }
+
+  void _arm() {
+    _periodic?.cancel();
+    _periodic = Timer.periodic(
+      state ? _offlineInterval : _onlineInterval,
+      (_) => _check(),
+    );
+  }
+
+  Future<void> _check() async {
+    final Dio dio;
+    try {
+      // Not configured yet (no server URL) → don't flip; the app is
+      // still on the connect screen and "offline" is meaningless.
+      dio = await ref.read(dioProvider.future);
+    } catch (_) {
+      return;
+    }
+    try {
+      // dio's own connect/receive timeouts bound this — no extra
+      // Timer (which would leak in widget tests).
+      await HealthApi(dio).check();
+      _consecutiveFails = 0;
+      _set(false);
+    } catch (_) {
+      _consecutiveFails++;
+      if (_consecutiveFails >= _threshold) {
+        _set(true);
+      }
+    }
+  }
+
+  void _set(bool offline) {
+    if (state == offline) return;
+    state = offline;
+    _arm(); // cadence follows the new state
+  }
+
+  /// Force an immediate probe — e.g. a user-initiated retry. Public
+  /// so S4's offline surfaces can offer a "try again" affordance.
+  Future<void> recheck() => _check();
+}
+
+/// `true` when the server is unreachable. Watch this to gate
+/// online-only affordances; read it once at app start to activate
+/// the poller.
+final offlineProvider =
+    NotifierProvider<OfflineMonitor, bool>(OfflineMonitor.new);

flutter_client/lib/cache/prefetcher.dart

@@ -0,0 +1,108 @@
+import 'dart:async';
+
+import 'package:audio_service/audio_service.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../likes/likes_provider.dart' show likedIdsProvider;
+import '../player/album_color_extractor.dart';
+import '../player/player_provider.dart';
+import 'audio_cache_manager.dart';
+import 'cache_settings_provider.dart';
+import 'db.dart';
+
+/// Listens to the player's currently-playing track. When it changes,
+/// computes the next-N tracks ahead in the queue and pins them via
+/// AudioCacheManager (source: autoPrefetch). After pinning, runs an
+/// eviction pass against the operator-set cap.
+///
+/// The window N comes from cacheSettingsProvider.prefetchWindow
+/// (default 5, configurable in Settings).
+class Prefetcher {
+  Prefetcher(this._ref) {
+    // The mediaItem stream changes whenever the active track changes
+    // (skipNext/skipPrev or natural progression). Settings changes (e.g.
+    // operator bumps prefetch window) also trigger a reconcile.
+    _ref.listen<AsyncValue<MediaItem?>>(mediaItemProvider, (_, __) => _reconcile());
+    _ref.listen<AsyncValue<CacheSettings>>(cacheSettingsProvider, (_, __) => _reconcile());
+  }
+
+  final Ref _ref;
+
+  Future<void> _reconcile() async {
+    final settings = _ref.read(cacheSettingsProvider).value;
+    if (settings == null) return;
+
+    final queue = _ref.read(queueProvider).value ?? const <MediaItem>[];
+    final current = _ref.read(mediaItemProvider).value;
+    if (queue.isEmpty || current == null) return;
+
+    final currentIdx = queue.indexWhere((m) => m.id == current.id);
+    if (currentIdx < 0) return;
+
+    final endIdx =
+        (currentIdx + settings.prefetchWindow).clamp(0, queue.length - 1);
+
+    final mgr = _ref.read(audioCacheManagerProvider);
+    final coverCache = _ref.read(albumCoverCacheProvider);
+    final colorCache = _ref.read(albumColorCacheProvider);
+
+    // Walk the window. For each upcoming track we want THREE things
+    // ready when the player transitions into it:
+    //
+    //   1. Audio file on disk (otherwise playback stalls on stream
+    //      load — the original prefetcher concern).
+    //   2. Cover bytes on disk under AlbumCoverCache (otherwise
+    //      _toMediaItem's peekCached returns null, mediaItem
+    //      broadcasts with artUri=null, and the now-playing screen
+    //      stalls in _scheduleSwap awaiting precacheImage of a file
+    //      that doesn't exist yet).
+    //   3. Palette color extracted and memoized in AlbumColorCache
+    //      (otherwise the gradient backdrop has to wait for
+    //      PaletteGenerator to run after the cover lands —
+    //      visible as the cover snapping in before the gradient).
+    //
+    // Each call is idempotent (cache-aware): if already cached, it's
+    // a no-op. Everything fire-and-forget so the reconcile completes
+    // quickly even on a fresh queue.
+    for (var i = currentIdx; i <= endIdx; i++) {
+      final media = queue[i];
+      final trackId = media.id;
+      final albumId = media.extras?['album_id'] as String?;
+
+      if (!await mgr.isCached(trackId)) {
+        // ignore: unawaited_futures
+        mgr.pin(trackId, source: CacheSource.autoPrefetch);
+      }
+
+      if (albumId != null && albumId.isNotEmpty) {
+        // Cover bytes: getOrFetch returns the file path; the side
+        // effect (writing to disk) is what we care about.
+        // ignore: unawaited_futures
+        coverCache.getOrFetch(albumId);
+        // Palette: getOrExtract chains off coverCache.getOrFetch so
+        // it'll wait for the cover before sampling — safe to call
+        // in parallel here.
+        // ignore: unawaited_futures
+        colorCache.getOrExtract(albumId);
+      }
+    }
+
+    // Eviction pass after pinning new files. Per-bucket (#427 S2):
+    // liked-ness decides the bucket, so a track that's both liked
+    // and recently played is protected by the Liked cap, not the
+    // rolling LRU.
+    final liked =
+        _ref.read(likedIdsProvider).value?.tracks ?? const <String>{};
+    await mgr.evictBuckets(
+      likedCap: settings.likedCapBytes,
+      rollingCap: settings.rollingCapBytes,
+      liked: liked,
+    );
+  }
+}
+
+/// Read this provider once at app start to activate the prefetcher.
+/// Constructor wires the listeners.
+final prefetcherProvider = Provider<Prefetcher>((ref) {
+  return Prefetcher(ref);
+});

flutter_client/lib/cache/shuffle_source.dart

@@ -0,0 +1,104 @@
+// Offline play sources over the local cache index (#427 S4).
+//
+// "Shuffle all" is always-present and degrades with reachability:
+//   online  → GET /api/library/shuffle (random over the whole library)
+//   offline → a client shuffle over the entire local cache index
+//
+// Offline-only pools surfaced on Home beside the (disabled) system
+// playlists: "Recently played" (cache by lastPlayedAt desc) and
+// "Liked" (cache ∩ liked set). All of these are UNIONs over the
+// cache regardless of storage bucket — liked AND recently-played
+// both included. The two-bucket split (S2) is storage/eviction-only
+// and never filters playback, which is exactly what this relies on.
+
+import 'dart:math';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../library/library_providers.dart' show libraryApiProvider;
+import '../likes/likes_provider.dart' show likedIdsProvider;
+import '../models/track.dart';
+import 'adapters.dart';
+import 'audio_cache_manager.dart' show appDbProvider;
+import 'offline_provider.dart';
+
+class ShuffleSource {
+  ShuffleSource(this._ref);
+  final Ref _ref;
+
+  /// Shuffle-all. Online: server-random. Offline: every cached
+  /// track, shuffled. Empty offline → nothing cached yet.
+  Future<List<TrackRef>> tracks({int limit = 100}) async {
+    if (_ref.read(offlineProvider)) {
+      final ids = await _cachedIdsByRecency();
+      final list = await _refs(ids);
+      list.shuffle(Random());
+      return list.length > limit ? list.sublist(0, limit) : list;
+    }
+    final api = await _ref.read(libraryApiProvider.future);
+    return api.shuffle(limit: limit);
+  }
+
+  /// Cached tracks, most-recently-played first (liked included).
+  /// Cache-only — surfaced on Home only when offline.
+  Future<List<TrackRef>> recentlyPlayed({int limit = 100}) async {
+    final ids = await _cachedIdsByRecency();
+    final list = await _refs(ids);
+    return list.length > limit ? list.sublist(0, limit) : list;
+  }
+
+  /// Cached tracks that are in the user's liked set. Cache-only —
+  /// surfaced on Home only when offline.
+  Future<List<TrackRef>> liked({int limit = 100}) async {
+    final likedSet =
+        _ref.read(likedIdsProvider).value?.tracks ?? const <String>{};
+    final ids =
+        (await _cachedIdsByRecency()).where(likedSet.contains).toList();
+    final list = await _refs(ids);
+    return list.length > limit ? list.sublist(0, limit) : list;
+  }
+
+  /// Cached track ids ordered by lastPlayedAt desc (nulls last so
+  /// never-touched downloads sort after real plays).
+  Future<List<String>> _cachedIdsByRecency() async {
+    final db = _ref.read(appDbProvider);
+    final rows = await db.select(db.audioCacheIndex).get();
+    rows.sort((a, b) {
+      final av = a.lastPlayedAt, bv = b.lastPlayedAt;
+      if (av == null && bv == null) return 0;
+      if (av == null) return 1;
+      if (bv == null) return -1;
+      return bv.compareTo(av);
+    });
+    return rows.map((r) => r.trackId).toList();
+  }
+
+  /// Materializes ordered track ids into TrackRefs from the cached
+  /// metadata tables, preserving the given order.
+  Future<List<TrackRef>> _refs(List<String> orderedIds) async {
+    if (orderedIds.isEmpty) return const [];
+    final db = _ref.read(appDbProvider);
+    final meta = await (db.select(db.cachedTracks)
+          ..where((t) => t.id.isIn(orderedIds)))
+        .get();
+    if (meta.isEmpty) return const [];
+    final byId = {for (final t in meta) t.id: t};
+    final artistName = {
+      for (final a in await db.select(db.cachedArtists).get()) a.id: a.name
+    };
+    final albumTitle = {
+      for (final a in await db.select(db.cachedAlbums).get()) a.id: a.title
+    };
+    return [
+      for (final id in orderedIds)
+        if (byId[id] case final t?)
+          t.toRef(
+            artistName: artistName[t.artistId] ?? '',
+            albumTitle: albumTitle[t.albumId] ?? '',
+          )
+    ];
+  }
+}
+
+final shuffleSourceProvider =
+    Provider<ShuffleSource>((ref) => ShuffleSource(ref));

flutter_client/lib/cache/sync_controller.dart

@@ -0,0 +1,360 @@
+import 'dart:async';
+
+import 'package:drift/drift.dart' as drift;
+import 'package:flutter_cache_manager/flutter_cache_manager.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../auth/auth_provider.dart' show serverUrlProvider, sessionTokenProvider;
+import '../library/library_providers.dart' show dioProvider;
+import 'audio_cache_manager.dart' show appDbProvider;
+import 'db.dart';
+
+/// Counts returned from a sync operation. Surfaced to the operator-
+/// facing "Sync now" button + Settings card.
+class SyncResult {
+  const SyncResult({
+    required this.upserts,
+    required this.deletes,
+    required this.cursor,
+  });
+  final int upserts;
+  final int deletes;
+  final int cursor;
+}
+
+/// Drives the delta-sync against the server (#357 Plan A endpoint).
+/// Reads cursor from drift, calls `/api/library/sync?since={cursor}`,
+/// applies upserts + deletes, advances cursor.
+class SyncController extends AsyncNotifier<SyncResult?> {
+  @override
+  Future<SyncResult?> build() async => null;
+
+  Future<SyncResult?> sync() async {
+    state = const AsyncLoading();
+    try {
+      final db = ref.read(appDbProvider);
+      final dio = await ref.read(dioProvider.future);
+
+      final meta = await db.select(db.syncMetadata).getSingleOrNull();
+      final cursor = meta?.cursor ?? 0;
+
+      final resp = await dio.get<dynamic>(
+        '/api/library/sync',
+        queryParameters: {'since': cursor},
+      );
+
+      // 204 No Content — no changes since cursor.
+      if (resp.statusCode == 204) {
+        await db.into(db.syncMetadata).insertOnConflictUpdate(
+              SyncMetadataCompanion.insert(
+                lastSyncAt: drift.Value(DateTime.now()),
+              ),
+            );
+        final r = SyncResult(upserts: 0, deletes: 0, cursor: cursor);
+        state = AsyncData(r);
+        return r;
+      }
+
+      // 410 Gone — cursor too old, server has compacted past it. Reset
+      // local state and retry once with cursor=0.
+      if (resp.statusCode == 410) {
+        await db.transaction(() async {
+          await db.delete(db.cachedArtists).go();
+          await db.delete(db.cachedAlbums).go();
+          await db.delete(db.cachedTracks).go();
+          await db.delete(db.cachedLikes).go();
+          await db.delete(db.cachedPlaylists).go();
+          await db.delete(db.cachedPlaylistTracks).go();
+          await db.into(db.syncMetadata).insertOnConflictUpdate(
+                SyncMetadataCompanion.insert(cursor: const drift.Value(0)),
+              );
+        });
+        return sync();
+      }
+
+      final body = resp.data as Map<String, dynamic>;
+      final newCursor = (body['cursor'] as num).toInt();
+      final upserts = body['upserts'] as Map<String, dynamic>? ?? {};
+      final deletes = body['deletes'] as Map<String, dynamic>? ?? {};
+
+      var upsertCount = 0;
+      var deleteCount = 0;
+      // IDs of upserted entities whose covers we'll pre-warm after the
+      // transaction commits. Filled inside the loops; consumed by
+      // _prewarmCovers fire-and-forget below. Artist covers are
+      // server-derived from "most-recent album" and aren't
+      // reconstructible client-side — album pre-warm already covers an
+      // artist's primary visual via its detail-page header.
+      final albumCoverIds = <String>[];
+      final playlistCoverIds = <String>[];
+
+      await db.transaction(() async {
+        // ---- Upserts ----
+        for (final a in (upserts['artist'] as List? ?? const [])) {
+          await db.into(db.cachedArtists).insertOnConflictUpdate(
+                _artistFromJson(a as Map<String, dynamic>),
+              );
+          upsertCount++;
+        }
+        for (final a in (upserts['album'] as List? ?? const [])) {
+          final m = a as Map<String, dynamic>;
+          await db.into(db.cachedAlbums).insertOnConflictUpdate(
+                _albumFromJson(m),
+              );
+          final id = m['id'];
+          if (id is String && id.isNotEmpty) albumCoverIds.add(id);
+          upsertCount++;
+        }
+        for (final t in (upserts['track'] as List? ?? const [])) {
+          await db.into(db.cachedTracks).insertOnConflictUpdate(
+                _trackFromJson(t as Map<String, dynamic>),
+              );
+          upsertCount++;
+        }
+        for (final l in (upserts['like_track'] as List? ?? const [])) {
+          final m = l as Map<String, dynamic>;
+          await db.into(db.cachedLikes).insertOnConflictUpdate(
+                CachedLikesCompanion.insert(
+                  userId: m['user_id'] as String,
+                  entityType: 'track',
+                  entityId: m['track_id'] as String,
+                ),
+              );
+          upsertCount++;
+        }
+        for (final l in (upserts['like_album'] as List? ?? const [])) {
+          final m = l as Map<String, dynamic>;
+          await db.into(db.cachedLikes).insertOnConflictUpdate(
+                CachedLikesCompanion.insert(
+                  userId: m['user_id'] as String,
+                  entityType: 'album',
+                  entityId: m['album_id'] as String,
+                ),
+              );
+          upsertCount++;
+        }
+        for (final l in (upserts['like_artist'] as List? ?? const [])) {
+          final m = l as Map<String, dynamic>;
+          await db.into(db.cachedLikes).insertOnConflictUpdate(
+                CachedLikesCompanion.insert(
+                  userId: m['user_id'] as String,
+                  entityType: 'artist',
+                  entityId: m['artist_id'] as String,
+                ),
+              );
+          upsertCount++;
+        }
+        for (final p in (upserts['playlist'] as List? ?? const [])) {
+          final m = p as Map<String, dynamic>;
+          await db.into(db.cachedPlaylists).insertOnConflictUpdate(
+                _playlistFromJson(m),
+              );
+          final id = m['id'];
+          if (id is String && id.isNotEmpty) playlistCoverIds.add(id);
+          upsertCount++;
+        }
+        for (final pt in (upserts['playlist_track'] as List? ?? const [])) {
+          final m = pt as Map<String, dynamic>;
+          await db.into(db.cachedPlaylistTracks).insertOnConflictUpdate(
+                CachedPlaylistTracksCompanion.insert(
+                  playlistId: m['playlist_id'] as String,
+                  trackId: m['track_id'] as String,
+                ),
+              );
+          upsertCount++;
+        }
+
+        // ---- Deletes ----
+        for (final id in (deletes['artist'] as List? ?? const [])) {
+          await (db.delete(db.cachedArtists)
+                ..where((t) => t.id.equals(id as String)))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['album'] as List? ?? const [])) {
+          await (db.delete(db.cachedAlbums)
+                ..where((t) => t.id.equals(id as String)))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['track'] as List? ?? const [])) {
+          await (db.delete(db.cachedTracks)
+                ..where((t) => t.id.equals(id as String)))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['like_track'] as List? ?? const [])) {
+          final parts = (id as String).split(':');
+          if (parts.length != 2) continue;
+          await (db.delete(db.cachedLikes)
+                ..where((t) =>
+                    t.userId.equals(parts[0]) &
+                    t.entityType.equals('track') &
+                    t.entityId.equals(parts[1])))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['like_album'] as List? ?? const [])) {
+          final parts = (id as String).split(':');
+          if (parts.length != 2) continue;
+          await (db.delete(db.cachedLikes)
+                ..where((t) =>
+                    t.userId.equals(parts[0]) &
+                    t.entityType.equals('album') &
+                    t.entityId.equals(parts[1])))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['like_artist'] as List? ?? const [])) {
+          final parts = (id as String).split(':');
+          if (parts.length != 2) continue;
+          await (db.delete(db.cachedLikes)
+                ..where((t) =>
+                    t.userId.equals(parts[0]) &
+                    t.entityType.equals('artist') &
+                    t.entityId.equals(parts[1])))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['playlist'] as List? ?? const [])) {
+          await (db.delete(db.cachedPlaylists)
+                ..where((t) => t.id.equals(id as String)))
+              .go();
+          deleteCount++;
+        }
+        for (final id in (deletes['playlist_track'] as List? ?? const [])) {
+          final parts = (id as String).split(':');
+          if (parts.length != 2) continue;
+          await (db.delete(db.cachedPlaylistTracks)
+                ..where((t) =>
+                    t.playlistId.equals(parts[0]) &
+                    t.trackId.equals(parts[1])))
+              .go();
+          deleteCount++;
+        }
+
+        // ---- Cursor + lastSyncAt ----
+        await db.into(db.syncMetadata).insertOnConflictUpdate(
+              SyncMetadataCompanion.insert(
+                cursor: drift.Value(newCursor),
+                lastSyncAt: drift.Value(DateTime.now()),
+              ),
+            );
+      });
+
+      // Fire-and-forget cover pre-warm so a cold-start scroll through
+      // the home grid paints from disk on the very first frame instead
+      // of firing one HTTP request per visible tile. Unawaited because
+      // the sync's "done" signal should fire as soon as the metadata
+      // delta is durable; cover downloads can finish in the background.
+      if (albumCoverIds.isNotEmpty || playlistCoverIds.isNotEmpty) {
+        unawaited(_prewarmCovers(albumCoverIds, playlistCoverIds));
+      }
+
+      final result = SyncResult(
+        upserts: upsertCount,
+        deletes: deleteCount,
+        cursor: newCursor,
+      );
+      state = AsyncData(result);
+      return result;
+    } catch (e, st) {
+      state = AsyncError(e, st);
+      return null;
+    }
+  }
+
+  /// Downloads cover bytes for each id into the shared flutter_cache_
+  /// manager disk cache that cached_network_image reads from.
+  /// Best-effort: per-URL failures (404 collage-not-built-yet, 401
+  /// during a token refresh race, network blip) are swallowed so one
+  /// missing cover doesn't abort the rest.
+  ///
+  /// Concurrency 3 balances disk-warming throughput against starving
+  /// foreground UI work — covers are ~30-200KB each, so three in
+  /// flight saturates most LAN connections without pinning the radio.
+  Future<void> _prewarmCovers(
+    List<String> albumIds,
+    List<String> playlistIds,
+  ) async {
+    final baseUrl = await ref.read(serverUrlProvider.future);
+    if (baseUrl == null || baseUrl.isEmpty) return;
+    final token = await ref.read(sessionTokenProvider.future);
+    final headers = (token != null && token.isNotEmpty)
+        ? {'Authorization': 'Bearer $token'}
+        : <String, String>{};
+    final base =
+        baseUrl.endsWith('/') ? baseUrl.substring(0, baseUrl.length - 1) : baseUrl;
+    final urls = <String>[
+      for (final id in albumIds) '$base/api/albums/$id/cover',
+      for (final id in playlistIds) '$base/api/playlists/$id/cover',
+    ];
+    final mgr = DefaultCacheManager();
+    var index = 0;
+    Future<void> worker() async {
+      while (index < urls.length) {
+        final i = index++;
+        try {
+          await mgr.downloadFile(urls[i], authHeaders: headers);
+        } catch (_) {
+          // Best-effort prewarm — failures are expected for system
+          // playlists whose collage hasn't been built yet, and for
+          // any transient auth race. Don't surface or abort.
+        }
+      }
+    }
+
+    await Future.wait(List.generate(3, (_) => worker()));
+  }
+
+  CachedArtistsCompanion _artistFromJson(Map<String, dynamic> j) =>
+      CachedArtistsCompanion.insert(
+        id: j['id'] as String,
+        name: (j['name'] as String?) ?? '',
+        sortName: (j['sort_name'] as String?) ?? '',
+        mbid: drift.Value(j['mbid'] as String?),
+        artistThumbPath: drift.Value(j['artist_thumb_path'] as String?),
+        artistFanartPath: drift.Value(j['artist_fanart_path'] as String?),
+      );
+
+  CachedAlbumsCompanion _albumFromJson(Map<String, dynamic> j) =>
+      CachedAlbumsCompanion.insert(
+        id: j['id'] as String,
+        artistId: j['artist_id'] as String,
+        title: (j['title'] as String?) ?? '',
+        sortTitle: (j['sort_title'] as String?) ?? '',
+        releaseDate: drift.Value(j['release_date'] as String?),
+        coverPath: drift.Value(j['cover_art_path'] as String?),
+        mbid: drift.Value(j['mbid'] as String?),
+      );
+
+  CachedTracksCompanion _trackFromJson(Map<String, dynamic> j) =>
+      CachedTracksCompanion.insert(
+        id: j['id'] as String,
+        albumId: j['album_id'] as String,
+        artistId: j['artist_id'] as String,
+        title: (j['title'] as String?) ?? '',
+        durationMs: drift.Value((j['duration_ms'] as num?)?.toInt() ?? 0),
+        trackNumber: drift.Value((j['track_number'] as num?)?.toInt()),
+        discNumber: drift.Value((j['disc_number'] as num?)?.toInt()),
+        filePath: drift.Value(j['file_path'] as String?),
+        fileFormat: drift.Value(j['file_format'] as String?),
+        genre: drift.Value(j['genre'] as String?),
+      );
+
+  CachedPlaylistsCompanion _playlistFromJson(Map<String, dynamic> j) =>
+      CachedPlaylistsCompanion.insert(
+        id: j['id'] as String,
+        userId: j['user_id'] as String,
+        name: (j['name'] as String?) ?? '',
+        description: drift.Value((j['description'] as String?) ?? ''),
+        isPublic: drift.Value((j['is_public'] as bool?) ?? false),
+        coverPath: drift.Value(j['cover_path'] as String?),
+        trackCount: drift.Value((j['track_count'] as num?)?.toInt() ?? 0),
+        durationSec: drift.Value((j['duration_sec'] as num?)?.toInt() ?? 0),
+        systemVariant: drift.Value(j['system_variant'] as String?),
+      );
+}
+
+final syncControllerProvider =
+    AsyncNotifierProvider<SyncController, SyncResult?>(SyncController.new);

flutter_client/lib/cache/tile_providers.dart

@@ -0,0 +1,144 @@
+// Per-entity tile providers for the per-item rendering architecture
+// (see docs/superpowers/specs/2026-05-13-per-item-rendering-design.md).
+//
+// Each provider is a StreamProvider.family<EntityRef?, String> keyed
+// by entity id. The stream:
+//   1. Watches the entity's drift row
+//   2. Yields the populated row on every emission
+//   3. Yields null while the row is absent (UI shows skeleton)
+//   4. On the first missing-row emission, enqueues a hydration via
+//      HydrationQueue so the row eventually lands
+//
+// The tile widget reacts to AsyncValue<EntityRef?>:
+//   - loading or data:null → skeleton
+//   - data:non-null        → real card
+//   - error                → error placeholder
+//
+// Subscriptions are per-tile. A 50-tile home screen creates 50 drift
+// 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';
+
+import '../cache/adapters.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../models/album.dart';
+import '../models/artist.dart';
+import '../models/track.dart';
+import 'hydration_queue.dart';
+
+/// Watches the cached_albums row for [id]. Triggers background
+/// hydration on miss; yields the row once it lands.
+final albumTileProvider =
+    StreamProvider.family<AlbumRef?, String>((ref, id) async* {
+  if (id.isEmpty) {
+    yield null;
+    return;
+  }
+  final db = ref.watch(appDbProvider);
+  final query = (db.select(db.cachedAlbums)..where((t) => t.id.equals(id)))
+      .join([
+    leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedAlbums.artistId)),
+  ]);
+  var enqueued = false;
+  await for (final rows in query.watch()) {
+    if (rows.isEmpty) {
+      if (!enqueued) {
+        enqueued = true;
+        ref
+            .read(hydrationQueueProvider)
+            .enqueue(entityType: 'album', entityId: id);
+      }
+      yield null;
+      continue;
+    }
+    final r = rows.first;
+    final album = r.readTable(db.cachedAlbums);
+    final artist = r.readTableOrNull(db.cachedArtists);
+    yield album.toRef(artistName: artist?.name ?? '');
+  }
+});
+
+/// 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) {
+    yield null;
+    return;
+  }
+  final db = ref.watch(appDbProvider);
+  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) {
+      if (!enqueued) {
+        enqueued = true;
+        ref
+            .read(hydrationQueueProvider)
+            .enqueue(entityType: 'artist', entityId: id);
+      }
+      yield null;
+      continue;
+    }
+    // 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 ?? '');
+  }
+});
+
+/// Watches the cached_tracks row for [id]. Triggers background
+/// hydration on miss; yields the row once it lands.
+final trackTileProvider =
+    StreamProvider.family<TrackRef?, String>((ref, id) async* {
+  if (id.isEmpty) {
+    yield null;
+    return;
+  }
+  final db = ref.watch(appDbProvider);
+  final query = (db.select(db.cachedTracks)..where((t) => t.id.equals(id)))
+      .join([
+    leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedTracks.artistId)),
+    leftOuterJoin(db.cachedAlbums,
+        db.cachedAlbums.id.equalsExp(db.cachedTracks.albumId)),
+  ]);
+  var enqueued = false;
+  await for (final rows in query.watch()) {
+    if (rows.isEmpty) {
+      if (!enqueued) {
+        enqueued = true;
+        ref
+            .read(hydrationQueueProvider)
+            .enqueue(entityType: 'track', entityId: id);
+      }
+      yield null;
+      continue;
+    }
+    final r = rows.first;
+    final t = r.readTable(db.cachedTracks);
+    final a = r.readTableOrNull(db.cachedArtists);
+    final al = r.readTableOrNull(db.cachedAlbums);
+    yield t.toRef(
+      artistName: a?.name ?? '',
+      albumTitle: al?.title ?? '',
+    );
+  }
+});

flutter_client/lib/discover/discover_screen.dart

@@ -1,3 +1,4 @@
+import 'package:cached_network_image/cached_network_image.dart';
 import 'package:dio/dio.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
@@ -5,6 +6,7 @@ import 'package:go_router/go_router.dart';
 
 import '../api/endpoints/discover.dart';
 import '../api/errors.dart';
+import '../cache/mutation_queue.dart';
 import '../library/library_providers.dart' show dioProvider;
 import '../models/lidarr.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
@@ -47,14 +49,23 @@ class _DiscoverScreenState extends ConsumerState<DiscoverScreen> {
 
   Future<void> _request(LidarrSearchResult row) async {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final args = {
+      'kind': _kind.wire,
+      'artistMbid':
+          _kind == LidarrRequestKind.artist ? row.mbid : row.artistMbid,
+      'artistName':
+          _kind == LidarrRequestKind.artist ? row.name : row.secondaryText,
+      'albumMbid': _kind == LidarrRequestKind.album ? row.mbid : null,
+      'albumTitle': _kind == LidarrRequestKind.album ? row.name : null,
+    };
     try {
       final api = await ref.read(_discoverApiProvider.future);
       await api.createRequest(
         kind: _kind,
-        artistMbid: _kind == LidarrRequestKind.artist ? row.mbid : row.artistMbid,
-        artistName: _kind == LidarrRequestKind.artist ? row.name : row.secondaryText,
-        albumMbid: _kind == LidarrRequestKind.album ? row.mbid : null,
-        albumTitle: _kind == LidarrRequestKind.album ? row.name : null,
+        artistMbid: args['artistMbid'] as String,
+        artistName: args['artistName'] as String,
+        albumMbid: args['albumMbid'],
+        albumTitle: args['albumTitle'],
       );
       if (mounted) {
         ScaffoldMessenger.of(context).showSnackBar(SnackBar(
@@ -64,12 +75,18 @@ class _DiscoverScreenState extends ConsumerState<DiscoverScreen> {
         // Re-run search to refresh the `requested` flag on the row.
         _runSearch();
       }
-    } on DioException catch (e) {
+    } on DioException catch (_) {
+      // Queue for replay so the user's request persists across
+      // network loss. We don't have a drift table for in-flight
+      // requests yet, so the row won't show on the Requests screen
+      // until replay succeeds — accept that for v1.
+      await ref
+          .read(mutationQueueProvider)
+          .enqueue(MutationKinds.requestCreate, args);
       if (mounted) {
-        final code = ApiError.fromDio(e).code;
         ScaffoldMessenger.of(context).showSnackBar(SnackBar(
-          content: Text('Request failed: $code'),
-          backgroundColor: fs.error,
+          content: Text('Request queued: ${row.name}'),
+          backgroundColor: fs.iron,
         ));
       }
     }
@@ -162,8 +179,9 @@ class _DiscoverScreenState extends ConsumerState<DiscoverScreen> {
                     final rows = snap.data ?? const [];
                     if (rows.isEmpty) {
                       return Center(
-                        child: Text('No matches.',
-                            style: TextStyle(color: fs.ash)),
+                        child: Text('Nothing to add for that search yet.',
+                            style: TextStyle(color: fs.ash),
+                            textAlign: TextAlign.center),
                       );
                     }
                     return ListView.separated(
@@ -203,9 +221,14 @@ class _ResultTile extends StatelessWidget {
             color: fs.slate,
             child: row.imageUrl.isEmpty
                 ? Icon(Icons.album, color: fs.ash)
-                : Image.network(row.imageUrl, fit: BoxFit.cover,
-                    errorBuilder: (_, __, ___) =>
-                        Icon(Icons.album, color: fs.ash)),
+                : CachedNetworkImage(
+                    imageUrl: row.imageUrl,
+                    fit: BoxFit.cover,
+                    fadeInDuration: const Duration(milliseconds: 120),
+                    fadeOutDuration: Duration.zero,
+                    errorWidget: (_, __, ___) =>
+                        Icon(Icons.album, color: fs.ash),
+                  ),
           ),
         ),
         const SizedBox(width: 12),

flutter_client/lib/library/album_detail_screen.dart

@@ -2,30 +2,103 @@ import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../api/endpoints/likes.dart';
+import '../models/album.dart';
 import '../likes/like_button.dart';
 import '../player/player_provider.dart';
+import '../shared/widgets/server_image.dart';
 import '../theme/theme_extension.dart';
 import 'library_providers.dart';
 import 'widgets/track_row.dart';
 
 class AlbumDetailScreen extends ConsumerWidget {
-  const AlbumDetailScreen({required this.id, super.key});
+  const AlbumDetailScreen({required this.id, this.seed, super.key});
   final String id;
 
+  /// Optional album reference passed by the caller (typically the
+  /// tile they tapped) so the header can render immediately while
+  /// the full provider loads tracks. Hydration only — provider data
+  /// still wins once it arrives.
+  final AlbumRef? seed;
+
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final live = ref.watch(albumProvider(id));
+
+    // Pick the best header info available: live data > seed > nothing.
+    final headerTitle = live.value?.album.title.isNotEmpty == true
+        ? live.value!.album.title
+        : seed?.title ?? '';
+    final headerArtist = live.value?.album.artistName.isNotEmpty == true
+        ? live.value!.album.artistName
+        : seed?.artistName ?? '';
+
+    Widget header() => Padding(
+          padding: const EdgeInsets.all(16),
+          child: Row(children: [
+            ClipRRect(
+              borderRadius: BorderRadius.circular(6),
+              child: SizedBox(
+                width: 96,
+                height: 96,
+                child: ServerImage(
+                  url: '/api/albums/$id/cover',
+                  fit: BoxFit.cover,
+                  fallback: Container(color: fs.slate),
+                ),
+              ),
+            ),
+            const SizedBox(width: 16),
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Text(
+                    headerTitle,
+                    style: TextStyle(
+                      color: fs.parchment,
+                      fontFamily: fs.display.fontFamily,
+                      fontSize: 22,
+                    ),
+                  ),
+                  if (headerArtist.isNotEmpty)
+                    Text(headerArtist, style: TextStyle(color: fs.ash)),
+                ],
+              ),
+            ),
+          ]),
+        );
+
     return Scaffold(
       appBar: AppBar(),
       backgroundColor: fs.obsidian,
-      body: ref.watch(albumProvider(id)).when(
+      body: live.when(
             error: (e, _) => Center(child: Text('$e', style: TextStyle(color: fs.error))),
-            loading: () => const Center(child: CircularProgressIndicator()),
+            loading: () => seed != null
+                ? ListView(children: [
+                    header(),
+                    const Padding(
+                      padding: EdgeInsets.symmetric(vertical: 24),
+                      child: Center(child: CircularProgressIndicator()),
+                    ),
+                  ])
+                : const Center(child: CircularProgressIndicator()),
             data: (r) => ListView(children: [
               Padding(
                 padding: const EdgeInsets.all(16),
                 child: Row(children: [
-                  Container(width: 96, height: 96, color: fs.slate),
+                  ClipRRect(
+                    borderRadius: BorderRadius.circular(6),
+                    child: SizedBox(
+                      width: 96,
+                      height: 96,
+                      child: ServerImage(
+                        url: '/api/albums/$id/cover',
+                        fit: BoxFit.cover,
+                        fallback: Container(color: fs.slate),
+                      ),
+                    ),
+                  ),
                   const SizedBox(width: 16),
                   Expanded(child: Column(
                     crossAxisAlignment: CrossAxisAlignment.start,

flutter_client/lib/library/artist_detail_screen.dart

@@ -5,34 +5,75 @@ import 'package:go_router/go_router.dart';
 import '../api/endpoints/likes.dart';
 import '../likes/like_button.dart';
 import '../models/album.dart';
+import '../models/artist.dart';
 import '../player/player_provider.dart';
+import '../shared/widgets/server_image.dart';
 import '../theme/theme_extension.dart';
 import 'library_providers.dart';
 import 'widgets/album_card.dart';
 
 class ArtistDetailScreen extends ConsumerWidget {
-  const ArtistDetailScreen({required this.id, super.key});
+  const ArtistDetailScreen({required this.id, this.seed, super.key});
   final String id;
 
+  /// Optional artist reference from the caller. Lets the screen render
+  /// the name + avatar immediately while albums load.
+  final ArtistRef? seed;
+
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     final artist = ref.watch(artistProvider(id));
     final albums = ref.watch(artistAlbumsProvider(id));
 
+    // Resolve which artist info to render in the header. Live wins
+    // when present and populated; seed fills the gap during the
+    // first frame after navigation.
+    final liveArtist = artist.value;
+    final hasLiveName = liveArtist != null && liveArtist.name.isNotEmpty;
+    final effective = hasLiveName ? liveArtist : (seed ?? liveArtist);
+
     return Scaffold(
       appBar: AppBar(),
       backgroundColor: fs.obsidian,
       body: artist.when(
         error: (e, _) => Center(child: Text('$e', style: TextStyle(color: fs.error))),
-        loading: () => const Center(child: CircularProgressIndicator()),
-        data: (a) => ListView(children: [
+        // While loading: render header from seed if available so the
+        // page isn't blank.
+        loading: () => seed == null
+            ? const Center(child: CircularProgressIndicator())
+            : _artistBody(context, ref, seed!, albums, fs),
+        data: (_) => _artistBody(context, ref, effective ?? seed!, albums, fs),
+      ),
+    );
+  }
+
+  Widget _artistBody(
+    BuildContext context,
+    WidgetRef ref,
+    ArtistRef a,
+    AsyncValue<List<AlbumRef>> albums,
+    FabledSwordTheme fs,
+  ) =>
+      ListView(children: [
           Padding(
             padding: const EdgeInsets.all(16),
             child: Row(children: [
-              Container(
-                width: 96, height: 96,
-                decoration: BoxDecoration(color: fs.slate, shape: BoxShape.circle),
+              ClipOval(
+                child: SizedBox(
+                  width: 96,
+                  height: 96,
+                  // Server derives artist cover from a representative
+                  // album. Drift cache doesn't persist that pointer, so
+                  // mirror the trick client-side: reuse the first album
+                  // returned by artistAlbumsProvider. Falls back to
+                  // slate while albums are loading or empty.
+                  child: _ArtistAvatar(
+                    serverCoverUrl: a.coverUrl,
+                    albums: albums,
+                    fs: fs,
+                  ),
+                ),
               ),
               const SizedBox(width: 16),
               Expanded(
@@ -51,10 +92,31 @@ class ArtistDetailScreen extends ConsumerWidget {
                 child: IconButton(
                   icon: Icon(Icons.play_arrow, color: fs.parchment),
                   onPressed: () async {
-                    final tracks = await ref.read(artistTracksProvider(id).future);
-                    if (tracks.isEmpty) return;
-                    final shuffled = [...tracks]..shuffle();
-                    ref.read(playerActionsProvider).playTracks(shuffled);
+                    try {
+                      final tracks =
+                          await ref.read(artistTracksProvider(id).future);
+                      if (tracks.isEmpty) {
+                        if (context.mounted) {
+                          ScaffoldMessenger.of(context).showSnackBar(
+                            const SnackBar(
+                                content: Text(
+                                    'No tracks found for this artist yet.')),
+                          );
+                        }
+                        return;
+                      }
+                      final shuffled = [...tracks]..shuffle();
+                      await ref
+                          .read(playerActionsProvider)
+                          .playTracks(shuffled);
+                    } catch (e) {
+                      debugPrint('artist_detail: play failed: $e');
+                      if (context.mounted) {
+                        ScaffoldMessenger.of(context).showSnackBar(
+                          SnackBar(content: Text("Couldn't start playback: $e")),
+                        );
+                      }
+                    }
                   },
                 ),
               ),
@@ -68,23 +130,79 @@ class ArtistDetailScreen extends ConsumerWidget {
           albums.when(
             error: (e, _) => Center(child: Text('$e', style: TextStyle(color: fs.error))),
             loading: () => const Padding(padding: EdgeInsets.all(16), child: Center(child: CircularProgressIndicator())),
-            data: (list) => GridView.builder(
-              shrinkWrap: true,
-              physics: const NeverScrollableScrollPhysics(),
-              padding: const EdgeInsets.all(8),
-              gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
-                crossAxisCount: 2,
-                childAspectRatio: 0.8,
-              ),
-              itemCount: list.length,
-              itemBuilder: (_, i) {
-                final AlbumRef album = list[i];
-                return AlbumCard(album: album, onTap: () => context.push('/albums/${album.id}'));
-              },
-            ),
+            data: (list) {
+              return LayoutBuilder(builder: (ctx, constraints) {
+              const cols = 3;
+              const sidePad = 8.0;
+              const gap = 8.0;
+              final cellW =
+                  (constraints.maxWidth - sidePad * 2 - gap * (cols - 1)) /
+                      cols;
+              // Card content: cover (cellW - 16) + 8 + title (≤2 lines
+              // ≈ 36) + slack. Artist line is suppressed in this
+              // grid (showArtist: false) since the page header already
+              // names the artist. Slack is generous on purpose — line-
+              // height variations would otherwise overflow by 1px.
+              final cellH = (cellW - 16) + 8 + 36 + 8;
+              return GridView.builder(
+                shrinkWrap: true,
+                physics: const NeverScrollableScrollPhysics(),
+                padding: const EdgeInsets.fromLTRB(sidePad, 0, sidePad, 16),
+                gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
+                  crossAxisCount: cols,
+                  mainAxisExtent: cellH,
+                  mainAxisSpacing: gap,
+                  crossAxisSpacing: gap,
+                ),
+                itemCount: list.length,
+                itemBuilder: (_, i) {
+                  final AlbumRef album = list[i];
+                  return AlbumCard(
+                    album: album,
+                    width: cellW,
+                    titleMaxLines: 2,
+                    showArtist: false,
+                    onTap: () =>
+                        context.push('/albums/${album.id}', extra: album),
+                  );
+                },
+              );
+            });
+            },
           ),
-        ]),
-      ),
+        ]);
+}
+
+/// Renders the artist's avatar. Server-emitted coverUrl wins when
+/// non-empty; otherwise we mirror the server's "use the first album's
+/// cover" rule client-side via the loaded album list.
+class _ArtistAvatar extends StatelessWidget {
+  const _ArtistAvatar({
+    required this.serverCoverUrl,
+    required this.albums,
+    required this.fs,
+  });
+  final String serverCoverUrl;
+  final AsyncValue<List<AlbumRef>> albums;
+  final FabledSwordTheme fs;
+
+  @override
+  Widget build(BuildContext context) {
+    if (serverCoverUrl.isNotEmpty) {
+      return ServerImage(
+        url: serverCoverUrl,
+        fit: BoxFit.cover,
+        fallback: Container(color: fs.slate),
+      );
+    }
+    final firstId = albums.value?.isNotEmpty == true ? albums.value!.first.id : null;
+    if (firstId == null) {
+      return Container(color: fs.slate);
+    }
+    return ServerImage(
+      url: '/api/albums/$firstId/cover',
+      fit: BoxFit.cover,
+      fallback: Container(color: fs.slate),
     );
   }
 }

flutter_client/lib/library/home_screen.dart

@@ -4,25 +4,40 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 
 import '../api/errors.dart';
-import '../models/album.dart';
-import '../models/artist.dart';
+import '../cache/offline_provider.dart';
+import '../cache/shuffle_source.dart';
+import '../cache/tile_providers.dart';
+import '../models/playlist.dart';
+import '../models/system_playlists_status.dart';
 import '../models/track.dart';
 import '../player/player_provider.dart';
+import '../playlists/playlists_provider.dart';
+import '../playlists/widgets/playlist_card.dart';
+import '../playlists/widgets/playlist_placeholder_card.dart';
 import '../shared/widgets/connection_error_banner.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
+import '../shared/widgets/skeletons.dart';
 import '../theme/theme_extension.dart';
 import 'library_providers.dart';
 import 'widgets/album_card.dart';
 import 'widgets/artist_card.dart';
+import 'widgets/compact_track_card.dart';
 import 'widgets/horizontal_scroll_row.dart';
-import 'widgets/track_row.dart';
 
+/// Home screen. Per-item rendering: a tiny /api/home/index discovery
+/// fetch returns just section→IDs, then each tile hydrates itself
+/// against the per-entity drift tables (sync-populated) with REST
+/// fallback via the HydrationQueue. Cold-visit dead air shrinks to a
+/// single small round-trip; tiles materialize as their data lands.
 class HomeScreen extends ConsumerWidget {
   const HomeScreen({super.key});
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final index = ref.watch(homeIndexProvider);
+    final allPlaylists = ref.watch(playlistsListProvider('all'));
+    final status = ref.watch(systemPlaylistsStatusProvider);
     return Scaffold(
       backgroundColor: fs.obsidian,
       appBar: AppBar(
@@ -32,64 +47,562 @@ class HomeScreen extends ConsumerWidget {
         actions: const [MainAppBarActions(currentRoute: '/home')],
       ),
       body: SafeArea(
-        child: ref.watch(homeProvider).when(
-              error: (e, _) {
-                final code = e is DioException ? ApiError.fromDio(e).code : 'unknown';
-                if (code == 'connection_refused') {
-                  return ConnectionErrorBanner(
-                    onRetry: () => ref.refresh(homeProvider),
-                  );
-                }
-                return Center(child: Text('$e', style: TextStyle(color: fs.error)));
-              },
-              loading: () => const Center(child: CircularProgressIndicator()),
-              data: (h) => RefreshIndicator(
-                onRefresh: () async => ref.refresh(homeProvider.future),
-                child: ListView(children: [
-                  _albumsRow(context, 'Recently added',  h.recentlyAddedAlbums),
-                  _albumsRow(context, 'Rediscover',      h.rediscoverAlbums),
-                  _artistsRow(context, 'Rediscover artists', h.rediscoverArtists),
-                  _tracksRow(context, ref, 'Most played', h.mostPlayedTracks),
-                  _artistsRow(context, 'Last played artists', h.lastPlayedArtists),
-                  const SizedBox(height: 96),
-                ]),
-              ),
+        child: index.when(
+          error: (e, _) {
+            final code = e is DioException ? ApiError.fromDio(e).code : 'unknown';
+            if (code == 'connection_refused') {
+              return ConnectionErrorBanner(
+                onRetry: () => ref.refresh(homeIndexProvider),
+              );
+            }
+            return Center(child: Text('$e', style: TextStyle(color: fs.error)));
+          },
+          loading: () => _HomeSkeleton(fs: fs),
+          data: (h) => RefreshIndicator(
+            onRefresh: () async => ref.refresh(homeIndexProvider.future),
+            child: ListView(
+              physics: const ClampingScrollPhysics(),
+              children: [
+                _PlaylistsSection(
+                  playlists: allPlaylists.value?.owned ?? const [],
+                  status: status.value ?? SystemPlaylistsStatus.empty(),
+                  offline: ref.watch(offlineProvider),
+                ),
+                _RecentlyAddedSection(ids: h.recentlyAddedAlbums),
+                _RediscoverSection(
+                  albumIds: h.rediscoverAlbums,
+                  artistIds: h.rediscoverArtists,
+                ),
+                _MostPlayedSection(ids: h.mostPlayedTracks),
+                _LastPlayedSection(ids: h.lastPlayedArtists),
+                const SizedBox(height: 140),
+              ],
             ),
+          ),
+        ),
       ),
     );
   }
-
-  Widget _albumsRow(BuildContext ctx, String title, List<AlbumRef> albums) =>
-      HorizontalScrollRow(
-        title: title,
-        children: [
-          for (final a in albums)
-            AlbumCard(album: a, onTap: () => ctx.push('/albums/${a.id}')),
-        ],
-      );
-
-  Widget _artistsRow(BuildContext ctx, String title, List<ArtistRef> artists) =>
-      HorizontalScrollRow(
-        title: title,
-        children: [
-          for (final a in artists)
-            ArtistCard(artist: a, onTap: () => ctx.push('/artists/${a.id}')),
-        ],
-      );
-
-  Widget _tracksRow(BuildContext ctx, WidgetRef ref, String title, List<TrackRef> tracks) =>
-      HorizontalScrollRow(
-        title: title,
-        height: 64,
-        children: [
-          for (final t in tracks)
-            SizedBox(
-              width: 280,
-              child: TrackRow(
-                track: t,
-                onTap: () => ref.read(playerActionsProvider).playTracks([t]),
-              ),
-            ),
-        ],
-      );
+}
+
+// ─── Per-tile widgets ────────────────────────────────────────────────
+
+/// Duration of the skeleton→content cross-fade. 220ms reads as "tile
+/// settled into place" — longer drags, shorter feels like a hard cut.
+/// Each tile cross-fades independently when its data lands, so the
+/// natural cascade from the hydration queue's bounded concurrency
+/// produces a staged-reveal feel without any per-tile delay math.
+const Duration _tileRevealDuration = Duration(milliseconds: 220);
+
+/// Album tile: skeleton until albumTileProvider yields a populated row.
+class _AlbumTile extends ConsumerWidget {
+  const _AlbumTile({required this.id});
+  final String id;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final asyncAlbum = ref.watch(albumTileProvider(id));
+    final album = asyncAlbum.asData?.value;
+    return AnimatedSwitcher(
+      duration: _tileRevealDuration,
+      switchInCurve: Curves.easeOut,
+      child: album == null
+          ? const SkeletonAlbumTile(key: ValueKey('skeleton'))
+          : AlbumCard(
+              key: ValueKey('album-${album.id}'),
+              album: album,
+              onTap: () =>
+                  context.push('/albums/${album.id}', extra: album),
+            ),
+    );
+  }
+}
+
+/// Artist tile: skeleton until artistTileProvider yields a populated row.
+class _ArtistTile extends ConsumerWidget {
+  const _ArtistTile({required this.id});
+  final String id;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final asyncArtist = ref.watch(artistTileProvider(id));
+    final artist = asyncArtist.asData?.value;
+    return AnimatedSwitcher(
+      duration: _tileRevealDuration,
+      switchInCurve: Curves.easeOut,
+      child: artist == null
+          ? const SkeletonArtistTile(key: ValueKey('skeleton'))
+          : ArtistCard(
+              key: ValueKey('artist-${artist.id}'),
+              artist: artist,
+              onTap: () =>
+                  context.push('/artists/${artist.id}', extra: artist),
+            ),
+    );
+  }
+}
+
+/// Track tile (used by Most-Played). On tap, gathers the currently-
+/// hydrated TrackRefs for the whole section so playback flows like
+/// it did with the bulk-loaded list. Tracks that haven't hydrated yet
+/// are skipped from the play list — typically transient on a cold
+/// visit since hydration runs in parallel and finishes quickly.
+class _TrackTile extends ConsumerWidget {
+  const _TrackTile({required this.id, required this.sectionIds});
+  final String id;
+  final List<String> sectionIds;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final asyncTrack = ref.watch(trackTileProvider(id));
+    final track = asyncTrack.asData?.value;
+    return AnimatedSwitcher(
+      duration: _tileRevealDuration,
+      switchInCurve: Curves.easeOut,
+      child: track == null
+          ? const _CompactTrackSkeleton(key: ValueKey('skeleton'))
+          : CompactTrackCard(
+              key: ValueKey('track-${track.id}'),
+              track: track,
+              sectionTracks: _resolveSectionTracks(ref, sectionIds),
+              index:
+                  sectionIds.indexOf(id).clamp(0, sectionIds.length - 1),
+            ),
+    );
+  }
+
+  /// Snapshots the section's current track states. Used at tile
+  /// construction time — CompactTrackCard's onTap uses it as the play
+  /// queue. Tracks still hydrating are dropped; once they land, a
+  /// rebuild re-runs this lookup so the queue grows naturally.
+  static List<TrackRef> _resolveSectionTracks(WidgetRef ref, List<String> ids) {
+    final out = <TrackRef>[];
+    for (final i in ids) {
+      final v = ref.read(trackTileProvider(i)).asData?.value;
+      if (v != null) out.add(v);
+    }
+    return out;
+  }
+}
+
+/// Compact-track placeholder. 56dp cover + two text lines, matched to
+/// CompactTrackCard so swapping in the real card doesn't shift the
+/// row's height.
+class _CompactTrackSkeleton extends StatelessWidget {
+  const _CompactTrackSkeleton({super.key});
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return Container(
+      width: 240,
+      margin: const EdgeInsets.symmetric(horizontal: 4),
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 6),
+      child: Row(children: [
+        Container(
+          width: 56,
+          height: 56,
+          decoration: BoxDecoration(
+            color: fs.slate,
+            borderRadius: BorderRadius.circular(6),
+          ),
+        ),
+        const SizedBox(width: 8),
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisAlignment: MainAxisAlignment.center,
+            children: [
+              Container(width: 120, height: 12, color: fs.slate),
+              const SizedBox(height: 6),
+              Container(width: 80, height: 10, color: fs.slate),
+            ],
+          ),
+        ),
+      ]),
+    );
+  }
+}
+
+// ─── Sections ────────────────────────────────────────────────────────
+
+class _PlaylistsSection extends StatelessWidget {
+  const _PlaylistsSection({
+    required this.playlists,
+    required this.status,
+    required this.offline,
+  });
+  final List<Playlist> playlists;
+  final SystemPlaylistsStatus status;
+  final bool offline;
+
+  @override
+  Widget build(BuildContext context) {
+    final items = _buildPlaylistsRow(playlists, status);
+    final children = <Widget>[
+      // Offline: surface the cache-backed pools where the (now
+      // play-disabled) system playlists sit, so there's something
+      // to play. #427 S4b.
+      if (offline) ...const [
+        _OfflinePoolCard(
+          label: 'Recently played',
+          icon: Icons.history,
+          kind: _OfflinePoolKind.recentlyPlayed,
+        ),
+        _OfflinePoolCard(
+          label: 'Liked',
+          icon: Icons.favorite,
+          kind: _OfflinePoolKind.liked,
+        ),
+      ],
+      for (final item in items)
+        if (item is _RealPlaylist)
+          PlaylistCard(playlist: item.playlist)
+        else
+          PlaylistPlaceholderCard(
+            label: (item as _PlaceholderPlaylist).label,
+            variant: item.variant,
+          ),
+    ];
+    return HorizontalScrollRow(
+      title: 'Playlists',
+      height: 220,
+      children: children,
+    );
+  }
+}
+
+enum _OfflinePoolKind { recentlyPlayed, liked }
+
+/// Home tile for an offline cache-backed pool. Tapping shuffles +
+/// plays that pool from the local cache. Sized to match
+/// PlaylistCard so the row stays visually consistent.
+class _OfflinePoolCard extends ConsumerWidget {
+  const _OfflinePoolCard({
+    required this.label,
+    required this.icon,
+    required this.kind,
+  });
+  final String label;
+  final IconData icon;
+  final _OfflinePoolKind kind;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return SizedBox(
+      width: 176,
+      child: Material(
+        color: Colors.transparent,
+        child: InkWell(
+          onTap: () async {
+            final messenger = ScaffoldMessenger.of(context);
+            final src = ref.read(shuffleSourceProvider);
+            final refs = await switch (kind) {
+              _OfflinePoolKind.recentlyPlayed => src.recentlyPlayed(),
+              _OfflinePoolKind.liked => src.liked(),
+            };
+            if (refs.isEmpty) {
+              messenger.showSnackBar(
+                SnackBar(content: Text('No cached $label tracks yet')),
+              );
+              return;
+            }
+            await ref
+                .read(playerActionsProvider)
+                .playTracks(refs, shuffle: true);
+          },
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 8),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Container(
+                  width: 144,
+                  height: 144,
+                  decoration: BoxDecoration(
+                    color: fs.slate,
+                    borderRadius: BorderRadius.circular(6),
+                  ),
+                  child: Icon(icon, color: fs.accent, size: 56),
+                ),
+                const SizedBox(height: 8),
+                Text(
+                  label,
+                  maxLines: 1,
+                  overflow: TextOverflow.ellipsis,
+                  style: TextStyle(color: fs.parchment, fontSize: 14),
+                ),
+                Padding(
+                  padding: const EdgeInsets.only(top: 2),
+                  child: Text(
+                    'Offline',
+                    style: TextStyle(color: fs.ash, fontSize: 11),
+                  ),
+                ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+abstract class _PlaylistRowItem {}
+class _RealPlaylist extends _PlaylistRowItem {
+  _RealPlaylist(this.playlist);
+  final Playlist playlist;
+}
+class _PlaceholderPlaylist extends _PlaylistRowItem {
+  _PlaceholderPlaylist(this.label, this.variant);
+  final String label;
+  final String variant;
+}
+
+List<_PlaylistRowItem> _buildPlaylistsRow(
+  List<Playlist> ownedAll,
+  SystemPlaylistsStatus status,
+) {
+  final out = <_PlaylistRowItem>[];
+
+  Playlist? findFirst(bool Function(Playlist) test) {
+    for (final p in ownedAll) {
+      if (test(p)) return p;
+    }
+    return null;
+  }
+
+  final forYou = findFirst((p) => p.systemVariant == 'for_you');
+  out.add(forYou != null
+      ? _RealPlaylist(forYou)
+      : _PlaceholderPlaylist('For You', _variantFor('for-you', status)));
+
+  final discover = findFirst((p) => p.systemVariant == 'discover');
+  out.add(discover != null
+      ? _RealPlaylist(discover)
+      : _PlaceholderPlaylist('Discover', _variantFor('discover', status)));
+
+  final songsLike = ownedAll
+      .where((p) => p.systemVariant == 'songs_like_artist')
+      .take(3)
+      .toList();
+  for (var i = 0; i < 3; i++) {
+    out.add(i < songsLike.length
+        ? _RealPlaylist(songsLike[i])
+        : _PlaceholderPlaylist('Songs like…', _variantFor('songs-like', status)));
+  }
+
+  for (final p in ownedAll.where((p) => p.systemVariant == null)) {
+    out.add(_RealPlaylist(p));
+  }
+
+  return out;
+}
+
+String _variantFor(String slot, SystemPlaylistsStatus s) {
+  if (s.inFlight) return 'building';
+  if (s.lastError != null) return 'failed';
+  if (slot == 'songs-like' && s.lastRunAt != null) return 'seed-needed';
+  return 'pending';
+}
+
+class _RecentlyAddedSection extends StatelessWidget {
+  const _RecentlyAddedSection({required this.ids});
+  final List<String> ids;
+
+  @override
+  Widget build(BuildContext context) {
+    if (ids.isEmpty) {
+      return const _EmptySection(
+        title: 'Recently added',
+        message: "Nothing added yet. Scan a folder via the server's config.",
+      );
+    }
+    final controller = ScrollController();
+    final rows = _chunk(ids, 25);
+    return Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+      for (var i = 0; i < rows.length; i++)
+        HorizontalScrollRow(
+          title: i == 0 ? 'Recently added' : '',
+          controller: controller,
+          children: rows[i].map((id) => _AlbumTile(id: id)).toList(),
+        ),
+    ]);
+  }
+}
+
+class _RediscoverSection extends StatelessWidget {
+  const _RediscoverSection({required this.albumIds, required this.artistIds});
+  final List<String> albumIds;
+  final List<String> artistIds;
+
+  @override
+  Widget build(BuildContext context) {
+    if (albumIds.isEmpty && artistIds.isEmpty) {
+      return const _EmptySection(
+        title: 'Rediscover',
+        message:
+            'No forgotten favourites yet. Like some albums or artists to fill this in.',
+      );
+    }
+    return Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+      if (albumIds.isNotEmpty)
+        HorizontalScrollRow(
+          title: 'Rediscover',
+          children: albumIds.map((id) => _AlbumTile(id: id)).toList(),
+        ),
+      if (artistIds.isNotEmpty)
+        HorizontalScrollRow(
+          title: albumIds.isEmpty ? 'Rediscover' : '',
+          height: 168,
+          children: artistIds.map((id) => _ArtistTile(id: id)).toList(),
+        ),
+    ]);
+  }
+}
+
+class _MostPlayedSection extends StatelessWidget {
+  const _MostPlayedSection({required this.ids});
+  final List<String> ids;
+
+  @override
+  Widget build(BuildContext context) {
+    if (ids.isEmpty) {
+      return const _EmptySection(
+        title: 'Most played',
+        message: 'No plays to draw from. Listen to something.',
+      );
+    }
+    final controller = ScrollController();
+    final rows = _chunk(ids, 25);
+    return Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+      for (var i = 0; i < rows.length; i++)
+        HorizontalScrollRow(
+          title: i == 0 ? 'Most played' : '',
+          height: 64,
+          controller: controller,
+          children: [
+            for (final id in rows[i]) _TrackTile(id: id, sectionIds: ids),
+          ],
+        ),
+    ]);
+  }
+}
+
+class _LastPlayedSection extends StatelessWidget {
+  const _LastPlayedSection({required this.ids});
+  final List<String> ids;
+
+  @override
+  Widget build(BuildContext context) {
+    if (ids.isEmpty) {
+      return const _EmptySection(
+        title: 'Last played',
+        message: 'No recent plays.',
+      );
+    }
+    return HorizontalScrollRow(
+      title: 'Last played',
+      height: 168,
+      children: ids.map((id) => _ArtistTile(id: id)).toList(),
+    );
+  }
+}
+
+class _EmptySection extends StatelessWidget {
+  const _EmptySection({required this.title, required this.message});
+  final String title;
+  final String message;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return Padding(
+      padding: const EdgeInsets.fromLTRB(16, 8, 16, 16),
+      child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+        Text(
+          title,
+          style: TextStyle(
+            fontFamily: fs.display.fontFamily,
+            fontSize: 18,
+            color: fs.parchment,
+          ),
+        ),
+        const SizedBox(height: 8),
+        Text(message, style: TextStyle(color: fs.ash)),
+      ]),
+    );
+  }
+}
+
+/// Cold-start skeleton — shown only between mount and the first
+/// homeIndexProvider emission (typically a single drift query + small
+/// REST round-trip). Each section then renders its own per-tile
+/// skeletons internally, so this widget's role is just the very first
+/// pre-discovery frame.
+class _HomeSkeleton extends StatelessWidget {
+  const _HomeSkeleton({required this.fs});
+  final FabledSwordTheme fs;
+
+  @override
+  Widget build(BuildContext context) {
+    return ListView(
+      physics: const ClampingScrollPhysics(),
+      children: [
+        _SkeletonSection(fs: fs, title: 'Playlists', cardWidth: 176),
+        _SkeletonSection(fs: fs, title: 'Recently added', cardWidth: 140),
+        _SkeletonSection(fs: fs, title: 'Rediscover', cardWidth: 140),
+        _SkeletonSection(fs: fs, title: 'Most played', cardWidth: 140),
+        _SkeletonSection(fs: fs, title: 'Last played', cardWidth: 140),
+        const SizedBox(height: 140),
+      ],
+    );
+  }
+}
+
+class _SkeletonSection extends StatelessWidget {
+  const _SkeletonSection({
+    required this.fs,
+    required this.title,
+    required this.cardWidth,
+  });
+  final FabledSwordTheme fs;
+  final String title;
+  final double cardWidth;
+
+  @override
+  Widget build(BuildContext context) {
+    final coverSize = cardWidth - 16;
+    return Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+      Padding(
+        padding: const EdgeInsets.fromLTRB(16, 8, 16, 8),
+        child: Text(
+          title,
+          style: TextStyle(
+            fontFamily: fs.display.fontFamily,
+            fontSize: 18,
+            color: fs.parchment,
+          ),
+        ),
+      ),
+      SizedBox(
+        height: coverSize + 40,
+        child: ListView.builder(
+          scrollDirection: Axis.horizontal,
+          padding: const EdgeInsets.symmetric(horizontal: 16),
+          physics: const NeverScrollableScrollPhysics(),
+          itemCount: 6,
+          itemBuilder: (_, __) => SkeletonAlbumTile(width: cardWidth),
+        ),
+      ),
+    ]);
+  }
+}
+
+List<List<T>> _chunk<T>(List<T> items, int size) {
+  final out = <List<T>>[];
+  for (var i = 0; i < items.length; i += size) {
+    out.add(items.sublist(i, i + size > items.length ? items.length : i + size));
+  }
+  return out;
 }

flutter_client/lib/library/library_providers.dart

@@ -1,12 +1,23 @@
+import 'dart:async';
+import 'dart:convert';
+
 import 'package:dio/dio.dart';
+import 'package:drift/drift.dart' as drift;
+import 'package:flutter/foundation.dart' show debugPrint;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../api/client.dart';
 import '../api/endpoints/library.dart';
 import '../auth/auth_provider.dart';
+import '../cache/adapters.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../cache/cache_first.dart';
+import '../cache/connectivity_provider.dart';
+import '../cache/db.dart';
 import '../models/album.dart';
 import '../models/artist.dart';
 import '../models/home_data.dart';
+import '../models/home_index.dart';
 import '../models/track.dart';
 
 /// Shared authenticated dio. This is the ONLY place tokenResolver is wired
@@ -33,28 +44,460 @@ final libraryApiProvider = FutureProvider<LibraryApi>((ref) async {
   return LibraryApi(await ref.watch(dioProvider.future));
 });
 
-final homeProvider = FutureProvider<HomeData>((ref) async {
-  return (await ref.watch(libraryApiProvider.future)).getHome();
+/// Drift-first home data (#357 follow-up). The home screen is the first
+/// view the user sees on app open; without a local cache the cold-start
+/// blocks on the /api/home round-trip, which is the dominant felt-
+/// latency on slow / remote connections.
+///
+/// Cache layout: a single row in `cached_home_snapshot` storing the
+/// last successful HomeData as JSON. On stream subscription:
+///
+///   - If a row exists, yield it immediately (parsed from JSON) and
+///     kick off a background revalidation against /api/home (SWR).
+///     The drift watch() re-emits when the new row is written.
+///   - If no row exists yet (cold cache), fetch /api/home synchronously,
+///     upsert into drift, and emit. Subsequent emissions come from the
+///     drift watch as background revalidations land.
+///
+/// The HomeData JSON encodes back to the same wire shape /api/home
+/// emits, so the existing HomeData.fromJson handles both sources.
+final homeProvider = StreamProvider<HomeData>((ref) {
+  final db = ref.watch(appDbProvider);
+  return cacheFirst<CachedHomeSnapshotData, HomeData>(
+    driftStream: db.select(db.cachedHomeSnapshot).watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(libraryApiProvider.future);
+      final fresh = await api.getHome();
+      await db.into(db.cachedHomeSnapshot).insertOnConflictUpdate(
+            CachedHomeSnapshotCompanion.insert(
+              json: _encodeHomeData(fresh),
+              updatedAt: drift.Value(DateTime.now()),
+            ),
+          );
+    },
+    toResult: (rows) => rows.isEmpty
+        ? const HomeData(
+            recentlyAddedAlbums: [],
+            rediscoverAlbums: [],
+            rediscoverArtists: [],
+            mostPlayedTracks: [],
+            lastPlayedArtists: [],
+          )
+        : HomeData.fromJson(jsonDecode(rows.first.json) as Map<String, dynamic>),
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    // SWR: when cached snapshot exists, still hit /api/home in the
+    // background so the user sees the freshest curation. The cache
+    // mostly serves the first frame, not the canonical state.
+    alwaysRefresh: true,
+    tag: 'home',
+  );
 });
 
+/// Drift-first per-item home index. Reads from cached_home_index
+/// (populated by /api/home/index discovery) and yields a HomeIndex
+/// the screen consumes to lay out section→tile slots. Each tile is
+/// rendered by a per-entity tile provider that hydrates itself.
+///
+/// Section keys mirror the server's response shape so the encode /
+/// decode round-trip is straightforward — the table stores
+/// (section, position, entityType, entityId), and toResult reassembles
+/// the parallel ID lists.
+final homeIndexProvider = StreamProvider<HomeIndex>((ref) {
+  final db = ref.watch(appDbProvider);
+  final query = (db.select(db.cachedHomeIndex)
+        ..orderBy([
+          (t) => drift.OrderingTerm.asc(t.section),
+          (t) => drift.OrderingTerm.asc(t.position),
+        ]))
+      .watch();
+  return cacheFirst<CachedHomeIndexData, HomeIndex>(
+    driftStream: query,
+    fetchAndPopulate: () async {
+      final api = await ref.read(libraryApiProvider.future);
+      final fresh = await api.getHomeIndex();
+      // Full replace in a transaction so the watch() sees exactly one
+      // post-fetch emission with the merged state. Section ordering is
+      // re-asserted on read (orderBy above) so the write order doesn't
+      // matter — letting us batch flat instead of section-by-section.
+      await db.transaction(() async {
+        await db.delete(db.cachedHomeIndex).go();
+        await db.batch((b) {
+          void rows(String section, String entityType, List<String> ids) {
+            for (var i = 0; i < ids.length; i++) {
+              b.insert(
+                db.cachedHomeIndex,
+                CachedHomeIndexCompanion.insert(
+                  section: section,
+                  position: i,
+                  entityType: entityType,
+                  entityId: ids[i],
+                ),
+              );
+            }
+          }
+
+          rows('recently_added_albums', 'album', fresh.recentlyAddedAlbums);
+          rows('rediscover_albums', 'album', fresh.rediscoverAlbums);
+          rows('rediscover_artists', 'artist', fresh.rediscoverArtists);
+          rows('most_played_tracks', 'track', fresh.mostPlayedTracks);
+          rows('last_played_artists', 'artist', fresh.lastPlayedArtists);
+        });
+      });
+    },
+    toResult: (rows) {
+      final recentlyAddedAlbums = <String>[];
+      final rediscoverAlbums = <String>[];
+      final rediscoverArtists = <String>[];
+      final mostPlayedTracks = <String>[];
+      final lastPlayedArtists = <String>[];
+      for (final r in rows) {
+        switch (r.section) {
+          case 'recently_added_albums':
+            recentlyAddedAlbums.add(r.entityId);
+          case 'rediscover_albums':
+            rediscoverAlbums.add(r.entityId);
+          case 'rediscover_artists':
+            rediscoverArtists.add(r.entityId);
+          case 'most_played_tracks':
+            mostPlayedTracks.add(r.entityId);
+          case 'last_played_artists':
+            lastPlayedArtists.add(r.entityId);
+        }
+      }
+      return HomeIndex(
+        recentlyAddedAlbums: recentlyAddedAlbums,
+        rediscoverAlbums: rediscoverAlbums,
+        rediscoverArtists: rediscoverArtists,
+        mostPlayedTracks: mostPlayedTracks,
+        lastPlayedArtists: lastPlayedArtists,
+      );
+    },
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    // SWR: cached layout shows instantly; fresh /api/home/index lands
+    // in the background and tiles re-resolve as the table mutates.
+    alwaysRefresh: true,
+    tag: 'homeIndex',
+  );
+});
+
+/// Encodes HomeData back to the wire-format JSON shape /api/home
+/// emits, so HomeData.fromJson can round-trip through the drift cache.
+String _encodeHomeData(HomeData h) => jsonEncode({
+      'recently_added_albums': h.recentlyAddedAlbums.map(_albumToJson).toList(),
+      'rediscover_albums': h.rediscoverAlbums.map(_albumToJson).toList(),
+      'rediscover_artists': h.rediscoverArtists.map(_artistToJson).toList(),
+      'most_played_tracks': h.mostPlayedTracks.map(_trackToJson).toList(),
+      'last_played_artists': h.lastPlayedArtists.map(_artistToJson).toList(),
+    });
+
+Map<String, dynamic> _albumToJson(AlbumRef a) => {
+      'id': a.id,
+      'title': a.title,
+      'sort_title': a.sortTitle,
+      'artist_id': a.artistId,
+      'artist_name': a.artistName,
+      'year': a.year,
+      'track_count': a.trackCount,
+      'duration_sec': a.durationSec,
+      'cover_url': a.coverUrl,
+    };
+
+Map<String, dynamic> _artistToJson(ArtistRef a) => {
+      'id': a.id,
+      'name': a.name,
+      'sort_name': a.sortName,
+      'album_count': a.albumCount,
+      'cover_url': a.coverUrl,
+    };
+
+Map<String, dynamic> _trackToJson(TrackRef t) => {
+      'id': t.id,
+      'title': t.title,
+      'album_id': t.albumId,
+      'album_title': t.albumTitle,
+      'artist_id': t.artistId,
+      'artist_name': t.artistName,
+      'track_number': t.trackNumber,
+      'disc_number': t.discNumber,
+      'duration_sec': t.durationSec,
+      'stream_url': t.streamUrl,
+    };
+
+/// Drift-first per #357 plan C. Watches cached_artists for the row;
+/// when empty + online, fetches via REST + populates drift, which
+/// re-emits via watch().
 final artistProvider =
-    FutureProvider.family<ArtistRef, String>((ref, id) async {
-  return (await ref.watch(libraryApiProvider.future)).getArtist(id);
+    StreamProvider.family<ArtistRef, String>((ref, id) {
+  final db = ref.watch(appDbProvider);
+  // 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) {
+      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)),
+    // No alwaysRefresh: artist rows don't change frequently, and the
+    // metadata prefetcher creates many subscriptions in parallel —
+    // each silently re-fetching once would saturate the request
+    // pipeline behind the user's actual playback request.
+    tag: 'artist($id)',
+  );
 });
 
 final artistAlbumsProvider =
-    FutureProvider.family<List<AlbumRef>, String>((ref, id) async {
-  return (await ref.watch(libraryApiProvider.future)).getArtistAlbums(id);
+    StreamProvider.family<List<AlbumRef>, String>((ref, artistId) {
+  final db = ref.watch(appDbProvider);
+  // Join cached_albums + cached_artists to fill artist_name on each row.
+  final query = db.select(db.cachedAlbums).join([
+    drift.leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedAlbums.artistId)),
+  ])..where(db.cachedAlbums.artistId.equals(artistId));
+
+  return cacheFirst<drift.TypedResult, List<AlbumRef>>(
+    driftStream: query.watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(libraryApiProvider.future);
+      final fresh = await api.getArtistAlbums(artistId);
+      await db.batch((b) {
+        b.insertAllOnConflictUpdate(
+            db.cachedAlbums, fresh.map((a) => a.toDrift()).toList());
+      });
+    },
+    toResult: (rows) => rows.map((r) {
+      final album = r.readTable(db.cachedAlbums);
+      final artist = r.readTableOrNull(db.cachedArtists);
+      return album.toRef(artistName: artist?.name ?? '');
+    }).toList(),
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    // SWR: re-fetch the full album list on every visit. Without this,
+    // a previously-incomplete drift cache (e.g. user had only opened
+    // one album by this artist, so cachedAlbums had just that row)
+    // would render forever as a partial list. The prefetcher only
+    // warms artistProvider (single row), so this provider isn't
+    // mass-instantiated and the storm risk that motivated dropping
+    // alwaysRefresh elsewhere doesn't apply here.
+    alwaysRefresh: true,
+    tag: 'artistAlbums($artistId)',
+  );
 });
 
 final artistTracksProvider =
-    FutureProvider.family<List<TrackRef>, String>((ref, id) async {
-  return (await ref.watch(libraryApiProvider.future)).getArtistTracks(id);
+    StreamProvider.family<List<TrackRef>, String>((ref, artistId) {
+  final db = ref.watch(appDbProvider);
+  final query = db.select(db.cachedTracks).join([
+    drift.leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedTracks.artistId)),
+    drift.leftOuterJoin(db.cachedAlbums,
+        db.cachedAlbums.id.equalsExp(db.cachedTracks.albumId)),
+  ])..where(db.cachedTracks.artistId.equals(artistId));
+
+  return cacheFirst<drift.TypedResult, List<TrackRef>>(
+    driftStream: query.watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(libraryApiProvider.future);
+      final fresh = await api.getArtistTracks(artistId);
+      await db.batch((b) {
+        b.insertAllOnConflictUpdate(
+            db.cachedTracks, fresh.map((t) => t.toDrift()).toList());
+      });
+    },
+    toResult: (rows) => rows.map((r) {
+      final track = r.readTable(db.cachedTracks);
+      final artist = r.readTableOrNull(db.cachedArtists);
+      final album = r.readTableOrNull(db.cachedAlbums);
+      return track.toRef(
+        artistName: artist?.name ?? '',
+        albumTitle: album?.title ?? '',
+      );
+    }).toList(),
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    tag: 'artistTracks($artistId)',
+  );
 });
 
-final albumProvider =
-    FutureProvider.family<({AlbumRef album, List<TrackRef> tracks}), String>(
-  (ref, id) async {
-    return (await ref.watch(libraryApiProvider.future)).getAlbum(id);
-  },
-);
+/// Composite shape (album + tracks) — uses async* + Stream.combineLatest
+/// for reactive updates over both rows.
+final albumProvider = StreamProvider.family<
+    ({AlbumRef album, List<TrackRef> tracks}), String>((ref, albumId) async* {
+  final db = ref.watch(appDbProvider);
+
+  final albumQuery = (db.select(db.cachedAlbums)
+        ..where((t) => t.id.equals(albumId)))
+      .join([
+    drift.leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedAlbums.artistId)),
+  ]);
+
+  final tracksQuery = (db.select(db.cachedTracks)
+        ..where((t) => t.albumId.equals(albumId))
+        ..orderBy([
+          (t) => drift.OrderingTerm.asc(t.discNumber),
+          (t) => drift.OrderingTerm.asc(t.trackNumber),
+        ]))
+      .join([
+    drift.leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedTracks.artistId)),
+  ]);
+
+  // Once-per-subscription guard so we don't re-fetch in a loop if the
+  // server genuinely returns zero tracks (or if the fetch fails).
+  var fetchAttempted = false;
+  // (revalidated flag removed; see SWR note below the yield.)
+
+  Future<bool> isOnline() async {
+    try {
+      return await ref
+          .read(connectivityProvider.future)
+          .timeout(const Duration(seconds: 3), onTimeout: () => true);
+    } catch (_) {
+      return true;
+    }
+  }
+
+  // Cold-cache fetch: pulls the album + its tracks + any unique
+  // artists referenced and writes all three tables in one batch.
+  // Returns true on success (drift watch will re-emit), false on
+  // failure so the caller can yield an empty result.
+  Future<bool> fetchAndPopulate() async {
+    try {
+      final api = await ref.read(libraryApiProvider.future);
+      final fresh = await api
+          .getAlbum(albumId)
+          .timeout(const Duration(seconds: 10));
+      // Collect every artist mentioned by the album + its tracks so
+      // the JOINs that drive both the album header and the track rows
+      // have something to bind to. Without this, drift returns null
+      // for the artist row and artistName surfaces empty — visible
+      // as a missing artist line in the mini player and row list.
+      final artists = <String, ArtistRef>{};
+      if (fresh.album.artistId.isNotEmpty &&
+          fresh.album.artistName.isNotEmpty) {
+        artists[fresh.album.artistId] = ArtistRef(
+          id: fresh.album.artistId,
+          name: fresh.album.artistName,
+        );
+      }
+      for (final t in fresh.tracks) {
+        if (t.artistId.isNotEmpty &&
+            t.artistName.isNotEmpty &&
+            !artists.containsKey(t.artistId)) {
+          artists[t.artistId] = ArtistRef(
+            id: t.artistId,
+            name: t.artistName,
+          );
+        }
+      }
+      await db.batch((b) {
+        if (artists.isNotEmpty) {
+          b.insertAllOnConflictUpdate(
+              db.cachedArtists, artists.values.map((a) => a.toDrift()).toList());
+        }
+        b.insertAllOnConflictUpdate(db.cachedAlbums, [fresh.album.toDrift()]);
+        b.insertAllOnConflictUpdate(db.cachedTracks,
+            fresh.tracks.map((t) => t.toDrift()).toList());
+      });
+      return true;
+    } catch (e, st) {
+      debugPrint('albumProvider($albumId): cold-cache fetch failed: $e\n$st');
+      return false;
+    }
+  }
+
+  await for (final albumRows in albumQuery.watch()) {
+    // Case 1: no album row at all → cold-fetch.
+    if (albumRows.isEmpty) {
+      if (fetchAttempted) {
+        // Already tried and got nothing back.
+        yield (
+          album: const AlbumRef(id: '', title: '', artistId: ''),
+          tracks: const <TrackRef>[],
+        );
+        continue;
+      }
+      fetchAttempted = true;
+      if (!await isOnline()) {
+        yield (
+          album: const AlbumRef(id: '', title: '', artistId: ''),
+          tracks: const <TrackRef>[],
+        );
+        continue;
+      }
+      final ok = await fetchAndPopulate();
+      if (!ok) {
+        yield (
+          album: const AlbumRef(id: '', title: '', artistId: ''),
+          tracks: const <TrackRef>[],
+        );
+      }
+      // On success, drift watch re-emits with rows; loop continues.
+      continue;
+    }
+
+    final albumRow = albumRows.first;
+    final album = albumRow.readTable(db.cachedAlbums).toRef(
+          artistName: albumRow.readTableOrNull(db.cachedArtists)?.name ?? '',
+        );
+
+    final trackRows = await tracksQuery.get();
+
+    // Case 2: album row exists but no tracks. This happens when an
+    // upstream provider (artistAlbumsProvider, sync, etc.) populated
+    // album rows without their track lists. Trigger the same
+    // fetchAndPopulate so the album becomes complete; drift watch
+    // re-emits and we land in the populated branch on the next pass.
+    if (trackRows.isEmpty && !fetchAttempted) {
+      fetchAttempted = true;
+      if (await isOnline()) {
+        final ok = await fetchAndPopulate();
+        if (ok) continue; // wait for watch re-emit
+      }
+      // Fall through and yield with the album + empty tracks if the
+      // fetch failed or we're offline.
+    }
+
+    final tracks = trackRows.map((r) {
+      final track = r.readTable(db.cachedTracks);
+      final artist = r.readTableOrNull(db.cachedArtists);
+      return track.toRef(
+        artistName: artist?.name ?? '',
+        albumTitle: album.title,
+      );
+    }).toList();
+
+    // Note: NO SWR here on purpose. Prior code kicked a background
+    // refresh on every first cache hit, which combined with the
+    // metadata prefetcher meant every prewarmed album id triggered
+    // an extra fetch even when drift was already populated. Tracks
+    // and album metadata don't change on the same timescale as
+    // playlists; a stale read is fine until the user invalidates
+    // (pull-to-refresh) or the album is genuinely re-fetched.
+
+    yield (album: album, tracks: tracks);
+  }
+});

flutter_client/lib/library/library_screen.dart

@@ -1,3 +1,6 @@
+import 'dart:convert';
+
+import 'package:drift/drift.dart' as drift;
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
@@ -5,17 +8,27 @@ import 'package:go_router/go_router.dart';
 import '../api/endpoints/library_lists.dart';
 import '../api/endpoints/likes.dart';
 import '../api/endpoints/me.dart';
+import '../auth/auth_provider.dart' show authControllerProvider;
+import '../cache/adapters.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../cache/cache_first.dart';
+import '../cache/connectivity_provider.dart';
+import '../cache/db.dart';
+import '../cache/metadata_prefetcher.dart';
+import '../cache/shuffle_source.dart';
+import '../cache/tile_providers.dart';
 import '../library/library_providers.dart' show dioProvider;
 import '../models/album.dart';
 import '../models/artist.dart';
 import '../models/history_event.dart';
-// Aliased: Flutter's Material exports a `Page` class (Navigator 2.0
-// route descriptor) that conflicts with our wire-format Page<T>.
-import '../models/page.dart' as wire;
 import '../models/quarantine_mine.dart';
 import '../models/track.dart';
 import '../player/player_provider.dart';
+import '../quarantine/quarantine_provider.dart';
+import '../shared/live_events_provider.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
+import '../shared/widgets/skeletons.dart';
+import '../shared/widgets/server_image.dart';
 import '../theme/theme_extension.dart';
 import 'widgets/album_card.dart';
 import 'widgets/artist_card.dart';
@@ -37,33 +50,294 @@ final _meApiProvider = FutureProvider<MeApi>((ref) async {
   return MeApi(await ref.watch(dioProvider.future));
 });
 
-final _libraryArtistsProvider = FutureProvider<wire.Paged<ArtistRef>>((ref) async {
-  return (await ref.watch(_libraryListsApiProvider.future)).listArtists();
+/// Drift-first all-artists list. Reads cached_artists ordered by
+/// sortName; GridView.builder takes care of lazy widget construction
+/// so loading the full set up front is fine for typical library sizes.
+/// SWR refresh on every subscription hits /api/artists with a generous
+/// limit so newly-scanned-but-not-yet-synced rows land soon after.
+///
+/// The old AsyncNotifier+loadMore infinite-scroll path went away: the
+/// previous "fetch one page at a time as you scroll" felt like the
+/// rest of the app was buffering when this tab was the slow surface,
+/// and SyncController already populates the full set of artist rows
+/// via /api/library/sync.
+final _libraryArtistsProvider = StreamProvider<List<ArtistRef>>((ref) {
+  final db = ref.watch(appDbProvider);
+  // 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,
+      // but a fresh install + first Library visit before sync completes
+      // will be empty. Fetch a generous chunk via /api/artists and
+      // persist; subsequent SWR refreshes keep things current.
+      final api = await ref.read(_libraryListsApiProvider.future);
+      final fresh = await api.listArtists(limit: 1000, offset: 0);
+      await db.batch((b) {
+        b.insertAllOnConflictUpdate(
+          db.cachedArtists,
+          fresh.items.map((a) => a.toDrift()).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)),
+    alwaysRefresh: true,
+    tag: 'libraryArtists',
+  );
 });
 
-final _libraryAlbumsProvider = FutureProvider<wire.Paged<AlbumRef>>((ref) async {
-  return (await ref.watch(_libraryListsApiProvider.future)).listAlbums();
+/// Drift-first all-albums list. Joins cached_albums with cached_artists
+/// for the artistName field. Same cold-cache fallback + SWR refresh
+/// pattern as libraryArtistsProvider.
+final _libraryAlbumsProvider = StreamProvider<List<AlbumRef>>((ref) {
+  final db = ref.watch(appDbProvider);
+  final query = db.select(db.cachedAlbums).join([
+    drift.leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedAlbums.artistId)),
+  ])
+    ..orderBy([drift.OrderingTerm.asc(db.cachedAlbums.sortTitle)]);
+  return cacheFirst<drift.TypedResult, List<AlbumRef>>(
+    driftStream: query.watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(_libraryListsApiProvider.future);
+      final fresh = await api.listAlbums(limit: 1000, offset: 0);
+      await db.batch((b) {
+        b.insertAllOnConflictUpdate(
+          db.cachedAlbums,
+          fresh.items.map((a) => a.toDrift()).toList(),
+        );
+      });
+    },
+    toResult: (rows) => rows.map((r) {
+      final album = r.readTable(db.cachedAlbums);
+      final artist = r.readTableOrNull(db.cachedArtists);
+      return album.toRef(artistName: artist?.name ?? '');
+    }).toList(),
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    alwaysRefresh: true,
+    tag: 'libraryAlbums',
+  );
 });
 
-final _historyProvider = FutureProvider<HistoryPage>((ref) async {
-  return (await ref.watch(_meApiProvider.future)).history();
+// Drift-first History tab. Mirrors homeProvider's pattern: store the
+// last /api/me/history page as JSON in a single-row drift table, yield
+// it immediately on subscribe (so the tab paints from disk on cold
+// open), then SWR-refresh in the background. Also gives basic offline
+// scrollback — the last fetched page survives connectivity loss.
+//
+// JSON blob (vs columnar) because the page is small, always read whole,
+// and the HistoryPage.fromJson constructor already accepts the wire
+// shape — no schema-evolution pain when server-side fields change.
+final _historyProvider = StreamProvider<HistoryPage>((ref) {
+  final db = ref.watch(appDbProvider);
+  return cacheFirst<CachedHistorySnapshotData, HistoryPage>(
+    driftStream: db.select(db.cachedHistorySnapshot).watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(_meApiProvider.future);
+      final fresh = await api.history();
+      await db.into(db.cachedHistorySnapshot).insertOnConflictUpdate(
+            CachedHistorySnapshotCompanion.insert(
+              json: _encodeHistoryPage(fresh),
+              updatedAt: drift.Value(DateTime.now()),
+            ),
+          );
+    },
+    toResult: (rows) => rows.isEmpty
+        ? const HistoryPage(events: [], hasMore: false)
+        : HistoryPage.fromJson(
+            jsonDecode(rows.first.json) as Map<String, dynamic>),
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    // SWR: yield cache instantly, then refresh in the background so the
+    // tab reflects the freshest plays. Matches homeProvider behavior.
+    alwaysRefresh: true,
+    tag: 'history',
+  );
 });
 
-final _likedTracksProvider = FutureProvider<wire.Paged<TrackRef>>((ref) async {
-  return (await ref.watch(_likesApiProvider.future)).listTracks();
+/// Encodes HistoryPage back to the wire-format JSON shape
+/// /api/me/history emits, so HistoryPage.fromJson can round-trip
+/// through the drift cache.
+String _encodeHistoryPage(HistoryPage h) => jsonEncode({
+      'events': h.events
+          .map((e) => {
+                'id': e.id,
+                'played_at': e.playedAt,
+                'track': {
+                  'id': e.track.id,
+                  'title': e.track.title,
+                  'album_id': e.track.albumId,
+                  'album_title': e.track.albumTitle,
+                  'artist_id': e.track.artistId,
+                  'artist_name': e.track.artistName,
+                  'track_number': e.track.trackNumber,
+                  'disc_number': e.track.discNumber,
+                  'duration_sec': e.track.durationSec,
+                  'stream_url': e.track.streamUrl,
+                },
+              })
+          .toList(),
+      'has_more': h.hasMore,
+    });
+
+// Per-item Liked tabs (Slice E of the per-item rendering pass).
+// Each provider yields just the ordered list of entity IDs; the UI
+// then renders per-tile widgets that hydrate each entity individually
+// via albumTileProvider / artistTileProvider / trackTileProvider.
+//
+// Reads come from cached_likes (sync- and optimistic-write-populated),
+// projected with ORDER BY likedAt DESC. fetchAndPopulate hits the
+// cheap /api/likes/ids endpoint — the bulk /api/likes/* endpoints
+// that returned fully denormalized entities are no longer needed for
+// this path since tile providers handle entity hydration themselves.
+//
+// likedAt ordering note: cached_likes.likedAt is whatever drift
+// assigned via currentDateAndTime when the row was first inserted
+// (either by sync or LikesController). insertOrIgnore on subsequent
+// fetches preserves the existing likedAt so ordering stays stable.
+// Approximate but acceptable — matches prior Slice 3 behavior.
+
+List<String> _idsForEntity(List<CachedLike> rows) =>
+    rows.map((r) => r.entityId).toList(growable: false);
+
+final _likedTrackIdsProvider = StreamProvider<List<String>>((ref) {
+  final db = ref.watch(appDbProvider);
+  final query = (db.select(db.cachedLikes)
+        ..where((t) => t.entityType.equals('track'))
+        ..orderBy([(t) => drift.OrderingTerm.desc(t.likedAt)]))
+      .watch();
+  return cacheFirst<CachedLike, List<String>>(
+    driftStream: query,
+    fetchAndPopulate: () => _populateLikeIds(ref),
+    toResult: _idsForEntity,
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    alwaysRefresh: true,
+    tag: 'likedTrackIds',
+  );
 });
 
-final _likedAlbumsProvider = FutureProvider<wire.Paged<AlbumRef>>((ref) async {
-  return (await ref.watch(_likesApiProvider.future)).listAlbums();
+final _likedAlbumIdsProvider = StreamProvider<List<String>>((ref) {
+  final db = ref.watch(appDbProvider);
+  final query = (db.select(db.cachedLikes)
+        ..where((t) => t.entityType.equals('album'))
+        ..orderBy([(t) => drift.OrderingTerm.desc(t.likedAt)]))
+      .watch();
+  return cacheFirst<CachedLike, List<String>>(
+    driftStream: query,
+    fetchAndPopulate: () => _populateLikeIds(ref),
+    toResult: _idsForEntity,
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    alwaysRefresh: true,
+    tag: 'likedAlbumIds',
+  );
 });
 
-final _likedArtistsProvider = FutureProvider<wire.Paged<ArtistRef>>((ref) async {
-  return (await ref.watch(_likesApiProvider.future)).listArtists();
+final _likedArtistIdsProvider = StreamProvider<List<String>>((ref) {
+  final db = ref.watch(appDbProvider);
+  final query = (db.select(db.cachedLikes)
+        ..where((t) => t.entityType.equals('artist'))
+        ..orderBy([(t) => drift.OrderingTerm.desc(t.likedAt)]))
+      .watch();
+  return cacheFirst<CachedLike, List<String>>(
+    driftStream: query,
+    fetchAndPopulate: () => _populateLikeIds(ref),
+    toResult: _idsForEntity,
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    alwaysRefresh: true,
+    tag: 'likedArtistIds',
+  );
 });
 
-final _quarantineProvider = FutureProvider<List<QuarantineMineRow>>((ref) async {
-  return (await ref.watch(_meApiProvider.future)).quarantineMine();
-});
+/// Shared cold-cache populator: hits /api/likes/ids once and writes
+/// rows for all three entity types via insertOrIgnore. The three
+/// providers above all trigger this on their first empty-drift
+/// emission; the dedup in cacheFirst's revalidate state plus drift's
+/// insertOrIgnore semantics make the multiple-trigger case cheap.
+Future<void> _populateLikeIds(Ref ref) async {
+  final api = await ref.read(_likesApiProvider.future);
+  final user = ref.read(authControllerProvider).value;
+  if (user == null) return;
+  final fresh = await api.ids();
+  final db = ref.read(appDbProvider);
+  await db.batch((b) {
+    for (final id in fresh.tracks) {
+      b.insert(
+        db.cachedLikes,
+        CachedLikesCompanion.insert(
+          userId: user.id,
+          entityType: 'track',
+          entityId: id,
+        ),
+        mode: drift.InsertMode.insertOrIgnore,
+      );
+    }
+    for (final id in fresh.albums) {
+      b.insert(
+        db.cachedLikes,
+        CachedLikesCompanion.insert(
+          userId: user.id,
+          entityType: 'album',
+          entityId: id,
+        ),
+        mode: drift.InsertMode.insertOrIgnore,
+      );
+    }
+    for (final id in fresh.artists) {
+      b.insert(
+        db.cachedLikes,
+        CachedLikesCompanion.insert(
+          userId: user.id,
+          entityType: 'artist',
+          entityId: id,
+        ),
+        mode: drift.InsertMode.insertOrIgnore,
+      );
+    }
+  });
+}
+
+// Hidden tab uses the canonical `myQuarantineProvider` (AsyncNotifier with
+// optimistic flag/unflag) so flagging from any kebab and unflagging from
+// the Hidden tab keep one source of truth.
 
 class LibraryScreen extends ConsumerStatefulWidget {
   const LibraryScreen({super.key});
@@ -85,13 +359,46 @@ class _LibraryScreenState extends ConsumerState<LibraryScreen>
   @override
   Widget build(BuildContext context) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // Pre-warm every tab's provider on Library mount so swiping
+    // between tabs feels instant rather than each tab paying its
+    // own cold-cache cost on first visit. ref.listen subscribes
+    // without rebuilding LibraryScreen on emit; subscriptions stay
+    // alive for the lifetime of this widget. cacheFirst handles
+    // dedupe of concurrent fetchAndPopulate triggers.
+    ref.listen(_libraryArtistsProvider, (_, __) {});
+    ref.listen(_libraryAlbumsProvider, (_, __) {});
+    ref.listen(_historyProvider, (_, __) {});
+    ref.listen(_likedTrackIdsProvider, (_, __) {});
+    ref.listen(_likedAlbumIdsProvider, (_, __) {});
+    ref.listen(_likedArtistIdsProvider, (_, __) {});
+    ref.listen(myQuarantineProvider, (_, __) {});
     return Scaffold(
       backgroundColor: fs.obsidian,
       appBar: AppBar(
         backgroundColor: fs.obsidian,
         elevation: 0,
         title: Text('Library', style: TextStyle(color: fs.parchment)),
-        actions: const [MainAppBarActions(currentRoute: '/library')],
+        actions: [
+          IconButton(
+            key: const Key('shuffle_all_button'),
+            tooltip: 'Shuffle all',
+            icon: Icon(Icons.shuffle, color: fs.parchment),
+            onPressed: () async {
+              final messenger = ScaffoldMessenger.of(context);
+              final refs = await ref.read(shuffleSourceProvider).tracks();
+              if (refs.isEmpty) {
+                messenger.showSnackBar(const SnackBar(
+                  content: Text('Nothing to shuffle yet'),
+                ));
+                return;
+              }
+              await ref
+                  .read(playerActionsProvider)
+                  .playTracks(refs, shuffle: true);
+            },
+          ),
+          const MainAppBarActions(currentRoute: '/library'),
+        ],
         bottom: TabBar(
           controller: _ctrl,
           isScrollable: true,
@@ -131,25 +438,58 @@ class _ArtistsTab extends ConsumerWidget {
     return ref.watch(_libraryArtistsProvider).when(
           loading: () => const Center(child: CircularProgressIndicator()),
           error: (e, _) => Center(child: Text('$e', style: TextStyle(color: fs.error))),
-          data: (page) => page.items.isEmpty
-              ? Center(child: Text('No artists.', style: TextStyle(color: fs.ash)))
+          data: (artists) {
+            // Warm details for the first screenful so taps are instant.
+            ref
+                .read(metadataPrefetcherProvider)
+                .warmArtists(artists.map((a) => a.id));
+            return artists.isEmpty
+              ? Center(child: Text("No artists yet — scan a library folder via the server's config.", style: TextStyle(color: fs.ash), textAlign: TextAlign.center))
               : RefreshIndicator(
                   onRefresh: () async => ref.refresh(_libraryArtistsProvider.future),
-                  child: GridView.builder(
-                    padding: const EdgeInsets.all(8),
-                    gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
-                      crossAxisCount: 3,
-                      mainAxisSpacing: 8,
-                      crossAxisSpacing: 8,
-                      childAspectRatio: 0.78,
-                    ),
-                    itemCount: page.items.length,
-                    itemBuilder: (ctx, i) => ArtistCard(
-                      artist: page.items[i],
-                      onTap: () => ctx.push('/artists/${page.items[i].id}'),
-                    ),
-                  ),
-                ),
+                  // LayoutBuilder + cell-aware ArtistCard width mirrors
+                  // the AlbumsTab pattern so the circular avatar stays
+                  // a true circle on narrow grid cells.
+                  //
+                  // Drift-first: GridView holds the full sorted list;
+                  // .builder lazily realizes only visible cells, so
+                  // even on large libraries the up-front cost is just
+                  // a sort over cached_artists, not N network round
+                  // trips.
+                  child: LayoutBuilder(builder: (ctx, constraints) {
+                    const cols = 3;
+                    const sidePad = 8.0;
+                    const gap = 8.0;
+                    final cellW = (constraints.maxWidth -
+                            sidePad * 2 -
+                            gap * (cols - 1)) /
+                        cols;
+                    // avatar (cellW - 16) + gap (8) + 1 line name (~18)
+                    // + slack matched to AlbumsTab's overflow guard.
+                    final cellH = (cellW - 16) + 8 + 18 + 8;
+                    return GridView.builder(
+                      padding: const EdgeInsets.all(sidePad),
+                      gridDelegate:
+                          SliverGridDelegateWithFixedCrossAxisCount(
+                        crossAxisCount: cols,
+                        mainAxisExtent: cellH,
+                        mainAxisSpacing: gap,
+                        crossAxisSpacing: gap,
+                      ),
+                      itemCount: artists.length,
+                      itemBuilder: (ctx, i) {
+                        final artist = artists[i];
+                        return ArtistCard(
+                          artist: artist,
+                          width: cellW,
+                          onTap: () => ctx.push('/artists/${artist.id}',
+                              extra: artist),
+                        );
+                      },
+                    );
+                  }),
+                );
+          },
         );
   }
 }
@@ -163,25 +503,54 @@ class _AlbumsTab extends ConsumerWidget {
     return ref.watch(_libraryAlbumsProvider).when(
           loading: () => const Center(child: CircularProgressIndicator()),
           error: (e, _) => Center(child: Text('$e', style: TextStyle(color: fs.error))),
-          data: (page) => page.items.isEmpty
-              ? Center(child: Text('No albums.', style: TextStyle(color: fs.ash)))
+          data: (albums) {
+            return albums.isEmpty
+              ? Center(child: Text("No albums yet — scan a library folder via the server's config.", style: TextStyle(color: fs.ash), textAlign: TextAlign.center))
               : RefreshIndicator(
                   onRefresh: () async => ref.refresh(_libraryAlbumsProvider.future),
-                  child: GridView.builder(
-                    padding: const EdgeInsets.all(8),
-                    gridDelegate: const SliverGridDelegateWithFixedCrossAxisCount(
-                      crossAxisCount: 2,
-                      mainAxisSpacing: 8,
-                      crossAxisSpacing: 8,
-                      childAspectRatio: 0.78,
-                    ),
-                    itemCount: page.items.length,
-                    itemBuilder: (ctx, i) => AlbumCard(
-                      album: page.items[i],
-                      onTap: () => ctx.push('/albums/${page.items[i].id}'),
-                    ),
-                  ),
-                ),
+                  // Same responsive 3-up grid as the artist detail
+                  // album list — LayoutBuilder + AlbumCard sized to the
+                  // cell, mainAxisExtent matched to actual card height.
+                  // Drift-first; full sorted list, lazy realization via
+                  // GridView.builder.
+                  child: LayoutBuilder(builder: (ctx, constraints) {
+                    const cols = 3;
+                    const sidePad = 8.0;
+                    const gap = 8.0;
+                    final cellW = (constraints.maxWidth -
+                            sidePad * 2 -
+                            gap * (cols - 1)) /
+                        cols;
+                    // cover (cellW - 16) + gap (8) + 2-line title (~36)
+                    // + artist line (~16) + slack. Slack is generous on
+                    // purpose — line-height + font scaling variations
+                    // would otherwise overflow the cell by a pixel
+                    // (logged as a noisy RenderFlex warning).
+                    final cellH = (cellW - 16) + 8 + 36 + 16 + 8;
+                    return GridView.builder(
+                      padding: const EdgeInsets.all(sidePad),
+                      gridDelegate:
+                          SliverGridDelegateWithFixedCrossAxisCount(
+                        crossAxisCount: cols,
+                        mainAxisExtent: cellH,
+                        mainAxisSpacing: gap,
+                        crossAxisSpacing: gap,
+                      ),
+                      itemCount: albums.length,
+                      itemBuilder: (ctx, i) {
+                        final album = albums[i];
+                        return AlbumCard(
+                          album: album,
+                          width: cellW,
+                          titleMaxLines: 2,
+                          onTap: () => ctx.push('/albums/${album.id}',
+                              extra: album),
+                        );
+                      },
+                    );
+                  }),
+                );
+          },
         );
   }
 }
@@ -227,71 +596,82 @@ class _LikedTab extends ConsumerWidget {
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
-    final tracksA = ref.watch(_likedTracksProvider);
-    final albumsA = ref.watch(_likedAlbumsProvider);
-    final artistsA = ref.watch(_likedArtistsProvider);
+    // SSE wire-up: any cross-device like / unlike triggers a refresh
+    // of the discovery providers. LikesController handles local
+    // mutations optimistically through the same cached_likes table,
+    // so toggling a like locally re-emits the streams instantly
+    // without needing an invalidate here.
+    ref.listen<AsyncValue<LiveEvent>>(liveEventsProvider, (_, next) {
+      final e = next.asData?.value;
+      if (e == null) return;
+      switch (e.kind) {
+        case 'track.liked':
+        case 'track.unliked':
+        case 'album.liked':
+        case 'album.unliked':
+        case 'artist.liked':
+        case 'artist.unliked':
+          ref.invalidate(_likedTrackIdsProvider);
+          ref.invalidate(_likedAlbumIdsProvider);
+          ref.invalidate(_likedArtistIdsProvider);
+      }
+    });
+    final tracksA = ref.watch(_likedTrackIdsProvider);
+    final albumsA = ref.watch(_likedAlbumIdsProvider);
+    final artistsA = ref.watch(_likedArtistIdsProvider);
 
     if (tracksA.isLoading || albumsA.isLoading || artistsA.isLoading) {
       return const Center(child: CircularProgressIndicator());
     }
-    final t = tracksA.value;
-    final al = albumsA.value;
-    final ar = artistsA.value;
-    if (t == null || al == null || ar == null) {
+    final trackIds = tracksA.value;
+    final albumIds = albumsA.value;
+    final artistIds = artistsA.value;
+    if (trackIds == null || albumIds == null || artistIds == null) {
       return Center(child: Text("Couldn't load liked items.", style: TextStyle(color: fs.error)));
     }
-    if (t.items.isEmpty && al.items.isEmpty && ar.items.isEmpty) {
-      return Center(child: Text('Nothing liked yet.', style: TextStyle(color: fs.ash)));
+    if (trackIds.isEmpty && albumIds.isEmpty && artistIds.isEmpty) {
+      return Center(child: Text('No liked artists, albums, or tracks yet.', style: TextStyle(color: fs.ash), textAlign: TextAlign.center));
     }
     return RefreshIndicator(
       onRefresh: () async {
         await Future.wait([
-          ref.refresh(_likedTracksProvider.future),
-          ref.refresh(_likedAlbumsProvider.future),
-          ref.refresh(_likedArtistsProvider.future),
+          ref.refresh(_likedTrackIdsProvider.future),
+          ref.refresh(_likedAlbumIdsProvider.future),
+          ref.refresh(_likedArtistIdsProvider.future),
         ]);
       },
       child: ListView(children: [
-        if (ar.items.isNotEmpty) ...[
-          _SectionHeader(label: 'Artists', count: ar.total),
+        if (artistIds.isNotEmpty) ...[
+          _SectionHeader(label: 'Artists', count: artistIds.length),
           SizedBox(
             height: 168,
             child: ListView.builder(
               scrollDirection: Axis.horizontal,
               padding: const EdgeInsets.symmetric(horizontal: 8),
-              itemCount: ar.items.length,
-              itemBuilder: (ctx, i) => ArtistCard(
-                artist: ar.items[i],
-                onTap: () => ctx.push('/artists/${ar.items[i].id}'),
-              ),
+              itemCount: artistIds.length,
+              itemBuilder: (ctx, i) =>
+                  _LikedArtistTile(id: artistIds[i]),
             ),
           ),
         ],
-        if (al.items.isNotEmpty) ...[
-          _SectionHeader(label: 'Albums', count: al.total),
+        if (albumIds.isNotEmpty) ...[
+          _SectionHeader(label: 'Albums', count: albumIds.length),
           SizedBox(
             height: 200,
             child: ListView.builder(
               scrollDirection: Axis.horizontal,
               padding: const EdgeInsets.symmetric(horizontal: 8),
-              itemCount: al.items.length,
-              itemBuilder: (ctx, i) => AlbumCard(
-                album: al.items[i],
-                onTap: () => ctx.push('/albums/${al.items[i].id}'),
-              ),
+              itemCount: albumIds.length,
+              itemBuilder: (ctx, i) =>
+                  _LikedAlbumTile(id: albumIds[i]),
             ),
           ),
         ],
-        if (t.items.isNotEmpty) ...[
-          _SectionHeader(label: 'Tracks', count: t.total),
-          ...t.items.asMap().entries.map((e) {
-            return TrackRow(
-              track: e.value,
-              onTap: () => ref
-                  .read(playerActionsProvider)
-                  .playTracks(t.items, initialIndex: e.key),
-            );
-          }),
+        if (trackIds.isNotEmpty) ...[
+          _SectionHeader(label: 'Tracks', count: trackIds.length),
+          ...trackIds.map(
+            (id) => _LikedTrackRow(id: id, sectionIds: trackIds),
+          ),
         ],
         const SizedBox(height: 96),
       ]),
@@ -299,13 +679,102 @@ class _LikedTab extends ConsumerWidget {
   }
 }
 
+/// Skeleton→content cross-fade duration. Matches home_screen so the
+/// reveal feel is consistent across surfaces. See _tileRevealDuration
+/// in home_screen.dart for the rationale.
+const Duration _likedTileReveal = Duration(milliseconds: 220);
+
+/// Liked-Artists carousel tile. Skeleton until artistTileProvider
+/// yields a populated row.
+class _LikedArtistTile extends ConsumerWidget {
+  const _LikedArtistTile({required this.id});
+  final String id;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final artist = ref.watch(artistTileProvider(id)).asData?.value;
+    return AnimatedSwitcher(
+      duration: _likedTileReveal,
+      switchInCurve: Curves.easeOut,
+      child: artist == null
+          ? const SkeletonArtistTile(key: ValueKey('skeleton'))
+          : ArtistCard(
+              key: ValueKey('artist-${artist.id}'),
+              artist: artist,
+              onTap: () =>
+                  context.push('/artists/${artist.id}', extra: artist),
+            ),
+    );
+  }
+}
+
+/// Liked-Albums carousel tile. Skeleton until albumTileProvider
+/// yields a populated row.
+class _LikedAlbumTile extends ConsumerWidget {
+  const _LikedAlbumTile({required this.id});
+  final String id;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final album = ref.watch(albumTileProvider(id)).asData?.value;
+    return AnimatedSwitcher(
+      duration: _likedTileReveal,
+      switchInCurve: Curves.easeOut,
+      child: album == null
+          ? const SkeletonAlbumTile(key: ValueKey('skeleton'))
+          : AlbumCard(
+              key: ValueKey('album-${album.id}'),
+              album: album,
+              onTap: () => context.push('/albums/${album.id}', extra: album),
+            ),
+    );
+  }
+}
+
+/// Liked-Tracks list row. Skeleton until trackTileProvider yields a
+/// populated row. Tap plays the section starting at this track,
+/// using whichever tracks are currently hydrated; still-loading
+/// tracks are skipped from the play queue and join on next rebuild.
+class _LikedTrackRow extends ConsumerWidget {
+  const _LikedTrackRow({required this.id, required this.sectionIds});
+  final String id;
+  final List<String> sectionIds;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final track = ref.watch(trackTileProvider(id)).asData?.value;
+    return AnimatedSwitcher(
+      duration: _likedTileReveal,
+      switchInCurve: Curves.easeOut,
+      child: track == null
+          ? const SkeletonTrackRow(key: ValueKey('skeleton'))
+          : TrackRow(
+              key: ValueKey('track-${track.id}'),
+              track: track,
+              onTap: () {
+                final hydrated = <TrackRef>[];
+                for (final i in sectionIds) {
+                  final v = ref.read(trackTileProvider(i)).asData?.value;
+                  if (v != null) hydrated.add(v);
+                }
+                final start = hydrated.indexWhere((t) => t.id == id);
+                ref.read(playerActionsProvider).playTracks(
+                      hydrated,
+                      initialIndex: start < 0 ? 0 : start,
+                    );
+              },
+            ),
+    );
+  }
+}
+
 class _HiddenTab extends ConsumerWidget {
   const _HiddenTab();
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
-    return ref.watch(_quarantineProvider).when(
+    return ref.watch(myQuarantineProvider).when(
           loading: () => const Center(child: CircularProgressIndicator()),
           error: (e, _) => Center(child: Text('$e', style: TextStyle(color: fs.error))),
           data: (rows) => rows.isEmpty
@@ -317,7 +786,7 @@ class _HiddenTab extends ConsumerWidget {
                   ),
                 )
               : RefreshIndicator(
-                  onRefresh: () async => ref.refresh(_quarantineProvider.future),
+                  onRefresh: () async => ref.refresh(myQuarantineProvider.future),
                   child: ListView.separated(
                     itemCount: rows.length,
                     separatorBuilder: (_, __) => Divider(height: 1, color: fs.iron),
@@ -328,12 +797,12 @@ class _HiddenTab extends ConsumerWidget {
   }
 }
 
-class _QuarantineTile extends StatelessWidget {
+class _QuarantineTile extends ConsumerWidget {
   const _QuarantineTile({required this.row});
   final QuarantineMineRow row;
 
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     final reasonLabel = switch (row.reason) {
       'bad_rip' => 'Bad rip',
@@ -342,9 +811,25 @@ class _QuarantineTile extends StatelessWidget {
       'duplicate' => 'Duplicate',
       _ => 'Other',
     };
+    final coverUrl = row.albumId.isNotEmpty ? '/api/albums/${row.albumId}/cover' : '';
     return Padding(
       padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
       child: Row(crossAxisAlignment: CrossAxisAlignment.start, children: [
+        ClipRRect(
+          borderRadius: BorderRadius.circular(4),
+          child: SizedBox(
+            width: 56,
+            height: 56,
+            child: coverUrl.isEmpty
+                ? Container(color: fs.slate)
+                : ServerImage(
+                    url: coverUrl,
+                    fit: BoxFit.cover,
+                    fallback: Container(color: fs.slate),
+                  ),
+          ),
+        ),
+        const SizedBox(width: 12),
         Expanded(
           child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
             Text(
@@ -361,17 +846,41 @@ class _QuarantineTile extends StatelessWidget {
             ),
             Padding(
               padding: const EdgeInsets.only(top: 4),
-              child: Container(
-                padding: const EdgeInsets.symmetric(horizontal: 6, vertical: 2),
-                decoration: BoxDecoration(
-                  color: fs.iron,
-                  borderRadius: BorderRadius.circular(4),
+              child: Row(children: [
+                Container(
+                  padding: const EdgeInsets.symmetric(horizontal: 6, vertical: 2),
+                  decoration: BoxDecoration(
+                    color: fs.iron,
+                    borderRadius: BorderRadius.circular(4),
+                  ),
+                  child: Text(reasonLabel, style: TextStyle(color: fs.ash, fontSize: 11)),
                 ),
-                child: Text(reasonLabel, style: TextStyle(color: fs.ash, fontSize: 11)),
-              ),
+                if (row.createdAt.isNotEmpty) ...[
+                  const SizedBox(width: 8),
+                  Text(_relativeTime(row.createdAt),
+                      style: TextStyle(color: fs.ash, fontSize: 11)),
+                ],
+              ]),
             ),
           ]),
         ),
+        IconButton(
+          tooltip: 'Unhide',
+          icon: Icon(Icons.restore, color: fs.ash, size: 20),
+          onPressed: () async {
+            try {
+              await ref.read(myQuarantineProvider.notifier).unflag(row.trackId);
+            } catch (_) {
+              // Optimistic rollback handled by the notifier; surface
+              // the failure only if the user kept the tab open.
+              if (context.mounted) {
+                ScaffoldMessenger.of(context).showSnackBar(
+                  const SnackBar(content: Text('Could not unhide; try again.')),
+                );
+              }
+            }
+          },
+        ),
       ]),
     );
   }

flutter_client/lib/library/widgets/album_card.dart

@@ -1,51 +1,112 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:flutter_svg/flutter_svg.dart';
 
 import '../../models/album.dart';
+import '../../player/player_provider.dart';
+import '../../shared/widgets/server_image.dart';
 import '../../theme/theme_extension.dart';
+import '../library_providers.dart';
+import 'play_circle_button.dart';
 
-class AlbumCard extends StatelessWidget {
-  const AlbumCard({required this.album, required this.onTap, super.key});
+class AlbumCard extends ConsumerWidget {
+  const AlbumCard({
+    required this.album,
+    required this.onTap,
+    this.width = 140,
+    this.titleMaxLines = 1,
+    this.showArtist = true,
+    super.key,
+  });
   final AlbumRef album;
   final VoidCallback onTap;
 
+  /// Outer width of the card. Cover is square at width - 16 (8dp
+  /// horizontal padding either side). Default suits horizontal lists;
+  /// grids should pass the cell width so the card scales down.
+  final double width;
+
+  /// Lets callers (e.g. the artist detail grid) allow the title to
+  /// wrap to a second line so it isn't truncated to a single
+  /// ellipsized character at narrower widths.
+  final int titleMaxLines;
+
+  /// Suppress the artist name. Useful on surfaces where the artist is
+  /// already implied by the page header (e.g. artist detail).
+  final bool showArtist;
+
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
-    return GestureDetector(
-      onTap: onTap,
-      child: SizedBox(
-        width: 140,
-        child: Padding(
-          padding: const EdgeInsets.symmetric(horizontal: 8),
-          child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
-            ClipRRect(
-              borderRadius: BorderRadius.circular(6),
-              child: Container(
-                width: 124,
-                height: 124,
-                color: fs.slate,
-                child: album.coverUrl.isEmpty
-                    ? SvgPicture.asset('assets/svg/album-fallback.svg', fit: BoxFit.cover)
-                    : Image.network(album.coverUrl, fit: BoxFit.cover),
-              ),
+    final coverSize = width - 16;
+    return SizedBox(
+      width: width,
+      child: Material(
+        color: Colors.transparent,
+        child: InkWell(
+          onTap: onTap,
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 8),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                // Stack: cover image + overlaid play button at bottom-right.
+                Stack(
+                  children: [
+                    ClipRRect(
+                      borderRadius: BorderRadius.circular(6),
+                      child: Container(
+                        width: coverSize,
+                        height: coverSize,
+                        color: fs.slate,
+                        child: album.coverUrl.isEmpty
+                            ? SvgPicture.asset('assets/svg/album-fallback.svg',
+                                fit: BoxFit.cover)
+                            : ServerImage(url: album.coverUrl, fit: BoxFit.cover),
+                      ),
+                    ),
+                    Positioned(
+                      bottom: 6,
+                      right: 6,
+                      child: PlayCircleButton(
+                        onPressed: () => _playAlbum(ref),
+                      ),
+                    ),
+                  ],
+                ),
+                const SizedBox(height: 8),
+                Text(
+                  album.title,
+                  maxLines: titleMaxLines,
+                  overflow: TextOverflow.ellipsis,
+                  style: TextStyle(color: fs.parchment, fontSize: 14),
+                ),
+                if (showArtist && album.artistName.isNotEmpty)
+                  Text(
+                    album.artistName,
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(color: fs.ash, fontSize: 12),
+                  ),
+              ],
             ),
-            const SizedBox(height: 8),
-            Text(
-              album.title,
-              maxLines: 1,
-              overflow: TextOverflow.ellipsis,
-              style: TextStyle(color: fs.parchment, fontSize: 14),
-            ),
-            Text(
-              album.artistName,
-              maxLines: 1,
-              overflow: TextOverflow.ellipsis,
-              style: TextStyle(color: fs.ash, fontSize: 12),
-            ),
-          ]),
+          ),
         ),
       ),
     );
   }
+
+  /// Fetches the album's tracks via /api/albums/{id} and starts playback
+  /// from the first track. Errors are swallowed by the button's outer
+  /// try/finally; callers don't surface them — failed fetches just keep
+  /// the spinner visible until the button is retapped.
+  Future<void> _playAlbum(WidgetRef ref) async {
+    final api = await ref.read(libraryApiProvider.future);
+    final result = await api.getAlbum(album.id);
+    if (result.tracks.isEmpty) return;
+    await ref
+        .read(playerActionsProvider)
+        .playTracks(result.tracks, initialIndex: 0);
+  }
 }

flutter_client/lib/library/widgets/artist_card.dart

@@ -1,44 +1,101 @@
+import 'dart:math';
+
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:flutter_svg/flutter_svg.dart';
 
 import '../../models/artist.dart';
+import '../../player/player_provider.dart';
+import '../../shared/widgets/server_image.dart';
 import '../../theme/theme_extension.dart';
+import '../library_providers.dart';
+import 'play_circle_button.dart';
 
-class ArtistCard extends StatelessWidget {
-  const ArtistCard({required this.artist, required this.onTap, super.key});
+class ArtistCard extends ConsumerWidget {
+  const ArtistCard({
+    required this.artist,
+    required this.onTap,
+    this.width = 140,
+    super.key,
+  });
   final ArtistRef artist;
   final VoidCallback onTap;
 
+  /// Outer width of the card. Avatar is a circle of width-16 (8dp
+  /// horizontal padding either side). Default suits horizontal lists;
+  /// grids should pass the cell width so the avatar shrinks
+  /// proportionally and stays a true circle.
+  final double width;
+
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
-    return GestureDetector(
-      onTap: onTap,
-      child: SizedBox(
-        width: 140,
-        child: Padding(
-          padding: const EdgeInsets.symmetric(horizontal: 8),
-          child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
-            ClipOval(
-              child: Container(
-                width: 124,
-                height: 124,
-                color: fs.slate,
-                child: artist.coverUrl.isEmpty
-                    ? SvgPicture.asset('assets/svg/album-fallback.svg', fit: BoxFit.cover)
-                    : Image.network(artist.coverUrl, fit: BoxFit.cover),
+    final coverSize = width - 16;
+    return SizedBox(
+      width: width,
+      child: Material(
+        color: Colors.transparent,
+        child: InkWell(
+          onTap: onTap,
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 8),
+            child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+              // Stack: circular avatar + overlaid play button at bottom-right.
+              // Avatar size derives from the [width] parameter so the
+              // Library Artists 3-column grid can pass its cell width
+              // (~109dp on typical phones) and the avatar stays a
+              // perfect circle. Previous hardcoded 124×124 got squeezed
+              // horizontally in the grid (cell narrower than 124+16
+              // padding) but kept its 124dp height — ClipOval produced
+              // a visible vertical ellipse. Mirrors AlbumCard's width-
+              // parameter convention.
+              Stack(
+                children: [
+                  ClipOval(
+                    child: Container(
+                      width: coverSize,
+                      height: coverSize,
+                      color: fs.slate,
+                      child: artist.coverUrl.isEmpty
+                          ? SvgPicture.asset('assets/svg/album-fallback.svg',
+                              fit: BoxFit.cover)
+                          : ServerImage(url: artist.coverUrl, fit: BoxFit.cover),
+                    ),
+                  ),
+                  Positioned(
+                    bottom: 4,
+                    right: 4,
+                    child: PlayCircleButton(
+                      onPressed: () => _playArtistShuffle(ref),
+                    ),
+                  ),
+                ],
               ),
-            ),
-            const SizedBox(height: 8),
-            Text(
-              artist.name,
-              maxLines: 1,
-              overflow: TextOverflow.ellipsis,
-              style: TextStyle(color: fs.parchment, fontSize: 14),
-            ),
-          ]),
+              const SizedBox(height: 8),
+              Text(
+                artist.name,
+                maxLines: 1,
+                overflow: TextOverflow.ellipsis,
+                style: TextStyle(color: fs.parchment, fontSize: 14),
+              ),
+            ]),
+          ),
         ),
       ),
     );
   }
+
+  /// Fetches the artist's tracks via /api/artists/{id}/tracks, shuffles
+  /// them (Fisher-Yates, default Random), and plays from index 0.
+  /// Matches the web ArtistCard's `playQueue(shuffle(tracks), 0)`.
+  Future<void> _playArtistShuffle(WidgetRef ref) async {
+    final api = await ref.read(libraryApiProvider.future);
+    final tracks = await api.getArtistTracks(artist.id);
+    if (tracks.isEmpty) return;
+    final shuffled = List.of(tracks);
+    shuffled.shuffle(Random());
+    await ref
+        .read(playerActionsProvider)
+        .playTracks(shuffled, initialIndex: 0);
+  }
 }

flutter_client/lib/library/widgets/cached_indicator.dart

@@ -0,0 +1,29 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../cache/audio_cache_manager.dart';
+import '../../theme/theme_extension.dart';
+
+/// Small download glyph shown next to a track row when the track is
+/// cached locally. FutureBuilder one-shot — track rows are short-lived
+/// and cache state rarely changes mid-render.
+class CachedIndicator extends ConsumerWidget {
+  const CachedIndicator({required this.trackId, super.key});
+  final String trackId;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final mgr = ref.read(audioCacheManagerProvider);
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return FutureBuilder<bool>(
+      future: mgr.isCached(trackId),
+      builder: (ctx, snap) {
+        if (snap.data != true) return const SizedBox.shrink();
+        return Padding(
+          padding: const EdgeInsets.only(left: 4),
+          child: Icon(Icons.download_done, size: 14, color: fs.accent),
+        );
+      },
+    );
+  }
+}

flutter_client/lib/library/widgets/compact_track_card.dart

@@ -0,0 +1,84 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../models/track.dart';
+import '../../player/player_provider.dart';
+import '../../shared/widgets/server_image.dart';
+import '../../shared/widgets/track_actions/track_actions_button.dart';
+import '../../theme/theme_extension.dart';
+
+/// Small horizontal track cell used by the home Most-played section.
+/// Mirrors the web CompactTrackCard sizing (~176dp wide, ~56dp tall).
+/// Tap plays from this track within [sectionTracks] starting at [index].
+class CompactTrackCard extends ConsumerWidget {
+  const CompactTrackCard({
+    super.key,
+    required this.track,
+    required this.sectionTracks,
+    required this.index,
+  });
+
+  final TrackRef track;
+
+  /// All tracks in the home section so play-from-here can queue them
+  /// in order.
+  final List<TrackRef> sectionTracks;
+  final int index;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // Cover URL derives from the track's album. Mirrors web
+    // CompactTrackCard which calls coverUrl(track.album_id).
+    final coverUrl = track.albumId.isNotEmpty
+        ? '/api/albums/${track.albumId}/cover'
+        : '';
+    return SizedBox(
+      width: 176,
+      child: InkWell(
+        onTap: () => ref
+            .read(playerActionsProvider)
+            .playTracks(sectionTracks, initialIndex: index),
+        child: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 4),
+          child: Row(children: [
+            ClipRRect(
+              borderRadius: BorderRadius.circular(4),
+              child: SizedBox(
+                width: 48,
+                height: 48,
+                child: ServerImage(
+                  url: coverUrl,
+                  fit: BoxFit.cover,
+                  fallback: Container(color: fs.slate),
+                ),
+              ),
+            ),
+            const SizedBox(width: 8),
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                mainAxisAlignment: MainAxisAlignment.center,
+                children: [
+                  Text(
+                    track.title,
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(color: fs.parchment, fontSize: 13),
+                  ),
+                  Text(
+                    track.artistName,
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(color: fs.ash, fontSize: 11),
+                  ),
+                ],
+              ),
+            ),
+            TrackActionsButton(track: track),
+          ]),
+        ),
+      ),
+    );
+  }
+}

flutter_client/lib/library/widgets/horizontal_scroll_row.dart

@@ -23,17 +23,18 @@ class HorizontalScrollRow extends StatelessWidget {
   Widget build(BuildContext context) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     return Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
-      Padding(
-        padding: const EdgeInsets.fromLTRB(16, 8, 16, 8),
-        child: Text(
-          title,
-          style: TextStyle(
-            fontFamily: fs.display.fontFamily,
-            fontSize: 18,
-            color: fs.parchment,
+      if (title.isNotEmpty)
+        Padding(
+          padding: const EdgeInsets.fromLTRB(16, 8, 16, 8),
+          child: Text(
+            title,
+            style: TextStyle(
+              fontFamily: fs.display.fontFamily,
+              fontSize: 18,
+              color: fs.parchment,
+            ),
           ),
         ),
-      ),
       SizedBox(
         height: height,
         child: ListView(

flutter_client/lib/library/widgets/play_circle_button.dart

@@ -0,0 +1,96 @@
+import 'package:flutter/material.dart';
+
+import '../../theme/theme_extension.dart';
+
+/// Always-visible 44dp circular play button overlaid on home-screen
+/// card art (AlbumCard / ArtistCard / PlaylistCard). Mirrors the
+/// hover-revealed `.play-overlay` on the web cards, but always shown
+/// because hover is not a real interaction on touch.
+///
+/// Manages its own loading state via [_starting] so the caller's tap
+/// handler can be `Future<void> Function()` without worrying about
+/// re-entrancy. Disabled state suppresses the tap (used for empty
+/// playlists).
+class PlayCircleButton extends StatefulWidget {
+  const PlayCircleButton({
+    required this.onPressed,
+    this.enabled = true,
+    this.size = 44,
+    super.key,
+  });
+
+  /// Tap handler. Returns a Future so the button can show a spinner
+  /// during the play setup (fetch detail tracks, etc.).
+  final Future<void> Function() onPressed;
+
+  /// When false, the button is rendered semi-transparent and taps are
+  /// ignored. Empty playlists / artists with no tracks should disable.
+  final bool enabled;
+
+  /// Outer diameter in logical pixels. 44 is the iOS / Android
+  /// touch-target minimum; matches the design doc.
+  final double size;
+
+  @override
+  State<PlayCircleButton> createState() => _PlayCircleButtonState();
+}
+
+class _PlayCircleButtonState extends State<PlayCircleButton> {
+  bool _starting = false;
+
+  Future<void> _handleTap() async {
+    if (_starting || !widget.enabled) return;
+    setState(() => _starting = true);
+    try {
+      await widget.onPressed();
+    } finally {
+      if (mounted) setState(() => _starting = false);
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final iconSize = widget.size * 0.5;
+    return Material(
+      color: Colors.transparent,
+      shape: const CircleBorder(),
+      child: InkResponse(
+        onTap: widget.enabled ? _handleTap : null,
+        radius: widget.size / 2,
+        containedInkWell: true,
+        customBorder: const CircleBorder(),
+        child: Container(
+          width: widget.size,
+          height: widget.size,
+          decoration: BoxDecoration(
+            color: fs.accent.withValues(alpha: widget.enabled ? 1.0 : 0.5),
+            shape: BoxShape.circle,
+            boxShadow: const [
+              BoxShadow(
+                color: Color(0x66000000),
+                blurRadius: 6,
+                offset: Offset(0, 2),
+              ),
+            ],
+          ),
+          alignment: Alignment.center,
+          child: _starting
+              ? SizedBox(
+                  width: iconSize,
+                  height: iconSize,
+                  child: CircularProgressIndicator(
+                    strokeWidth: 2,
+                    valueColor: AlwaysStoppedAnimation<Color>(fs.parchment),
+                  ),
+                )
+              : Icon(
+                  Icons.play_arrow,
+                  color: fs.parchment,
+                  size: iconSize,
+                ),
+        ),
+      ),
+    );
+  }
+}

flutter_client/lib/library/widgets/track_row.dart

@@ -1,60 +1,99 @@
 import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../../models/track.dart';
+import '../../player/player_provider.dart';
+import '../../shared/widgets/track_actions/track_actions_button.dart';
 import '../../theme/theme_extension.dart';
+import 'cached_indicator.dart';
 
-class TrackRow extends StatelessWidget {
+class TrackRow extends ConsumerWidget {
   const TrackRow({
     required this.track,
     required this.onTap,
     this.trailing,
+    this.actions = true,
     super.key,
   });
   final TrackRef track;
   final VoidCallback onTap;
   final Widget? trailing;
 
+  /// Render the 3-dot TrackActionsButton at the end of the row. Default
+  /// true; pass false in surfaces that don't want the menu (e.g. when
+  /// showing a static read-only list).
+  final bool actions;
+
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     final mins = (track.durationSec ~/ 60).toString().padLeft(2, '0');
     final secs = (track.durationSec % 60).toString().padLeft(2, '0');
-    return InkWell(
-      onTap: onTap,
-      child: Padding(
-        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
-        child: Row(children: [
-          if (track.trackNumber != null)
-            SizedBox(
-              width: 28,
-              child: Text(
-                track.trackNumber.toString(),
-                style: TextStyle(color: fs.ash, fontSize: 13),
+    // Watch the currently-playing media item so the row's accent
+    // highlight tracks playback state. Matches _QueueRow's visual
+    // treatment in queue_screen.dart so the "you are here" cue is
+    // consistent across album / playlist / queue surfaces.
+    final currentId = ref.watch(mediaItemProvider).value?.id;
+    final isCurrent = currentId != null && currentId == track.id;
+    return Container(
+      decoration: BoxDecoration(
+        color: isCurrent ? fs.iron : null,
+        border: isCurrent
+            ? Border(left: BorderSide(color: fs.accent, width: 2))
+            : null,
+      ),
+      child: InkWell(
+        onTap: onTap,
+        child: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 6),
+          child: Row(children: [
+            if (track.trackNumber != null)
+              SizedBox(
+                width: 22,
+                child: Text(
+                  track.trackNumber.toString(),
+                  style: TextStyle(color: fs.ash, fontSize: 13),
+                ),
+              ),
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  Text(
+                    track.title,
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(
+                      color: isCurrent ? fs.accent : fs.parchment,
+                      fontSize: 14,
+                      fontWeight:
+                          isCurrent ? FontWeight.w500 : FontWeight.w400,
+                    ),
+                  ),
+                  // Skip the artist line entirely when empty so the row
+                  // height collapses to a single line of title — keeps
+                  // dense album views from looking padded.
+                  if (track.artistName.isNotEmpty)
+                    Text(
+                      track.artistName,
+                      maxLines: 1,
+                      overflow: TextOverflow.ellipsis,
+                      style: TextStyle(color: fs.ash, fontSize: 12),
+                    ),
+                ],
               ),
             ),
-          Expanded(
-            child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
-              Text(
-                track.title,
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-                style: TextStyle(color: fs.parchment, fontSize: 14),
+            CachedIndicator(trackId: track.id),
+            Text('$mins:$secs', style: TextStyle(color: fs.ash, fontSize: 12)),
+            if (trailing != null)
+              Padding(
+                padding: const EdgeInsets.only(left: 8),
+                child: trailing!,
               ),
-              Text(
-                track.artistName,
-                maxLines: 1,
-                overflow: TextOverflow.ellipsis,
-                style: TextStyle(color: fs.ash, fontSize: 12),
-              ),
-            ]),
-          ),
-          Text('$mins:$secs', style: TextStyle(color: fs.ash, fontSize: 12)),
-          if (trailing != null)
-            Padding(
-              padding: const EdgeInsets.only(left: 8),
-              child: trailing!,
-            ),
-        ]),
+            if (actions) TrackActionsButton(track: track),
+          ]),
+        ),
       ),
     );
   }

flutter_client/lib/likes/like_button.dart

@@ -30,7 +30,7 @@ class LikeButton extends ConsumerWidget {
         color: liked ? fs.accent : fs.ash,
         size: size,
       ),
-      onPressed: () => ref.read(likedIdsProvider.notifier).toggle(kind, id),
+      onPressed: () => ref.read(likesControllerProvider).toggle(kind, id),
     );
   }
 }

flutter_client/lib/likes/likes_provider.dart

@@ -1,6 +1,13 @@
+import 'package:drift/drift.dart' as drift;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../api/endpoints/likes.dart';
+import '../auth/auth_provider.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../cache/cache_first.dart';
+import '../cache/connectivity_provider.dart';
+import '../cache/db.dart';
+import '../cache/mutation_queue.dart';
 import '../library/library_providers.dart';
 
 final likesApiProvider = FutureProvider<LikesApi>((ref) async {
@@ -22,67 +29,146 @@ class LikedIds {
         LikeKind.album => albums.contains(id),
         LikeKind.track => tracks.contains(id),
       };
+
+  static const empty = LikedIds(artists: {}, albums: {}, tracks: {});
 }
 
-class LikedIdsController extends AsyncNotifier<LikedIds> {
-  @override
-  Future<LikedIds> build() async {
-    final api = await ref.watch(likesApiProvider.future);
-    final r = await api.ids();
-    return LikedIds(artists: r.artists, albums: r.albums, tracks: r.tracks);
-  }
+/// Drift-first per #357 plan C. Reads from cached_likes (populated by
+/// SyncController). Reactive — sync writes propagate via watch().
+/// Empty + online triggers REST cold-cache fallback that re-populates.
+final likedIdsProvider = StreamProvider<LikedIds>((ref) {
+  final db = ref.watch(appDbProvider);
+  return cacheFirst<CachedLike, LikedIds>(
+    driftStream: db.select(db.cachedLikes).watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(likesApiProvider.future);
+      final fresh = await api.ids();
+      // Need a userId for the composite primary key. The auth controller
+      // exposes the current user.
+      final user = ref.read(authControllerProvider).value;
+      if (user == null) return; // not logged in; skip
+      await db.batch((b) {
+        for (final id in fresh.tracks) {
+          b.insert(
+            db.cachedLikes,
+            CachedLikesCompanion.insert(
+              userId: user.id,
+              entityType: 'track',
+              entityId: id,
+            ),
+            mode: drift.InsertMode.insertOrIgnore,
+          );
+        }
+        for (final id in fresh.albums) {
+          b.insert(
+            db.cachedLikes,
+            CachedLikesCompanion.insert(
+              userId: user.id,
+              entityType: 'album',
+              entityId: id,
+            ),
+            mode: drift.InsertMode.insertOrIgnore,
+          );
+        }
+        for (final id in fresh.artists) {
+          b.insert(
+            db.cachedLikes,
+            CachedLikesCompanion.insert(
+              userId: user.id,
+              entityType: 'artist',
+              entityId: id,
+            ),
+            mode: drift.InsertMode.insertOrIgnore,
+          );
+        }
+      });
+    },
+    toResult: (rows) => LikedIds(
+      tracks: rows
+          .where((r) => r.entityType == 'track')
+          .map((r) => r.entityId)
+          .toSet(),
+      albums: rows
+          .where((r) => r.entityType == 'album')
+          .map((r) => r.entityId)
+          .toSet(),
+      artists: rows
+          .where((r) => r.entityType == 'artist')
+          .map((r) => r.entityId)
+          .toSet(),
+    ),
+    isOnline: () async => (await ref.read(connectivityProvider.future)),
+  );
+});
+
+/// Mutation controller. Writes optimistically to drift first (so the
+/// likedIdsProvider stream re-emits immediately for snappy UI), then to
+/// REST. Rolls back drift on REST failure.
+class LikesController {
+  LikesController(this._ref);
+  final Ref _ref;
 
   Future<void> toggle(LikeKind kind, String id) async {
-    final api = await ref.read(likesApiProvider.future);
-    final current = state.value ??
-        const LikedIds(artists: {}, albums: {}, tracks: {});
+    final user = _ref.read(authControllerProvider).value;
+    if (user == null) return;
+    final db = _ref.read(appDbProvider);
+    final entityType = _entityType(kind);
 
-    final isLiked = current.has(kind, id);
-    final optimistic = _flip(current, kind, id);
-    state = AsyncData(optimistic);
+    final existing = await (db.select(db.cachedLikes)
+          ..where((t) =>
+              t.userId.equals(user.id) &
+              t.entityType.equals(entityType) &
+              t.entityId.equals(id)))
+        .getSingleOrNull();
+    final wasLiked = existing != null;
+
+    // Optimistic mutation — drift watch() re-emits immediately.
+    if (wasLiked) {
+      await (db.delete(db.cachedLikes)
+            ..where((t) =>
+                t.userId.equals(user.id) &
+                t.entityType.equals(entityType) &
+                t.entityId.equals(id)))
+          .go();
+    } else {
+      await db.into(db.cachedLikes).insert(
+            CachedLikesCompanion.insert(
+              userId: user.id,
+              entityType: entityType,
+              entityId: id,
+            ),
+            mode: drift.InsertMode.insertOrIgnore,
+          );
+    }
 
     try {
-      if (isLiked) {
+      final api = await _ref.read(likesApiProvider.future);
+      if (wasLiked) {
         await api.unlike(kind, id);
       } else {
         await api.like(kind, id);
       }
-    } catch (e, st) {
-      state = AsyncData(current);
-      Error.throwWithStackTrace(e, st);
+    } catch (_) {
+      // REST failed (network or HTTP). Don't roll back drift — the
+      // user's intent is to like/unlike, and we want that visible to
+      // them even when offline. Queue the call for replay; the
+      // MutationReplayer will retry on next connectivity transition.
+      // If retries exhaust (5 attempts), the row drops and the next
+      // SyncController.sync brings drift back in line with the
+      // server's authoritative state.
+      await _ref.read(mutationQueueProvider).enqueue(
+        wasLiked ? MutationKinds.likeRemove : MutationKinds.likeAdd,
+        {'kind': entityType, 'id': id},
+      );
     }
   }
 
-  LikedIds _flip(LikedIds before, LikeKind kind, String id) {
-    Set<String> swap(Set<String> s) {
-      final next = {...s};
-      if (s.contains(id)) {
-        next.remove(id);
-      } else {
-        next.add(id);
-      }
-      return next;
-    }
-
-    return switch (kind) {
-      LikeKind.artist => LikedIds(
-          artists: swap(before.artists),
-          albums: before.albums,
-          tracks: before.tracks,
-        ),
-      LikeKind.album => LikedIds(
-          artists: before.artists,
-          albums: swap(before.albums),
-          tracks: before.tracks,
-        ),
-      LikeKind.track => LikedIds(
-          artists: before.artists,
-          albums: before.albums,
-          tracks: swap(before.tracks),
-        ),
-    };
-  }
+  String _entityType(LikeKind kind) => switch (kind) {
+        LikeKind.artist => 'artist',
+        LikeKind.album => 'album',
+        LikeKind.track => 'track',
+      };
 }
 
-final likedIdsProvider =
-    AsyncNotifierProvider<LikedIdsController, LikedIds>(LikedIdsController.new);
+final likesControllerProvider =
+    Provider<LikesController>((ref) => LikesController(ref));

flutter_client/lib/models/admin_request.dart

@@ -18,6 +18,9 @@ class AdminRequest {
     this.notes,
     required this.importedAlbumCount,
     required this.importedTrackCount,
+    this.matchedTrackId,
+    this.matchedAlbumId,
+    this.matchedArtistId,
   });
 
   final String id;
@@ -38,6 +41,13 @@ class AdminRequest {
   final int importedAlbumCount;
   final int importedTrackCount;
 
+  /// Set when the ingest matched into the local library. The user-side
+  /// "Listen" CTA on a completed request links to whichever id is set
+  /// (most-specific first: track → album → artist).
+  final String? matchedTrackId;
+  final String? matchedAlbumId;
+  final String? matchedArtistId;
+
   /// Display label depending on the kind of request — what the user
   /// asked for. For an album request it's the album title; for an
   /// artist request it's the artist name; etc.
@@ -60,5 +70,8 @@ class AdminRequest {
         notes: j['notes'] as String?,
         importedAlbumCount: (j['imported_album_count'] as int?) ?? 0,
         importedTrackCount: (j['imported_track_count'] as int?) ?? 0,
+        matchedTrackId: j['matched_track_id'] as String?,
+        matchedAlbumId: j['matched_album_id'] as String?,
+        matchedArtistId: j['matched_artist_id'] as String?,
       );
 }

flutter_client/lib/models/home_index.dart

@@ -0,0 +1,41 @@
+/// Mirrors internal/api/types.go HomeIndexPayload. Five flat slices of
+/// entity ID strings — the per-item rendering variant of HomeData.
+/// Section name implies entity type; no per-entry type tag is needed.
+///
+/// Slices are non-null after fromJson so callers can branch on `length`
+/// instead of dealing with null sections.
+class HomeIndex {
+  const HomeIndex({
+    required this.recentlyAddedAlbums,
+    required this.rediscoverAlbums,
+    required this.rediscoverArtists,
+    required this.mostPlayedTracks,
+    required this.lastPlayedArtists,
+  });
+
+  final List<String> recentlyAddedAlbums;
+  final List<String> rediscoverAlbums;
+  final List<String> rediscoverArtists;
+  final List<String> mostPlayedTracks;
+  final List<String> lastPlayedArtists;
+
+  static const empty = HomeIndex(
+    recentlyAddedAlbums: [],
+    rediscoverAlbums: [],
+    rediscoverArtists: [],
+    mostPlayedTracks: [],
+    lastPlayedArtists: [],
+  );
+
+  factory HomeIndex.fromJson(Map<String, dynamic> j) {
+    List<String> ids(String key) =>
+        ((j[key] as List?) ?? const []).map((e) => e.toString()).toList();
+    return HomeIndex(
+      recentlyAddedAlbums: ids('recently_added_albums'),
+      rediscoverAlbums: ids('rediscover_albums'),
+      rediscoverArtists: ids('rediscover_artists'),
+      mostPlayedTracks: ids('most_played_tracks'),
+      lastPlayedArtists: ids('last_played_artists'),
+    );
+  }
+}

flutter_client/lib/models/playlist.dart

@@ -38,6 +38,16 @@ class Playlist {
 
   bool get isSystem => systemVariant != null;
 
+  /// Whether this playlist supports the generic by-kind refresh/
+  /// shuffle endpoints (#411 R2) — i.e. a singleton system kind.
+  /// The server exposes a `refreshable` flag for JSON-sourced
+  /// playlists, but the list tiles are drift-cache-sourced (no
+  /// migration just for this), so derive it: every system kind is a
+  /// singleton except songs_like_artist (multi-per-user). This rule
+  /// holds for For-You/Discover and all planned discovery mixes; if
+  /// a future non-singleton kind appears, extend the exclusion.
+  bool get refreshable => isSystem && systemVariant != 'songs_like_artist';
+
   factory Playlist.fromJson(Map<String, dynamic> j) => Playlist(
         id: j['id'] as String,
         userId: j['user_id'] as String? ?? '',

flutter_client/lib/models/system_playlists_status.dart

@@ -0,0 +1,24 @@
+/// Mirrors `systemPlaylistsStatusResp` from internal/api/me_system_playlists.go.
+/// Reflects the caller's most recent system_playlist_runs row, or zero
+/// values when no row exists yet (the user has never had a build attempted).
+class SystemPlaylistsStatus {
+  const SystemPlaylistsStatus({
+    required this.inFlight,
+    this.lastRunAt,
+    this.lastError,
+  });
+
+  final bool inFlight;
+  final String? lastRunAt;
+  final String? lastError;
+
+  factory SystemPlaylistsStatus.empty() =>
+      const SystemPlaylistsStatus(inFlight: false);
+
+  factory SystemPlaylistsStatus.fromJson(Map<String, dynamic> j) =>
+      SystemPlaylistsStatus(
+        inFlight: j['in_flight'] as bool? ?? false,
+        lastRunAt: j['last_run_at'] as String?,
+        lastError: j['last_error'] as String?,
+      );
+}

flutter_client/lib/player/album_color_extractor.dart

@@ -0,0 +1,92 @@
+// Dominant-color extraction from album cover art (#396 item 1).
+// The full-screen Now Playing screen uses this to paint a top-to-bottom
+// gradient backdrop that grounds each track in its album's palette.
+//
+// Implementation: reuses AlbumCoverCache to get a local file path for
+// the cover, then runs PaletteGenerator over it. Results are cached
+// in-memory keyed by album_id so back-to-back plays of the same album
+// don't repeat the work. Cache is process-lifetime; album-art changes
+// are rare enough that LRU eviction isn't worth the complexity.
+//
+// Returns null on any failure (no cover, empty album_id, palette
+// extraction returned nothing). Callers fall back to the FabledSword
+// obsidian color for the gradient when null.
+
+import 'dart:io';
+
+import 'package:flutter/painting.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:palette_generator/palette_generator.dart';
+
+import 'player_provider.dart';
+
+/// Caches dominant colors keyed by album_id. Process-lifetime; refilled
+/// on app restart.
+class AlbumColorCache {
+  AlbumColorCache(this._ref);
+
+  final Ref _ref;
+  final Map<String, Color?> _cache = {};
+
+  /// Returns the dominant color for the album's cover, or null if no
+  /// cover is available or extraction fails. Same call for the same
+  /// album_id is cached after the first successful resolution.
+  Future<Color?> getOrExtract(String albumId) async {
+    if (albumId.isEmpty) return null;
+    if (_cache.containsKey(albumId)) return _cache[albumId];
+    final color = await _extract(albumId);
+    _cache[albumId] = color;
+    return color;
+  }
+
+  /// Synchronous peek. Returns the previously-extracted color if this
+  /// album has been resolved this process; otherwise null. Used by
+  /// the now-playing fast-path swap so a warm cache transitions the
+  /// gradient in lockstep with the audio, instead of awaiting the
+  /// async [getOrExtract] future. A null return means "either no
+  /// extraction yet or extraction returned null" — caller falls back
+  /// to the async path.
+  Color? peekColor(String albumId) => _cache[albumId];
+
+  Future<Color?> _extract(String albumId) async {
+    try {
+      final coverCache = _ref.read(albumCoverCacheProvider);
+      final path = await coverCache.getOrFetch(albumId);
+      if (path == null) return null;
+      final file = File(path);
+      if (!await file.exists()) return null;
+      final palette = await PaletteGenerator.fromImageProvider(
+        FileImage(file),
+        // Small target size: palette extraction is CPU-bound and the
+        // gradient only needs a single dominant color, so we don't
+        // need full-resolution sampling.
+        size: const Size(80, 80),
+        maximumColorCount: 8,
+      );
+      // Prefer the explicit dominant color; fall back to the strongest
+      // muted swatch (which tends to read better as a background than
+      // a hot vibrant pick), then any populated swatch.
+      final swatch = palette.dominantColor ??
+          palette.darkMutedColor ??
+          palette.darkVibrantColor ??
+          palette.mutedColor;
+      return swatch?.color;
+    } catch (_) {
+      return null;
+    }
+  }
+}
+
+final albumColorCacheProvider = Provider<AlbumColorCache>(
+  (ref) => AlbumColorCache(ref),
+);
+
+/// Family provider: dominant color for the given album_id, or null if
+/// no cover / extraction failed. The Now Playing screen watches this
+/// keyed by the current MediaItem's album_id.
+final albumColorProvider = FutureProvider.family<Color?, String>(
+  (ref, albumId) async {
+    final cache = ref.watch(albumColorCacheProvider);
+    return cache.getOrExtract(albumId);
+  },
+);

flutter_client/lib/player/album_cover_cache.dart

@@ -0,0 +1,94 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:dio/dio.dart';
+import 'package:flutter/foundation.dart';
+import 'package:path_provider/path_provider.dart';
+
+/// Caches album cover bytes to disk so MediaItem.artUri can point at a
+/// file:// URI. Android's MediaSession framework fetches artUri itself
+/// and doesn't carry our Bearer header, so we pre-fetch via the
+/// authenticated dio and hand the system a local file path instead.
+///
+/// Cache layout: `{applicationCacheDirectory}/album_covers/{albumId}.jpg`.
+/// No explicit eviction — covers are tiny and OS clears app cache when
+/// space is tight.
+class AlbumCoverCache {
+  AlbumCoverCache({
+    required Future<Dio> Function() dioFactory,
+    Future<Directory> Function()? cacheDirFactory,
+  })  : _dioFactory = dioFactory,
+        _cacheDirFactory = cacheDirFactory ?? getApplicationCacheDirectory;
+
+  final Future<Dio> Function() _dioFactory;
+  final Future<Directory> Function() _cacheDirFactory;
+
+  /// In-flight requests keyed by albumId so concurrent callers for the
+  /// 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) {
+    if (albumId.isEmpty) return Future.value(null);
+    final existing = _inflight[albumId];
+    if (existing != null) return existing;
+    final fut = _doFetch(albumId);
+    _inflight[albumId] = fut;
+    fut.whenComplete(() => _inflight.remove(albumId));
+    return fut;
+  }
+
+  Future<String?> _doFetch(String albumId) async {
+    try {
+      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;
+
+      final dio = await _dioFactory();
+      final r = await dio.get<List<int>>(
+        '/api/albums/$albumId/cover',
+        options: Options(responseType: ResponseType.bytes),
+      );
+      final bytes = r.data;
+      if (bytes == null || bytes.isEmpty) return null;
+      await file.writeAsBytes(bytes, flush: true);
+      return filePath;
+    } catch (e) {
+      debugPrint('AlbumCoverCache: fetch failed for $albumId: $e');
+      return null;
+    }
+  }
+}

flutter_client/lib/player/audio_handler.dart

@@ -1,52 +1,476 @@
-import 'package:audio_service/audio_service.dart';
-import 'package:just_audio/just_audio.dart';
+import 'dart:async';
+import 'dart:io';
 
+import 'package:audio_service/audio_service.dart';
+import 'package:flutter/foundation.dart';
+import 'package:just_audio/just_audio.dart';
+import 'package:path_provider/path_provider.dart';
+
+import '../cache/audio_cache_manager.dart';
 import '../models/track.dart';
+import 'album_cover_cache.dart';
 
 class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandler {
   MinstrelAudioHandler() {
-    _player.playbackEventStream.listen(_broadcastState);
+    _player.playbackEventStream.listen(
+      _broadcastState,
+      // ExoPlayer surfaces stream errors (404, premature EOS, decoder
+      // failure, network drop) here. Logging alone leaves the UI
+      // claiming "now playing X" while audio is silent — the user-
+      // observable mismatch between visual and audio state. Skip
+      // forward so the queue advances past the failed track and
+      // mediaItem updates to whatever's actually playing. If the
+      // failure is at the queue tail, just_audio will go idle on its
+      // own and _broadcastState reflects that.
+      onError: (Object e, StackTrace st) {
+        debugPrint('audio_handler: playbackEventStream error: $e\n$st');
+        unawaited(_handlePlaybackError());
+      },
+    );
+    _player.currentIndexStream.listen(_onCurrentIndexChanged);
+    // Re-broadcast on shuffle/repeat changes so the PlaybackState's
+    // shuffleMode + repeatMode fields stay current for UI subscribers.
+    _player.shuffleModeEnabledStream.listen((_) => _broadcastState(null));
+    _player.loopModeStream.listen((_) => _broadcastState(null));
+    // Watch buffered-position so we can register stream-cached files
+    // in the audio cache index once they're fully downloaded. Without
+    // this, files written by LockCachingAudioSource never appear in
+    // the index and the eviction loop can't reclaim them.
+    _player.bufferedPositionStream
+        .listen((_) => unawaited(_maybeRegisterStreamCache()));
   }
 
   final AudioPlayer _player = AudioPlayer();
   String _baseUrl = '';
   String? _token;
+  AlbumCoverCache? _coverCache;
+  AudioCacheManager? _audioCacheManager;
+  LikeBridge? _likeBridge;
 
-  void configure({required String baseUrl, required String? token}) {
+  /// Trackers to dedupe registration — once we've inserted an index row
+  /// for a trackId, don't repeat the work on every buffered-position
+  /// emit. Cleared on dispose only; surviving across queue rebuilds is
+  /// fine because the index is itself the source of truth.
+  final Set<String> _streamCacheRegistered = {};
+
+  /// Cached on first use so we don't hit the platform channel every
+  /// time the buffered-position stream emits (~200ms cadence).
+  String? _cacheDirPath;
+
+  /// True while _fillRemainingSources is doing backward-fill inserts
+  /// at index 0..initialIndex-1. Each insert shifts the player's
+  /// currentIndex (it tracks the actively-playing source through
+  /// list mutations), and the resulting _onCurrentIndexChanged
+  /// callbacks would push the wrong MediaItem onto the stream
+  /// (queue.value[shifted_idx] != actively-playing track). When
+  /// the fill completes, currentIndex == initialIndex, mediaItem
+  /// is already correct, and we re-enable normal listener behavior.
+  bool _suppressIndexUpdates = false;
+
+  /// Increments on every setQueueFromTracks call. The background
+  /// fill task captures the value at start and bails if the live
+  /// counter has moved on — without this, a stale fill will keep
+  /// addAudioSource'ing tracks from the previous playlist into the
+  /// new queue, leaving the player "locked" to a corrupted state.
+  int _queueGeneration = 0;
+
+  /// Tracks the most recent setQueueFromTracks() input so
+  /// skipToQueueItem can reconstruct the source list. just_audio
+  /// requires every source to be built before it can be a skip
+  /// target, but setQueueFromTracks only builds the initial source
+  /// and fills the rest in the background — so a skip to an index
+  /// past the fill front needs to rebuild from the stored tracks.
+  List<TrackRef> _lastTracks = const [];
+
+  /// #415: which system playlist this queue was seeded from
+  /// ('for_you' | 'discover'), or null for library / user-playlist /
+  /// radio. The play-events reporter reads this so play_started
+  /// carries `source` and the server advances that rotation. A fresh
+  /// setQueueFromTracks from a non-system surface clears it; internal
+  /// rebuilds (skipToQueueItem) preserve it.
+  String? _queueSource;
+  String? get queueSource => _queueSource;
+
+  /// Volume stream for UI subscribers. Mirrors the just_audio player's
+  /// volume directly; set via setVolume(double).
+  Stream<double> get volumeStream => _player.volumeStream;
+  double get volume => _player.volume;
+
+  /// Position stream for UI subscribers. just_audio emits roughly every
+  /// 200ms while playing, which is what makes the seek bar advance
+  /// smoothly. PlaybackState.updatePosition only changes on event
+  /// transitions (play/pause/buffer), so it's too coarse for live
+  /// scrubbing UI.
+  Stream<Duration> get positionStream => _player.positionStream;
+  Duration get position => _player.position;
+
+  void configure({
+    required String baseUrl,
+    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;
   }
 
-  Future<void> setQueueFromTracks(List<TrackRef> tracks, {int initialIndex = 0}) async {
-    final items = tracks.map(_toMediaItem).toList();
-    queue.add(items);
-    if (items.isNotEmpty) {
-      mediaItem.add(items[initialIndex.clamp(0, items.length - 1)]);
+  Future<void> setQueueFromTracks(
+    List<TrackRef> tracks, {
+    int initialIndex = 0,
+    String? source,
+  }) async {
+    if (tracks.isEmpty) return;
+    _queueSource = source;
+    final clampedInitial = initialIndex.clamp(0, tracks.length - 1);
+
+    // Bump the generation FIRST. Any in-flight _fillRemainingSources
+    // from a previous play will see the mismatch on its next gen
+    // check and stop calling player mutations — important so a stale
+    // fill doesn't append old-playlist tracks into the new queue.
+    final myGen = ++_queueGeneration;
+    _lastTracks = tracks;
+
+    // Pause the old source immediately so the previous track stops
+    // audibly the moment the user taps, instead of bleeding through
+    // until the new source finishes building. setAudioSources below
+    // will swap the source list cleanly; pause is the simplest way
+    // to silence the player during the (possibly multi-100ms) build.
+    if (_player.playing) {
+      await _player.pause();
     }
 
-    final headers = _token == null ? null : {'Authorization': 'Bearer $_token'};
-    final sources = tracks.map((t) {
-      final url = t.streamUrl.isNotEmpty
-          ? (Uri.tryParse(t.streamUrl)?.hasScheme == true
-              ? t.streamUrl
-              : '$_baseUrl${t.streamUrl}')
-          : '$_baseUrl/api/tracks/${t.id}/stream';
-      return AudioSource.uri(Uri.parse(url), headers: headers);
-    }).toList();
+    // Build MediaItems up front (pure — no side effects); we'll
+    // broadcast queue/mediaItem only AFTER setAudioSources resolves
+    // so the audio engine and the UI flip together. If the build
+    // throws, the UI stays on the previous track (correct: audio
+    // also stays on the previous track since setAudioSources never
+    // ran).
+    final items = tracks.map(_toMediaItem).toList();
 
-    await _player.setAudioSources(
-      sources,
-      initialIndex: initialIndex,
+    // Build only the initial source for fast start. Remaining
+    // sources stream in via _fillRemainingSources() — addAudioSource
+    // for next/auto-advance tracks, insertAudioSource for skipPrev.
+    final AudioSource initial;
+    try {
+      initial = await _buildAudioSource(tracks[clampedInitial]);
+    } catch (e, st) {
+      // Source build failed (bad URL, missing baseUrl, etc.). Don't
+      // broadcast the new state — leaving queue/mediaItem on the
+      // previous track keeps UI in sync with what the player is
+      // actually doing (which is "still on the previous track,
+      // paused").
+      debugPrint('audio_handler: _buildAudioSource failed: $e\n$st');
+      return;
+    }
+    if (myGen != _queueGeneration) {
+      debugPrint('audio_handler: superseded before setAudioSources (gen=$myGen)');
+      return;
+    }
+
+    // Suppress _onCurrentIndexChanged side effects while the source
+    // list is being swapped — without this, a transient currentIndex
+    // emission during setAudioSources could broadcast the OLD queue's
+    // entry at the NEW index. Re-enabled after the broadcasts land.
+    _suppressIndexUpdates = true;
+    try {
+      await _player.setAudioSources([initial], initialIndex: 0);
+      // Broadcast in this order: queue first (so any consumer that
+      // reacts to mediaItem and reads queue.value sees the consistent
+      // pair), then mediaItem.
+      queue.add(items);
+      mediaItem.add(items[clampedInitial]);
+    } finally {
+      _suppressIndexUpdates = false;
+    }
+
+    unawaited(_loadArtForCurrentItem());
+    unawaited(_fillRemainingSources(tracks, clampedInitial, myGen));
+  }
+
+  /// Switches playback to the [index]th queue item. The full
+  /// just_audio source list isn't necessarily built yet
+  /// (_fillRemainingSources runs in the background), so we
+  /// reconstruct from the stored TrackRef list rather than calling
+  /// _player.seek(index: ...) on a possibly-missing source. Calling
+  /// setQueueFromTracks again is the safe path: it bumps the
+  /// generation, cancels any in-flight fill, rebuilds source[0] as
+  /// the target, and re-fills around. play() restarts playback so
+  /// queue taps feel like "jump to this song" rather than "set the
+  /// pointer and wait for me to press play."
+  @override
+  Future<void> skipToQueueItem(int index) async {
+    if (index < 0 || index >= _lastTracks.length) return;
+    // Preserve the system-playlist source across an internal rebuild
+    // — a queue-item skip is still playing from the same playlist.
+    await setQueueFromTracks(_lastTracks, initialIndex: index, source: _queueSource);
+    await play();
+  }
+
+  /// Background fill of the rest of the just_audio source list after
+  /// the initial source is playing. Forward direction first (most
+  /// common skipNext target). Backward inserts shift the player's
+  /// currentIndex; we suppress _onCurrentIndexChanged side effects
+  /// for those so the mediaItem stream doesn't bounce to the wrong
+  /// queue entry.
+  ///
+  /// `gen` is the queue generation captured when this fill started.
+  /// Every loop iteration checks against _queueGeneration; if a
+  /// newer setQueueFromTracks has run (user tapped play on something
+  /// else), bail immediately so we don't pollute the new queue with
+  /// addAudioSource calls from this stale fill.
+  Future<void> _fillRemainingSources(
+      List<TrackRef> tracks, int initialIndex, int gen) async {
+    for (var i = initialIndex + 1; i < tracks.length; i++) {
+      if (gen != _queueGeneration) return;
+      try {
+        final src = await _buildAudioSource(tracks[i]);
+        if (gen != _queueGeneration) return;
+        await _player.addAudioSource(src);
+      } catch (e) {
+        debugPrint('audio_handler: forward fill failed for ${tracks[i].id}: $e');
+      }
+    }
+    if (initialIndex > 0) {
+      _suppressIndexUpdates = true;
+      try {
+        for (var i = 0; i < initialIndex; i++) {
+          if (gen != _queueGeneration) return;
+          final src = await _buildAudioSource(tracks[i]);
+          if (gen != _queueGeneration) return;
+          await _player.insertAudioSource(i, src);
+        }
+      } catch (e) {
+        debugPrint('audio_handler: backward fill failed: $e');
+      } finally {
+        // Only release the flag if we're still the active gen — a
+        // newer setQueueFromTracks already reset it for itself.
+        if (gen == _queueGeneration) _suppressIndexUpdates = false;
+      }
+    }
+  }
+
+  String _resolveStreamUrl(TrackRef t) {
+    if (t.streamUrl.isEmpty) {
+      return '$_baseUrl/api/tracks/${t.id}/stream';
+    }
+    final parsed = Uri.tryParse(t.streamUrl);
+    if (parsed != null && parsed.hasScheme) {
+      return t.streamUrl;
+    }
+    return '$_baseUrl${t.streamUrl}';
+  }
+
+  /// Builds an AudioSource for a track. Cache-aware:
+  /// 1. If the track is fully cached on disk, returns a file:// source.
+  /// 2. Else returns a LockCachingAudioSource that streams + caches as
+  ///    it plays (subsequent plays will hit the cache).
+  ///
+  /// Without an audio cache manager configured (e.g. in older code paths
+  /// that pre-date #357), falls back to a plain network AudioSource.uri.
+  Future<AudioSource> _buildAudioSource(TrackRef t) async {
+    final headers = _token == null ? null : {'Authorization': 'Bearer $_token'};
+    final mgr = _audioCacheManager;
+
+    // 1. Cache hit: play from disk, no headers needed.
+    if (mgr != null) {
+      final path = await mgr.pathFor(t.id);
+      if (path != null) {
+        return AudioSource.uri(Uri.file(path));
+      }
+    }
+
+    final url = _resolveStreamUrl(t);
+    final parsed = Uri.parse(url);
+    if (!parsed.hasScheme || parsed.host.isEmpty) {
+      throw StateError(
+        'audio_handler: refused to play scheme-less URL "$url" '
+        '(baseUrl="$_baseUrl", track.streamUrl="${t.streamUrl}", '
+        'track.id="${t.id}"). configure() must be called with a '
+        'non-empty baseUrl before setQueueFromTracks().',
+      );
+    }
+
+    // 2. Cache miss WITH manager: stream + cache-as-you-play. Future
+    // plays of this track will hit the cache. If the cache write
+    // completes, we don't currently register an index row — that would
+    // require a download-complete hook from just_audio that's not
+    // exposed cleanly. Acceptable for v1: prefetcher / explicit
+    // pin / Download buttons cover the index path; LockCaching handles
+    // the network optimization.
+    if (mgr != null) {
+      _cacheDirPath ??= (await getApplicationCacheDirectory()).path;
+      final cacheFile = File('${_cacheDirPath!}/audio_cache/${t.id}.mp3');
+      // ignore: experimental_member_use
+      return LockCachingAudioSource(parsed,
+          headers: headers, cacheFile: cacheFile);
+    }
+
+    // 3. No manager configured: plain network source (legacy path).
+    return AudioSource.uri(parsed, headers: headers);
+  }
+
+  /// Inserts [track] right after the currently-playing item so it plays
+  /// next. If nothing is playing, appends to the end.
+  Future<void> playNext(TrackRef track) async {
+    final source = await _buildAudioSource(track);
+    final item = _toMediaItem(track);
+    final currentIdx = _player.currentIndex;
+    final insertAt = currentIdx == null ? queue.value.length : currentIdx + 1;
+    await _player.insertAudioSource(insertAt, source);
+    final current = queue.value;
+    queue.add([
+      ...current.sublist(0, insertAt),
+      item,
+      ...current.sublist(insertAt),
+    ]);
+  }
+
+  /// Appends [track] to the end of the queue.
+  Future<void> enqueue(TrackRef track) async {
+    final source = await _buildAudioSource(track);
+    final item = _toMediaItem(track);
+    await _player.addAudioSource(source);
+    queue.add([...queue.value, item]);
+  }
+
+  MediaItem _toMediaItem(TrackRef t) {
+    // Stash album_id + artist_id in extras so widgets reconstructing
+    // a TrackRef from the MediaItem (player kebab → "Go to artist",
+    // "Go to album") have the IDs they need to navigate. Earlier code
+    // only carried album_id which left "Go to artist" pushing
+    // /artists/ (empty id, route 404).
+    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 intentionally NOT set: audio_service propagates
+    // it to MediaSession.setRating(), but the Android session also
+    // needs setRatingType(RATING_HEART) configured to expose that to
+    // controllers — audio_service doesn't surface that config knob,
+    // and broadcasting an unanchored rating made Wear OS reject the
+    // session entirely. The LikeBridge wiring stays in place so
+    // setRating can still fire from any surface that DOES route it,
+    // we just don't advertise it.
+    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,
+      extras: extras.isEmpty ? null : extras,
     );
   }
 
-  MediaItem _toMediaItem(TrackRef t) => MediaItem(
-        id: t.id,
-        title: t.title,
-        artist: t.artistName,
-        album: t.albumTitle,
-        duration: Duration(seconds: t.durationSec),
-      );
+  /// Once a track is fully buffered (LockCaching has written the whole
+  /// file to disk), insert an audio_cache_index row so the file shows
+  /// up to AudioCacheManager.evict() and clearAll(). No-op if the
+  /// cache manager isn't configured, no current track, the file isn't
+  /// fully buffered yet, the on-disk file is missing, or we already
+  /// registered this trackId during this subscription.
+  Future<void> _maybeRegisterStreamCache() async {
+    final mgr = _audioCacheManager;
+    if (mgr == null) return;
+    final current = mediaItem.value;
+    if (current == null) return;
+    final trackId = current.id;
+    if (_streamCacheRegistered.contains(trackId)) return;
+
+    final dur = _player.duration;
+    if (dur == null) return;
+    final buf = _player.bufferedPosition;
+    // 200ms slack for header bytes / encoding rounding.
+    if (buf < dur - const Duration(milliseconds: 200)) return;
+
+    _cacheDirPath ??= (await getApplicationCacheDirectory()).path;
+    final path = '${_cacheDirPath!}/audio_cache/$trackId.mp3';
+    final file = File(path);
+    if (!await file.exists()) return;
+    final size = await file.length();
+    if (size <= 0) return;
+
+    _streamCacheRegistered.add(trackId);
+    await mgr.registerStreamCache(trackId, path, size);
+  }
+
+  /// Called when playbackEventStream emits an error. Skips past the
+  /// failing track so the UI and audio re-converge — without this,
+  /// _player goes silent on a 404 / decoder failure / EOS but
+  /// mediaItem stays on the failed track and the user sees a "now
+  /// playing" header for something that isn't.
+  ///
+  /// If we're at the last track, seekToNext is a no-op; the state
+  /// drops to idle and _broadcastState reflects that.
+  Future<void> _handlePlaybackError() async {
+    final currentIdx = _player.currentIndex;
+    final queueLen = queue.value.length;
+    if (currentIdx == null || currentIdx + 1 >= queueLen) {
+      // Last track or no queue context — just pause; _broadcastState
+      // already reflects the idle/error processingState.
+      try {
+        await _player.pause();
+      } catch (_) {}
+      return;
+    }
+    try {
+      await _player.seekToNext();
+    } catch (_) {
+      // If seekToNext fails too (next source not built yet, etc.),
+      // there's nothing safe to do — pause and let the user recover
+      // manually.
+      try {
+        await _player.pause();
+      } catch (_) {}
+    }
+  }
+
+  void _onCurrentIndexChanged(int? idx) {
+    if (idx == null) return;
+    if (_suppressIndexUpdates) return;
+    // Push the new track's MediaItem onto the mediaItem stream so
+    // the player UI rebuilds with the new title/artist/album/cover.
+    // Without this, the bar and full player stayed pinned to whichever
+    // track was passed via setQueueFromTracks(initialIndex:) regardless
+    // of skip/auto-advance.
+    final items = queue.value;
+    if (idx >= 0 && idx < items.length) {
+      mediaItem.add(items[idx]);
+    }
+    unawaited(_loadArtForCurrentItem());
+  }
+
+  /// Async-fetches the cover for whichever item is currently active and
+  /// pushes a MediaItem update with artUri set. No-op if no cache is
+  /// configured, no current item, the item has no album_id in extras,
+  /// or the fetch returns null.
+  Future<void> _loadArtForCurrentItem() async {
+    final cache = _coverCache;
+    if (cache == null) return;
+    final current = mediaItem.value;
+    if (current == null) return;
+    final albumId = current.extras?['album_id'] as String?;
+    if (albumId == null || albumId.isEmpty) return;
+    if (current.artUri != null) return; // already set
+    final path = await cache.getOrFetch(albumId);
+    if (path == null) return;
+    // Discard if the user advanced to another track while we waited.
+    if (mediaItem.value?.id != current.id) return;
+    mediaItem.add(current.copyWith(artUri: Uri.file(path)));
+  }
 
   @override
   Future<void> play() => _player.play();
@@ -63,7 +487,73 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
   @override
   Future<void> skipToPrevious() => _player.seekToPrevious();
 
-  void _broadcastState(PlaybackEvent event) {
+  /// 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
+        .setShuffleModeEnabled(shuffleMode != AudioServiceShuffleMode.none);
+    // _broadcastState picks up the change via shuffleModeEnabledStream.
+  }
+
+  @override
+  Future<void> setRepeatMode(AudioServiceRepeatMode repeatMode) async {
+    final loop = switch (repeatMode) {
+      AudioServiceRepeatMode.none => LoopMode.off,
+      AudioServiceRepeatMode.one => LoopMode.one,
+      AudioServiceRepeatMode.all || AudioServiceRepeatMode.group => LoopMode.all,
+    };
+    await _player.setLoopMode(loop);
+  }
+
+  /// Sets player volume in [0.0, 1.0]. Note: most mobile browsers tie
+  /// page audio to system volume — this is the in-app slider for parity
+  /// with desktop/web; on mobile the system volume is the real control.
+  Future<void> setVolume(double v) async {
+    await _player.setVolume(v.clamp(0.0, 1.0));
+  }
+
+  // _broadcastState accepts a nullable event because the shuffle/repeat
+  // listeners don't have one — we just want to re-emit PlaybackState
+  // with up-to-date shuffleMode/repeatMode fields.
+  void _broadcastState(PlaybackEvent? event) {
     final playing = _player.playing;
     playbackState.add(PlaybackState(
       controls: [
@@ -71,7 +561,32 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
         if (playing) MediaControl.pause else MediaControl.play,
         MediaControl.skipToNext,
       ],
-      systemActions: const {MediaAction.seek},
+      // androidCompactActionIndices tells the system which controls
+      // appear in the collapsed/lock-screen view. Without this, some
+      // Android versions render the player without working buttons.
+      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+.
+      //
+      // v2026.05.13.3 added stop, skipToQueueItem, setShuffleMode,
+      // setRepeatMode, and setRating to this set; reverted because
+      // Pixel Watch 2 stopped showing controls entirely after that
+      // change. The MediaSession contract on Wear OS requires more
+      // setup than just advertising the action (e.g. setRatingType
+      // for setRating) and audio_service doesn't expose those knobs.
+      // Keep the override methods themselves (skipToQueueItem is
+      // still routed via QueueScreen's direct handler call;
+      // setRating is harmless if never invoked) so we don't lose
+      // the underlying functionality — just don't tell the system
+      // we support them.
+      systemActions: const {
+        MediaAction.play,
+        MediaAction.pause,
+        MediaAction.skipToNext,
+        MediaAction.skipToPrevious,
+        MediaAction.seek,
+      },
       processingState: switch (_player.processingState) {
         ProcessingState.idle => AudioProcessingState.idle,
         ProcessingState.loading => AudioProcessingState.loading,
@@ -83,7 +598,39 @@ class MinstrelAudioHandler extends BaseAudioHandler with QueueHandler, SeekHandl
       updatePosition: _player.position,
       bufferedPosition: _player.bufferedPosition,
       speed: _player.speed,
-      queueIndex: event.currentIndex,
+      queueIndex: event?.currentIndex ?? _player.currentIndex,
+      shuffleMode: _player.shuffleModeEnabled
+          ? AudioServiceShuffleMode.all
+          : AudioServiceShuffleMode.none,
+      repeatMode: switch (_player.loopMode) {
+        LoopMode.off => AudioServiceRepeatMode.none,
+        LoopMode.one => AudioServiceRepeatMode.one,
+        LoopMode.all => AudioServiceRepeatMode.all,
+      },
     ));
   }
 }
+
+/// 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

@@ -1,83 +1,646 @@
+import 'dart:io';
+
+import 'package:audio_service/audio_service.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 
+import '../api/endpoints/likes.dart' show LikeKind;
+import '../likes/like_button.dart';
+import '../models/track.dart';
+import '../shared/widgets/server_image.dart';
+import '../shared/widgets/track_actions/track_actions_button.dart';
 import '../theme/theme_extension.dart';
+import 'album_color_extractor.dart';
 import 'player_provider.dart';
 
-class NowPlayingScreen extends ConsumerWidget {
+/// Hero tag shared between the mini player's cover and the full-screen
+/// _AlbumArt's cover so tapping the mini bar animates the artwork from
+/// the bar's footprint to the full-screen size. Stable per-route (not
+/// keyed by media.id) so the transition works regardless of what's
+/// playing.
+const String kPlayerCoverHeroTag = 'player-cover';
+
+/// Duration for the AnimatedSwitcher / AnimatedContainer track-change
+/// crossfade. ~300ms reads as a smooth transition without dragging.
+const Duration _trackChangeDuration = Duration(milliseconds: 300);
+
+/// Full-screen player. Mounted on /now-playing. Pushed via a slide-up
+/// transition (see routing.dart). Dismisses three ways:
+///
+/// - System back / leading button → Navigator.pop
+/// - Vertical drag down past threshold → Navigator.pop (matches the
+///   slide-down animation users expect from a "pull down to close"
+///   sheet)
+/// - Tap of the mini player ascends here; reverse motion descends back.
+class NowPlayingScreen extends ConsumerStatefulWidget {
   const NowPlayingScreen({super.key});
 
   @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
-    final media = ref.watch(mediaItemProvider).value;
-    final playback = ref.watch(playbackStateProvider).value;
+  ConsumerState<NowPlayingScreen> createState() => _NowPlayingScreenState();
+}
 
-    if (media == null) {
+class _NowPlayingScreenState extends ConsumerState<NowPlayingScreen> {
+  // Cumulative drag distance used to decide if a vertical drag should
+  // dismiss. Reset on each drag start.
+  double _dragOffset = 0;
+
+  /// 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;
+
+  /// 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;
+
+    // Fast path: when Prefetcher has already warmed both the cover
+    // bytes (file:// artUri populated via _toMediaItem's peekCached)
+    // AND the palette color (AlbumColorCache.peekColor returns
+    // non-null), we can commit synchronously. The slow async path
+    // exists for genuine cold-cache moments (first play of an album
+    // that sync hasn't seen yet); the fast path is what makes the
+    // common in-queue auto-advance flip the visual in lockstep with
+    // the audio transition instead of lagging a tick behind.
+    final artUri = newMedia.artUri;
+    final albumId = newMedia.extras?['album_id'] as String?;
+    if (artUri != null &&
+        artUri.isScheme('file') &&
+        albumId != null &&
+        albumId.isNotEmpty) {
+      final cachedColor = ref.read(albumColorCacheProvider).peekColor(albumId);
+      if (cachedColor != null) {
+        if (!mounted) return;
+        if (_pendingPreloadId != newMedia.id) return;
+        setState(() {
+          _displayedMedia = newMedia;
+          _displayedDominant = cachedColor;
+        });
+        return;
+      }
+    }
+
+    // Slow path: cover and/or color are not yet cached. Hold the
+    // current displayed state, preload, then atomic-commit.
+    //
+    // 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.
+    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;
+    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;
+  }
+
+  void _onDragUpdate(DragUpdateDetails d) {
+    _dragOffset += d.delta.dy;
+  }
+
+  void _onDragEnd(DragEndDetails d) {
+    // Pop when either the user has dragged > 80px down OR flicked
+    // downward at speed (>500 px/s). Either should feel responsive
+    // without dismissing on accidental drags.
+    final flicked = d.primaryVelocity != null && d.primaryVelocity! > 500;
+    if (_dragOffset > 80 || flicked) {
+      Navigator.of(context).maybePop();
+    }
+    _dragOffset = 0;
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+
+    // 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.')));
     }
 
-    final pos = playback?.updatePosition ?? Duration.zero;
-    final dur = media.duration ?? Duration.zero;
+    // Use positionProvider (just_audio's positionStream, ~200ms) for
+    // the seek bar so it scrubs live; PlaybackState.updatePosition
+    // only fires on state transitions and would leave the bar frozen
+    // between them.
+    final pos = ref.watch(positionProvider).value ?? 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 = (displayedMedia.extras?['album_id'] as String?) ?? '';
+
+    // 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);
 
     return Scaffold(
       backgroundColor: fs.obsidian,
-      appBar: AppBar(
-        backgroundColor: fs.obsidian,
-        leading: IconButton(
-          icon: Icon(Icons.expand_more, color: fs.parchment),
-          onPressed: () => Navigator.of(context).pop(),
-        ),
-        actions: [
-          IconButton(
-            icon: Icon(Icons.queue_music, color: fs.parchment),
-            tooltip: 'Queue',
-            onPressed: () => GoRouter.of(context).push('/queue'),
+      // The whole screen accepts vertical drag for dismissal. Buttons
+      // and the seek slider are still tappable since gesture arena
+      // gives priority to their child gesture detectors.
+      body: GestureDetector(
+        onVerticalDragStart: _onDragStart,
+        onVerticalDragUpdate: _onDragUpdate,
+        onVerticalDragEnd: _onDragEnd,
+        behavior: HitTestBehavior.translucent,
+        child: AnimatedContainer(
+          duration: _trackChangeDuration,
+          decoration: BoxDecoration(
+            gradient: LinearGradient(
+              begin: Alignment.topCenter,
+              end: Alignment.bottomCenter,
+              colors: [gradientTop, fs.obsidian],
+              stops: const [0.0, 0.7],
+            ),
           ),
-        ],
-      ),
-      body: SafeArea(
-        child: Padding(
-          padding: const EdgeInsets.all(24),
-          child: Column(children: [
-            const Spacer(),
-            Container(
-              width: 280, height: 280, color: fs.slate,
-            ),
-            const SizedBox(height: 24),
-            Text(media.title, style: TextStyle(color: fs.parchment, fontSize: 22)),
-            Text(media.artist ?? '', style: TextStyle(color: fs.ash, fontSize: 14)),
-            const SizedBox(height: 16),
-            Slider(
-              activeColor: fs.accent,
-              min: 0,
-              max: dur.inMilliseconds.toDouble().clamp(1, double.infinity),
-              value: pos.inMilliseconds.toDouble().clamp(0, dur.inMilliseconds.toDouble()),
-              onChanged: (v) => ref.read(audioHandlerProvider).seek(Duration(milliseconds: v.toInt())),
-            ),
-            Row(mainAxisAlignment: MainAxisAlignment.spaceEvenly, children: [
-              IconButton(
-                icon: Icon(Icons.skip_previous, color: fs.parchment, size: 32),
-                onPressed: () => ref.read(audioHandlerProvider).skipToPrevious(),
+          child: SafeArea(
+          child: Column(
+            children: [
+              _TopBar(fs: fs),
+              Expanded(
+                child: Padding(
+                  padding: const EdgeInsets.symmetric(horizontal: 24),
+                  child: Column(
+                    children: [
+                      const Spacer(),
+                      // 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),
+                      _TitleRow(media: displayedMedia, fs: fs),
+                      const SizedBox(height: 4),
+                      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(
+                              displayedMedia.album!,
+                              style: TextStyle(color: fs.ash, fontSize: 12),
+                              maxLines: 1,
+                              overflow: TextOverflow.ellipsis,
+                            ),
+                          ],
+                        ],
+                      ),
+                      const SizedBox(height: 24),
+                      _SecondaryControls(
+                        fs: fs,
+                        actions: actions,
+                        shuffleOn: shuffleOn,
+                        repeatMode: repeatMode,
+                        media: displayedMedia,
+                      ),
+                      const SizedBox(height: 8),
+                      _SeekRow(position: pos, duration: dur, fs: fs, ref: ref),
+                      const SizedBox(height: 24),
+                      _PrimaryControls(
+                        fs: fs,
+                        ref: ref,
+                        isPlaying: isPlaying,
+                      ),
+                      const SizedBox(height: 24),
+                    ],
+                  ),
+                ),
               ),
-              IconButton(
-                iconSize: 56,
-                icon: Icon(playback?.playing == true ? Icons.pause_circle_filled : Icons.play_circle_filled, color: fs.accent),
-                onPressed: () {
-                  final h = ref.read(audioHandlerProvider);
-                  if (playback?.playing == true) { h.pause(); } else { h.play(); }
-                },
-              ),
-              IconButton(
-                icon: Icon(Icons.skip_next, color: fs.parchment, size: 32),
-                onPressed: () => ref.read(audioHandlerProvider).skipToNext(),
-              ),
-            ]),
-            const Spacer(),
-          ]),
+            ],
+          ),
+          ),
         ),
       ),
     );
   }
 }
+
+class _TopBar extends StatelessWidget {
+  const _TopBar({required this.fs});
+  final FabledSwordTheme fs;
+
+  @override
+  Widget build(BuildContext context) {
+    return SizedBox(
+      height: 48,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 4),
+        child: Row(children: [
+          IconButton(
+            icon: Icon(Icons.expand_more, color: fs.parchment),
+            tooltip: 'Close',
+            onPressed: () => Navigator.of(context).maybePop(),
+          ),
+          const Spacer(),
+          IconButton(
+            icon: Icon(Icons.queue_music, color: fs.parchment),
+            tooltip: 'Queue',
+            onPressed: () => GoRouter.of(context).push('/queue'),
+          ),
+        ]),
+      ),
+    );
+  }
+}
+
+class _AlbumArt extends StatelessWidget {
+  const _AlbumArt({required this.media, required this.albumId, required this.fs});
+  final MediaItem media;
+  final String albumId;
+  final FabledSwordTheme fs;
+
+  @override
+  Widget build(BuildContext context) {
+    // Pick the best available source. AlbumCoverCache writes a file://
+    // URI to media.artUri once the cover lands on disk; before then,
+    // fall back to fetching via ServerImage from /api/albums/<id>/cover
+    // (which carries the auth header and falls back gracefully on
+    // failure).
+    Widget cover;
+    final artUri = media.artUri;
+    if (artUri != null && artUri.isScheme('file')) {
+      cover = Image(
+        image: FileImage(File.fromUri(artUri)),
+        fit: BoxFit.cover,
+        errorBuilder: (_, __, ___) => Container(color: fs.slate),
+      );
+    } else if (albumId.isNotEmpty) {
+      cover = ServerImage(
+        url: '/api/albums/$albumId/cover',
+        fit: BoxFit.cover,
+        fallback: Container(color: fs.slate),
+      );
+    } else {
+      cover = Container(color: fs.slate);
+    }
+    return AspectRatio(
+      aspectRatio: 1,
+      child: ConstrainedBox(
+        constraints: const BoxConstraints(maxWidth: 320, maxHeight: 320),
+        child: Hero(
+          tag: kPlayerCoverHeroTag,
+          // flightShuttleBuilder ensures the in-flight Hero renders the
+          // destination's cover image (not the mini bar's small one)
+          // during the entire animation, which reads as a smooth grow
+          // rather than a swap mid-flight.
+          flightShuttleBuilder:
+              (_, __, ___, ____, toHeroContext) => toHeroContext.widget,
+          child: ClipRRect(
+            borderRadius: BorderRadius.circular(8),
+            child: cover,
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+class _TitleRow extends StatelessWidget {
+  const _TitleRow({required this.media, required this.fs});
+  final MediaItem media;
+  final FabledSwordTheme fs;
+
+  @override
+  Widget build(BuildContext context) {
+    // Title-only — like + kebab moved into _SecondaryControls above
+    // the seek bar so they share the same row as shuffle/repeat/queue.
+    return Text(
+      media.title,
+      style: TextStyle(color: fs.parchment, fontSize: 22),
+      maxLines: 1,
+      overflow: TextOverflow.ellipsis,
+      textAlign: TextAlign.center,
+    );
+  }
+}
+
+class _SeekRow extends StatelessWidget {
+  const _SeekRow({
+    required this.position,
+    required this.duration,
+    required this.fs,
+    required this.ref,
+  });
+  final Duration position;
+  final Duration duration;
+  final FabledSwordTheme fs;
+  final WidgetRef ref;
+
+  String _fmt(Duration d) {
+    final m = d.inMinutes.remainder(60).toString();
+    final s = d.inSeconds.remainder(60).toString().padLeft(2, '0');
+    return '$m:$s';
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final maxMs = duration.inMilliseconds.toDouble().clamp(1.0, double.infinity);
+    return Column(children: [
+      SliderTheme(
+        data: SliderTheme.of(context).copyWith(
+          trackHeight: 3,
+          thumbShape: const RoundSliderThumbShape(enabledThumbRadius: 7),
+          overlayShape: const RoundSliderOverlayShape(overlayRadius: 14),
+        ),
+        child: Slider(
+          activeColor: fs.accent,
+          inactiveColor: fs.slate,
+          min: 0,
+          max: maxMs,
+          value: position.inMilliseconds
+              .toDouble()
+              .clamp(0.0, duration.inMilliseconds.toDouble()),
+          onChanged: (v) => ref
+              .read(audioHandlerProvider)
+              .seek(Duration(milliseconds: v.toInt())),
+        ),
+      ),
+      Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 4),
+        child: Row(
+          mainAxisAlignment: MainAxisAlignment.spaceBetween,
+          children: [
+            Text(_fmt(position), style: TextStyle(color: fs.ash, fontSize: 11)),
+            Text(_fmt(duration), style: TextStyle(color: fs.ash, fontSize: 11)),
+          ],
+        ),
+      ),
+    ]);
+  }
+}
+
+class _PrimaryControls extends StatelessWidget {
+  const _PrimaryControls({
+    required this.fs,
+    required this.ref,
+    required this.isPlaying,
+  });
+  final FabledSwordTheme fs;
+  final WidgetRef ref;
+  final bool isPlaying;
+
+  @override
+  Widget build(BuildContext context) {
+    return Row(
+      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
+      children: [
+        IconButton(
+          iconSize: 36,
+          icon: Icon(Icons.skip_previous, color: fs.parchment),
+          onPressed: () => ref.read(audioHandlerProvider).skipToPrevious(),
+        ),
+        IconButton(
+          iconSize: 72,
+          icon: Icon(
+            isPlaying ? Icons.pause_circle_filled : Icons.play_circle_filled,
+            color: fs.accent,
+          ),
+          onPressed: () {
+            final h = ref.read(audioHandlerProvider);
+            if (isPlaying) {
+              h.pause();
+            } else {
+              h.play();
+            }
+          },
+        ),
+        IconButton(
+          iconSize: 36,
+          icon: Icon(Icons.skip_next, color: fs.parchment),
+          onPressed: () => ref.read(audioHandlerProvider).skipToNext(),
+        ),
+      ],
+    );
+  }
+}
+
+/// Action row sitting just above the seek bar. Holds shuffle / repeat
+/// / queue plus the like + kebab that used to live in the title row,
+/// so the title can sit truly centered above and this row carries
+/// every per-track action in one place.
+class _SecondaryControls extends StatelessWidget {
+  const _SecondaryControls({
+    required this.fs,
+    required this.actions,
+    required this.shuffleOn,
+    required this.repeatMode,
+    required this.media,
+  });
+  final FabledSwordTheme fs;
+  final PlayerActions actions;
+  final bool shuffleOn;
+  final AudioServiceRepeatMode repeatMode;
+  final MediaItem media;
+
+  @override
+  Widget build(BuildContext context) {
+    return Row(
+      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
+      children: [
+        IconButton(
+          tooltip: shuffleOn ? 'Shuffle on' : 'Shuffle off',
+          icon: Icon(
+            Icons.shuffle,
+            color: shuffleOn ? fs.accent : fs.ash,
+          ),
+          onPressed: actions.toggleShuffle,
+        ),
+        IconButton(
+          tooltip: switch (repeatMode) {
+            AudioServiceRepeatMode.none => 'Repeat off',
+            AudioServiceRepeatMode.one => 'Repeat one',
+            _ => 'Repeat all',
+          },
+          icon: Icon(
+            repeatMode == AudioServiceRepeatMode.one
+                ? Icons.repeat_one
+                : Icons.repeat,
+            color: repeatMode == AudioServiceRepeatMode.none
+                ? fs.ash
+                : fs.accent,
+          ),
+          onPressed: actions.cycleRepeat,
+        ),
+        IconButton(
+          tooltip: 'Queue',
+          icon: Icon(Icons.queue_music, color: fs.ash),
+          onPressed: () => GoRouter.of(context).push('/queue'),
+        ),
+        LikeButton(kind: LikeKind.track, id: media.id, size: 22),
+        TrackActionsButton(
+          track: TrackRef(
+            id: media.id,
+            title: media.title,
+            albumId: (media.extras?['album_id'] as String?) ?? '',
+            albumTitle: media.album ?? '',
+            artistId: (media.extras?['artist_id'] as String?) ?? '',
+            artistName: media.artist ?? '',
+            durationSec: media.duration?.inSeconds ?? 0,
+            streamUrl: '',
+          ),
+          hideQueueActions: true,
+          // /now-playing lives outside the ShellRoute. Pushing
+          // /artists/:id or /albums/:id (both shell-children) on top
+          // of it would make go_router try to mount a duplicate
+          // ShellRoute (the same _debugCheckDuplicatedPageKeys crash
+          // we hit before with /queue). Await our own pop fully
+          // before pushing the destination so go_router never sees
+          // both pages active in the same frame.
+          onNavigate: (path) async {
+            await Navigator.of(context).maybePop();
+            if (context.mounted) GoRouter.of(context).push(path);
+          },
+        ),
+      ],
+    );
+  }
+}

flutter_client/lib/player/play_events_reporter.dart

@@ -0,0 +1,277 @@
+// Flutter play-event lifecycle reporter (#415 stage 3).
+//
+// The Flutter client previously reported NO plays — listening on
+// mobile never reached the server's play_events, so history,
+// recommendation scoring, ListenBrainz scrobbles, and (since #415)
+// system-playlist rotation all missed mobile activity entirely. This
+// closes that gap and is the path that carries the #415 `source` tag.
+//
+// State machine over (current track id, playing). Mirrors the web
+// events dispatcher, with one deliberate divergence: when a track
+// changes inside a queue we classify ended-vs-skipped by whether the
+// prior track reached (near) its duration, instead of the web
+// dispatcher's blanket "track change = skip". Blanket-skip would mark
+// every naturally-finished in-queue track as a skip and dilute the
+// recommendation skip-ratio — the exact failure mode that motivated
+// doing this properly. (The web dispatcher likely has the same
+// false-skip issue; flagged separately, not fixed here.)
+
+import 'dart:async';
+import 'dart:math';
+
+import 'package:audio_service/audio_service.dart';
+import 'package:flutter/widgets.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../api/endpoints/events.dart';
+import '../auth/auth_provider.dart' show secureStorageProvider;
+import '../cache/mutation_queue.dart'
+    show MutationKinds, mutationQueueProvider;
+import '../library/library_providers.dart' show dioProvider;
+import 'audio_handler.dart' show MinstrelAudioHandler;
+import 'player_provider.dart' show audioHandlerProvider;
+
+const _clientIdKey = 'play_events_client_id';
+
+/// Tolerance for "the track basically finished": within 3s of the
+/// known duration counts as a natural completion, not a skip.
+const _completionToleranceMs = 3000;
+
+class PlayEventsReporter with WidgetsBindingObserver {
+  PlayEventsReporter(this._ref);
+  final Ref _ref;
+
+  final _subs = <StreamSubscription<dynamic>>[];
+  bool _disposed = false;
+
+  String? _clientId;
+  EventsApi? _api;
+
+  // Server play_event_id when the live play_started succeeded; null
+  // if start failed / offline — then the close is captured into the
+  // offline mutation queue instead of a live ended/skipped call.
+  String? _openPlayEventId;
+
+  // The play currently being tracked, captured independently of
+  // connectivity so an offline play is still a complete record.
+  String? _curTrackId;
+  DateTime? _curStartedAt;
+  String? _curSource;
+  int _curLastPositionMs = 0;
+  int _curDurationMs = 0;
+  bool _curReachedEnd = false;
+
+  String? _prevTrackId;
+
+  Future<void> start() async {
+    final MinstrelAudioHandler handler;
+    try {
+      // audioHandlerProvider throws until main() overrides it (real
+      // app always does). In tests / no-audio environments there's
+      // nothing to report — fail safe and stay inert rather than
+      // surfacing an unhandled async error.
+      handler = _ref.read(audioHandlerProvider);
+      _clientId = await _resolveClientId();
+      final dio = await _ref.read(dioProvider.future);
+      _api = EventsApi(dio);
+    } catch (_) {
+      return;
+    }
+    if (_disposed) return;
+    WidgetsBinding.instance.addObserver(this);
+
+    _subs.add(handler.positionStream.listen((p) {
+      final ms = p.inMilliseconds;
+      // Advance the tracked play's progress ONLY while its track is
+      // the current one. A track change resets position to 0; gating
+      // on _curTrackId keeps the finishing track's last-known values
+      // intact for the close branch.
+      final mi = handler.mediaItem.value;
+      if (mi != null && mi.id == _curTrackId) {
+        _curLastPositionMs = ms;
+        final d = mi.duration;
+        if (d != null && d.inMilliseconds > 0) {
+          _curDurationMs = d.inMilliseconds;
+          if (ms >= _curDurationMs - _completionToleranceMs) {
+            _curReachedEnd = true;
+          }
+        }
+      }
+    }));
+    _subs.add(handler.mediaItem.listen((_) => _evaluate(handler)));
+    _subs.add(handler.playbackState.listen((_) => _evaluate(handler)));
+  }
+
+  void _evaluate(MinstrelAudioHandler handler) {
+    if (_disposed) return;
+    final mi = handler.mediaItem.value;
+    final st = handler.playbackState.value;
+    final tid = mi?.id;
+    final playing = st.playing;
+    final completed = st.processingState == AudioProcessingState.completed;
+
+    // Track changed → close the prior tracked play.
+    if (tid != _prevTrackId && _curTrackId != null) {
+      _closeCurrent(viaOffline: false);
+    }
+
+    // Entered playing for a new track → begin tracking it.
+    if (tid != null && playing && _curTrackId != tid) {
+      _beginTrack(handler, tid);
+    }
+
+    // Whole-queue natural end (just_audio only emits `completed` at
+    // the end of the sequence, not between items) → close it.
+    if (completed && _curTrackId != null) {
+      _curReachedEnd = true;
+      _closeCurrent(viaOffline: false);
+    }
+
+    _prevTrackId = tid;
+  }
+
+  void _beginTrack(MinstrelAudioHandler handler, String trackId) {
+    _curTrackId = trackId;
+    _curStartedAt = DateTime.now().toUtc();
+    _curSource = handler.queueSource;
+    _curLastPositionMs = 0;
+    _curReachedEnd = false;
+    final d = handler.mediaItem.value?.duration;
+    _curDurationMs = d?.inMilliseconds ?? 0;
+    _openPlayEventId = null;
+    // Fire the live play_started; adopt the server id only if we're
+    // still on this track when the response lands. Failure is fine —
+    // the close path captures the whole play into the offline queue.
+    _startLive(handler, trackId);
+  }
+
+  Future<void> _startLive(MinstrelAudioHandler handler, String trackId) async {
+    final api = _api;
+    final cid = _clientId;
+    if (api == null || cid == null) return;
+    try {
+      final id = await api.playStarted(
+        trackId: trackId,
+        clientId: cid,
+        source: _curSource,
+      );
+      if (id != null && _curTrackId == trackId) {
+        _openPlayEventId = id;
+      }
+    } catch (_) {
+      // Offline / flaky — _openPlayEventId stays null; the close path
+      // enqueues the completed play for replay.
+    }
+  }
+
+  /// Closes the currently-tracked play. `finished` is derived from
+  /// whether it reached ~its duration. If the live start registered a
+  /// server id we attempt the live ended/skipped close and fall back
+  /// to the offline queue on failure; with no server id (offline
+  /// start) — or viaOffline (app teardown, must be durable) — the
+  /// completed play is enqueued directly. The server's RecordOffline
+  /// Play applies the canonical skip rule, so the offline payload
+  /// only needs duration, not our finished/skipped guess.
+  void _closeCurrent({required bool viaOffline}) {
+    final trackId = _curTrackId;
+    final startedAt = _curStartedAt;
+    if (trackId == null || startedAt == null) {
+      _resetCurrent();
+      return;
+    }
+    final reached = _curReachedEnd;
+    final lastPos = _curLastPositionMs;
+    final durationMs = (reached && _curDurationMs > 0)
+        ? _curDurationMs
+        : lastPos;
+    final source = _curSource;
+    final id = _openPlayEventId;
+
+    if (!viaOffline && id != null) {
+      // Live close; on failure, fall back to the durable offline path
+      // so a transient blip at close time doesn't lose the play.
+      final fut = reached
+          ? _api?.playEnded(playEventId: id, durationPlayedMs: durationMs)
+          : _api?.playSkipped(playEventId: id, positionMs: lastPos);
+      fut?.catchError((_) {
+        _enqueueOffline(trackId, startedAt, source, durationMs);
+      });
+    } else {
+      _enqueueOffline(trackId, startedAt, source, durationMs);
+    }
+    _resetCurrent();
+  }
+
+  void _resetCurrent() {
+    _curTrackId = null;
+    _curStartedAt = null;
+    _curSource = null;
+    _curLastPositionMs = 0;
+    _curDurationMs = 0;
+    _curReachedEnd = false;
+    _openPlayEventId = null;
+  }
+
+  void _enqueueOffline(
+    String trackId,
+    DateTime startedAt,
+    String? source,
+    int durationPlayedMs,
+  ) {
+    final cid = _clientId;
+    if (cid == null) return;
+    // ignore: unawaited_futures
+    _ref.read(mutationQueueProvider).enqueue(MutationKinds.playOffline, {
+      'trackId': trackId,
+      'clientId': cid,
+      'at': startedAt.toIso8601String(),
+      'durationPlayedMs': durationPlayedMs,
+      if (source != null && source.isNotEmpty) 'source': source,
+    });
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    // App backgrounded / killed mid-play: close durably via the
+    // offline queue (a fire-and-forget POST during teardown is
+    // unreliable; the queue survives a process kill and drains on
+    // next launch). Mirrors the intent of web's pagehide beacon.
+    if (state == AppLifecycleState.paused ||
+        state == AppLifecycleState.detached) {
+      if (_curTrackId != null) {
+        _closeCurrent(viaOffline: true);
+      }
+    }
+  }
+
+  Future<String> _resolveClientId() async {
+    final storage = _ref.read(secureStorageProvider);
+    final existing = await storage.read(key: _clientIdKey);
+    if (existing != null && existing.isNotEmpty) return existing;
+    final rnd = Random.secure();
+    final bytes = List<int>.generate(16, (_) => rnd.nextInt(256));
+    final id =
+        bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
+    await storage.write(key: _clientIdKey, value: id);
+    return id;
+  }
+
+  void dispose() {
+    _disposed = true;
+    WidgetsBinding.instance.removeObserver(this);
+    for (final s in _subs) {
+      s.cancel();
+    }
+    _subs.clear();
+  }
+}
+
+/// Read once at app start (app.dart postFrame) to activate reporting.
+/// Disposed via ref.onDispose when the scope tears down.
+final playEventsReporterProvider = Provider<PlayEventsReporter>((ref) {
+  final r = PlayEventsReporter(ref);
+  ref.onDispose(r.dispose);
+  // ignore: unawaited_futures
+  r.start();
+  return r;
+});

flutter_client/lib/player/player_bar.dart

@@ -1,53 +1,345 @@
+import 'dart:io';
+
+import 'package:audio_service/audio_service.dart';
+import 'package:cached_network_image/cached_network_image.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:go_router/go_router.dart';
 
+import '../api/endpoints/likes.dart' show LikeKind;
+import '../likes/like_button.dart';
+import '../models/track.dart';
+import '../shared/widgets/track_actions/track_actions_button.dart';
 import '../theme/theme_extension.dart';
+import 'now_playing_screen.dart' show kPlayerCoverHeroTag;
 import 'player_provider.dart';
 
-class PlayerBar extends ConsumerWidget {
+/// Compact player bar mounted at the bottom of the app shell. Mini
+/// view only — the heavyweight shuffle/repeat/queue/volume controls
+/// live in NowPlayingScreen, accessible by tap or swipe-up.
+///
+///   ┌─────────────────────────────────────┬──────────┐
+///   │ [art] Title          ♥ ⋮              │ ⏮ ⏯ ⏭   │
+///   │       Artist                          │          │
+///   ├─────────────────────────────────────────────────┤
+///   │ 0:00 ━━●━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3:06       │
+///   └─────────────────────────────────────────────────┘
+///
+/// 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 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 mediaItem = ref.watch(mediaItemProvider).value;
+    final media = ref.watch(mediaItemProvider).value;
     final playback = ref.watch(playbackStateProvider).value;
-    if (mediaItem == null) return const SizedBox.shrink();
+    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.
+    final pos = ref.watch(positionProvider).value ?? Duration.zero;
+    final dur = media.duration ?? Duration.zero;
 
     return Material(
       color: fs.iron,
-      child: InkWell(
+      child: GestureDetector(
+        behavior: HitTestBehavior.opaque,
         onTap: () => context.push('/now-playing'),
+        // Swipe up anywhere on the bar to expand into the full player.
+        // We only act on a clear upward flick (>200 px/s) so a slow
+        // tap-with-tiny-jitter doesn't accidentally open the screen.
+        onVerticalDragEnd: (d) {
+          final v = d.primaryVelocity ?? 0;
+          if (v < -200) context.push('/now-playing');
+        },
         child: Padding(
           padding: const EdgeInsets.symmetric(horizontal: 12, vertical: 8),
-          child: Row(children: [
-            Container(width: 48, height: 48, color: fs.slate),
-            const SizedBox(width: 12),
-            Expanded(child: Column(
-              crossAxisAlignment: CrossAxisAlignment.start,
-              mainAxisAlignment: MainAxisAlignment.center,
-              children: [
-                Text(mediaItem.title, maxLines: 1, overflow: TextOverflow.ellipsis,
-                    style: TextStyle(color: fs.parchment, fontSize: 14)),
-                Text(mediaItem.artist ?? '', maxLines: 1, overflow: TextOverflow.ellipsis,
-                    style: TextStyle(color: fs.ash, fontSize: 12)),
-              ],
-            )),
-            IconButton(
-              icon: Icon(playback?.playing == true ? Icons.pause : Icons.play_arrow, color: fs.parchment),
-              onPressed: () {
-                final h = ref.read(audioHandlerProvider);
-                if (playback?.playing == true) { h.pause(); } else { h.play(); }
-              },
-            ),
-            IconButton(
-              icon: Icon(Icons.skip_next, color: fs.parchment),
-              onPressed: () => ref.read(audioHandlerProvider).skipToNext(),
-            ),
-          ]),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              IntrinsicHeight(
+                child: Row(
+                  crossAxisAlignment: CrossAxisAlignment.center,
+                  children: [
+                    Expanded(child: _TrackInfo(media: displayMedia)),
+                    const SizedBox(width: 8),
+                    _PlayControls(playback: playback, ref: ref),
+                  ],
+                ),
+              ),
+              const SizedBox(height: 4),
+              _SeekRow(position: pos, duration: dur),
+            ],
+          ),
         ),
       ),
     );
   }
 }
+
+class _TrackInfo extends StatelessWidget {
+  const _TrackInfo({required this.media});
+  final MediaItem media;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final artistName = (media.artist ?? '').trim();
+
+    // Cover is wrapped in a Hero with the shared kPlayerCoverHeroTag so
+    // tapping the mini bar to expand into NowPlayingScreen animates the
+    // artwork from this 48dp footprint to the full-screen size rather
+    // than fade-cutting. Tag is stable per-route (not keyed by media.id)
+    // so the transition works regardless of what's playing.
+    //
+    // 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.
+      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
+        // resolution inside the 48dp box — a thumbnail-sized cover
+        // would render as a tiny inset. Cover stretches/crops to fill
+        // the box uniformly.
+        fit: BoxFit.cover,
+        errorBuilder: (_, __, ___) =>
+            Container(width: 48, height: 48, color: fs.slate),
+      );
+    } else {
+      cover = Container(width: 48, height: 48, color: fs.slate);
+    }
+    return Row(
+      // Default centering vertically aligns the like/kebab buttons
+      // against the album art (48dp) — visually they span the title +
+      // artist block instead of sitting on the title baseline.
+      crossAxisAlignment: CrossAxisAlignment.center,
+      children: [
+        Hero(
+          tag: kPlayerCoverHeroTag,
+          child: cover,
+        ),
+        const SizedBox(width: 12),
+        Expanded(
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisAlignment: MainAxisAlignment.center,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Text(
+                media.title,
+                maxLines: 1,
+                overflow: TextOverflow.ellipsis,
+                style: TextStyle(color: fs.parchment, fontSize: 14),
+              ),
+              if (artistName.isNotEmpty)
+                Text(
+                  artistName,
+                  maxLines: 1,
+                  overflow: TextOverflow.ellipsis,
+                  style: TextStyle(color: fs.ash, fontSize: 12),
+                ),
+            ],
+          ),
+        ),
+        // Like + kebab as siblings to the title/artist column rather
+        // than nested inside the title row. Width stays 32dp each so
+        // horizontal footprint matches what we had; height stretches
+        // to the row's full 48dp so the icons sit at vertical center
+        // against the title+artist block.
+        SizedBox(
+          width: 32,
+          height: 48,
+          child: LikeButton(
+            kind: LikeKind.track,
+            id: media.id,
+            size: 20,
+          ),
+        ),
+        SizedBox(
+          width: 32,
+          height: 48,
+          child: TrackActionsButton(
+            track: _trackRefFromMediaItem(media),
+            hideQueueActions: true,
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+class _PlayControls extends StatelessWidget {
+  const _PlayControls({required this.playback, required this.ref});
+  final PlaybackState? playback;
+  final WidgetRef ref;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final isPlaying = playback?.playing == true;
+    return Row(
+      mainAxisSize: MainAxisSize.min,
+      children: [
+        SizedBox(
+          width: 36,
+          height: 36,
+          child: IconButton(
+            padding: EdgeInsets.zero,
+            iconSize: 22,
+            icon: Icon(Icons.skip_previous, color: fs.parchment),
+            onPressed: () => ref.read(audioHandlerProvider).skipToPrevious(),
+          ),
+        ),
+        SizedBox(
+          width: 44,
+          height: 44,
+          child: IconButton(
+            padding: EdgeInsets.zero,
+            iconSize: 32,
+            icon: Icon(
+              isPlaying ? Icons.pause_circle_filled : Icons.play_circle_filled,
+              color: fs.accent,
+            ),
+            onPressed: () {
+              final h = ref.read(audioHandlerProvider);
+              if (isPlaying) {
+                h.pause();
+              } else {
+                h.play();
+              }
+            },
+          ),
+        ),
+        SizedBox(
+          width: 36,
+          height: 36,
+          child: IconButton(
+            padding: EdgeInsets.zero,
+            iconSize: 22,
+            icon: Icon(Icons.skip_next, color: fs.parchment),
+            onPressed: () => ref.read(audioHandlerProvider).skipToNext(),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+class _SeekRow extends ConsumerWidget {
+  const _SeekRow({required this.position, required this.duration});
+  final Duration position;
+  final Duration duration;
+
+  String _fmt(Duration d) {
+    final m = d.inMinutes.remainder(60).toString();
+    final s = d.inSeconds.remainder(60).toString().padLeft(2, '0');
+    return '$m:$s';
+  }
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final maxMs =
+        duration.inMilliseconds.toDouble().clamp(1.0, double.infinity);
+    return Row(
+      children: [
+        SizedBox(
+          width: 36,
+          child: Text(
+            _fmt(position),
+            textAlign: TextAlign.right,
+            style: TextStyle(color: fs.ash, fontSize: 10),
+          ),
+        ),
+        Expanded(
+          child: SliderTheme(
+            data: SliderTheme.of(context).copyWith(
+              trackHeight: 2,
+              thumbShape: const RoundSliderThumbShape(enabledThumbRadius: 6),
+              overlayShape: const RoundSliderOverlayShape(overlayRadius: 12),
+            ),
+            child: Slider(
+              activeColor: fs.accent,
+              inactiveColor: fs.slate,
+              min: 0,
+              max: maxMs,
+              value: position.inMilliseconds
+                  .toDouble()
+                  .clamp(0.0, duration.inMilliseconds.toDouble()),
+              onChanged: (v) => ref
+                  .read(audioHandlerProvider)
+                  .seek(Duration(milliseconds: v.toInt())),
+            ),
+          ),
+        ),
+        SizedBox(
+          width: 36,
+          child: Text(
+            _fmt(duration),
+            style: TextStyle(color: fs.ash, fontSize: 10),
+          ),
+        ),
+      ],
+    );
+  }
+}
+
+/// Reconstructs a minimal TrackRef from a MediaItem so the
+/// TrackActionsButton has the fields its sheet expects. Mirrors the
+/// pattern used by NowPlayingScreen — extras['album_id'] is what
+/// audio_handler stashed at queue-build time.
+TrackRef _trackRefFromMediaItem(MediaItem media) => TrackRef(
+      id: media.id,
+      title: media.title,
+      albumId: (media.extras?['album_id'] as String?) ?? '',
+      albumTitle: media.album ?? '',
+      // artist_id is stashed in extras by audio_handler — without it
+      // the kebab's "Go to artist" pushes /artists/ (empty id) and 404s.
+      artistId: (media.extras?['artist_id'] as String?) ?? '',
+      artistName: media.artist ?? '',
+      durationSec: media.duration?.inSeconds ?? 0,
+      streamUrl: '',
+    );

flutter_client/lib/player/player_provider.dart

@@ -1,14 +1,28 @@
+import 'dart:math' show Random;
+
 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';
 
 final audioHandlerProvider = Provider<MinstrelAudioHandler>((ref) {
   throw UnimplementedError('overridden in main()');
 });
 
+final albumCoverCacheProvider = Provider<AlbumCoverCache>((ref) {
+  return AlbumCoverCache(
+    dioFactory: () => ref.read(dioProvider.future),
+  );
+});
+
 final playbackStateProvider = StreamProvider<PlaybackState>(
   (ref) => ref.watch(audioHandlerProvider).playbackState,
 );
@@ -21,17 +35,132 @@ final queueProvider = StreamProvider<List<MediaItem>>(
   (ref) => ref.watch(audioHandlerProvider).queue,
 );
 
+/// Player volume in [0.0, 1.0]. Mirrors just_audio's player.volume;
+/// modify via PlayerActions.setVolume(). Surfaced separately from
+/// PlaybackState because audio_service's PlaybackState doesn't carry
+/// volume — it's a player-side concern.
+final volumeProvider = StreamProvider<double>(
+  (ref) => ref.watch(audioHandlerProvider).volumeStream,
+);
+
+/// Live playback position. just_audio emits at ~200ms cadence so seek
+/// bars driven by this provider scrub smoothly. Don't use
+/// PlaybackState.updatePosition for that — it only changes on state
+/// transitions (play/pause/buffer/seek) and the bar would appear
+/// frozen between events.
+final positionProvider = StreamProvider<Duration>(
+  (ref) => ref.watch(audioHandlerProvider).positionStream,
+);
+
 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 {
+  Future<void> playTracks(
+    List<TrackRef> tracks, {
+    int initialIndex = 0,
+    bool shuffle = false,
+    String? source,
+  }) async {
+    // shuffle=true means "play this pool randomly, starting at a
+    // random track" (client-side; used for non-system surfaces that
+    // want shuffle). System playlists instead fetch a server-ordered
+    // list and pass source — no client shuffle, the order is already
+    // rotation-aware (#415).
+    var startAt = initialIndex;
+    if (shuffle && tracks.length > 1) {
+      startAt = Random().nextInt(tracks.length);
+    }
     final url   = await _ref.read(serverUrlProvider.future);
     final token = await _ref.read(secureStorageProvider).read(key: 'session_token');
-    final h = _ref.read(audioHandlerProvider)..configure(baseUrl: url ?? '', token: token);
-    await h.setQueueFromTracks(tracks, initialIndex: initialIndex);
+    final cache = _ref.read(albumCoverCacheProvider);
+    final audioCache = _ref.read(audioCacheManagerProvider);
+    final h = _ref.read(audioHandlerProvider)
+      ..configure(
+        baseUrl: url ?? '',
+        token: token,
+        coverCache: cache,
+        audioCacheManager: audioCache,
+        likeBridge: _buildLikeBridge(),
+      );
+    await h.setQueueFromTracks(tracks, initialIndex: startAt, source: source);
+    if (shuffle) {
+      await h.setShuffleMode(AudioServiceShuffleMode.all);
+    }
     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);
+  }
+
+  Future<void> enqueue(TrackRef track) async {
+    final h = _ref.read(audioHandlerProvider);
+    await h.enqueue(track);
+  }
+
+  /// Toggles shuffle on/off. Pre-existing audio_service convention.
+  Future<void> toggleShuffle() async {
+    final h = _ref.read(audioHandlerProvider);
+    final state = await h.playbackState.first;
+    final next = state.shuffleMode == AudioServiceShuffleMode.none
+        ? AudioServiceShuffleMode.all
+        : AudioServiceShuffleMode.none;
+    await h.setShuffleMode(next);
+  }
+
+  /// Cycles repeat mode: none → all → one → none.
+  Future<void> cycleRepeat() async {
+    final h = _ref.read(audioHandlerProvider);
+    final state = await h.playbackState.first;
+    final next = switch (state.repeatMode) {
+      AudioServiceRepeatMode.none => AudioServiceRepeatMode.all,
+      AudioServiceRepeatMode.all => AudioServiceRepeatMode.one,
+      _ => AudioServiceRepeatMode.none,
+    };
+    await h.setRepeatMode(next);
+  }
+
+  Future<void> setVolume(double v) async {
+    await _ref.read(audioHandlerProvider).setVolume(v);
+  }
+
+  /// Fetches `/api/radio?seed_track=<id>` and starts playing the
+  /// returned track list (seed at index 0 + recommended picks).
+  Future<void> startRadio(String trackId) async {
+    final dio = await _ref.read(dioProvider.future);
+    final tracks = await RadioApi(dio).seedTrack(trackId);
+    if (tracks.isEmpty) return;
+    await playTracks(tracks);
+  }
 }
 
 final playerActionsProvider = Provider<PlayerActions>((ref) => PlayerActions(ref));

flutter_client/lib/playlists/playlist_detail_screen.dart

@@ -5,17 +5,49 @@ import 'package:go_router/go_router.dart';
 import '../models/playlist.dart';
 import '../models/track.dart';
 import '../player/player_provider.dart';
+import '../shared/live_events_provider.dart';
+import '../shared/widgets/track_actions/track_actions_button.dart';
 import '../theme/theme_extension.dart';
 import 'playlists_provider.dart';
 
 class PlaylistDetailScreen extends ConsumerWidget {
-  const PlaylistDetailScreen({required this.id, super.key});
+  const PlaylistDetailScreen({required this.id, this.seed, super.key});
   final String id;
 
+  /// Optional Playlist passed via go_router extra so the header
+  /// (title, cover, track count, play/download CTAs) can render
+  /// before the full detail fetch resolves. Same pattern as album
+  /// + artist nav hydration.
+  final Playlist? seed;
+
   @override
   Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // #402 wire-up: invalidate the detail provider on playlist.updated /
+    // .tracks_changed events whose payload matches the visible id. On
+    // .deleted matching this id, navigate back so the user isn't left
+    // staring at a gone-from-server playlist.
+    ref.listen<AsyncValue<LiveEvent>>(liveEventsProvider, (_, next) {
+      final e = next.asData?.value;
+      if (e == null) return;
+      final eventPlaylistId = e.data['playlist_id'] as String?;
+      if (eventPlaylistId != id) return;
+      switch (e.kind) {
+        case 'playlist.updated':
+        case 'playlist.tracks_changed':
+          ref.invalidate(playlistDetailProvider(id));
+        case 'playlist.deleted':
+          if (context.mounted) context.pop();
+      }
+    });
     final detail = ref.watch(playlistDetailProvider(id));
+
+    // Resolve the best playlist info available for the AppBar title.
+    final livePlaylist = detail.value?.playlist;
+    final headerName = (livePlaylist != null && livePlaylist.name.isNotEmpty)
+        ? livePlaylist.name
+        : (seed?.name ?? '');
+
     return Scaffold(
       backgroundColor: fs.obsidian,
       appBar: AppBar(
@@ -25,31 +57,123 @@ class PlaylistDetailScreen extends ConsumerWidget {
           icon: Icon(Icons.arrow_back, color: fs.parchment),
           onPressed: () => context.pop(),
         ),
-        title: detail.maybeWhen(
-          data: (d) => Text(
-            d.playlist.name,
-            style: TextStyle(color: fs.parchment),
-            overflow: TextOverflow.ellipsis,
+        title: headerName.isEmpty
+            ? const SizedBox.shrink()
+            : Text(
+                headerName,
+                style: TextStyle(color: fs.parchment),
+                overflow: TextOverflow.ellipsis,
+              ),
+      ),
+      // AnimatedSwitcher between the skeleton body and the real body
+      // smooths the cold-visit moment when bulk detail lands. 220ms
+      // matches the per-tile reveal feel used on home / liked tabs.
+      body: AnimatedSwitcher(
+        duration: const Duration(milliseconds: 220),
+        switchInCurve: Curves.easeOut,
+        child: detail.when(
+          loading: () => _SkeletonBody(
+            key: const ValueKey('skeleton'),
+            seed: seed,
           ),
-          orElse: () => const SizedBox.shrink(),
+          error: (e, _) => Center(
+            key: const ValueKey('error'),
+            child: Text('$e', style: TextStyle(color: fs.error)),
+          ),
+          data: (d) => _Body(key: const ValueKey('body'), detail: d),
         ),
       ),
-      body: detail.when(
-        loading: () => const Center(child: CircularProgressIndicator()),
-        error: (e, _) =>
-            Center(child: Text('$e', style: TextStyle(color: fs.error))),
-        data: (d) => _Body(detail: d),
+    );
+  }
+}
+
+/// Cold-visit body: header from the seed (if any) + N skeleton rows.
+/// N comes from the seed's trackCount so the row count matches the
+/// real list when it lands — no layout jump on swap. Without a seed
+/// (deep link straight to a playlist with no prior cache) the
+/// skeleton renders a small default and grows when real data arrives.
+class _SkeletonBody extends StatelessWidget {
+  const _SkeletonBody({super.key, this.seed});
+  final Playlist? seed;
+
+  static const _defaultSkeletonCount = 8;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final count = seed?.trackCount ?? _defaultSkeletonCount;
+    return ListView.builder(
+      itemCount: count + 1, // +1 for header
+      itemBuilder: (ctx, i) {
+        if (i == 0) {
+          return Padding(
+            padding: const EdgeInsets.fromLTRB(16, 8, 16, 16),
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                if (seed != null && seed!.description.isNotEmpty)
+                  Padding(
+                    padding: const EdgeInsets.only(bottom: 12),
+                    child: Text(
+                      seed!.description,
+                      style: TextStyle(color: fs.ash, fontSize: 13),
+                    ),
+                  ),
+                Text(
+                  seed == null
+                      ? 'Loading…'
+                      : '${seed!.trackCount} ${seed!.trackCount == 1 ? "track" : "tracks"}',
+                  style: TextStyle(color: fs.ash, fontSize: 12),
+                ),
+              ],
+            ),
+          );
+        }
+        return const _PlaylistTrackSkeleton();
+      },
+    );
+  }
+}
+
+/// Skeleton matched to _PlaylistTrackRow's layout (no cover image —
+/// playlist rows are text-only). Two text-shaped placeholders for
+/// title + secondary line, plus a duration block on the right.
+class _PlaylistTrackSkeleton extends StatelessWidget {
+  const _PlaylistTrackSkeleton();
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return Padding(
+      padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
+      child: Row(
+        children: [
+          Expanded(
+            child: Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                Container(width: 200, height: 14, color: fs.slate),
+                const SizedBox(height: 6),
+                Container(width: 140, height: 12, color: fs.slate),
+              ],
+            ),
+          ),
+          const SizedBox(width: 16),
+          Container(width: 32, height: 12, color: fs.slate),
+        ],
       ),
     );
   }
 }
 
 class _Body extends ConsumerWidget {
-  const _Body({required this.detail});
+  const _Body({super.key, required this.detail});
   final PlaylistDetail detail;
 
   @override
   Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     final tracks = detail.tracks;
     final playable = tracks.where((t) => t.isAvailable).toList();
 
@@ -57,9 +181,22 @@ class _Body extends ConsumerWidget {
       onRefresh: () async =>
           ref.refresh(playlistDetailProvider(detail.playlist.id).future),
       child: ListView.builder(
-        itemCount: tracks.length + 1, // header + rows
+        // Header + (track rows | empty hint).
+        itemCount: tracks.isEmpty ? 2 : tracks.length + 1,
         itemBuilder: (ctx, i) {
           if (i == 0) return _Header(detail: detail, playable: playable);
+          if (tracks.isEmpty) {
+            return Padding(
+              padding: const EdgeInsets.all(24),
+              child: Center(
+                child: Text(
+                  'No tracks yet. Add some via the "Add to playlist…" entry on any track row.',
+                  style: TextStyle(color: fs.ash),
+                  textAlign: TextAlign.center,
+                ),
+              ),
+            );
+          }
           final t = tracks[i - 1];
           return _PlaylistTrackRow(
             row: t,
@@ -73,6 +210,9 @@ class _Body extends ConsumerWidget {
                     ref.read(playerActionsProvider).playTracks(
                           playableRefs,
                           initialIndex: startIdx >= 0 ? startIdx : 0,
+                          source: detail.playlist.refreshable
+                              ? detail.playlist.systemVariant
+                              : null,
                         );
                     // Keep liveTrack referenced to avoid an unused-variable
                     // warning while we leave hooks for menu wiring later.
@@ -123,11 +263,23 @@ class _Header extends ConsumerWidget {
             style: TextStyle(color: fs.ash, fontSize: 12),
           ),
           const Spacer(),
-          if (playable.isNotEmpty)
+          if (playable.isNotEmpty) ...[
+            if (p.refreshable) ...[
+              OutlinedButton.icon(
+                key: const Key('regenerate_playlist_button'),
+                onPressed: () => _regenerate(context, ref),
+                icon: const Icon(Icons.refresh, size: 16),
+                label: const Text('Regenerate'),
+              ),
+              const SizedBox(width: 8),
+            ],
             FilledButton.icon(
               onPressed: () {
                 final refs = playable.map(_toTrackRef).toList(growable: false);
-                ref.read(playerActionsProvider).playTracks(refs);
+                ref.read(playerActionsProvider).playTracks(
+                      refs,
+                      source: p.refreshable ? p.systemVariant : null,
+                    );
               },
               icon: const Icon(Icons.play_arrow),
               label: const Text('Play'),
@@ -136,55 +288,107 @@ class _Header extends ConsumerWidget {
                 foregroundColor: fs.parchment,
               ),
             ),
+          ],
         ]),
       ]),
     );
   }
+
+  /// Forces a server-side rebuild of this system playlist. The
+  /// rebuild rotates the playlist UUID, so the old detail route now
+  /// 404s — rebind by pushReplacement-ing to the new id. The
+  /// aggregate list is invalidated too so the home row's tile points
+  /// at the fresh UUID. ScaffoldMessenger + router captured before
+  /// the await so we don't touch a stale BuildContext after.
+  Future<void> _regenerate(BuildContext context, WidgetRef ref) async {
+    final messenger = ScaffoldMessenger.of(context);
+    final router = GoRouter.of(context);
+    final p = detail.playlist;
+    try {
+      final api = await ref.read(playlistsApiProvider.future);
+      final newId = await api.refreshSystem(p.systemVariant!);
+      ref.invalidate(playlistsListProvider);
+      if (newId == null) {
+        messenger.showSnackBar(const SnackBar(
+          content: Text('Nothing to build yet — library is empty.'),
+        ));
+        return;
+      }
+      messenger.showSnackBar(
+        SnackBar(content: Text('${p.name} regenerated')),
+      );
+      router.pushReplacement('/playlists/$newId');
+    } catch (e) {
+      messenger.showSnackBar(
+        SnackBar(content: Text("Couldn't regenerate: $e")),
+      );
+    }
+  }
 }
 
-class _PlaylistTrackRow extends StatelessWidget {
+class _PlaylistTrackRow extends ConsumerWidget {
   const _PlaylistTrackRow({required this.row, required this.onTap});
   final PlaylistTrack row;
   final VoidCallback? onTap;
 
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
     final fs = Theme.of(context).extension<FabledSwordTheme>()!;
     final mins = (row.durationSec ~/ 60).toString().padLeft(2, '0');
     final secs = (row.durationSec % 60).toString().padLeft(2, '0');
-    final color = row.isAvailable ? fs.parchment : fs.ash;
-    return InkWell(
-      onTap: onTap,
-      child: Padding(
-        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
-        child: Row(children: [
-          Expanded(
-            child: Column(
-              crossAxisAlignment: CrossAxisAlignment.start,
-              children: [
-                Text(
-                  row.title,
-                  maxLines: 1,
-                  overflow: TextOverflow.ellipsis,
-                  style: TextStyle(
-                    color: color,
-                    fontSize: 14,
-                    decoration: row.isAvailable
-                        ? null
-                        : TextDecoration.lineThrough,
+    // "Now playing" highlight — matches _QueueRow and TrackRow so the
+    // user sees which playlist row is current without reading the
+    // player bar. Unavailable rows never match.
+    final currentId = ref.watch(mediaItemProvider).value?.id;
+    final isCurrent = row.isAvailable &&
+        currentId != null &&
+        currentId == row.trackId;
+    final baseColor = row.isAvailable ? fs.parchment : fs.ash;
+    final titleColor = isCurrent ? fs.accent : baseColor;
+    return Container(
+      decoration: BoxDecoration(
+        color: isCurrent ? fs.iron : null,
+        border: isCurrent
+            ? Border(left: BorderSide(color: fs.accent, width: 2))
+            : null,
+      ),
+      child: InkWell(
+        onTap: onTap,
+        child: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
+          child: Row(children: [
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  Text(
+                    row.title,
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(
+                      color: titleColor,
+                      fontSize: 14,
+                      fontWeight:
+                          isCurrent ? FontWeight.w500 : FontWeight.w400,
+                      decoration: row.isAvailable
+                          ? null
+                          : TextDecoration.lineThrough,
+                    ),
                   ),
-                ),
-                Text(
-                  '${row.artistName} · ${row.albumTitle}',
-                  maxLines: 1,
-                  overflow: TextOverflow.ellipsis,
-                  style: TextStyle(color: fs.ash, fontSize: 12),
-                ),
-              ],
+                  Text(
+                    '${row.artistName} · ${row.albumTitle}',
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(color: fs.ash, fontSize: 12),
+                  ),
+                ],
+              ),
             ),
-          ),
-          Text('$mins:$secs', style: TextStyle(color: fs.ash, fontSize: 12)),
-        ]),
+            Text('$mins:$secs', style: TextStyle(color: fs.ash, fontSize: 12)),
+            if (row.trackId != null)
+              TrackActionsButton(track: _toTrackRef(row)),
+          ]),
+        ),
       ),
     );
   }

flutter_client/lib/playlists/playlists_list_screen.dart

@@ -4,6 +4,7 @@ import 'package:go_router/go_router.dart';
 
 import '../models/playlist.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
+import '../shared/widgets/server_image.dart';
 import '../theme/theme_extension.dart';
 import 'playlists_provider.dart';
 
@@ -30,7 +31,8 @@ class PlaylistsListScreen extends ConsumerWidget {
         error: (e, _) => Center(
           child: Text('$e', style: TextStyle(color: fs.error)),
         ),
-        data: (items) {
+        data: (lists) {
+          final items = lists.all;
           if (items.isEmpty) {
             return Center(
               child: Text(
@@ -49,7 +51,7 @@ class PlaylistsListScreen extends ConsumerWidget {
                 final p = items[i];
                 return _PlaylistTile(
                   playlist: p,
-                  onTap: () => ctx.push('/playlists/${p.id}'),
+                  onTap: () => ctx.push('/playlists/${p.id}', extra: p),
                 );
               },
             ),
@@ -81,7 +83,11 @@ class _PlaylistTile extends StatelessWidget {
               color: fs.slate,
               child: playlist.coverUrl.isEmpty
                   ? Icon(Icons.queue_music, color: fs.ash)
-                  : Image.network(playlist.coverUrl, fit: BoxFit.cover),
+                  : ServerImage(
+                      url: playlist.coverUrl,
+                      fit: BoxFit.cover,
+                      fallback: Icon(Icons.queue_music, color: fs.ash),
+                    ),
             ),
           ),
           const SizedBox(width: 12),

flutter_client/lib/playlists/playlists_provider.dart

@@ -1,19 +1,403 @@
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:dio/dio.dart';
+import 'package:drift/drift.dart' as drift;
+import 'package:flutter/foundation.dart' show debugPrint;
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 
+import '../api/endpoints/me.dart';
 import '../api/endpoints/playlists.dart';
+import '../auth/auth_provider.dart';
+import '../cache/adapters.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../cache/cache_first.dart';
+import '../cache/connectivity_provider.dart';
+import '../cache/db.dart';
 import '../library/library_providers.dart' show dioProvider;
 import '../models/playlist.dart';
+import '../models/system_playlists_status.dart';
 
 final playlistsApiProvider = FutureProvider<PlaylistsApi>((ref) async {
   return PlaylistsApi(await ref.watch(dioProvider.future));
 });
 
+/// Drift-first per #357 plan C. Returns cached playlists filtered to
+/// match the `kind` family arg:
+///   - 'user' → only user-created (systemVariant null), owned by current user
+///   - 'system' → only system-generated (systemVariant non-null), owned
+///   - 'all' → everything: own user playlists + own system + others' public
+///
+/// systemVariant column added in drift schema v2 (#357 follow-up); previous
+/// behavior leaked system playlists into add-to-playlist sheet because we
+/// couldn't filter locally.
 final playlistsListProvider =
-    FutureProvider.family<List<Playlist>, String>((ref, kind) async {
-  return (await ref.watch(playlistsApiProvider.future)).list(kind: kind);
+    StreamProvider.family<PlaylistsList, String>((ref, kind) {
+  final db = ref.watch(appDbProvider);
+  final user = ref.watch(authControllerProvider).value;
+
+  return cacheFirst<CachedPlaylist, PlaylistsList>(
+    driftStream: db.select(db.cachedPlaylists).watch(),
+    fetchAndPopulate: () async {
+      final api = await ref.read(playlistsApiProvider.future);
+      final fresh = await api.list(kind: kind);
+
+      // Reconcile: BuildSystemPlaylists rotates system-playlist UUIDs
+      // every rebuild, so insertOrReplace alone leaves stale rows in
+      // drift. Tapping one of those stale tiles 404s. Delete every
+      // owned drift row whose id isn't in the fresh response, then
+      // upsert the fresh set.
+      final freshOwnedIds =
+          fresh.owned.map((p) => p.id).toSet();
+      await db.batch((b) {
+        if (user != null) {
+          b.deleteWhere(db.cachedPlaylists, (t) {
+            return t.userId.equals(user.id) &
+                t.id.isNotIn(freshOwnedIds);
+          });
+        }
+        for (final p in fresh.all) {
+          b.insert(db.cachedPlaylists, p.toDrift(),
+              mode: drift.InsertMode.insertOrReplace);
+        }
+      });
+    },
+    toResult: (rows) {
+      if (user == null) return PlaylistsList.empty();
+      final filtered = rows.where((r) {
+        if (kind == 'user') return r.systemVariant == null;
+        if (kind == 'system') return r.systemVariant != null;
+        return true; // 'all'
+      }).toList();
+      final owned = filtered
+          .where((r) => r.userId == user.id)
+          .map((r) => r.toRef())
+          .toList();
+      final pub = filtered
+          .where((r) => r.userId != user.id && r.isPublic)
+          .map((r) => r.toRef())
+          .toList();
+      return PlaylistsList(owned: owned, public: pub);
+    },
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    // Aggregate list — server may add system playlists (For-You /
+    // Discover) that the per-user delta sync doesn't always emit.
+    // Stale-while-revalidate ensures the home tile row reflects the
+    // current server state on every screen visit.
+    alwaysRefresh: true,
+  );
 });
 
+/// Composite shape (playlist + tracks). async* over the playlist watch
+/// stream + a one-shot tracks fetch per emission.
 final playlistDetailProvider =
-    FutureProvider.family<PlaylistDetail, String>((ref, id) async {
-  return (await ref.watch(playlistsApiProvider.future)).get(id);
+    StreamProvider.family<PlaylistDetail, String>((ref, id) async* {
+  final db = ref.watch(appDbProvider);
+  final user = ref.watch(authControllerProvider).value;
+
+  final playlistQuery = db.select(db.cachedPlaylists)
+    ..where((t) => t.id.equals(id));
+
+  final tracksQuery = (db.select(db.cachedPlaylistTracks)
+        ..where((t) => t.playlistId.equals(id))
+        ..orderBy([(t) => drift.OrderingTerm.asc(t.position)]))
+      .join([
+    drift.leftOuterJoin(db.cachedTracks,
+        db.cachedTracks.id.equalsExp(db.cachedPlaylistTracks.trackId)),
+    drift.leftOuterJoin(db.cachedArtists,
+        db.cachedArtists.id.equalsExp(db.cachedTracks.artistId)),
+    drift.leftOuterJoin(db.cachedAlbums,
+        db.cachedAlbums.id.equalsExp(db.cachedTracks.albumId)),
+  ]);
+
+  PlaylistDetail emptyDetail() => PlaylistDetail(
+        playlist: Playlist(
+          id: id,
+          userId: user?.id ?? '',
+          name: '',
+          description: '',
+          isPublic: false,
+          systemVariant: null,
+          trackCount: 0,
+          coverUrl: '',
+          ownerUsername: '',
+          createdAt: '',
+          updatedAt: '',
+        ),
+        tracks: const [],
+      );
+
+  Future<bool> isOnline() async {
+    try {
+      return await ref
+          .read(connectivityProvider.future)
+          .timeout(const Duration(seconds: 3), onTimeout: () => true);
+    } catch (_) {
+      return true;
+    }
+  }
+
+  Future<bool> fetchAndPopulate() async {
+    try {
+      final api = await ref.read(playlistsApiProvider.future);
+      final fresh = await api.get(id).timeout(const Duration(seconds: 10));
+
+      // Collect the track + artist + album rows referenced by these
+      // playlist entries. Without writing the cachedTracks rows
+      // themselves, the detail-screen JOIN against cachedTracks
+      // returns null on every row (only the playlist_tracks join
+      // succeeds), so the UI shows a list with empty titles and
+      // unplayable tracks.
+      final tracks = <String, _TrackRefRow>{};
+      final artists = <String, ArtistRefRow>{};
+      final albums = <String, AlbumRefRow>{};
+      for (final t in fresh.tracks) {
+        final tId = t.trackId;
+        if (tId != null && tId.isNotEmpty) {
+          tracks.putIfAbsent(
+            tId,
+            () => _TrackRefRow(
+              id: tId,
+              title: t.title,
+              albumId: t.albumId ?? '',
+              artistId: t.artistId ?? '',
+              durationSec: t.durationSec,
+            ),
+          );
+        }
+        final aId = t.artistId;
+        final aName = t.artistName;
+        if (aId != null && aId.isNotEmpty && aName.isNotEmpty) {
+          artists.putIfAbsent(aId, () => ArtistRefRow(aId, aName));
+        }
+        final lbId = t.albumId;
+        final lbTitle = t.albumTitle;
+        if (lbId != null && lbId.isNotEmpty && lbTitle.isNotEmpty) {
+          albums.putIfAbsent(lbId, () => AlbumRefRow(lbId, lbTitle, aId ?? ''));
+        }
+      }
+
+      await db.batch((b) {
+        b.insert(db.cachedPlaylists, fresh.playlist.toDrift(),
+            mode: drift.InsertMode.insertOrReplace);
+
+        // Wipe + re-insert this playlist's track positions so deletions
+        // propagate. Without the wipe, removed tracks would linger in
+        // drift after the playlist mutated server-side.
+        b.deleteWhere(
+            db.cachedPlaylistTracks, (t) => t.playlistId.equals(id));
+
+        for (var i = 0; i < fresh.tracks.length; i++) {
+          final t = fresh.tracks[i];
+          if (t.trackId == null) continue;
+          b.insert(
+            db.cachedPlaylistTracks,
+            CachedPlaylistTracksCompanion.insert(
+              playlistId: id,
+              trackId: t.trackId!,
+              position: drift.Value(i),
+            ),
+            mode: drift.InsertMode.insertOrReplace,
+          );
+        }
+
+        if (artists.isNotEmpty) {
+          b.insertAllOnConflictUpdate(
+            db.cachedArtists,
+            artists.values
+                .map((a) => CachedArtistsCompanion.insert(
+                      id: a.id,
+                      name: a.name,
+                      sortName: a.name,
+                    ))
+                .toList(),
+          );
+        }
+        if (tracks.isNotEmpty) {
+          // Insert/update cachedTracks so the detail screen's JOIN
+          // produces real titles + durations. We don't have
+          // track_number / disc_number on the wire (PlaylistTrack
+          // omits them), so they default to 0 — UI doesn't surface
+          // them on this screen so it's fine.
+          b.insertAllOnConflictUpdate(
+            db.cachedTracks,
+            tracks.values
+                .map((t) => CachedTracksCompanion.insert(
+                      id: t.id,
+                      albumId: t.albumId,
+                      artistId: t.artistId,
+                      title: t.title,
+                      durationMs: drift.Value(t.durationSec * 1000),
+                    ))
+                .toList(),
+          );
+        }
+        if (albums.isNotEmpty) {
+          b.insertAllOnConflictUpdate(
+            db.cachedAlbums,
+            albums.values
+                .map((a) => CachedAlbumsCompanion.insert(
+                      id: a.id,
+                      artistId: a.artistId,
+                      title: a.title,
+                      sortTitle: a.title,
+                    ))
+                .toList(),
+          );
+        }
+      });
+      return true;
+    } catch (e, st) {
+      // 404 = the playlist row in drift is stale (BuildSystemPlaylists
+      // rotates UUIDs on each rebuild, so old For-You / Songs-Like
+      // tiles can outlive the actual server-side playlist). Wipe the
+      // stale row + its track positions so the home tile disappears
+      // on next render and we don't keep trying.
+      if (e is DioException && e.response?.statusCode == 404) {
+        await db.batch((b) {
+          b.deleteWhere(
+              db.cachedPlaylistTracks, (t) => t.playlistId.equals(id));
+          b.deleteWhere(db.cachedPlaylists, (t) => t.id.equals(id));
+        });
+        return false;
+      }
+      debugPrint('playlistDetailProvider($id): fetch failed: $e\n$st');
+      return false;
+    }
+  }
+
+  // Once-per-subscription guard so an empty server response doesn't
+  // cause repeated re-fetches.
+  var fetchAttempted = false;
+
+  await for (final playlistRows in playlistQuery.watch()) {
+    if (playlistRows.isEmpty) {
+      if (fetchAttempted) {
+        yield emptyDetail();
+        continue;
+      }
+      fetchAttempted = true;
+      if (!await isOnline()) {
+        yield emptyDetail();
+        continue;
+      }
+      final ok = await fetchAndPopulate();
+      if (!ok) yield emptyDetail();
+      continue;
+    }
+
+    final playlist = playlistRows.first.toRef();
+    final trackRows = await tracksQuery.get();
+
+    // Same pattern as albumProvider: playlist row exists but no tracks
+    // (e.g., playlistsListProvider wrote the row, sync hasn't carried
+    // tracks for system playlists). Trigger the same fetch, drift
+    // watch re-emits with populated tracks.
+    if (trackRows.isEmpty && !fetchAttempted) {
+      fetchAttempted = true;
+      if (await isOnline()) {
+        final ok = await fetchAndPopulate();
+        if (ok) continue; // wait for watch re-emit
+      }
+    }
+
+    final tracks = trackRows.asMap().entries.map((e) {
+      final r = e.value;
+      final track = r.readTableOrNull(db.cachedTracks);
+      final artist = r.readTableOrNull(db.cachedArtists);
+      final album = r.readTableOrNull(db.cachedAlbums);
+      return PlaylistTrack(
+        position: e.key,
+        trackId: track?.id,
+        title: track?.title ?? '',
+        albumId: album?.id,
+        albumTitle: album?.title ?? '',
+        artistId: artist?.id,
+        artistName: artist?.name ?? '',
+        durationSec: track == null ? 0 : track.durationMs ~/ 1000,
+        streamUrl: null,
+      );
+    }).toList();
+
+    yield PlaylistDetail(playlist: playlist, tracks: tracks);
+
+    // No SWR refresh here. The aggregate playlistsListProvider does
+    // alwaysRefresh (system playlists rotate UUIDs), but per-detail
+    // refresh on every visit was multiplying with the prefetcher's
+    // parallel fetches and starving user-initiated playback. Pull-
+    // to-refresh on the detail page invalidates the provider, which
+    // is the right path for an explicit refresh.
+  }
+});
+
+/// Lightweight tuples used inside fetchAndPopulate to dedupe artist
+/// and album rows referenced by playlist tracks before we batch-write
+/// them to drift.
+class ArtistRefRow {
+  ArtistRefRow(this.id, this.name);
+  final String id;
+  final String name;
+}
+
+class AlbumRefRow {
+  AlbumRefRow(this.id, this.title, this.artistId);
+  final String id;
+  final String title;
+  final String artistId;
+}
+
+class _TrackRefRow {
+  _TrackRefRow({
+    required this.id,
+    required this.title,
+    required this.albumId,
+    required this.artistId,
+    required this.durationSec,
+  });
+  final String id;
+  final String title;
+  final String albumId;
+  final String artistId;
+  final int durationSec;
+}
+
+/// Drift-first per #357 pattern. Reads from cached_system_playlists_
+/// status (single-row JSON blob populated by /api/me/system-playlists-
+/// status). Home Playlists row reads this every render to choose
+/// between real cards and "building / pending / failed" placeholders
+/// — drift-first means the row paints with the prior status instantly
+/// rather than flickering through SystemPlaylistsStatus.empty() while
+/// the REST round-trip resolves. SWR refresh on every visit keeps it
+/// current.
+final systemPlaylistsStatusProvider =
+    StreamProvider<SystemPlaylistsStatus>((ref) {
+  final db = ref.watch(appDbProvider);
+  return cacheFirst<CachedSystemPlaylistsStatusData, SystemPlaylistsStatus>(
+    driftStream: db.select(db.cachedSystemPlaylistsStatus).watch(),
+    fetchAndPopulate: () async {
+      final dio = await ref.read(dioProvider.future);
+      final fresh = await MeApi(dio).systemPlaylistsStatus();
+      await db.into(db.cachedSystemPlaylistsStatus).insertOnConflictUpdate(
+            CachedSystemPlaylistsStatusCompanion.insert(
+              json: jsonEncode({
+                'in_flight': fresh.inFlight,
+                'last_run_at': fresh.lastRunAt,
+                'last_error': fresh.lastError,
+              }),
+              updatedAt: drift.Value(DateTime.now()),
+            ),
+          );
+    },
+    toResult: (rows) => rows.isEmpty
+        ? SystemPlaylistsStatus.empty()
+        : SystemPlaylistsStatus.fromJson(
+            jsonDecode(rows.first.json) as Map<String, dynamic>),
+    isOnline: () async => (await ref
+        .read(connectivityProvider.future)
+        .timeout(const Duration(seconds: 3), onTimeout: () => true)),
+    alwaysRefresh: true,
+    tag: 'systemPlaylistsStatus',
+  );
 });

flutter_client/lib/playlists/widgets/playlist_card.dart

@@ -0,0 +1,223 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+
+import '../../cache/offline_provider.dart';
+import '../../library/widgets/play_circle_button.dart';
+import '../../models/playlist.dart';
+import '../../models/track.dart';
+import '../../player/player_provider.dart';
+import '../../shared/widgets/server_image.dart';
+import '../../theme/theme_extension.dart';
+import '../playlists_provider.dart';
+
+/// Mirrors the web PlaylistCard. ~176dp wide, square cover (~144dp),
+/// name + optional system-variant badge below. Tap pushes
+/// `/playlists/{id}`. The bottom-right play button fetches the
+/// playlist and starts playback from track 0; disabled when the
+/// playlist has no tracks.
+class PlaylistCard extends ConsumerWidget {
+  const PlaylistCard({super.key, required this.playlist});
+
+  final Playlist playlist;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // #427 S4: refreshable system playlists need the live build/
+    // shuffle endpoints — unavailable offline. Disable their play
+    // (use Shuffle all instead). User playlists play from cache.
+    final offline = ref.watch(offlineProvider);
+    final hasTracks = playlist.trackCount > 0 &&
+        !(offline && playlist.refreshable);
+    return SizedBox(
+      width: 176,
+      child: Material(
+        color: Colors.transparent,
+        child: InkWell(
+          onTap: () =>
+              context.push('/playlists/${playlist.id}', extra: playlist),
+          child: Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 8),
+            child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+              // Stack: collage + overlaid play button at bottom-right.
+              Stack(
+                children: [
+                  ClipRRect(
+                    borderRadius: BorderRadius.circular(6),
+                    child: Container(
+                      width: 144,
+                      height: 144,
+                      color: fs.slate,
+                      // coverUrl is deterministic per playlist (see
+                      // CachedPlaylistAdapter.toRef). When the server's
+                      // collage isn't built yet, ServerImage's
+                      // errorBuilder shows the queue_music icon over the
+                      // slate background.
+                      child: playlist.coverUrl.isEmpty
+                          ? Icon(Icons.queue_music, color: fs.ash, size: 56)
+                          : ServerImage(
+                              url: playlist.coverUrl,
+                              fit: BoxFit.cover,
+                              fallback:
+                                  Icon(Icons.queue_music, color: fs.ash, size: 56),
+                            ),
+                    ),
+                  ),
+                  Positioned(
+                    bottom: 6,
+                    right: 6,
+                    child: PlayCircleButton(
+                      enabled: hasTracks,
+                      onPressed: () => _playPlaylist(ref),
+                    ),
+                  ),
+                  // System playlists get a refresh affordance so the
+                  // user can force a fresh mix instead of waiting for
+                  // the daily 03:00 rebuild. Mirrors the web kebab.
+                  if (playlist.refreshable)
+                    Positioned(
+                      top: 2,
+                      right: 2,
+                      child: PopupMenuButton<String>(
+                        icon: Icon(Icons.more_vert, color: fs.parchment, size: 18),
+                        tooltip: 'Playlist actions',
+                        color: fs.iron,
+                        onSelected: (_) => _refresh(context, ref),
+                        itemBuilder: (_) => [
+                          PopupMenuItem<String>(
+                            value: 'refresh',
+                            child: Row(children: [
+                              Icon(Icons.refresh, color: fs.parchment, size: 18),
+                              const SizedBox(width: 8),
+                              Text(_refreshLabel,
+                                  style: TextStyle(color: fs.parchment)),
+                            ]),
+                          ),
+                        ],
+                      ),
+                    ),
+                ],
+              ),
+              const SizedBox(height: 8),
+              Text(
+                playlist.name,
+                maxLines: 1,
+                overflow: TextOverflow.ellipsis,
+                style: TextStyle(color: fs.parchment, fontSize: 14),
+              ),
+              if (playlist.isSystem)
+                Padding(
+                  padding: const EdgeInsets.only(top: 2),
+                  child: Container(
+                    padding:
+                        const EdgeInsets.symmetric(horizontal: 6, vertical: 2),
+                    decoration: BoxDecoration(
+                      color: fs.iron,
+                      borderRadius: BorderRadius.circular(4),
+                    ),
+                    child: Text(
+                      playlist.systemVariant!.replaceAll('_', ' '),
+                      style: TextStyle(color: fs.accent, fontSize: 11),
+                    ),
+                  ),
+                ),
+              if (playlist.isSystem && _refreshedLabel(playlist.createdAt) != '')
+                Padding(
+                  padding: const EdgeInsets.only(top: 2),
+                  child: Text(
+                    _refreshedLabel(playlist.createdAt),
+                    maxLines: 1,
+                    overflow: TextOverflow.ellipsis,
+                    style: TextStyle(color: fs.ash, fontSize: 11),
+                  ),
+                ),
+            ]),
+          ),
+        ),
+      ),
+    );
+  }
+
+  String get _refreshLabel => 'Refresh ${playlist.name}';
+
+  /// #417: system playlists atomic-replace on rebuild, so createdAt
+  /// is the last-rotated time. Friendly wording mirrors the web
+  /// PlaylistCard. Empty string when the timestamp is unparseable.
+  String _refreshedLabel(String iso) {
+    final t = DateTime.tryParse(iso);
+    if (t == null) return '';
+    final now = DateTime.now();
+    final mins = now.difference(t).inMinutes;
+    if (mins < 5) return 'Refreshed just now';
+    final startOfToday = DateTime(now.year, now.month, now.day);
+    if (!t.isBefore(startOfToday)) return 'Refreshed today';
+    final days = startOfToday.difference(DateTime(t.year, t.month, t.day)).inDays;
+    if (days <= 1) return 'Refreshed yesterday';
+    if (days < 7) return 'Refreshed $days days ago';
+    const months = [
+      'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+      'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+    ];
+    return 'Refreshed ${months[t.month - 1]} ${t.day}';
+  }
+
+  /// Forces a server-side rebuild of this system playlist, then
+  /// invalidates the aggregate list so the rotated UUID + new tracks
+  /// land on the next read. ScaffoldMessenger is captured before the
+  /// await so we don't touch a stale BuildContext afterward.
+  Future<void> _refresh(BuildContext context, WidgetRef ref) async {
+    final messenger = ScaffoldMessenger.of(context);
+    try {
+      final api = await ref.read(playlistsApiProvider.future);
+      await api.refreshSystem(playlist.systemVariant!);
+      ref.invalidate(playlistsListProvider);
+      messenger.showSnackBar(
+        SnackBar(content: Text('${playlist.name} refreshed')),
+      );
+    } catch (e) {
+      messenger.showSnackBar(
+        SnackBar(content: Text("Couldn't refresh: $e")),
+      );
+    }
+  }
+
+  /// Fetches the playlist via /api/playlists/{id}, materializes each
+  /// PlaylistTrack into a TrackRef (filtering out unavailable rows
+  /// whose `trackId` is null after a track-delete), and plays from
+  /// index 0. Mirrors the web PlaylistCard's onPlayClick.
+  Future<void> _playPlaylist(WidgetRef ref) async {
+    final api = await ref.read(playlistsApiProvider.future);
+    // Refreshable (singleton) system playlists: fetch the server's
+    // rotation-aware order (#415) and play as-is, tagged with the
+    // source so the reporter advances rotation. User playlists AND
+    // non-singleton system kinds (songs_like_artist — no by-kind
+    // endpoint) play the stored order via get(), untagged.
+    final detail = playlist.refreshable
+        ? await api.systemShuffle(playlist.systemVariant!)
+        : await api.get(playlist.id);
+    final refs = <TrackRef>[];
+    for (final t in detail.tracks) {
+      if (t.trackId == null) continue;
+      refs.add(TrackRef(
+        id: t.trackId!,
+        title: t.title,
+        albumId: t.albumId ?? '',
+        albumTitle: t.albumTitle,
+        artistId: t.artistId ?? '',
+        artistName: t.artistName,
+        durationSec: t.durationSec,
+        streamUrl: t.streamUrl ?? '',
+      ));
+    }
+    if (refs.isEmpty) return;
+    // Rotation-aware kinds arrive pre-ordered from the server — play
+    // as-is, tagged so the reporter advances rotation. No client
+    // shuffle. Everything else plays stored order, untagged.
+    await ref.read(playerActionsProvider).playTracks(
+          refs,
+          initialIndex: 0,
+          source: playlist.refreshable ? playlist.systemVariant : null,
+        );
+  }
+}

flutter_client/lib/playlists/widgets/playlist_placeholder_card.dart

@@ -0,0 +1,86 @@
+import 'package:flutter/material.dart';
+
+import '../../theme/theme_extension.dart';
+
+/// Same dimensions as PlaylistCard so the home Playlists row keeps
+/// visual rhythm whether real or placeholder. Mirrors the web
+/// PlaylistPlaceholderCard. Variant decides the state copy below
+/// the label.
+class PlaylistPlaceholderCard extends StatelessWidget {
+  const PlaylistPlaceholderCard({
+    super.key,
+    required this.label,
+    required this.variant,
+  });
+
+  /// "For You" or "Songs like…" — what the slot is reserved for.
+  final String label;
+
+  /// One of: 'building' | 'failed' | 'pending' | 'seed-needed'.
+  final String variant;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return SizedBox(
+      width: 176,
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 8),
+        child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+          Container(
+            width: 144,
+            height: 144,
+            decoration: BoxDecoration(
+              color: fs.iron,
+              borderRadius: BorderRadius.circular(6),
+              border: Border.all(color: fs.slate, width: 1),
+            ),
+            child: Center(child: _stateIcon(fs)),
+          ),
+          const SizedBox(height: 8),
+          Text(
+            label,
+            maxLines: 1,
+            overflow: TextOverflow.ellipsis,
+            style: TextStyle(color: fs.parchment, fontSize: 14),
+          ),
+          Padding(
+            padding: const EdgeInsets.only(top: 2),
+            child: Text(
+              _stateText(),
+              style: TextStyle(color: fs.ash, fontSize: 11),
+            ),
+          ),
+        ]),
+      ),
+    );
+  }
+
+  Widget _stateIcon(FabledSwordTheme fs) {
+    switch (variant) {
+      case 'building':
+        return SizedBox(
+          width: 28,
+          height: 28,
+          child: CircularProgressIndicator(strokeWidth: 2, color: fs.accent),
+        );
+      case 'failed':
+        return Icon(Icons.warning_amber, color: fs.error, size: 32);
+      default:
+        return Icon(Icons.queue_music, color: fs.ash, size: 40);
+    }
+  }
+
+  String _stateText() {
+    switch (variant) {
+      case 'building':
+        return 'Building…';
+      case 'failed':
+        return "Couldn't generate";
+      case 'seed-needed':
+        return 'Like more music';
+      default:
+        return 'Coming soon';
+    }
+  }
+}

flutter_client/lib/quarantine/quarantine_provider.dart

@@ -0,0 +1,184 @@
+import 'dart:async';
+
+import 'package:drift/drift.dart' as drift;
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../api/endpoints/me.dart';
+import '../api/endpoints/quarantine.dart';
+import '../cache/audio_cache_manager.dart' show appDbProvider;
+import '../cache/connectivity_provider.dart';
+import '../cache/db.dart';
+import '../cache/mutation_queue.dart';
+import '../library/library_providers.dart' show dioProvider;
+import '../models/quarantine_mine.dart';
+import '../models/track.dart';
+
+final quarantineApiProvider = FutureProvider<QuarantineApi>((ref) async {
+  return QuarantineApi(await ref.watch(dioProvider.future));
+});
+
+/// Drift-first ("hidden") tab controller. Reads from cached_quarantine_
+/// mine via a drift watch() subscription set up in build(), so any drift
+/// mutation (incoming sync, optimistic flag/unflag, SSE-triggered
+/// refresh) re-emits the list automatically.
+///
+/// API surface unchanged from the prior FutureProvider-backed controller
+/// — call sites still do `ref.read(myQuarantineProvider.notifier).flag()`
+/// / `.unflag()` / `.isHidden()`. Internal storage moved from in-memory
+/// AsyncNotifier state to drift so the Hidden tab paints from disk on
+/// cold open and the quarantine list is queryable offline.
+class MyQuarantineController extends AsyncNotifier<List<QuarantineMineRow>> {
+  @override
+  Future<List<QuarantineMineRow>> build() async {
+    final db = ref.watch(appDbProvider);
+
+    // Subscribe to drift first so any mutation (incoming sync, flag/
+    // unflag, etc.) propagates without needing a manual invalidate.
+    // Disposed when the provider rebuilds or the listener detaches.
+    final sub = db.select(db.cachedQuarantineMine).watch().listen((rows) {
+      state = AsyncData(rows.map(_rowToModel).toList());
+    });
+    ref.onDispose(sub.cancel);
+
+    // SWR refresh on every build so the freshest server-side state
+    // overtakes drift in the background. Don't await — UI gets the
+    // cached snapshot first, freshness lands later via the watch().
+    unawaited(_refreshFromServer());
+
+    final initial = await db.select(db.cachedQuarantineMine).get();
+    return initial.map(_rowToModel).toList();
+  }
+
+  /// Hits /api/quarantine/mine and replaces the local table with the
+  /// authoritative server set. Best-effort: offline / 5xx / unresolved
+  /// dependencies (e.g. uninitialised serverUrl in tests) all collapse
+  /// to a no-op — drift stays on the prior cached state.
+  Future<void> _refreshFromServer() async {
+    try {
+      final online = await ref
+          .read(connectivityProvider.future)
+          .timeout(const Duration(seconds: 3), onTimeout: () => true);
+      if (!online) return;
+      final dio = await ref.read(dioProvider.future);
+      final fresh = await MeApi(dio).quarantineMine();
+      final db = ref.read(appDbProvider);
+      await db.transaction(() async {
+        // Full replace — quarantine list is small and we want server
+        // unflags from other devices to take effect. Doing this in a
+        // transaction means the watch() sees exactly one emission with
+        // the merged state, not a delete-then-insert flicker.
+        await db.delete(db.cachedQuarantineMine).go();
+        for (final r in fresh) {
+          await db
+              .into(db.cachedQuarantineMine)
+              .insertOnConflictUpdate(_modelToCompanion(r));
+        }
+      });
+    } catch (_) {
+      // Swallow — cached state stays visible.
+    }
+  }
+
+  /// True when this track is in the caller's quarantine list.
+  bool isHidden(String trackId) =>
+      (state.value ?? const []).any((r) => r.trackId == trackId);
+
+  /// Optimistic flag: inserts the synthetic row into drift (watch fires
+  /// immediately so the UI updates), calls server, rolls back on error.
+  Future<void> flag(TrackRef track, String reason, String notes) async {
+    final db = ref.read(appDbProvider);
+    final existed = await (db.select(db.cachedQuarantineMine)
+          ..where((t) => t.trackId.equals(track.id)))
+        .getSingleOrNull();
+    if (existed != null) return; // already hidden
+
+    final companion = CachedQuarantineMineCompanion.insert(
+      trackId: track.id,
+      reason: reason,
+      notes: notes.isEmpty
+          ? const drift.Value.absent()
+          : drift.Value(notes),
+      createdAt: DateTime.now().toUtc().toIso8601String(),
+      trackTitle: track.title,
+      trackDurationMs: drift.Value(track.durationSec * 1000),
+      albumId: track.albumId,
+      albumTitle: track.albumTitle,
+      artistId: track.artistId,
+      artistName: track.artistName,
+    );
+    await db.into(db.cachedQuarantineMine).insertOnConflictUpdate(companion);
+
+    try {
+      final api = await ref.read(quarantineApiProvider.future);
+      await api.flag(track.id, reason, notes: notes);
+    } catch (_) {
+      // REST failed — don't roll back; queue for replay so the user's
+      // "hide this track" intent persists offline.
+      await ref.read(mutationQueueProvider).enqueue(
+        MutationKinds.quarantineFlag,
+        {'trackId': track.id, 'reason': reason, 'notes': notes},
+      );
+    }
+  }
+
+  /// Optimistic unflag: removes the drift row, calls server, queues
+  /// the call on failure so the unhide intent persists offline.
+  Future<void> unflag(String trackId) async {
+    final db = ref.read(appDbProvider);
+    final existing = await (db.select(db.cachedQuarantineMine)
+          ..where((t) => t.trackId.equals(trackId)))
+        .getSingleOrNull();
+    if (existing == null) return;
+
+    await (db.delete(db.cachedQuarantineMine)
+          ..where((t) => t.trackId.equals(trackId)))
+        .go();
+
+    try {
+      final api = await ref.read(quarantineApiProvider.future);
+      await api.unflag(trackId);
+    } catch (_) {
+      // Don't restore the drift row; queue the unflag for replay.
+      await ref
+          .read(mutationQueueProvider)
+          .enqueue(MutationKinds.quarantineUnflag, {'trackId': trackId});
+    }
+  }
+
+  static QuarantineMineRow _rowToModel(CachedQuarantineMineData r) =>
+      QuarantineMineRow(
+        trackId: r.trackId,
+        reason: r.reason,
+        notes: r.notes,
+        createdAt: r.createdAt,
+        trackTitle: r.trackTitle,
+        trackDurationMs: r.trackDurationMs,
+        albumId: r.albumId,
+        albumTitle: r.albumTitle,
+        albumCoverArtPath: r.albumCoverArtPath,
+        artistId: r.artistId,
+        artistName: r.artistName,
+      );
+
+  static CachedQuarantineMineCompanion _modelToCompanion(QuarantineMineRow r) =>
+      CachedQuarantineMineCompanion.insert(
+        trackId: r.trackId,
+        reason: r.reason,
+        notes: r.notes == null ? const drift.Value.absent() : drift.Value(r.notes),
+        createdAt: r.createdAt,
+        trackTitle: r.trackTitle,
+        trackDurationMs: drift.Value(r.trackDurationMs),
+        albumId: r.albumId,
+        albumTitle: r.albumTitle,
+        albumCoverArtPath: r.albumCoverArtPath == null
+            ? const drift.Value.absent()
+            : drift.Value(r.albumCoverArtPath),
+        artistId: r.artistId,
+        artistName: r.artistName,
+      );
+}
+
+final myQuarantineProvider =
+    AsyncNotifierProvider<MyQuarantineController, List<QuarantineMineRow>>(
+  MyQuarantineController.new,
+);

flutter_client/lib/requests/requests_provider.dart

@@ -0,0 +1,65 @@
+import 'dart:async';
+
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../api/endpoints/requests.dart';
+import '../cache/mutation_queue.dart';
+import '../library/library_providers.dart' show dioProvider;
+import '../models/admin_request.dart';
+
+final requestsApiProvider = FutureProvider<RequestsApi>((ref) async {
+  return RequestsApi(await ref.watch(dioProvider.future));
+});
+
+/// Mirrors the web's createMyRequestsQuery auto-poll (#369): refresh
+/// every 12s while any row is mid-ingest (status='approved'), stop when
+/// all rows settle. Polls regardless of app foreground/background — a
+/// future enhancement could pause via WidgetsBindingObserver, but for
+/// v1 the small extra refresh is acceptable.
+class MyRequestsController extends AsyncNotifier<List<AdminRequest>> {
+  static const Duration _pollInterval = Duration(seconds: 12);
+
+  Timer? _pollTimer;
+
+  @override
+  Future<List<AdminRequest>> build() async {
+    ref.onDispose(() {
+      _pollTimer?.cancel();
+      _pollTimer = null;
+    });
+    final api = await ref.watch(requestsApiProvider.future);
+    final rows = await api.listMine();
+    _maybeStartPolling(rows);
+    return rows;
+  }
+
+  void _maybeStartPolling(List<AdminRequest> rows) {
+    _pollTimer?.cancel();
+    if (rows.any((r) => r.status == 'approved')) {
+      _pollTimer = Timer.periodic(_pollInterval, (_) {
+        ref.invalidateSelf();
+      });
+    }
+  }
+
+  /// Optimistic remove + REST cancel. On failure the row stays
+  /// removed in-memory and the cancel is queued for replay — this
+  /// keeps the user's intent visible across network loss instead of
+  /// restoring a row they explicitly asked to remove.
+  Future<void> cancel(String id) async {
+    final api = await ref.read(requestsApiProvider.future);
+    final current = state.value ?? const <AdminRequest>[];
+    state = AsyncData(current.where((r) => r.id != id).toList());
+    try {
+      await api.cancel(id);
+    } catch (_) {
+      await ref
+          .read(mutationQueueProvider)
+          .enqueue(MutationKinds.requestCancel, {'id': id});
+    }
+  }
+}
+
+final myRequestsProvider =
+    AsyncNotifierProvider<MyRequestsController, List<AdminRequest>>(
+        MyRequestsController.new);

flutter_client/lib/requests/requests_screen.dart

@@ -0,0 +1,252 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+
+import '../models/admin_request.dart';
+import '../shared/live_events_provider.dart';
+import '../shared/widgets/main_app_bar_actions.dart';
+import '../theme/theme_extension.dart';
+import 'requests_provider.dart';
+
+class RequestsScreen extends ConsumerWidget {
+  const RequestsScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    // #402 wire-up: refresh the user's own requests list on
+    // request.status_changed. Server-side events are user-scoped
+    // (admin actions on someone else's request route to that other
+    // user's stream); the dispatcher's filter already drops mismatches.
+    ref.listen<AsyncValue<LiveEvent>>(liveEventsProvider, (_, next) {
+      final e = next.asData?.value;
+      if (e?.kind == 'request.status_changed') {
+        ref.invalidate(myRequestsProvider);
+      }
+    });
+    final requests = ref.watch(myRequestsProvider);
+
+    return Scaffold(
+      backgroundColor: fs.obsidian,
+      appBar: AppBar(
+        backgroundColor: fs.obsidian,
+        elevation: 0,
+        leading: IconButton(
+          icon: Icon(Icons.arrow_back, color: fs.parchment),
+          onPressed: () => context.pop(),
+        ),
+        title: Text('Your requests', style: TextStyle(color: fs.parchment)),
+        actions: const [MainAppBarActions(currentRoute: '/requests')],
+      ),
+      body: SafeArea(
+        child: requests.when(
+          loading: () => const Center(child: CircularProgressIndicator()),
+          error: (e, _) => Center(
+            child: Padding(
+              padding: const EdgeInsets.all(24),
+              child: Text('$e', style: TextStyle(color: fs.error)),
+            ),
+          ),
+          data: (rows) {
+            if (rows.isEmpty) {
+              return Center(
+                child: Text('Nothing requested yet.',
+                    style: TextStyle(color: fs.ash)),
+              );
+            }
+            final notifier = ref.read(myRequestsProvider.notifier);
+            return RefreshIndicator(
+              onRefresh: () async => ref.refresh(myRequestsProvider.future),
+              child: ListView.separated(
+                itemCount: rows.length,
+                padding: const EdgeInsets.symmetric(vertical: 8),
+                separatorBuilder: (_, __) => Divider(color: fs.iron, height: 1),
+                itemBuilder: (_, i) => _RequestRow(
+                  key: Key('request_row_${rows[i].id}'),
+                  request: rows[i],
+                  onCancel: () => notifier.cancel(rows[i].id),
+                ),
+              ),
+            );
+          },
+        ),
+      ),
+    );
+  }
+}
+
+class _RequestRow extends StatelessWidget {
+  const _RequestRow({
+    super.key,
+    required this.request,
+    required this.onCancel,
+  });
+
+  final AdminRequest request;
+  final VoidCallback onCancel;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final href = _listenHref(request);
+    return ListTile(
+      leading: _kindAvatar(fs),
+      title: Text(
+        request.displayName,
+        style: TextStyle(
+          color: fs.parchment,
+          fontFamily: 'Fraunces',
+          fontSize: 16,
+        ),
+      ),
+      subtitle: Column(
+        crossAxisAlignment: CrossAxisAlignment.start,
+        children: [
+          const SizedBox(height: 4),
+          Row(
+            children: [
+              _KindPill(label: request.kind),
+              const SizedBox(width: 6),
+              _StatusPill(status: request.status),
+            ],
+          ),
+          if (request.importedAlbumCount > 0 ||
+              request.importedTrackCount > 0) ...[
+            const SizedBox(height: 4),
+            Text(
+              _ingestProgressText(request),
+              style: TextStyle(color: fs.accent, fontSize: 13),
+            ),
+          ],
+          if (request.status == 'rejected' && (request.notes ?? '').isNotEmpty) ...[
+            const SizedBox(height: 4),
+            Text(request.notes!, style: TextStyle(color: fs.ash, fontSize: 13)),
+          ],
+        ],
+      ),
+      trailing: _trailing(context, fs, href),
+    );
+  }
+
+  Widget _kindAvatar(FabledSwordTheme fs) {
+    final icon = switch (request.kind) {
+      'artist' => Icons.album,
+      'album' => Icons.library_music,
+      _ => Icons.music_note,
+    };
+    return CircleAvatar(
+      backgroundColor: fs.iron,
+      child: Icon(icon, size: 20, color: fs.ash),
+    );
+  }
+
+  Widget? _trailing(BuildContext context, FabledSwordTheme fs, String? href) {
+    if (request.status == 'pending') {
+      return TextButton.icon(
+        onPressed: () async {
+          final ok = await showDialog<bool>(
+            context: context,
+            builder: (ctx) => AlertDialog(
+              title: const Text('Cancel request?'),
+              content: Text('Cancel "${request.displayName}"?'),
+              actions: [
+                TextButton(
+                  onPressed: () => Navigator.pop(ctx, false),
+                  child: const Text('Keep'),
+                ),
+                TextButton(
+                  onPressed: () => Navigator.pop(ctx, true),
+                  style: TextButton.styleFrom(foregroundColor: fs.oxblood),
+                  child: const Text('Cancel request'),
+                ),
+              ],
+            ),
+          );
+          if (ok == true) onCancel();
+        },
+        icon: const Icon(Icons.close, size: 16),
+        label: const Text('Cancel'),
+        style: TextButton.styleFrom(foregroundColor: fs.ash),
+      );
+    }
+    if (request.status == 'completed' && href != null) {
+      return TextButton.icon(
+        onPressed: () => context.push(href),
+        icon: const Icon(Icons.play_arrow, size: 16),
+        label: const Text('Listen'),
+        style: TextButton.styleFrom(foregroundColor: fs.accent),
+      );
+    }
+    return null;
+  }
+
+  String _ingestProgressText(AdminRequest r) {
+    if (r.kind == 'artist') {
+      final albums = '${r.importedAlbumCount} '
+          '${r.importedAlbumCount == 1 ? 'album' : 'albums'}';
+      final tracks = '${r.importedTrackCount} '
+          '${r.importedTrackCount == 1 ? 'track' : 'tracks'} ingested';
+      return '$albums · $tracks';
+    }
+    if (r.kind == 'album') {
+      return '${r.importedTrackCount} '
+          '${r.importedTrackCount == 1 ? 'track' : 'tracks'} ingested';
+    }
+    return 'Track ingested';
+  }
+
+  String? _listenHref(AdminRequest r) {
+    if (r.matchedTrackId != null) return '/albums/${r.matchedAlbumId ?? r.matchedTrackId}';
+    if (r.matchedAlbumId != null) return '/albums/${r.matchedAlbumId}';
+    if (r.matchedArtistId != null) return '/artists/${r.matchedArtistId}';
+    return null;
+  }
+}
+
+class _KindPill extends StatelessWidget {
+  const _KindPill({required this.label});
+  final String label;
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return Container(
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+      decoration: BoxDecoration(
+        color: fs.accent.withValues(alpha: 0.15),
+        borderRadius: BorderRadius.circular(999),
+      ),
+      child: Text(
+        label,
+        style: TextStyle(color: fs.accent, fontSize: 11),
+      ),
+    );
+  }
+}
+
+class _StatusPill extends StatelessWidget {
+  const _StatusPill({required this.status});
+  final String status;
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final color = switch (status) {
+      'pending' => fs.ash,
+      'approved' => fs.bronze,
+      'completed' => fs.moss,
+      'rejected' => fs.oxblood,
+      'failed' => fs.oxblood,
+      _ => fs.ash,
+    };
+    return Container(
+      padding: const EdgeInsets.symmetric(horizontal: 8, vertical: 2),
+      decoration: BoxDecoration(
+        color: color.withValues(alpha: 0.15),
+        borderRadius: BorderRadius.circular(999),
+      ),
+      child: Text(
+        status,
+        style: TextStyle(color: color, fontSize: 11),
+      ),
+    );
+  }
+}

flutter_client/lib/search/search_screen.dart

@@ -88,7 +88,7 @@ class _SearchScreenState extends ConsumerState<SearchScreen> {
         data: (r) => r == null
             ? const _Hint(message: 'Type to search your library.')
             : r.isEmpty
-                ? const _Hint(message: 'No matches.')
+                ? const _Hint(message: 'No matches for that query.')
                 : _Results(results: r),
       ),
     );

flutter_client/lib/settings/about_section.dart

@@ -0,0 +1,227 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:package_info_plus/package_info_plus.dart';
+
+import '../theme/theme_extension.dart';
+import '../update/client_update_provider.dart';
+import '../update/update_info.dart';
+
+final _packageInfoProvider = FutureProvider<PackageInfo>((_) {
+  return PackageInfo.fromPlatform();
+});
+
+class AboutSection extends ConsumerStatefulWidget {
+  const AboutSection({super.key});
+
+  @override
+  ConsumerState<AboutSection> createState() => _AboutSectionState();
+}
+
+enum _InstallStage { idle, downloading, error }
+
+class _AboutSectionState extends ConsumerState<AboutSection> {
+  DateTime? _lastChecked;
+  bool _checking = false;
+
+  _InstallStage _installStage = _InstallStage.idle;
+  double _installProgress = 0;
+  String? _installError;
+
+  Future<void> _checkNow() async {
+    setState(() => _checking = true);
+    ref.invalidate(clientUpdateProvider);
+    try {
+      await ref.read(clientUpdateProvider.future);
+    } finally {
+      if (mounted) {
+        setState(() {
+          _checking = false;
+          _lastChecked = DateTime.now();
+        });
+      }
+    }
+  }
+
+  Future<void> _install(UpdateInfo info) async {
+    setState(() {
+      _installStage = _InstallStage.downloading;
+      _installProgress = 0;
+      _installError = null;
+    });
+    try {
+      final installer = await ref.read(updateInstallerProvider.future);
+      final path = await installer.download(
+        info.apkUrl,
+        onProgress: (p) {
+          if (mounted) setState(() => _installProgress = p);
+        },
+      );
+      await installer.install(path);
+    } catch (e) {
+      if (!mounted) return;
+      setState(() {
+        _installStage = _InstallStage.error;
+        _installError = '$e';
+      });
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final pkg = ref.watch(_packageInfoProvider);
+    final update = ref.watch(clientUpdateProvider);
+
+    final installed = pkg.value == null
+        ? '…'
+        : '${pkg.value!.version}+${pkg.value!.buildNumber}';
+
+    final UpdateInfo? available = update.value;
+    final hasUpdate = available != null;
+
+    return Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+      const Padding(
+        padding: EdgeInsets.fromLTRB(16, 4, 16, 8),
+        child: _SectionHeader('About'),
+      ),
+      Padding(
+        padding: const EdgeInsets.fromLTRB(16, 0, 16, 4),
+        child: Row(
+          children: [
+            Icon(Icons.info_outline, color: fs.parchment, size: 18),
+            const SizedBox(width: 8),
+            Text('Installed version',
+                style: TextStyle(color: fs.parchment, fontSize: 14)),
+            const Spacer(),
+            Text(installed,
+                style: TextStyle(
+                    color: fs.ash,
+                    fontSize: 13,
+                    fontFamily: 'JetBrainsMono')),
+          ],
+        ),
+      ),
+      Padding(
+        padding: const EdgeInsets.fromLTRB(16, 4, 16, 4),
+        child: Row(
+          children: [
+            Icon(Icons.cloud_outlined, color: fs.parchment, size: 18),
+            const SizedBox(width: 8),
+            Text('Latest version',
+                style: TextStyle(color: fs.parchment, fontSize: 14)),
+            const Spacer(),
+            Text(
+              hasUpdate ? available.version : _statusFor(update, installed),
+              style: TextStyle(
+                  color: hasUpdate ? fs.accent : fs.ash,
+                  fontSize: 13,
+                  fontFamily: 'JetBrainsMono'),
+            ),
+          ],
+        ),
+      ),
+      if (_lastChecked != null)
+        Padding(
+          padding: const EdgeInsets.fromLTRB(16, 4, 16, 0),
+          child: Text(
+            'Last checked ${_formatTime(_lastChecked!)}',
+            style: TextStyle(color: fs.ash, fontSize: 11),
+          ),
+        ),
+      Padding(
+        padding: const EdgeInsets.fromLTRB(16, 12, 16, 0),
+        child: Row(
+          children: [
+            FilledButton.icon(
+              key: const Key('about_check_for_updates'),
+              onPressed: _checking ? null : _checkNow,
+              style: FilledButton.styleFrom(
+                backgroundColor: fs.accent,
+                foregroundColor: fs.parchment,
+              ),
+              icon: _checking
+                  ? SizedBox(
+                      width: 14,
+                      height: 14,
+                      child: CircularProgressIndicator(
+                        strokeWidth: 2,
+                        valueColor: AlwaysStoppedAnimation(fs.parchment),
+                      ),
+                    )
+                  : const Icon(Icons.refresh, size: 18),
+              label: Text(_checking ? 'Checking…' : 'Check for updates'),
+            ),
+            if (hasUpdate) ...[
+              const SizedBox(width: 12),
+              FilledButton.icon(
+                key: const Key('about_install_update'),
+                onPressed: _installStage == _InstallStage.downloading
+                    ? null
+                    : () => _install(available),
+                style: FilledButton.styleFrom(
+                  backgroundColor: fs.moss,
+                  foregroundColor: fs.parchment,
+                ),
+                icon: _installStage == _InstallStage.downloading
+                    ? SizedBox(
+                        width: 14,
+                        height: 14,
+                        child: CircularProgressIndicator(
+                          strokeWidth: 2,
+                          value: _installProgress > 0 ? _installProgress : null,
+                          valueColor: AlwaysStoppedAnimation(fs.parchment),
+                        ),
+                      )
+                    : const Icon(Icons.system_update, size: 18),
+                label: Text(
+                  _installStage == _InstallStage.downloading
+                      ? 'Downloading…'
+                      : _installStage == _InstallStage.error
+                          ? 'Retry install'
+                          : 'Install ${available.version}',
+                ),
+              ),
+            ],
+          ],
+        ),
+      ),
+      if (_installStage == _InstallStage.error && _installError != null)
+        Padding(
+          padding: const EdgeInsets.fromLTRB(16, 8, 16, 0),
+          child: Text(_installError!,
+              style: TextStyle(color: fs.error, fontSize: 12),
+              maxLines: 2,
+              overflow: TextOverflow.ellipsis),
+        ),
+    ]);
+  }
+
+  String _statusFor(AsyncValue<UpdateInfo?> update, String installed) {
+    if (update.isLoading) return 'Checking…';
+    if (update.hasError) return 'Check failed';
+    return 'Up to date';
+  }
+
+  String _formatTime(DateTime t) {
+    final h = t.hour.toString().padLeft(2, '0');
+    final m = t.minute.toString().padLeft(2, '0');
+    return '$h:$m';
+  }
+}
+
+class _SectionHeader extends StatelessWidget {
+  const _SectionHeader(this.label);
+  final String label;
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return Text(
+      label,
+      style: TextStyle(
+        color: fs.parchment,
+        fontSize: 16,
+        fontWeight: FontWeight.w500,
+      ),
+    );
+  }
+}

flutter_client/lib/settings/settings_screen.dart

@@ -9,6 +9,9 @@ import '../library/library_providers.dart' show dioProvider;
 import '../models/my_profile.dart';
 import '../shared/widgets/main_app_bar_actions.dart';
 import '../theme/theme_extension.dart';
+import 'about_section.dart';
+import 'storage_section.dart';
+import '../theme/theme_mode_provider.dart';
 
 final _settingsApiProvider = FutureProvider<SettingsApi>((ref) async {
   return SettingsApi(await ref.watch(dioProvider.future));
@@ -45,9 +48,17 @@ class SettingsScreen extends ConsumerWidget {
         children: const [
           _ProfileSection(),
           _Divider(),
+          _RequestsSection(),
+          _Divider(),
+          _AppearanceSection(),
+          _Divider(),
+          StorageSection(),
+          _Divider(),
           _PasswordSection(),
           _Divider(),
           _ListenBrainzSection(),
+          _Divider(),
+          AboutSection(),
           _AdminSection(),
           SizedBox(height: 96),
         ],
@@ -88,6 +99,33 @@ class _SectionHeader extends StatelessWidget {
   }
 }
 
+class _RequestsSection extends StatelessWidget {
+  const _RequestsSection();
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return ListTile(
+      key: const Key('settings_requests_card'),
+      leading: Icon(Icons.queue_music, color: fs.parchment),
+      title: Text(
+        'My requests',
+        style: TextStyle(
+          color: fs.parchment,
+          fontFamily: 'Fraunces',
+          fontSize: 18,
+        ),
+      ),
+      subtitle: Text(
+        "Track what you've asked Minstrel to add",
+        style: TextStyle(color: fs.ash),
+      ),
+      trailing: Icon(Icons.chevron_right, color: fs.ash),
+      onTap: () => context.push('/requests'),
+    );
+  }
+}
+
 /// Renders an "Admin" entry only when the current profile has
 /// `is_admin = true`. Returns an empty SizedBox otherwise so the
 /// const-children layout above stays valid.
@@ -492,3 +530,45 @@ InputDecoration _inputDecoration(FabledSwordTheme fs, String label) {
     ),
   );
 }
+
+class _AppearanceSection extends ConsumerWidget {
+  const _AppearanceSection();
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final current = ref.watch(themeModeProvider).value ?? AppThemeMode.system;
+    // RadioGroup is the post-Flutter-3.32 API: the ancestor owns
+    // groupValue/onChanged so individual RadioListTiles don't have
+    // to repeat them. Pre-3.32 RadioListTile.groupValue/onChanged
+    // are deprecated.
+    return RadioGroup<AppThemeMode>(
+      groupValue: current,
+      onChanged: (m) {
+        if (m != null) {
+          ref.read(themeModeProvider.notifier).set(m);
+        }
+      },
+      child: Column(crossAxisAlignment: CrossAxisAlignment.start, children: [
+        const _SectionHeader('Appearance'),
+        for (final mode in AppThemeMode.values)
+          RadioListTile<AppThemeMode>(
+            key: Key('appearance_${mode.name}'),
+            title: Text(_label(mode), style: TextStyle(color: fs.parchment)),
+            subtitle: mode == AppThemeMode.system
+                ? Text('Match the device setting',
+                    style: TextStyle(color: fs.ash))
+                : null,
+            value: mode,
+            activeColor: fs.accent,
+          ),
+      ]),
+    );
+  }
+
+  String _label(AppThemeMode m) => switch (m) {
+        AppThemeMode.system => 'System',
+        AppThemeMode.light => 'Light',
+        AppThemeMode.dark => 'Dark',
+      };
+}

flutter_client/lib/settings/storage_section.dart

@@ -0,0 +1,254 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../cache/audio_cache_manager.dart';
+import '../cache/cache_settings_provider.dart';
+import '../cache/sync_controller.dart';
+import '../likes/likes_provider.dart' show likedIdsProvider;
+import '../theme/theme_extension.dart';
+
+/// Settings card: per-bucket usage, two cap selectors (Liked +
+/// Recently-played), prefetch window, cache-liked toggle, Clear
+/// cache + Sync now. #427 S2/S3: two independent budgets.
+class StorageSection extends ConsumerStatefulWidget {
+  const StorageSection({super.key});
+
+  @override
+  ConsumerState<StorageSection> createState() => _StorageSectionState();
+}
+
+class _StorageSectionState extends ConsumerState<StorageSection> {
+  BucketUsage? _usage;
+  bool _syncing = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _refreshUsage();
+  }
+
+  Set<String> _likedSet() =>
+      ref.read(likedIdsProvider).value?.tracks ?? const <String>{};
+
+  Future<void> _refreshUsage() async {
+    final mgr = ref.read(audioCacheManagerProvider);
+    final u = await mgr.bucketUsage(_likedSet());
+    if (mounted) setState(() => _usage = u);
+  }
+
+  String _fmtBytes(int? n) {
+    if (n == null) return '—';
+    if (n == 0) return '0 B';
+    if (n < 1024) return '$n B';
+    if (n < 1024 * 1024) return '${(n / 1024).toStringAsFixed(1)} KB';
+    if (n < 1024 * 1024 * 1024) {
+      return '${(n / 1024 / 1024).toStringAsFixed(1)} MB';
+    }
+    return '${(n / 1024 / 1024 / 1024).toStringAsFixed(2)} GB';
+  }
+
+  String _cap(int bytes) => bytes == 0 ? 'unlimited' : _fmtBytes(bytes);
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final settings = ref.watch(cacheSettingsProvider);
+    return Padding(
+      padding: const EdgeInsets.fromLTRB(16, 0, 16, 8),
+      child: Card(
+        color: fs.iron,
+        child: Padding(
+          padding: const EdgeInsets.all(16),
+          child: settings.when(
+            loading: () => const Padding(
+              padding: EdgeInsets.all(8),
+              child: Center(child: CircularProgressIndicator()),
+            ),
+            error: (e, _) => Text('$e', style: TextStyle(color: fs.error)),
+            data: (s) => Column(
+              crossAxisAlignment: CrossAxisAlignment.start,
+              children: [
+                Text('Storage',
+                    style: TextStyle(
+                        color: fs.parchment,
+                        fontSize: 18,
+                        fontWeight: FontWeight.w500)),
+                const SizedBox(height: 12),
+                _usageRow('Liked', _usage?.liked, s.likedCapBytes, fs),
+                const SizedBox(height: 4),
+                _usageRow('Recently played', _usage?.rolling,
+                    s.rollingCapBytes, fs),
+                const SizedBox(height: 16),
+                _capSelector(
+                  'Liked cache limit',
+                  const Key('liked_cap_selector'),
+                  s.likedCapBytes,
+                  (v) => ref
+                      .read(cacheSettingsProvider.notifier)
+                      .setLikedCapBytes(v),
+                  s,
+                  fs,
+                ),
+                const SizedBox(height: 8),
+                _capSelector(
+                  'Recently-played cache limit',
+                  const Key('rolling_cap_selector'),
+                  s.rollingCapBytes,
+                  (v) => ref
+                      .read(cacheSettingsProvider.notifier)
+                      .setRollingCapBytes(v),
+                  s,
+                  fs,
+                ),
+                const SizedBox(height: 8),
+                _prefetchSelector(s, fs),
+                const SizedBox(height: 8),
+                SwitchListTile(
+                  key: const Key('cache_liked_toggle'),
+                  contentPadding: EdgeInsets.zero,
+                  title: Text('Cache liked tracks',
+                      style: TextStyle(color: fs.parchment)),
+                  value: s.cacheLikedTracks,
+                  onChanged: (v) => ref
+                      .read(cacheSettingsProvider.notifier)
+                      .setCacheLikedTracks(v),
+                ),
+                const SizedBox(height: 12),
+                Wrap(spacing: 8, runSpacing: 8, children: [
+                  OutlinedButton(
+                    key: const Key('clear_cache_button'),
+                    onPressed: _confirmClear,
+                    child: const Text('Clear cache'),
+                  ),
+                  OutlinedButton.icon(
+                    key: const Key('sync_now_button'),
+                    onPressed: _syncing
+                        ? null
+                        : () async {
+                            setState(() => _syncing = true);
+                            try {
+                              await ref
+                                  .read(syncControllerProvider.notifier)
+                                  .sync();
+                            } finally {
+                              if (mounted) setState(() => _syncing = false);
+                            }
+                          },
+                    icon: _syncing
+                        ? const SizedBox(
+                            width: 14,
+                            height: 14,
+                            child: CircularProgressIndicator(strokeWidth: 2),
+                          )
+                        : const Icon(Icons.sync, size: 16),
+                    label: const Text('Sync now'),
+                  ),
+                ]),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+
+  Widget _usageRow(String label, int? used, int cap, FabledSwordTheme fs) {
+    return Row(children: [
+      Text(label, style: TextStyle(color: fs.ash)),
+      const Spacer(),
+      Text('${_fmtBytes(used)} / ${_cap(cap)}',
+          style: TextStyle(color: fs.parchment)),
+    ]);
+  }
+
+  static const _capOptions = [
+    (1024 * 1024 * 1024, '1 GB'),
+    (5 * 1024 * 1024 * 1024, '5 GB'),
+    (10 * 1024 * 1024 * 1024, '10 GB'),
+    (25 * 1024 * 1024 * 1024, '25 GB'),
+    (0, 'Unlimited'),
+  ];
+
+  Widget _capSelector(
+    String label,
+    Key key,
+    int current,
+    Future<void> Function(int) setCap,
+    CacheSettings s,
+    FabledSwordTheme fs,
+  ) {
+    return Row(children: [
+      Expanded(child: Text(label, style: TextStyle(color: fs.ash))),
+      DropdownButton<int>(
+        key: key,
+        value: _capOptions.any((o) => o.$1 == current)
+            ? current
+            : 5 * 1024 * 1024 * 1024,
+        items: _capOptions
+            .map((o) => DropdownMenuItem(value: o.$1, child: Text(o.$2)))
+            .toList(),
+        onChanged: (v) async {
+          if (v == null) return;
+          await setCap(v);
+          // Enforce immediately against the freshest settings.
+          final fresh = ref.read(cacheSettingsProvider).value;
+          if (fresh != null) {
+            await ref.read(audioCacheManagerProvider).evictBuckets(
+                  likedCap: fresh.likedCapBytes,
+                  rollingCap: fresh.rollingCapBytes,
+                  liked: _likedSet(),
+                );
+          }
+          await _refreshUsage();
+        },
+      ),
+    ]);
+  }
+
+  Widget _prefetchSelector(CacheSettings s, FabledSwordTheme fs) {
+    const options = [1, 3, 5, 7, 10];
+    return Row(children: [
+      Expanded(
+          child: Text('Pre-fetch ahead', style: TextStyle(color: fs.ash))),
+      DropdownButton<int>(
+        key: const Key('prefetch_selector'),
+        value: options.contains(s.prefetchWindow) ? s.prefetchWindow : 5,
+        items: options
+            .map((n) => DropdownMenuItem(value: n, child: Text('$n tracks')))
+            .toList(),
+        onChanged: (v) async {
+          if (v == null) return;
+          await ref.read(cacheSettingsProvider.notifier).setPrefetchWindow(v);
+        },
+      ),
+    ]);
+  }
+
+  Future<void> _confirmClear() async {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final confirmed = await showDialog<bool>(
+      context: context,
+      builder: (ctx) => AlertDialog(
+        title: const Text('Clear cache?'),
+        content: const Text(
+          'This deletes all cached audio (liked and recently-played). '
+          'The next play of any track re-downloads from the server.',
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.pop(ctx, false),
+            child: const Text('Cancel'),
+          ),
+          FilledButton(
+            style: FilledButton.styleFrom(backgroundColor: fs.error),
+            onPressed: () => Navigator.pop(ctx, true),
+            child: const Text('Clear'),
+          ),
+        ],
+      ),
+    );
+    if (confirmed != true) return;
+    await ref.read(audioCacheManagerProvider).clearAll();
+    await _refreshUsage();
+  }
+}

flutter_client/lib/shared/delayed_loading.dart

@@ -0,0 +1,66 @@
+import 'dart:async';
+import 'package:flutter/widgets.dart';
+
+/// Renders [whileDelayed] only after [isLoading] has been true
+/// continuously for [delay], then renders [whenReady] once loading
+/// completes. Mirrors the web `useDelayed` hook: a brief loading flash
+/// doesn't trigger a skeleton; sustained loading does.
+///
+/// Once [isLoading] flips back to false, the timer resets.
+class DelayedLoading extends StatefulWidget {
+  const DelayedLoading({
+    super.key,
+    required this.isLoading,
+    required this.whileDelayed,
+    required this.whenReady,
+    this.delay = const Duration(milliseconds: 200),
+  });
+
+  final bool isLoading;
+  final Widget whileDelayed;
+  final Widget whenReady;
+  final Duration delay;
+
+  @override
+  State<DelayedLoading> createState() => _DelayedLoadingState();
+}
+
+class _DelayedLoadingState extends State<DelayedLoading> {
+  Timer? _timer;
+  bool _delayPassed = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _maybeStart();
+  }
+
+  @override
+  void didUpdateWidget(DelayedLoading old) {
+    super.didUpdateWidget(old);
+    if (widget.isLoading != old.isLoading) {
+      _timer?.cancel();
+      _delayPassed = false;
+      _maybeStart();
+    }
+  }
+
+  void _maybeStart() {
+    if (!widget.isLoading) return;
+    _timer = Timer(widget.delay, () {
+      if (mounted) setState(() => _delayPassed = true);
+    });
+  }
+
+  @override
+  void dispose() {
+    _timer?.cancel();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    if (!widget.isLoading) return widget.whenReady;
+    return _delayPassed ? widget.whileDelayed : const SizedBox.shrink();
+  }
+}

flutter_client/lib/shared/live_events_dispatcher.dart

@@ -0,0 +1,104 @@
+// Maps incoming LiveEvent kinds to provider invalidations.
+//
+// Activated by ref.read(liveEventsDispatcherProvider) in app.dart; once
+// activated, the dispatcher listens to liveEventsProvider for the
+// lifetime of the ProviderScope and invalidates the small set of
+// public-scoped providers we know about.
+//
+// Screen-scoped providers (file-private providers in library_screen.dart,
+// admin handlers, etc.) opt in to live-refresh by themselves listening
+// to liveEventsProvider — the dispatcher only handles cross-screen,
+// publicly-importable providers. This keeps the dispatcher small and
+// avoids a back-edge dependency from /shared onto every feature folder.
+//
+// Includes an AppLifecycleState resume handler that defensively
+// invalidates the same set on app foreground. SSE will catch up on its
+// own, but on cold-start or after a long background period the
+// re-invalidate is fast and avoids stale data flashing before the
+// stream reconnects.
+
+import 'package:flutter/widgets.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../library/library_providers.dart' show homeProvider;
+import '../quarantine/quarantine_provider.dart';
+import 'live_events_provider.dart';
+
+/// Activates the SSE → invalidation dispatcher for the lifetime of the
+/// containing ProviderScope. Read this once at startup (from app.dart);
+/// the provider's body runs once, sets up listeners, and returns a
+/// sentinel value.
+final liveEventsDispatcherProvider = Provider<_LiveEventsDispatcher>((ref) {
+  final d = _LiveEventsDispatcher(ref);
+  ref.onDispose(d.dispose);
+  return d;
+});
+
+class _LiveEventsDispatcher with WidgetsBindingObserver {
+  _LiveEventsDispatcher(this._ref) {
+    // Subscribe to the event stream. Each emitted event invokes
+    // _handle. Errors / disconnects auto-rebuild the underlying
+    // provider; we don't need to react to them here.
+    _sub = _ref.listen<AsyncValue<LiveEvent>>(
+      liveEventsProvider,
+      (_, next) => next.whenData(_handle),
+      fireImmediately: false,
+    );
+    WidgetsBinding.instance.addObserver(this);
+  }
+
+  final Ref _ref;
+  late final ProviderSubscription<AsyncValue<LiveEvent>> _sub;
+
+  void _handle(LiveEvent e) {
+    // Map event kinds to provider invalidations. Keep this list short:
+    // only providers reachable from /shared. Screen-private providers
+    // listen to liveEventsProvider themselves.
+    switch (e.kind) {
+      case 'quarantine.flagged':
+      case 'quarantine.unflagged':
+      case 'quarantine.resolved':
+      case 'quarantine.file_deleted':
+      case 'quarantine.deleted_via_lidarr':
+        _ref.invalidate(myQuarantineProvider);
+        // Hidden / liked / album rows referencing a deleted track may
+        // now be stale — homeProvider re-fetch refreshes the cards.
+        _ref.invalidate(homeProvider);
+      case 'playlist.created':
+      case 'playlist.updated':
+      case 'playlist.deleted':
+      case 'playlist.tracks_changed':
+        // Home renders a Playlists row; refresh it so a delete or add
+        // is reflected immediately. Detail screens that need the
+        // mutated row will get a separate invalidate from their own
+        // listener (filed as a follow-up).
+        _ref.invalidate(homeProvider);
+      case 'scan.run_started':
+      case 'scan.run_finished':
+        // Admin scan card provider lives in the admin feature folder
+        // and is file-private today; will be invalidated by the admin
+        // dashboard's own listener once that exists.
+        break;
+      default:
+        // track.liked / track.unliked / request.status_changed reach
+        // screen-private providers; their screens listen directly.
+        break;
+    }
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    if (state == AppLifecycleState.resumed) {
+      // Defensive cold-start invalidation. SSE will catch up on its
+      // own, but the re-invalidate flushes any stale data that
+      // landed while the app was backgrounded.
+      _ref.invalidate(myQuarantineProvider);
+      _ref.invalidate(homeProvider);
+    }
+  }
+
+  void dispose() {
+    WidgetsBinding.instance.removeObserver(this);
+    _sub.close();
+  }
+}

flutter_client/lib/shared/live_events_provider.dart

@@ -0,0 +1,126 @@
+// Subscribes to the server's Server-Sent Events stream
+// (GET /api/events/stream, see Fable #392) and exposes a parsed event
+// stream as a Riverpod StreamProvider. Consumers wire invalidation
+// behavior in live_events_dispatcher.dart.
+//
+// On disconnect (network blip, server restart, token rotation), the
+// provider's StreamController completes; the dispatcher's auto-rebuild
+// when the auth state changes re-subscribes. Explicit exponential
+// backoff lives at the dispatcher layer so we don't re-create the dio
+// connection too aggressively.
+
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:dio/dio.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../auth/auth_provider.dart';
+import '../library/library_providers.dart' show dioProvider;
+
+/// Parsed event from the server's SSE stream. `kind` follows
+/// "domain.action" naming; `data` carries the payload map.
+class LiveEvent {
+  const LiveEvent({required this.kind, required this.userId, required this.data});
+
+  final String kind;
+  final String userId;
+  final Map<String, dynamic> data;
+
+  @override
+  String toString() => 'LiveEvent($kind, user=$userId, data=$data)';
+}
+
+/// Streams parsed LiveEvent values from /api/events/stream. Errors and
+/// disconnects surface as stream errors; the dispatcher decides whether
+/// to retry.
+final liveEventsProvider = StreamProvider<LiveEvent>((ref) async* {
+  // Gate the subscription on having both a server URL and a session
+  // token. If either is missing, emit nothing and let the provider
+  // auto-rebuild when auth state lands.
+  final token = await ref.watch(sessionTokenProvider.future);
+  if (token == null || token.isEmpty) {
+    return;
+  }
+  final dio = await ref.watch(dioProvider.future);
+
+  final controller = StreamController<LiveEvent>();
+  ref.onDispose(controller.close);
+
+  // ignore: unawaited_futures
+  _runSubscription(dio, controller);
+
+  yield* controller.stream;
+});
+
+/// Runs the dio streaming request and pushes parsed events into
+/// [controller]. Closes the controller when the stream ends or errors.
+Future<void> _runSubscription(Dio dio, StreamController<LiveEvent> controller) async {
+  try {
+    final resp = await dio.get<ResponseBody>(
+      '/api/events/stream',
+      options: Options(
+        responseType: ResponseType.stream,
+        // No timeout — the server emits 15s heartbeats; idle timeouts
+        // on the client side would tear down a healthy connection.
+        receiveTimeout: Duration.zero,
+        headers: const {'Accept': 'text/event-stream'},
+      ),
+    );
+
+    // SSE frames are delimited by blank lines. Accumulate raw bytes
+    // into a string buffer; flush parsed events on each "\n\n".
+    var buffer = '';
+    await for (final chunk in resp.data!.stream) {
+      buffer += utf8.decode(chunk, allowMalformed: true);
+      while (true) {
+        final i = buffer.indexOf('\n\n');
+        if (i < 0) break;
+        final frame = buffer.substring(0, i);
+        buffer = buffer.substring(i + 2);
+        final event = _parseFrame(frame);
+        if (event != null && !controller.isClosed) {
+          controller.add(event);
+        }
+      }
+    }
+    if (!controller.isClosed) {
+      await controller.close();
+    }
+  } catch (e, st) {
+    if (!controller.isClosed) {
+      controller.addError(e, st);
+      await controller.close();
+    }
+  }
+}
+
+/// Parses one SSE frame. Heartbeat comments (starting with ":") and
+/// frames without a `data:` line return null. Frames with a `data:`
+/// payload that doesn't parse as JSON are also dropped (logged at
+/// debug level by the caller if needed).
+LiveEvent? _parseFrame(String frame) {
+  String? kind;
+  String? dataLine;
+  for (final line in frame.split('\n')) {
+    if (line.isEmpty || line.startsWith(':')) {
+      continue;
+    }
+    if (line.startsWith('event:')) {
+      kind = line.substring(6).trim();
+    } else if (line.startsWith('data:')) {
+      dataLine = line.substring(5).trim();
+    }
+  }
+  if (dataLine == null) return null;
+  try {
+    final decoded = jsonDecode(dataLine) as Map<String, dynamic>;
+    return LiveEvent(
+      kind: kind ?? (decoded['kind'] as String? ?? ''),
+      userId: decoded['user_id'] as String? ?? '',
+      data: (decoded['data'] as Map<String, dynamic>?) ?? const {},
+    );
+  } catch (_) {
+    return null;
+  }
+}

flutter_client/lib/shared/routing.dart

@@ -7,6 +7,9 @@ import '../auth/login_screen.dart';
 import '../auth/server_url_screen.dart';
 import '../library/album_detail_screen.dart';
 import '../library/artist_detail_screen.dart';
+import '../models/album.dart';
+import '../models/artist.dart';
+import '../models/playlist.dart';
 import '../discover/discover_screen.dart';
 import '../library/home_screen.dart';
 import '../library/library_screen.dart';
@@ -15,8 +18,11 @@ import '../player/player_bar.dart';
 import '../player/queue_screen.dart';
 import '../playlists/playlist_detail_screen.dart';
 import '../playlists/playlists_list_screen.dart';
+import '../requests/requests_screen.dart';
 import '../search/search_screen.dart';
 import '../settings/settings_screen.dart';
+import '../update/client_update_provider.dart';
+import '../update/update_banner.dart';
 import '../admin/admin_landing_screen.dart';
 import '../admin/admin_requests_screen.dart';
 import '../admin/admin_quarantine_screen.dart';
@@ -52,20 +58,62 @@ GoRouter buildRouter(Ref ref) {
       GoRoute(path: '/', redirect: (_, __) => '/home'),
       GoRoute(path: '/server-url', builder: (_, __) => const ServerUrlScreen()),
       GoRoute(path: '/login',      builder: (_, __) => const LoginScreen()),
+      // /now-playing lives outside the ShellRoute on purpose. The full
+      // player IS the player UI when active, and we don't want the mini
+      // bar from the shell underneath fighting for the bottom strip.
+      // Pushing this route unmounts the shell entirely; the slide-up
+      // transition still feels right because the shell stays painted
+      // for the duration of the animation.
+      GoRoute(
+        path: '/now-playing',
+        pageBuilder: (_, __) => CustomTransitionPage(
+          child: const NowPlayingScreen(),
+          transitionDuration: const Duration(milliseconds: 280),
+          reverseTransitionDuration: const Duration(milliseconds: 240),
+          transitionsBuilder: (_, anim, __, child) {
+            final eased = CurvedAnimation(
+              parent: anim,
+              curve: Curves.easeOutCubic,
+              reverseCurve: Curves.easeInCubic,
+            );
+            return SlideTransition(
+              position: Tween(
+                begin: const Offset(0, 1),
+                end: Offset.zero,
+              ).animate(eased),
+              child: child,
+            );
+          },
+        ),
+      ),
+      // /queue lives outside the ShellRoute too. Why: pushing /queue
+      // from /now-playing (which is also outside the shell) used to
+      // cause go_router to mount a second ShellRoute instance under
+      // the existing one, producing a duplicate page-key assertion
+      // (NavigatorState._debugCheckDuplicatedPageKeys). Top-level
+      // routes can stack on each other freely; shell-children can't
+      // when something on top of the shell is already routing.
+      GoRoute(path: '/queue', builder: (_, __) => const QueueScreen()),
       ShellRoute(
         builder: (ctx, state, child) => VersionGate(child: _ShellWithPlayerBar(child: child)),
         routes: [
           GoRoute(path: '/home', builder: (_, __) => const HomeScreen()),
           GoRoute(
             path: '/artists/:id',
-            builder: (_, s) => ArtistDetailScreen(id: s.pathParameters['id']!),
+            // `extra` carries an optional ArtistRef so the detail
+            // header renders immediately while tracks/albums load.
+            builder: (_, s) => ArtistDetailScreen(
+              id: s.pathParameters['id']!,
+              seed: s.extra is ArtistRef ? s.extra as ArtistRef : null,
+            ),
           ),
           GoRoute(
             path: '/albums/:id',
-            builder: (_, s) => AlbumDetailScreen(id: s.pathParameters['id']!),
+            builder: (_, s) => AlbumDetailScreen(
+              id: s.pathParameters['id']!,
+              seed: s.extra is AlbumRef ? s.extra as AlbumRef : null,
+            ),
           ),
-          GoRoute(path: '/now-playing', builder: (_, __) => const NowPlayingScreen()),
-          GoRoute(path: '/queue', builder: (_, __) => const QueueScreen()),
           GoRoute(path: '/search', builder: (_, __) => const SearchScreen()),
           GoRoute(path: '/library', builder: (_, __) => const LibraryScreen()),
           GoRoute(path: '/discover', builder: (_, __) => const DiscoverScreen()),
@@ -73,8 +121,12 @@ GoRouter buildRouter(Ref ref) {
           GoRoute(path: '/playlists', builder: (_, __) => const PlaylistsListScreen()),
           GoRoute(
             path: '/playlists/:id',
-            builder: (_, s) => PlaylistDetailScreen(id: s.pathParameters['id']!),
+            builder: (_, s) => PlaylistDetailScreen(
+              id: s.pathParameters['id']!,
+              seed: s.extra is Playlist ? s.extra as Playlist : null,
+            ),
           ),
+          GoRoute(path: '/requests',         builder: (_, __) => const RequestsScreen()),
           GoRoute(path: '/admin',            builder: (_, __) => const AdminLandingScreen()),
           GoRoute(path: '/admin/requests',   builder: (_, __) => const AdminRequestsScreen()),
           GoRoute(path: '/admin/quarantine', builder: (_, __) => const AdminQuarantineScreen()),
@@ -85,14 +137,35 @@ GoRouter buildRouter(Ref ref) {
   );
 }
 
-class _ShellWithPlayerBar extends StatelessWidget {
+class _ShellWithPlayerBar extends ConsumerWidget {
   const _ShellWithPlayerBar({required this.child});
   final Widget child;
   @override
-  Widget build(BuildContext context) {
+  Widget build(BuildContext context, WidgetRef ref) {
+    // The banner sits above the routed child and uses SafeArea to clear
+    // the system status bar. MediaQuery.padding is screen-relative
+    // though, so the child's Scaffold/AppBar would still apply its own
+    // top status-bar inset on top of the banner — doubling the gap.
+    // When the banner is showing, strip that inset from the child so
+    // its AppBar lands directly under the banner.
+    final hasBanner = ref.watch(shouldShowUpdateBannerProvider) != null;
     return Column(
       children: [
-        Expanded(child: child),
+        // VersionTooOldBanner above UpdateBanner: a server-rejects-you
+        // soft warning carries more user-relevant urgency than the APK
+        // download prompt below it. The two banners can coexist
+        // (server says you're too old AND a local APK is queued).
+        const VersionTooOldBanner(),
+        const UpdateBanner(),
+        Expanded(
+          child: hasBanner
+              ? MediaQuery.removePadding(
+                  context: context,
+                  removeTop: true,
+                  child: child,
+                )
+              : child,
+        ),
         const PlayerBar(),
       ],
     );

flutter_client/lib/shared/widgets/server_image.dart

@@ -0,0 +1,104 @@
+import 'package:cached_network_image/cached_network_image.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_cache_manager/flutter_cache_manager.dart'
+    show HttpExceptionWithStatus;
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../auth/auth_provider.dart';
+
+/// CachedNetworkImage wrapper that resolves server-relative URLs (e.g.
+/// `/api/albums/<id>/cover`) against the configured server base URL
+/// from [serverUrlProvider]. Absolute URLs (with scheme) pass through
+/// unchanged. Empty/null base or empty URL render the [fallback]
+/// (defaults to a transparent SizedBox so callers can supply their own
+/// surrounding placeholder).
+///
+/// Mirrors the absolute-or-relative logic the audio handler uses for
+/// stream URLs, so cover art and audio resolve URLs the same way.
+///
+/// Uses CachedNetworkImage so cover bytes land on disk (path_provider
+/// temp dir, keyed by URL) and survive scroll-off + app restart. The
+/// previous Image.network behavior cached only in-memory, so the cold-
+/// start home grid re-downloaded every cover.
+class ServerImage extends ConsumerWidget {
+  const ServerImage({
+    super.key,
+    required this.url,
+    this.fit,
+    this.fallback,
+  });
+
+  final String url;
+  final BoxFit? fit;
+  final Widget? fallback;
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final empty = fallback ?? const SizedBox.shrink();
+    if (url.isEmpty) return empty;
+    final base = ref.watch(serverUrlProvider).value;
+    final resolved = _resolve(base, url);
+    if (resolved == null) return empty;
+    // Cover endpoints are gated by RequireUser server-side. The image
+    // loader doesn't carry cookies/Bearer tokens automatically the way
+    // the browser's <img> tag does, so we forward the session token as
+    // a header. Without this, the server returns 401 and the image
+    // fails.
+    //
+    // sessionTokenProvider is a FutureProvider — on first read after a
+    // hot restart its .value is null until the secure-storage read
+    // resolves. If we mounted the image with httpHeaders:null at that
+    // moment, the disk cache would lock in the 401 response and never
+    // retry. Hold the fallback until the token is available, then
+    // mount the image with the auth header attached.
+    final tokenAsync = ref.watch(sessionTokenProvider);
+    return tokenAsync.when(
+      loading: () => empty,
+      error: (_, __) => empty,
+      data: (token) {
+        final headers = (token != null && token.isNotEmpty)
+            ? {'Authorization': 'Bearer $token'}
+            : <String, String>{};
+        return CachedNetworkImage(
+          imageUrl: resolved,
+          httpHeaders: headers,
+          fit: fit,
+          // 120ms feels like cover bytes settling in on a cache miss
+          // (smoother than the abrupt zero-fade); on cache hits the
+          // image is decoded synchronously so the fade is imperceptible.
+          // The default 500ms is too long — looks like a regression on
+          // a populated grid.
+          fadeInDuration: const Duration(milliseconds: 120),
+          fadeOutDuration: Duration.zero,
+          // Keep failures local — a single 401/timeout shouldn't dump
+          // a stack trace or replace the parent Container's background.
+          errorWidget: (_, __, ___) => empty,
+          // Filter expected 404s out of dev console noise: playlist
+          // collages aren't built until the playlist has tracks and
+          // the build job runs (system playlists like For-You /
+          // Discover hit this on first-render). The errorWidget
+          // already renders the fallback for the user; this just
+          // keeps the dev console clean. Non-404 errors still
+          // surface so auth/connectivity issues remain visible.
+          errorListener: (err) {
+            if (err is HttpExceptionWithStatus && err.statusCode == 404) {
+              return;
+            }
+            debugPrint('ServerImage: $err');
+          },
+        );
+      },
+    );
+  }
+
+  static String? _resolve(String? baseUrl, String url) {
+    final parsed = Uri.tryParse(url);
+    if (parsed != null && parsed.hasScheme) return url;
+    if (baseUrl == null || baseUrl.isEmpty) return null;
+    final base = baseUrl.endsWith('/')
+        ? baseUrl.substring(0, baseUrl.length - 1)
+        : baseUrl;
+    final path = url.startsWith('/') ? url : '/$url';
+    return '$base$path';
+  }
+}

flutter_client/lib/shared/widgets/skeletons.dart

@@ -0,0 +1,199 @@
+// Skeleton placeholder widgets for the per-item rendering architecture
+// (see docs/superpowers/specs/2026-05-13-per-item-rendering-design.md).
+//
+// Each skeleton matches the exact dimensions of its corresponding real
+// card so the layout doesn't shift when content lands. A subtle
+// shimmer sweep makes the page feel alive while individual tiles
+// hydrate against drift / REST in the background.
+//
+// Self-contained shimmer (no `shimmer` package dep) so we can keep
+// pubspec lean and tune the sweep colors against FabledSword tokens.
+
+import 'package:flutter/material.dart';
+
+import '../../theme/theme_extension.dart';
+
+/// Period of one full shimmer sweep across the skeleton.
+const Duration _shimmerPeriod = Duration(milliseconds: 1200);
+
+/// Wraps a child with a slow-moving highlight band on top of the
+/// skeleton's base color. Cheap — uses a single AnimationController
+/// per surface and a LinearGradient shader.
+class _Shimmer extends StatefulWidget {
+  const _Shimmer({required this.child});
+  final Widget child;
+
+  @override
+  State<_Shimmer> createState() => _ShimmerState();
+}
+
+class _ShimmerState extends State<_Shimmer>
+    with SingleTickerProviderStateMixin {
+  late final AnimationController _ctrl = AnimationController(
+    vsync: this,
+    duration: _shimmerPeriod,
+  )..repeat();
+
+  @override
+  void dispose() {
+    _ctrl.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return AnimatedBuilder(
+      animation: _ctrl,
+      builder: (context, child) {
+        return ShaderMask(
+          blendMode: BlendMode.srcATop,
+          shaderCallback: (rect) {
+            // Sweep starts off-screen left, ends off-screen right.
+            final dx = (_ctrl.value * 2 - 1) * rect.width;
+            return LinearGradient(
+              begin: Alignment.centerLeft,
+              end: Alignment.centerRight,
+              colors: [
+                fs.slate,
+                fs.iron,
+                fs.slate,
+              ],
+              stops: const [0.0, 0.5, 1.0],
+              transform: _SlideGradient(dx),
+            ).createShader(rect);
+          },
+          child: child,
+        );
+      },
+      child: widget.child,
+    );
+  }
+}
+
+/// Helper for translating a gradient horizontally inside its rect.
+class _SlideGradient extends GradientTransform {
+  const _SlideGradient(this.dx);
+  final double dx;
+
+  @override
+  Matrix4 transform(Rect bounds, {TextDirection? textDirection}) {
+    return Matrix4.translationValues(dx, 0, 0);
+  }
+}
+
+/// Skeleton matched to AlbumCard's 140px outer width / 124px cover /
+/// title + artist text rows. Used in horizontal carousels where the
+/// real card lives.
+class SkeletonAlbumTile extends StatelessWidget {
+  const SkeletonAlbumTile({super.key, this.width = 140});
+  final double width;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final coverSize = width - 16;
+    return _Shimmer(
+      child: SizedBox(
+        width: width,
+        child: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 8),
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              ClipRRect(
+                borderRadius: BorderRadius.circular(6),
+                child: Container(
+                  width: coverSize,
+                  height: coverSize,
+                  color: fs.slate,
+                ),
+              ),
+              const SizedBox(height: 8),
+              Container(width: coverSize * 0.8, height: 14, color: fs.slate),
+              const SizedBox(height: 4),
+              Container(width: coverSize * 0.6, height: 12, color: fs.slate),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+/// Skeleton matched to ArtistCard's 140px / 124px round-thumb shape.
+class SkeletonArtistTile extends StatelessWidget {
+  const SkeletonArtistTile({super.key, this.width = 140});
+  final double width;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final coverSize = width - 16;
+    return _Shimmer(
+      child: SizedBox(
+        width: width,
+        child: Padding(
+          padding: const EdgeInsets.symmetric(horizontal: 8),
+          child: Column(
+            crossAxisAlignment: CrossAxisAlignment.start,
+            mainAxisSize: MainAxisSize.min,
+            children: [
+              Container(
+                width: coverSize,
+                height: coverSize,
+                decoration: BoxDecoration(
+                  color: fs.slate,
+                  shape: BoxShape.circle,
+                ),
+              ),
+              const SizedBox(height: 8),
+              Container(width: coverSize * 0.7, height: 14, color: fs.slate),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}
+
+/// Skeleton matched to TrackRow's vertical-list layout. 56dp cover +
+/// title + artist line, similar to the real row.
+class SkeletonTrackRow extends StatelessWidget {
+  const SkeletonTrackRow({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return _Shimmer(
+      child: Padding(
+        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
+        child: Row(
+          children: [
+            Container(
+              width: 56,
+              height: 56,
+              decoration: BoxDecoration(
+                color: fs.slate,
+                borderRadius: BorderRadius.circular(6),
+              ),
+            ),
+            const SizedBox(width: 12),
+            Expanded(
+              child: Column(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                mainAxisSize: MainAxisSize.min,
+                children: [
+                  Container(width: 180, height: 14, color: fs.slate),
+                  const SizedBox(height: 6),
+                  Container(width: 120, height: 12, color: fs.slate),
+                ],
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}

flutter_client/lib/shared/widgets/track_actions/add_to_playlist_sheet.dart

@@ -0,0 +1,94 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../../playlists/playlists_provider.dart';
+import '../../../theme/theme_extension.dart';
+
+/// Modal bottom sheet listing the caller's user-created playlists.
+/// Returns the picked playlistId via Navigator.pop, or null on cancel.
+class AddToPlaylistSheet extends ConsumerWidget {
+  const AddToPlaylistSheet({super.key});
+
+  static Future<String?> show(BuildContext context) {
+    return showModalBottomSheet<String>(
+      context: context,
+      isScrollControlled: true,
+      builder: (_) => const AddToPlaylistSheet(),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final lists = ref.watch(playlistsListProvider('user'));
+    return SafeArea(
+      child: Container(
+        color: fs.iron,
+        padding: const EdgeInsets.symmetric(vertical: 8),
+        constraints: BoxConstraints(
+          maxHeight: MediaQuery.of(context).size.height * 0.6,
+        ),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          crossAxisAlignment: CrossAxisAlignment.start,
+          children: [
+            Padding(
+              padding: const EdgeInsets.fromLTRB(20, 8, 20, 8),
+              child: Text(
+                'Add to playlist',
+                style: TextStyle(
+                  color: fs.parchment,
+                  fontFamily: 'Fraunces',
+                  fontSize: 20,
+                ),
+              ),
+            ),
+            Flexible(
+              child: lists.when(
+                loading: () => const Center(child: CircularProgressIndicator()),
+                error: (e, _) => Padding(
+                  padding: const EdgeInsets.all(16),
+                  child: Text('$e', style: TextStyle(color: fs.error)),
+                ),
+                data: (data) {
+                  final owned = data.owned
+                      .where((p) => p.systemVariant == null)
+                      .toList();
+                  if (owned.isEmpty) {
+                    return Padding(
+                      padding: const EdgeInsets.all(20),
+                      child: Text(
+                        "You haven't created any playlists yet.",
+                        style: TextStyle(color: fs.ash),
+                      ),
+                    );
+                  }
+                  return ListView.builder(
+                    shrinkWrap: true,
+                    itemCount: owned.length,
+                    itemBuilder: (_, i) {
+                      final p = owned[i];
+                      return ListTile(
+                        key: Key('add_to_playlist_${p.id}'),
+                        leading: Icon(Icons.queue_music, color: fs.parchment),
+                        title: Text(
+                          p.name,
+                          style: TextStyle(color: fs.parchment),
+                        ),
+                        subtitle: Text(
+                          '${p.trackCount} ${p.trackCount == 1 ? "track" : "tracks"}',
+                          style: TextStyle(color: fs.ash, fontSize: 12),
+                        ),
+                        onTap: () => Navigator.pop(context, p.id),
+                      );
+                    },
+                  );
+                },
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}

flutter_client/lib/shared/widgets/track_actions/hide_track_sheet.dart

@@ -0,0 +1,122 @@
+import 'package:flutter/material.dart';
+
+import '../../../theme/theme_extension.dart';
+
+/// Modal bottom sheet for picking a hide reason + optional notes.
+/// Returns ({reason, notes}) on submit, null on cancel.
+class HideTrackSheet extends StatefulWidget {
+  const HideTrackSheet({super.key});
+
+  static Future<({String reason, String notes})?> show(BuildContext context) {
+    return showModalBottomSheet<({String reason, String notes})>(
+      context: context,
+      isScrollControlled: true,
+      builder: (_) => const HideTrackSheet(),
+    );
+  }
+
+  @override
+  State<HideTrackSheet> createState() => _HideTrackSheetState();
+}
+
+class _HideTrackSheetState extends State<HideTrackSheet> {
+  String _reason = 'bad_rip';
+  final _notesCtrl = TextEditingController();
+
+  // Wire values mirror the server vocabulary; display labels mirror the
+  // existing _QuarantineTile in library_screen.dart.
+  static const _options = [
+    ('bad_rip', 'Bad rip'),
+    ('wrong_file', 'Wrong file'),
+    ('wrong_tags', 'Wrong tags'),
+    ('duplicate', 'Duplicate'),
+    ('other', 'Other'),
+  ];
+
+  @override
+  void dispose() {
+    _notesCtrl.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return SafeArea(
+      child: Padding(
+        padding: EdgeInsets.only(
+          bottom: MediaQuery.of(context).viewInsets.bottom,
+        ),
+        child: Container(
+          color: fs.iron,
+          padding: const EdgeInsets.all(20),
+          child: Column(
+            mainAxisSize: MainAxisSize.min,
+            crossAxisAlignment: CrossAxisAlignment.start,
+            children: [
+              Text(
+                'Hide this track',
+                style: TextStyle(
+                  color: fs.parchment,
+                  fontFamily: 'Fraunces',
+                  fontSize: 20,
+                ),
+              ),
+              const SizedBox(height: 12),
+              Text(
+                'Pick a reason. Optional notes are visible to admins.',
+                style: TextStyle(color: fs.ash),
+              ),
+              const SizedBox(height: 12),
+              Wrap(
+                spacing: 8,
+                runSpacing: 8,
+                children: [
+                  for (final (value, label) in _options)
+                    ChoiceChip(
+                      key: Key('hide_reason_$value'),
+                      label: Text(label),
+                      selected: _reason == value,
+                      onSelected: (_) => setState(() => _reason = value),
+                    ),
+                ],
+              ),
+              const SizedBox(height: 12),
+              TextField(
+                key: const Key('hide_notes_input'),
+                controller: _notesCtrl,
+                decoration: const InputDecoration(
+                  labelText: 'Notes (optional)',
+                ),
+                maxLines: 2,
+              ),
+              const SizedBox(height: 16),
+              Row(
+                mainAxisAlignment: MainAxisAlignment.end,
+                children: [
+                  TextButton(
+                    onPressed: () => Navigator.pop(context),
+                    child: const Text('Cancel'),
+                  ),
+                  const SizedBox(width: 8),
+                  ElevatedButton(
+                    key: const Key('hide_confirm'),
+                    style: ElevatedButton.styleFrom(
+                      backgroundColor: fs.oxblood,
+                      foregroundColor: fs.parchment,
+                    ),
+                    onPressed: () => Navigator.pop(
+                      context,
+                      (reason: _reason, notes: _notesCtrl.text.trim()),
+                    ),
+                    child: const Text('Hide'),
+                  ),
+                ],
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

flutter_client/lib/shared/widgets/track_actions/track_actions_button.dart

@@ -0,0 +1,42 @@
+import 'package:flutter/material.dart';
+
+import '../../../models/track.dart';
+import '../../../theme/theme_extension.dart';
+import 'track_actions_sheet.dart';
+
+/// Small 3-dot trigger that opens TrackActionsSheet. Drop into any
+/// track row / card to expose the canonical 7-action menu.
+class TrackActionsButton extends StatelessWidget {
+  const TrackActionsButton({
+    super.key,
+    required this.track,
+    this.hideQueueActions = false,
+    this.onNavigate,
+  });
+
+  final TrackRef track;
+
+  /// Suppresses Play next / Add to queue. Set true on the Now Playing
+  /// screen where the menu's track IS the currently-playing one.
+  final bool hideQueueActions;
+
+  /// Forwarded to TrackActionsSheet.onNavigate. The host receives the
+  /// destination path AFTER the sheet has popped and is responsible
+  /// for navigating to it (typically: pop self first, then push).
+  final Future<void> Function(String path)? onNavigate;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return IconButton(
+      icon: Icon(Icons.more_vert, color: fs.ash, size: 18),
+      tooltip: 'Track actions',
+      onPressed: () => TrackActionsSheet.show(
+        context,
+        track,
+        hideQueueActions: hideQueueActions,
+        onNavigate: onNavigate,
+      ),
+    );
+  }
+}

flutter_client/lib/shared/widgets/track_actions/track_actions_sheet.dart

@@ -0,0 +1,296 @@
+import 'package:drift/drift.dart' as drift;
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:go_router/go_router.dart';
+
+import '../../../api/endpoints/likes.dart';
+import '../../../cache/audio_cache_manager.dart' show appDbProvider;
+import '../../../cache/db.dart';
+import '../../../cache/mutation_queue.dart';
+import '../../../likes/likes_provider.dart';
+import '../../../models/track.dart';
+import '../../../player/player_provider.dart';
+import '../../../playlists/playlists_provider.dart';
+import '../../../quarantine/quarantine_provider.dart';
+import '../../../theme/theme_extension.dart';
+import 'add_to_playlist_sheet.dart';
+import 'hide_track_sheet.dart';
+
+/// Modal bottom sheet that lists the 7 canonical track actions.
+/// Pops first when an item is tapped (immediate visual feedback) and
+/// then runs the action — for actions that open a sub-sheet, the
+/// sub-sheet opens after the parent pops.
+class TrackActionsSheet extends ConsumerWidget {
+  const TrackActionsSheet({
+    super.key,
+    required this.track,
+    required this.hideQueueActions,
+    this.onNavigate,
+  });
+
+  final TrackRef track;
+  final bool hideQueueActions;
+
+  /// Optional hook for "Go to album" / "Go to artist". Called with
+  /// the destination route path AFTER the sheet has popped. Lets
+  /// callers that live OUTSIDE the ShellRoute (e.g. the full player
+  /// at /now-playing) pop themselves first then push, so go_router
+  /// doesn't try to mount a second ShellRoute on top of the active
+  /// top-level route. When null, the sheet does its own
+  /// context.push, which is correct for surfaces already inside the
+  /// shell (mini player, track rows on detail screens, etc.).
+  final Future<void> Function(String path)? onNavigate;
+
+  static Future<void> show(
+    BuildContext context,
+    TrackRef track, {
+    bool hideQueueActions = false,
+    Future<void> Function(String path)? onNavigate,
+  }) {
+    return showModalBottomSheet<void>(
+      context: context,
+      isScrollControlled: true,
+      builder: (_) => TrackActionsSheet(
+        track: track,
+        hideQueueActions: hideQueueActions,
+        onNavigate: onNavigate,
+      ),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    final liked = ref.watch(likedIdsProvider).value?.has(LikeKind.track, track.id) ?? false;
+    final hidden = ref.watch(myQuarantineProvider).value?.any((r) => r.trackId == track.id) ?? false;
+    return SafeArea(
+      child: Container(
+        color: fs.iron,
+        padding: const EdgeInsets.symmetric(vertical: 8),
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            if (!hideQueueActions) ...[
+              _MenuItem(
+                key: const Key('track_actions_play_next'),
+                icon: Icons.playlist_play,
+                label: 'Play next',
+                onTap: () async {
+                  Navigator.pop(context);
+                  await ref.read(playerActionsProvider).playNext(track);
+                  if (context.mounted) {
+                    ScaffoldMessenger.of(context).showSnackBar(
+                      const SnackBar(content: Text('Added to queue (next)')),
+                    );
+                  }
+                },
+              ),
+              _MenuItem(
+                key: const Key('track_actions_enqueue'),
+                icon: Icons.queue_music,
+                label: 'Add to queue',
+                onTap: () async {
+                  Navigator.pop(context);
+                  await ref.read(playerActionsProvider).enqueue(track);
+                  if (context.mounted) {
+                    ScaffoldMessenger.of(context).showSnackBar(
+                      const SnackBar(content: Text('Added to queue')),
+                    );
+                  }
+                },
+              ),
+              const _Divider(),
+            ],
+            _MenuItem(
+              key: const Key('track_actions_like'),
+              icon: liked ? Icons.favorite : Icons.favorite_border,
+              label: liked ? 'Unlike' : 'Like',
+              onTap: () async {
+                Navigator.pop(context);
+                await ref.read(likesControllerProvider).toggle(LikeKind.track, track.id);
+              },
+            ),
+            _MenuItem(
+              key: const Key('track_actions_add_to_playlist'),
+              icon: Icons.playlist_add,
+              label: 'Add to playlist…',
+              onTap: () async {
+                Navigator.pop(context);
+                final playlistId = await AddToPlaylistSheet.show(context);
+                if (playlistId == null || !context.mounted) return;
+                try {
+                  await ref.read(addToPlaylistActionProvider).call(playlistId, track.id);
+                  if (context.mounted) {
+                    ScaffoldMessenger.of(context).showSnackBar(
+                      const SnackBar(content: Text('Added to playlist')),
+                    );
+                  }
+                } catch (e) {
+                  if (context.mounted) {
+                    ScaffoldMessenger.of(context).showSnackBar(
+                      SnackBar(content: Text("Couldn't add to playlist: $e")),
+                    );
+                  }
+                }
+              },
+            ),
+            _MenuItem(
+              key: const Key('track_actions_start_radio'),
+              icon: Icons.radio,
+              label: 'Start radio',
+              onTap: () async {
+                Navigator.pop(context);
+                try {
+                  await ref.read(playerActionsProvider).startRadio(track.id);
+                } catch (e) {
+                  if (context.mounted) {
+                    ScaffoldMessenger.of(context).showSnackBar(
+                      SnackBar(content: Text("Couldn't start radio: $e")),
+                    );
+                  }
+                }
+              },
+            ),
+            const _Divider(),
+            _MenuItem(
+              key: const Key('track_actions_go_to_album'),
+              icon: Icons.album,
+              label: 'Go to album',
+              onTap: () {
+                Navigator.pop(context);
+                final path = '/albums/${track.albumId}';
+                if (onNavigate != null) {
+                  onNavigate!(path);
+                } else {
+                  context.push(path);
+                }
+              },
+            ),
+            _MenuItem(
+              key: const Key('track_actions_go_to_artist'),
+              icon: Icons.person,
+              label: 'Go to artist',
+              onTap: () {
+                Navigator.pop(context);
+                final path = '/artists/${track.artistId}';
+                if (onNavigate != null) {
+                  onNavigate!(path);
+                } else {
+                  context.push(path);
+                }
+              },
+            ),
+            const _Divider(),
+            _MenuItem(
+              key: const Key('track_actions_hide'),
+              icon: hidden ? Icons.visibility : Icons.visibility_off,
+              label: hidden ? 'Unhide' : 'Hide',
+              onTap: () async {
+                Navigator.pop(context);
+                if (hidden) {
+                  try {
+                    await ref.read(myQuarantineProvider.notifier).unflag(track.id);
+                  } catch (e) {
+                    if (context.mounted) {
+                      ScaffoldMessenger.of(context).showSnackBar(
+                        SnackBar(content: Text("Couldn't unhide: $e")),
+                      );
+                    }
+                  }
+                  return;
+                }
+                final result = await HideTrackSheet.show(context);
+                if (result == null || !context.mounted) return;
+                try {
+                  await ref
+                      .read(myQuarantineProvider.notifier)
+                      .flag(track, result.reason, result.notes);
+                } catch (e) {
+                  if (context.mounted) {
+                    ScaffoldMessenger.of(context).showSnackBar(
+                      SnackBar(content: Text("Couldn't hide: $e")),
+                    );
+                  }
+                }
+              },
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _MenuItem extends StatelessWidget {
+  const _MenuItem({
+    super.key,
+    required this.icon,
+    required this.label,
+    required this.onTap,
+  });
+  final IconData icon;
+  final String label;
+  final VoidCallback onTap;
+
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return ListTile(
+      leading: Icon(icon, color: fs.parchment),
+      title: Text(label, style: TextStyle(color: fs.parchment)),
+      onTap: onTap,
+    );
+  }
+}
+
+class _Divider extends StatelessWidget {
+  const _Divider();
+  @override
+  Widget build(BuildContext context) {
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return Divider(height: 1, color: fs.slate);
+  }
+}
+
+/// Convenience callable for "append a single track to a playlist."
+/// Lives here (not in playlists_provider) because it's purely a
+/// menu-flow concern — no other caller.
+typedef AddToPlaylistAction = Future<void> Function(String playlistId, String trackId);
+
+final addToPlaylistActionProvider = Provider<AddToPlaylistAction>((ref) {
+  return (playlistId, trackId) async {
+    final db = ref.read(appDbProvider);
+    // Optimistic drift write so the playlist detail screen shows the
+    // new track instantly. The position is best-effort — append after
+    // the current max for this playlist. The server's authoritative
+    // position lands on next playlistDetailProvider fetch (SWR), or
+    // when the queued mutation replays.
+    final maxPos = await (db.selectOnly(db.cachedPlaylistTracks)
+          ..addColumns([db.cachedPlaylistTracks.position.max()])
+          ..where(db.cachedPlaylistTracks.playlistId.equals(playlistId)))
+        .getSingleOrNull();
+    final nextPos =
+        ((maxPos?.read(db.cachedPlaylistTracks.position.max()) ?? -1) + 1);
+    await db.into(db.cachedPlaylistTracks).insertOnConflictUpdate(
+          CachedPlaylistTracksCompanion.insert(
+            playlistId: playlistId,
+            trackId: trackId,
+            position: drift.Value(nextPos),
+          ),
+        );
+
+    try {
+      final api = await ref.read(playlistsApiProvider.future);
+      await api.appendTracks(playlistId, [trackId]);
+    } catch (_) {
+      // REST failed — keep the optimistic drift row; queue the call.
+      await ref.read(mutationQueueProvider).enqueue(
+        MutationKinds.playlistAppend,
+        {
+          'playlistId': playlistId,
+          'trackIds': [trackId],
+        },
+      );
+    }
+  };
+});

flutter_client/lib/shared/widgets/version_gate.dart

@@ -1,3 +1,6 @@
+import 'dart:async';
+
+import 'package:dio/dio.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:package_info_plus/package_info_plus.dart';
@@ -6,61 +9,255 @@ import 'package:pub_semver/pub_semver.dart';
 import '../../api/client.dart';
 import '../../api/endpoints/health.dart';
 import '../../auth/auth_provider.dart';
+import '../../theme/theme_extension.dart';
 
-final _versionCheckProvider = FutureProvider<_VersionResult>((ref) async {
-  final url = await ref.watch(serverUrlProvider.future);
-  if (url == null) return _VersionResult.skipped;
-  final dio = ApiClient.buildDio(baseUrl: url, tokenResolver: () async => null);
-  final body = await HealthApi(dio).check();
-  final min = body['min_client_version'];
-  if (min == null || min.isEmpty) return _VersionResult.skipped;
-  final info = await PackageInfo.fromPlatform();
-  final mine = Version.parse(info.version);
-  final required = Version.parse(min);
-  return mine < required ? _VersionResult.tooOld : _VersionResult.ok;
-});
+/// Result of the most recent /healthz version compatibility check.
+///
+/// `skipped` means the server didn't emit a `min_client_version` field
+/// (older servers, partial deploys). Treat as compatible.
+enum VersionResult { ok, tooOld, skipped }
 
-enum _VersionResult { ok, tooOld, skipped }
+VersionResult _resultFromString(String? s) {
+  switch (s) {
+    case 'ok':
+      return VersionResult.ok;
+    case 'tooOld':
+      return VersionResult.tooOld;
+    default:
+      return VersionResult.skipped;
+  }
+}
 
-class VersionGate extends ConsumerWidget {
+String _stringFromResult(VersionResult r) {
+  switch (r) {
+    case VersionResult.ok:
+      return 'ok';
+    case VersionResult.tooOld:
+      return 'tooOld';
+    case VersionResult.skipped:
+      return 'skipped';
+  }
+}
+
+/// Drives the version-compatibility check against /healthz. Non-blocking:
+/// the controller hydrates from a 1h-throttled cache on boot, exposes
+/// the current `VersionResult`, and refreshes itself in the background.
+/// UI (VersionGate + _VersionTooOldBanner) reads this state to decide
+/// whether to surface the "too old" banner — never blocks rendering.
+///
+/// Cache keys live in flutter_secure_storage so the cadence survives
+/// app restarts. 1h throttle bounds /healthz traffic; explicit
+/// `recheck()` (from the banner's "Check now" button or app resume)
+/// bypasses the throttle.
+class VersionCheckController extends AsyncNotifier<VersionResult> {
+  static const _kResult = 'version_check_result';
+  static const _kAtMs = 'version_check_at_ms';
+  // 1 minute. The /healthz response is sub-1KB and the call is
+  // non-blocking, so a tight cadence buys faster recovery from
+  // server-side min_client_version bumps without measurable cost. The
+  // gate also acts as a safety net against duplicate calls when the
+  // periodic timer and a resume event fire close together.
+  static const _staleMs = 60 * 1000;
+
+  @override
+  Future<VersionResult> build() async {
+    final storage = ref.read(secureStorageProvider);
+    final resultStr = await storage.read(key: _kResult);
+    final atStr = await storage.read(key: _kAtMs);
+    final cached = _resultFromString(resultStr);
+    final at = int.tryParse(atStr ?? '') ?? 0;
+    final nowMs = DateTime.now().millisecondsSinceEpoch;
+
+    // Fire background recheck on cold-start when cache is missing or stale.
+    // Doesn't block: build returns the cached result immediately; the
+    // recheck updates state asynchronously when it lands.
+    if (nowMs - at > _staleMs) {
+      Future.microtask(_runCheck);
+    }
+    return cached;
+  }
+
+  /// Force a fresh check, bypassing the 1h staleness gate. Used by the
+  /// "Check now" banner button and (indirectly) by the AppLifecycleState
+  /// resume observer in VersionGate.
+  Future<void> recheck() async => _runCheck();
+
+  /// Recheck only if the cache is older than the 1h throttle. No-op
+  /// when fresh. Used on app resume to avoid hammering /healthz when
+  /// the user is briefly switching between apps.
+  Future<void> recheckIfStale() async {
+    final storage = ref.read(secureStorageProvider);
+    final atStr = await storage.read(key: _kAtMs);
+    final at = int.tryParse(atStr ?? '') ?? 0;
+    if (DateTime.now().millisecondsSinceEpoch - at > _staleMs) {
+      await _runCheck();
+    }
+  }
+
+  Future<void> _runCheck() async {
+    try {
+      final url = await ref.read(serverUrlProvider.future);
+      if (url == null || url.isEmpty) return;
+      // Bounded timeouts for a health probe — the default
+      // ApiClient.buildDio dio is tuned for actual data fetches
+      // (8s connect + 30s receive). /healthz should resolve in
+      // tens of milliseconds; failing fast unblocks slow networks.
+      final dio = ApiClient.buildDio(
+        baseUrl: url,
+        tokenResolver: () async => null,
+      );
+      dio.options.connectTimeout = const Duration(seconds: 3);
+      dio.options.receiveTimeout = const Duration(seconds: 2);
+      final body = await HealthApi(dio).check();
+      final min = body['min_client_version'];
+      VersionResult result;
+      if (min == null || min.isEmpty) {
+        result = VersionResult.skipped;
+      } else {
+        final info = await PackageInfo.fromPlatform();
+        final mine = Version.parse(info.version);
+        final required = Version.parse(min);
+        result = mine < required ? VersionResult.tooOld : VersionResult.ok;
+      }
+      // Persist + flip state. Storage write before state assignment so
+      // a hot reload immediately after won't see a fresh state with a
+      // stale cache.
+      final storage = ref.read(secureStorageProvider);
+      await storage.write(key: _kResult, value: _stringFromResult(result));
+      await storage.write(
+        key: _kAtMs,
+        value: DateTime.now().millisecondsSinceEpoch.toString(),
+      );
+      state = AsyncData(result);
+    } on DioException catch (_) {
+      // Network error / timeout. Keep the cached state; don't bump the
+      // timestamp so the next staleness check still triggers a retry.
+    } catch (_) {
+      // Other errors (PackageInfo, parsing, etc.). Same handling —
+      // soft-fail so the UI never sees an error state from a defensive
+      // background check.
+    }
+  }
+}
+
+final versionCheckProvider =
+    AsyncNotifierProvider<VersionCheckController, VersionResult>(
+  VersionCheckController.new,
+);
+
+/// Wraps the shell. Non-blocking: always renders the child. Activates
+/// the version check controller on mount and reruns it on app resume
+/// (gated by the controller's 1h staleness throttle).
+class VersionGate extends ConsumerStatefulWidget {
   const VersionGate({required this.child, super.key});
   final Widget child;
 
   @override
-  Widget build(BuildContext context, WidgetRef ref) {
-    return ref.watch(_versionCheckProvider).when(
-          data: (r) => r == _VersionResult.tooOld ? const _TooOldScreen() : child,
-          error: (_, __) => child, // soft-fail if /healthz is unreachable; let the rest of the flow surface a real error
-          loading: () => const Scaffold(body: Center(child: CircularProgressIndicator())),
-        );
-  }
+  ConsumerState<VersionGate> createState() => _VersionGateState();
 }
 
-class _TooOldScreen extends StatelessWidget {
-  const _TooOldScreen();
+class _VersionGateState extends ConsumerState<VersionGate>
+    with WidgetsBindingObserver {
+  // Polling interval during active foreground use. Paired with the
+  // controller's 1m staleness gate so concurrent fires (timer + resume)
+  // dedupe to a single network call. Tight cadence is affordable —
+  // /healthz is sub-1KB and the call is non-blocking.
+  static const _pollInterval = Duration(minutes: 1);
+  Timer? _pollTimer;
+
   @override
-  Widget build(BuildContext context) {
-    return const Scaffold(
-      body: SafeArea(
-        child: Padding(
-          padding: EdgeInsets.all(24),
-          child: Center(
-            child: Column(
-              mainAxisAlignment: MainAxisAlignment.center,
-              children: [
-                Text(
-                  'Update required',
-                  style: TextStyle(fontSize: 24, fontWeight: FontWeight.w500),
-                ),
-                SizedBox(height: 12),
-                Text(
-                  'This client is too old for that Minstrel server. Install the latest build to continue.',
-                  textAlign: TextAlign.center,
-                ),
-              ],
+  void initState() {
+    super.initState();
+    // Read once so the provider's build() runs; the controller
+    // hydrates from cache + fires a background check when stale.
+    ref.read(versionCheckProvider);
+    WidgetsBinding.instance.addObserver(this);
+    _startPolling();
+  }
+
+  @override
+  void dispose() {
+    _stopPolling();
+    WidgetsBinding.instance.removeObserver(this);
+    super.dispose();
+  }
+
+  void _startPolling() {
+    _pollTimer?.cancel();
+    _pollTimer = Timer.periodic(_pollInterval, (_) {
+      // ignore: unawaited_futures
+      ref.read(versionCheckProvider.notifier).recheckIfStale();
+    });
+  }
+
+  void _stopPolling() {
+    _pollTimer?.cancel();
+    _pollTimer = null;
+  }
+
+  @override
+  void didChangeAppLifecycleState(AppLifecycleState state) {
+    switch (state) {
+      case AppLifecycleState.resumed:
+        // Re-arm the timer + fire one immediate (staleness-gated) check
+        // so users who foreground after a long away period get a fresh
+        // result without waiting for the next tick.
+        // ignore: unawaited_futures
+        ref.read(versionCheckProvider.notifier).recheckIfStale();
+        _startPolling();
+      case AppLifecycleState.paused:
+      case AppLifecycleState.inactive:
+      case AppLifecycleState.hidden:
+      case AppLifecycleState.detached:
+        // Stop firing while backgrounded — no need to burn battery on
+        // health probes the user can't see the result of.
+        _stopPolling();
+    }
+  }
+
+  @override
+  Widget build(BuildContext context) => widget.child;
+}
+
+/// Banner that surfaces when the server reports our client is too old.
+/// Non-blocking: the rest of the app keeps working (offline-mode-style
+/// — locally cached metadata + audio still play). Tap "Check now" to
+/// force a re-check after installing a new build.
+class VersionTooOldBanner extends ConsumerWidget {
+  const VersionTooOldBanner({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final asyncResult = ref.watch(versionCheckProvider);
+    final result = asyncResult.asData?.value;
+    if (result != VersionResult.tooOld) return const SizedBox.shrink();
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+    return SafeArea(
+      bottom: false,
+      child: Container(
+        color: fs.error.withValues(alpha: 0.15),
+        padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 10),
+        child: Row(children: [
+          Icon(Icons.warning_amber_rounded, color: fs.error, size: 18),
+          const SizedBox(width: 8),
+          Expanded(
+            child: Text(
+              "This app is older than the server requires. "
+              "You can keep using cached content; install an update when ready.",
+              style: TextStyle(color: fs.parchment, fontSize: 13),
             ),
           ),
-        ),
+          TextButton(
+            onPressed: () =>
+                ref.read(versionCheckProvider.notifier).recheck(),
+            style: TextButton.styleFrom(
+              foregroundColor: fs.parchment,
+              minimumSize: const Size(0, 36),
+              padding: const EdgeInsets.symmetric(horizontal: 12),
+            ),
+            child: const Text('Check now'),
+          ),
+        ]),
       ),
     );
   }

flutter_client/lib/theme/theme_data.dart

@@ -4,8 +4,8 @@ import 'package:google_fonts/google_fonts.dart';
 import 'theme_extension.dart';
 import 'tokens.dart';
 
-ThemeData buildThemeData() {
-  final fs = FabledSwordTheme.fromTokens();
+ThemeData buildDarkTheme() {
+  final fs = FabledSwordTheme.dark();
   final colorScheme = ColorScheme.dark(
     surface: fs.iron,
     onSurface: fs.parchment,
@@ -14,16 +14,45 @@ ThemeData buildThemeData() {
     secondary: fs.moss,
     error: fs.error,
   );
-
   return ThemeData(
     useMaterial3: true,
+    brightness: Brightness.dark,
     colorScheme: colorScheme,
     scaffoldBackgroundColor: fs.obsidian,
     textTheme: GoogleFonts.interTextTheme().apply(
       bodyColor: fs.parchment,
       displayColor: fs.parchment,
     ),
-    fontFamily: FabledSwordTokens.fontBody,
+    fontFamily: FabledSwordFlatTokens.fontBody,
     extensions: <ThemeExtension<dynamic>>[fs],
   );
 }
+
+ThemeData buildLightTheme() {
+  final fs = FabledSwordTheme.light();
+  final colorScheme = ColorScheme.light(
+    surface: fs.iron,
+    onSurface: fs.parchment, // semantic — light's "parchment" is dark text
+    primary: fs.accent,
+    onPrimary: FabledSwordFlatTokens.onAction,
+    secondary: fs.moss,
+    error: fs.error,
+  );
+  return ThemeData(
+    useMaterial3: true,
+    brightness: Brightness.light,
+    colorScheme: colorScheme,
+    scaffoldBackgroundColor: fs.obsidian, // semantic — light's obsidian is the bg
+    textTheme: GoogleFonts.interTextTheme().apply(
+      bodyColor: fs.parchment,
+      displayColor: fs.parchment,
+    ),
+    fontFamily: FabledSwordFlatTokens.fontBody,
+    extensions: <ThemeExtension<dynamic>>[fs],
+  );
+}
+
+/// Back-compat alias. Existing tests + code call buildThemeData(); it
+/// returns the dark theme to preserve current behaviour. New code
+/// should prefer buildDarkTheme()/buildLightTheme() explicitly.
+ThemeData buildThemeData() => buildDarkTheme();

flutter_client/lib/theme/theme_extension.dart

@@ -30,26 +30,51 @@ class FabledSwordTheme extends ThemeExtension<FabledSwordTheme> {
   final Color warning, error, info;
   final TextStyle display, body, mono;
 
-  static FabledSwordTheme fromTokens() => const FabledSwordTheme(
-        accent: FabledSwordTokens.accent,
-        obsidian: FabledSwordTokens.obsidian,
-        iron: FabledSwordTokens.iron,
-        slate: FabledSwordTokens.slate,
-        pewter: FabledSwordTokens.pewter,
-        parchment: FabledSwordTokens.parchment,
-        vellum: FabledSwordTokens.vellum,
-        ash: FabledSwordTokens.ash,
-        moss: FabledSwordTokens.moss,
-        bronze: FabledSwordTokens.bronze,
-        oxblood: FabledSwordTokens.oxblood,
-        warning: FabledSwordTokens.warning,
-        error: FabledSwordTokens.error,
-        info: FabledSwordTokens.info,
-        display: TextStyle(fontFamily: FabledSwordTokens.fontDisplay),
-        body: TextStyle(fontFamily: FabledSwordTokens.fontBody),
-        mono: TextStyle(fontFamily: FabledSwordTokens.fontMono),
+  factory FabledSwordTheme.dark() => const FabledSwordTheme(
+        accent: FabledSwordFlatTokens.accent,
+        obsidian: FabledSwordDarkTokens.obsidian,
+        iron: FabledSwordDarkTokens.iron,
+        slate: FabledSwordDarkTokens.slate,
+        pewter: FabledSwordDarkTokens.pewter,
+        parchment: FabledSwordDarkTokens.parchment,
+        vellum: FabledSwordDarkTokens.vellum,
+        ash: FabledSwordDarkTokens.ash,
+        moss: FabledSwordFlatTokens.moss,
+        bronze: FabledSwordFlatTokens.bronze,
+        oxblood: FabledSwordFlatTokens.oxblood,
+        warning: FabledSwordFlatTokens.warning,
+        error: FabledSwordFlatTokens.error,
+        info: FabledSwordFlatTokens.info,
+        display: TextStyle(fontFamily: FabledSwordFlatTokens.fontDisplay),
+        body: TextStyle(fontFamily: FabledSwordFlatTokens.fontBody),
+        mono: TextStyle(fontFamily: FabledSwordFlatTokens.fontMono),
       );
 
+  factory FabledSwordTheme.light() => const FabledSwordTheme(
+        accent: FabledSwordFlatTokens.accent,
+        obsidian: FabledSwordLightTokens.obsidian,
+        iron: FabledSwordLightTokens.iron,
+        slate: FabledSwordLightTokens.slate,
+        pewter: FabledSwordLightTokens.pewter,
+        parchment: FabledSwordLightTokens.parchment,
+        vellum: FabledSwordLightTokens.vellum,
+        ash: FabledSwordLightTokens.ash,
+        moss: FabledSwordFlatTokens.moss,
+        bronze: FabledSwordFlatTokens.bronze,
+        oxblood: FabledSwordFlatTokens.oxblood,
+        warning: FabledSwordFlatTokens.warning,
+        error: FabledSwordFlatTokens.error,
+        info: FabledSwordFlatTokens.info,
+        display: TextStyle(fontFamily: FabledSwordFlatTokens.fontDisplay),
+        body: TextStyle(fontFamily: FabledSwordFlatTokens.fontBody),
+        mono: TextStyle(fontFamily: FabledSwordFlatTokens.fontMono),
+      );
+
+  /// Back-compat alias for the original API. Returns the dark theme.
+  /// Existing call sites can keep using fromTokens() until they're
+  /// migrated to .dark() / .light() explicitly.
+  static FabledSwordTheme fromTokens() => FabledSwordTheme.dark();
+
   @override
   FabledSwordTheme copyWith({
     Color? accent,

flutter_client/lib/theme/theme_mode_provider.dart

@@ -0,0 +1,40 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../auth/auth_provider.dart';
+
+const _kThemeModeKey = 'theme_mode';
+
+enum AppThemeMode { system, dark, light }
+
+extension AppThemeModeMaterial on AppThemeMode {
+  ThemeMode get materialMode => switch (this) {
+        AppThemeMode.system => ThemeMode.system,
+        AppThemeMode.dark => ThemeMode.dark,
+        AppThemeMode.light => ThemeMode.light,
+      };
+}
+
+class ThemeModeController extends AsyncNotifier<AppThemeMode> {
+  @override
+  Future<AppThemeMode> build() async {
+    final storage = ref.watch(secureStorageProvider);
+    final raw = await storage.read(key: _kThemeModeKey);
+    return switch (raw) {
+      'dark' => AppThemeMode.dark,
+      'light' => AppThemeMode.light,
+      _ => AppThemeMode.system,
+    };
+  }
+
+  Future<void> set(AppThemeMode mode) async {
+    final storage = ref.read(secureStorageProvider);
+    await storage.write(key: _kThemeModeKey, value: mode.name);
+    state = AsyncData(mode);
+  }
+}
+
+final themeModeProvider =
+    AsyncNotifierProvider<ThemeModeController, AppThemeMode>(
+  ThemeModeController.new,
+);

flutter_client/lib/theme/tokens.dart

@@ -2,6 +2,46 @@
 // Run `dart run tool/gen_tokens.dart` to regenerate.
 import 'package:flutter/material.dart';
 
+class FabledSwordDarkTokens {
+  static const Color obsidian = Color(0xFF14171A);
+  static const Color iron = Color(0xFF1E2228);
+  static const Color slate = Color(0xFF2C313A);
+  static const Color pewter = Color(0xFF3F4651);
+  static const Color parchment = Color(0xFFE8E4D8);
+  static const Color vellum = Color(0xFFC2BFB4);
+  static const Color ash = Color(0xFF9C9A92);
+}
+
+class FabledSwordLightTokens {
+  static const Color obsidian = Color(0xFFF8F5EE);
+  static const Color iron = Color(0xFFECE6D5);
+  static const Color slate = Color(0xFFDCD3BD);
+  static const Color pewter = Color(0xFFB8AE94);
+  static const Color parchment = Color(0xFF14171A);
+  static const Color vellum = Color(0xFF2C313A);
+  static const Color ash = Color(0xFF5C6068);
+}
+
+class FabledSwordFlatTokens {
+  static const Color moss = Color(0xFF4A5D3F);
+  static const Color bronze = Color(0xFF8B7355);
+  static const Color oxblood = Color(0xFF6B2118);
+  static const Color warning = Color(0xFF8B6F1E);
+  static const Color error = Color(0xFFC04A1F);
+  static const Color info = Color(0xFF3D5A6E);
+  static const Color accent = Color(0xFF4A6B5C);
+  static const Color onAction = Color(0xFFE8E4D8);
+  static const double radiusSm = 4;
+  static const double radiusMd = 8;
+  static const double radiusLg = 12;
+  static const double radiusXl = 16;
+  static const String fontDisplay = "Fraunces";
+  static const String fontBody = "Inter";
+  static const String fontMono = "JetBrains Mono";
+}
+
+/// Back-compat alias — dark surface tokens + flat. Prefer the explicit
+/// FabledSwordDarkTokens / FabledSwordLightTokens / FabledSwordFlatTokens.
 class FabledSwordTokens {
   static const Color obsidian = Color(0xFF14171A);
   static const Color iron = Color(0xFF1E2228);

flutter_client/lib/update/client_update_provider.dart

@@ -0,0 +1,143 @@
+import 'dart:async';
+
+import 'package:dio/dio.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+import 'package:package_info_plus/package_info_plus.dart';
+
+import '../library/library_providers.dart' show dioProvider;
+import 'installer.dart';
+import 'update_info.dart';
+
+/// Tracks the bundled-server APK version vs. the installed app version.
+/// Polls /api/client/version on startup + every 24h. Returns null when
+/// no update is available (or the channel is unreachable / disabled).
+///
+/// Server returns 404 when no APK is bundled (dev environments, pre-CI
+/// images) — we treat that as "no update channel" and stay silent.
+class ClientUpdateController extends AsyncNotifier<UpdateInfo?> {
+  static const Duration _pollInterval = Duration(hours: 24);
+
+  Timer? _pollTimer;
+
+  @override
+  Future<UpdateInfo?> build() async {
+    ref.onDispose(() {
+      _pollTimer?.cancel();
+      _pollTimer = null;
+    });
+    _pollTimer ??= Timer.periodic(_pollInterval, (_) => ref.invalidateSelf());
+    return _check();
+  }
+
+  Future<UpdateInfo?> _check() async {
+    final dio = await ref.read(dioProvider.future);
+    final Response<Map<String, dynamic>> r;
+    try {
+      r = await dio.get<Map<String, dynamic>>('/api/client/version');
+    } on DioException catch (e) {
+      // 404 = no APK bundled; any other error = treat as silent.
+      if (e.response?.statusCode == 404) return null;
+      return null;
+    }
+    if (r.data == null) return null;
+
+    final info = UpdateInfo.fromJson(r.data!);
+    final installed = (await PackageInfo.fromPlatform()).version;
+    if (!isVersionNewer(info.version, installed)) return null;
+    return info;
+  }
+}
+
+/// True when `serverVersion` is strictly newer than `installedVersion`.
+///
+/// Comparison strategy: split both strings on `.`, parse each component
+/// as an int (non-numeric = 0), pad the shorter list with zeros, then
+/// compare component-wise. This handles our date-style versions
+/// (2026.05.10.1) which exceed the 3-part semver shape that
+/// `pub_semver.Version.parse` accepts, and treats "2026.05.10" as
+/// equal to "2026.05.10.0" rather than "different = newer".
+///
+/// Falls back to pub_semver as a secondary attempt when the components
+/// look semver-like (handles pre-release suffixes, build metadata, etc).
+///
+/// Exposed for testing; the polling logic in ClientUpdateController
+/// is the only production caller.
+bool isVersionNewer(String serverVersion, String installedVersion) {
+  List<int> parts(String v) => v
+      .replaceFirst(RegExp(r'^v'), '')
+      .split('.')
+      .map((p) => int.tryParse(p) ?? 0)
+      .toList();
+
+  final svr = parts(serverVersion);
+  final ins = parts(installedVersion);
+
+  // Safety net for non-numeric versions (e.g. branch-name builds like
+  // "main" vs "dev"): if neither side parsed any non-zero component,
+  // fall back to string inequality so an operator on a dev build
+  // still gets the banner instead of silently matching everything.
+  final svrAllZero = svr.every((c) => c == 0);
+  final insAllZero = ins.every((c) => c == 0);
+  if (svrAllZero && insAllZero) {
+    return serverVersion.replaceFirst(RegExp(r'^v'), '') !=
+        installedVersion.replaceFirst(RegExp(r'^v'), '');
+  }
+
+  final n = svr.length > ins.length ? svr.length : ins.length;
+  while (svr.length < n) {
+    svr.add(0);
+  }
+  while (ins.length < n) {
+    ins.add(0);
+  }
+  for (var i = 0; i < n; i++) {
+    if (svr[i] > ins[i]) return true;
+    if (svr[i] < ins[i]) return false;
+  }
+  return false;
+}
+
+final clientUpdateProvider =
+    AsyncNotifierProvider<ClientUpdateController, UpdateInfo?>(
+        ClientUpdateController.new);
+
+/// In-memory dismissed-versions set. Keyed by version string so a
+/// later release's banner re-appears even if the operator dismissed
+/// the previous one. Not persisted — restart re-shows the banner,
+/// which is acceptable nudging for v1.
+class _DismissedVersionsNotifier extends Notifier<Set<String>> {
+  @override
+  Set<String> build() => <String>{};
+
+  void add(String version) {
+    state = {...state, version};
+  }
+}
+
+final _dismissedVersionsProvider =
+    NotifierProvider<_DismissedVersionsNotifier, Set<String>>(
+        _DismissedVersionsNotifier.new);
+
+/// True when the update banner should render: an UpdateInfo is
+/// available AND the operator hasn't dismissed this specific version.
+final shouldShowUpdateBannerProvider = Provider<UpdateInfo?>((ref) {
+  final info = ref.watch(clientUpdateProvider).value;
+  if (info == null) return null;
+  final dismissed = ref.watch(_dismissedVersionsProvider);
+  if (dismissed.contains(info.version)) return null;
+  return info;
+});
+
+/// Dismiss controller: marks the given version as dismissed so the
+/// banner stops showing for this session.
+final dismissUpdateProvider = Provider<void Function(String)>((ref) {
+  return (version) =>
+      ref.read(_dismissedVersionsProvider.notifier).add(version);
+});
+
+/// Installer provider — depends on dio so the install download uses
+/// the same authenticated client (though /api/client/apk is unauthed,
+/// reusing dio keeps configuration consistent).
+final updateInstallerProvider = FutureProvider<UpdateInstaller>((ref) async {
+  return UpdateInstaller(await ref.watch(dioProvider.future));
+});

flutter_client/lib/update/installer.dart

@@ -0,0 +1,46 @@
+import 'package:dio/dio.dart';
+import 'package:flutter/services.dart';
+import 'package:path_provider/path_provider.dart';
+
+/// Bridges to MainActivity.kt's MethodChannel for the Android
+/// PackageInstaller intent (#397). Web / iOS don't support self-
+/// install; this class is Android-only at v1.
+class UpdateInstaller {
+  UpdateInstaller(this._dio);
+  final Dio _dio;
+
+  static const _channel = MethodChannel('com.fabledsword.minstrel/installer');
+  static const _filename = 'minstrel-update.apk';
+
+  /// Streams the APK from `apkUrl` into the cache directory. `onProgress`
+  /// receives 0..1 fractions; emits 1.0 once when the download completes.
+  /// Returns the local path the install intent will read from.
+  Future<String> download(
+    String apkUrl, {
+    void Function(double progress)? onProgress,
+  }) async {
+    final cacheDir = await getApplicationCacheDirectory();
+    final path = '${cacheDir.path}/$_filename';
+    await _dio.download(
+      apkUrl,
+      path,
+      onReceiveProgress: (received, total) {
+        if (total > 0 && onProgress != null) {
+          onProgress(received / total);
+        }
+      },
+    );
+    return path;
+  }
+
+  /// Hands the downloaded APK to Android's PackageInstaller via a
+  /// FileProvider content:// URI. The system shows the install confirm
+  /// dialog; user must tap Install. App restarts on the new version.
+  ///
+  /// First-ever install attempt prompts the user to flip "Install
+  /// unknown apps" for Minstrel in Settings → Apps → Special access.
+  /// One-time grant; persists across updates.
+  Future<void> install(String apkPath) async {
+    await _channel.invokeMethod('install', {'path': apkPath});
+  }
+}

flutter_client/lib/update/update_banner.dart

@@ -0,0 +1,145 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../theme/theme_extension.dart';
+import 'client_update_provider.dart';
+import 'update_info.dart';
+
+/// Soft banner mounted at the top of the shell. Renders nothing when
+/// no update is available or the user has dismissed this version's
+/// banner. Tapping Install downloads the APK and fires the system
+/// install intent (Android only).
+class UpdateBanner extends ConsumerStatefulWidget {
+  const UpdateBanner({super.key});
+
+  @override
+  ConsumerState<UpdateBanner> createState() => _UpdateBannerState();
+}
+
+enum _Stage { idle, downloading, error }
+
+class _UpdateBannerState extends ConsumerState<UpdateBanner> {
+  _Stage _stage = _Stage.idle;
+  double _progress = 0;
+  String? _error;
+
+  Future<void> _onInstall(UpdateInfo info) async {
+    setState(() {
+      _stage = _Stage.downloading;
+      _progress = 0;
+      _error = null;
+    });
+    try {
+      final installer = await ref.read(updateInstallerProvider.future);
+      final path = await installer.download(
+        info.apkUrl,
+        onProgress: (p) => setState(() => _progress = p),
+      );
+      await installer.install(path);
+      // Stage stays 'downloading' — Android system install dialog has
+      // taken over. If user cancels, the banner is still here.
+    } catch (e) {
+      if (!mounted) return;
+      setState(() {
+        _stage = _Stage.error;
+        _error = '$e';
+      });
+    }
+  }
+
+  void _onDismiss(UpdateInfo info) {
+    ref.read(dismissUpdateProvider)(info.version);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    final info = ref.watch(shouldShowUpdateBannerProvider);
+    if (info == null) return const SizedBox.shrink();
+    final fs = Theme.of(context).extension<FabledSwordTheme>()!;
+
+    return Material(
+      color: fs.iron,
+      child: SafeArea(
+        bottom: false,
+        child: Padding(
+          padding: const EdgeInsets.fromLTRB(12, 4, 4, 4),
+          child: Row(
+            crossAxisAlignment: CrossAxisAlignment.center,
+            children: [
+              Icon(Icons.system_update, color: fs.parchment, size: 16),
+              const SizedBox(width: 8),
+              Expanded(
+                child: Column(
+                  crossAxisAlignment: CrossAxisAlignment.start,
+                  mainAxisSize: MainAxisSize.min,
+                  children: [
+                    Text(
+                      _stage == _Stage.error
+                          ? 'Update failed'
+                          : 'Update Minstrel · ${info.version} available',
+                      style: TextStyle(color: fs.parchment, fontSize: 12),
+                      overflow: TextOverflow.ellipsis,
+                    ),
+                    if (_stage == _Stage.downloading) ...[
+                      const SizedBox(height: 2),
+                      LinearProgressIndicator(
+                        value: _progress > 0 ? _progress : null,
+                        minHeight: 2,
+                        backgroundColor: fs.obsidian,
+                        valueColor: AlwaysStoppedAnimation(fs.accent),
+                      ),
+                    ],
+                    if (_stage == _Stage.error && _error != null) ...[
+                      const SizedBox(height: 1),
+                      Text(
+                        _error!,
+                        style: TextStyle(color: fs.ash, fontSize: 11),
+                        maxLines: 1,
+                        overflow: TextOverflow.ellipsis,
+                      ),
+                    ],
+                  ],
+                ),
+              ),
+              if (_stage == _Stage.idle)
+                TextButton(
+                  onPressed: () => _onInstall(info),
+                  style: TextButton.styleFrom(
+                    foregroundColor: fs.accent,
+                    minimumSize: const Size(56, 28),
+                    padding: const EdgeInsets.symmetric(horizontal: 8),
+                    tapTargetSize: MaterialTapTargetSize.shrinkWrap,
+                    visualDensity: VisualDensity.compact,
+                  ),
+                  child: const Text('Install', style: TextStyle(fontSize: 13)),
+                ),
+              if (_stage == _Stage.error)
+                TextButton(
+                  onPressed: () => _onInstall(info),
+                  style: TextButton.styleFrom(
+                    foregroundColor: fs.accent,
+                    minimumSize: const Size(56, 28),
+                    padding: const EdgeInsets.symmetric(horizontal: 8),
+                    tapTargetSize: MaterialTapTargetSize.shrinkWrap,
+                    visualDensity: VisualDensity.compact,
+                  ),
+                  child: const Text('Retry', style: TextStyle(fontSize: 13)),
+                ),
+              SizedBox(
+                width: 32,
+                height: 32,
+                child: IconButton(
+                  tooltip: 'Dismiss',
+                  padding: EdgeInsets.zero,
+                  iconSize: 16,
+                  icon: Icon(Icons.close, color: fs.ash),
+                  onPressed: () => _onDismiss(info),
+                ),
+              ),
+            ],
+          ),
+        ),
+      ),
+    );
+  }
+}

flutter_client/lib/update/update_info.dart

@@ -0,0 +1,21 @@
+// Wire shape returned by GET /api/client/version. `version` is the
+// server-bundled APK version (raw — may have a "v" prefix from the
+// git tag); `apkUrl` is server-relative (e.g. "/api/client/apk").
+
+class UpdateInfo {
+  const UpdateInfo({
+    required this.version,
+    required this.apkUrl,
+    required this.sizeBytes,
+  });
+
+  final String version;
+  final String apkUrl;
+  final int sizeBytes;
+
+  factory UpdateInfo.fromJson(Map<String, dynamic> j) => UpdateInfo(
+        version: (j['version'] as String?) ?? '',
+        apkUrl: (j['apk_url'] as String?) ?? '/api/client/apk',
+        sizeBytes: (j['size_bytes'] as num?)?.toInt() ?? 0,
+      );
+}

flutter_client/pubspec.lock

@@ -73,6 +73,78 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.2"
+  build:
+    dependency: transitive
+    description:
+      name: build
+      sha256: a156715e7cd728130c592f30552575908aae5b100005fbc1f0fb16b3c03a3d10
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.0.6"
+  build_config:
+    dependency: transitive
+    description:
+      name: build_config
+      sha256: "4070d2a59f8eec34c97c86ceb44403834899075f66e8a9d59706f8e7834f6f71"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.0"
+  build_daemon:
+    dependency: transitive
+    description:
+      name: build_daemon
+      sha256: bf05f6e12cfea92d3c09308d7bcdab1906cd8a179b023269eed00c071004b957
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.1"
+  build_runner:
+    dependency: "direct dev"
+    description:
+      name: build_runner
+      sha256: "1523ce62448ebac2c15a8ba5fbad8acac169788658a7dd2a1c2d9c2a9318b9a6"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.15.0"
+  built_collection:
+    dependency: transitive
+    description:
+      name: built_collection
+      sha256: "376e3dd27b51ea877c28d525560790aee2e6fbb5f20e2f85d5081027d94e2100"
+      url: "https://pub.dev"
+    source: hosted
+    version: "5.1.1"
+  built_value:
+    dependency: transitive
+    description:
+      name: built_value
+      sha256: "34e4067d30ce212937df995f03b69992eea683539ceeac7f679a1f1eba055b56"
+      url: "https://pub.dev"
+    source: hosted
+    version: "8.12.6"
+  cached_network_image:
+    dependency: "direct main"
+    description:
+      name: cached_network_image
+      sha256: "7c1183e361e5c8b0a0f21a28401eecdbde252441106a9816400dd4c2b2424916"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.4.1"
+  cached_network_image_platform_interface:
+    dependency: transitive
+    description:
+      name: cached_network_image_platform_interface
+      sha256: "35814b016e37fbdc91f7ae18c8caf49ba5c88501813f73ce8a07027a395e2829"
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.1"
+  cached_network_image_web:
+    dependency: transitive
+    description:
+      name: cached_network_image_web
+      sha256: "980842f4e8e2535b8dbd3d5ca0b1f0ba66bf61d14cc3a17a9b4788a3685ba062"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.3.1"
   characters:
     dependency: transitive
     description:
@@ -81,6 +153,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.4.1"
+  charcode:
+    dependency: transitive
+    description:
+      name: charcode
+      sha256: fb0f1107cac15a5ea6ef0a6ef71a807b9e4267c713bb93e00e92d737cc8dbd8a
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.4.0"
+  checked_yaml:
+    dependency: transitive
+    description:
+      name: checked_yaml
+      sha256: "959525d3162f249993882720d52b7e0c833978df229be20702b33d48d91de70f"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.0.4"
   cli_config:
     dependency: transitive
     description:
@@ -89,6 +177,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.2.0"
+  cli_util:
+    dependency: transitive
+    description:
+      name: cli_util
+      sha256: ff6785f7e9e3c38ac98b2fb035701789de90154024a75b6cb926445e83197d1c
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.4.2"
   clock:
     dependency: transitive
     description:
@@ -113,6 +209,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.19.1"
+  connectivity_plus:
+    dependency: "direct main"
+    description:
+      name: connectivity_plus
+      sha256: b5e72753cf63becce2c61fd04dfe0f1c430cc5278b53a1342dc5ad839eab29ec
+      url: "https://pub.dev"
+    source: hosted
+    version: "6.1.5"
+  connectivity_plus_platform_interface:
+    dependency: transitive
+    description:
+      name: connectivity_plus_platform_interface
+      sha256: "3c09627c536d22fd24691a905cdd8b14520de69da52c7a97499c8be5284a32ed"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.0"
   convert:
     dependency: transitive
     description:
@@ -145,6 +257,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.0.9"
+  dart_style:
+    dependency: transitive
+    description:
+      name: dart_style
+      sha256: "29f7ecc274a86d32920b1d9cfc7502fa87220da41ec60b55f329559d5732e2b2"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.1.7"
+  dbus:
+    dependency: transitive
+    description:
+      name: dbus
+      sha256: d0c98dcd4f5169878b6cf8f6e0a52403a9dff371a3e2f019697accbf6f44a270
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.7.12"
   dio:
     dependency: "direct main"
     description:
@@ -161,6 +289,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.2"
+  drift:
+    dependency: "direct main"
+    description:
+      name: drift
+      sha256: "970cd188fddb111b26ea6a9b07a62bf5c2432d74147b8122c67044ae3b97e99e"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.31.0"
+  drift_dev:
+    dependency: "direct dev"
+    description:
+      name: drift_dev
+      sha256: "917184b2fb867b70a548a83bf0d36268423b38d39968c06cce4905683da49587"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.31.0"
+  drift_flutter:
+    dependency: "direct main"
+    description:
+      name: drift_flutter
+      sha256: c07120854742a0cae2f7501a0da02493addde550db6641d284983c08762e60a7
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.2.8"
   fake_async:
     dependency: transitive
     description:
@@ -199,7 +351,7 @@ packages:
     source: sdk
     version: "0.0.0"
   flutter_cache_manager:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: flutter_cache_manager
       sha256: "400b6592f16a4409a7f2bb929a9a7e38c72cceb8ffb99ee57bbf2cb2cecf8386"
@@ -283,6 +435,14 @@ packages:
     description: flutter
     source: sdk
     version: "0.0.0"
+  flutter_timezone:
+    dependency: "direct main"
+    description:
+      name: flutter_timezone
+      sha256: "13b2109ad75651faced4831bf262e32559e44aa549426eab8a597610d385d934"
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.1"
   flutter_web_plugins:
     dependency: transitive
     description: flutter
@@ -320,6 +480,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "8.1.0"
+  graphs:
+    dependency: transitive
+    description:
+      name: graphs
+      sha256: "741bbf84165310a68ff28fe9e727332eef1407342fca52759cb21ad8177bb8d0"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.3.2"
   hooks:
     dependency: transitive
     description:
@@ -384,6 +552,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.6.7"
+  json_annotation:
+    dependency: transitive
+    description:
+      name: json_annotation
+      sha256: cb09e7dac6210041fad964ed7fbee004f14258b4eca4040f72d1234062ace4c8
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.11.0"
   just_audio:
     dependency: "direct main"
     description:
@@ -496,6 +672,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.17.6"
+  nm:
+    dependency: transitive
+    description:
+      name: nm
+      sha256: "2c9aae4127bdc8993206464fcc063611e0e36e72018696cd9631023a31b24254"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.5.0"
   node_preamble:
     dependency: transitive
     description:
@@ -512,6 +696,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "9.3.0"
+  octo_image:
+    dependency: transitive
+    description:
+      name: octo_image
+      sha256: "34faa6639a78c7e3cbe79be6f9f96535867e879748ade7d17c9b1ae7536293bd"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.0"
   package_config:
     dependency: transitive
     description:
@@ -536,6 +728,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "3.2.1"
+  palette_generator:
+    dependency: "direct main"
+    description:
+      name: palette_generator
+      sha256: "4420f7ccc3f0a4a906144e73f8b6267cd940b64f57a7262e95cb8cec3a8ae0ed"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.3.3+7"
   path:
     dependency: transitive
     description:
@@ -553,7 +753,7 @@ packages:
     source: hosted
     version: "1.1.0"
   path_provider:
-    dependency: transitive
+    dependency: "direct main"
     description:
       name: path_provider
       sha256: "50c5dd5b6e1aaf6fb3a78b33f6aa3afca52bf903a8a5298f53101fdaee55bbcd"
@@ -640,6 +840,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.2.0"
+  pubspec_parse:
+    dependency: transitive
+    description:
+      name: pubspec_parse
+      sha256: "0560ba233314abbed0a48a2956f7f022cce7c3e1e73df540277da7544cad4082"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.5.0"
+  recase:
+    dependency: transitive
+    description:
+      name: recase
+      sha256: e4eb4ec2dcdee52dcf99cb4ceabaffc631d7424ee55e56f280bc039737f89213
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.0"
   record_use:
     dependency: transitive
     description:
@@ -701,6 +917,14 @@ packages:
     description: flutter
     source: sdk
     version: "0.0.0"
+  source_gen:
+    dependency: transitive
+    description:
+      name: source_gen
+      sha256: ec37cc0e6694374cbef59ed79685572c870a54ede6fa30a3e420feb3adffea02
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.2.3"
   source_map_stack_trace:
     dependency: transitive
     description:
@@ -765,6 +989,30 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.4.0"
+  sqlite3:
+    dependency: transitive
+    description:
+      name: sqlite3
+      sha256: "3145bd74dcdb4fd6f5c6dda4d4e4490a8087d7f286a14dee5d37087290f0f8a2"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.9.4"
+  sqlite3_flutter_libs:
+    dependency: "direct main"
+    description:
+      name: sqlite3_flutter_libs
+      sha256: eeb9e3a45207649076b808f8a5a74d68770d0b7f26ccef6d5f43106eee5375ad
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.5.42"
+  sqlparser:
+    dependency: transitive
+    description:
+      name: sqlparser
+      sha256: "337e9997f7141ffdd054259128553c348635fa318f7ca492f07a4ab76f850d19"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.43.1"
   stack_trace:
     dependency: transitive
     description:
@@ -789,6 +1037,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "2.1.4"
+  stream_transform:
+    dependency: transitive
+    description:
+      name: stream_transform
+      sha256: ad47125e588cfd37a9a7f86c7d6356dde8dfe89d071d293f80ca9e9273a33871
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.1"
   string_scanner:
     dependency: transitive
     description:

flutter_client/pubspec.yaml

@@ -1,7 +1,7 @@
 name: minstrel
 description: Minstrel mobile client
 publish_to: 'none'
-version: 0.1.0+1
+version: 2026.5.15+7
 
 environment:
   sdk: '>=3.5.0 <4.0.0'
@@ -23,12 +23,34 @@ dependencies:
   package_info_plus: ^8.3.1
   pub_semver: ^2.1.4
   cupertino_icons: ^1.0.8
+  path_provider: ^2.1.5
+  drift: ^2.18.0
+  drift_flutter: ^0.2.0
+  sqlite3_flutter_libs: ^0.5.24
+  connectivity_plus: ^6.0.5
+  flutter_timezone: ^4.1.1
+  palette_generator: ^0.3.3
+  # Disk-persistent image cache. Image.network only caches in memory, so
+  # cover art repainted after a scroll-off or app restart re-fetches from
+  # the server. cached_network_image stores the bytes under
+  # path_provider's temp dir keyed by URL, surviving both. Used directly
+  # by ServerImage (auth-aware path) and as CachedNetworkImageProvider
+  # for the mini bar (which composes its own Image widget).
+  cached_network_image: ^3.4.1
+  # flutter_cache_manager is the disk-cache layer cached_network_image
+  # sits on top of. SyncController uses DefaultCacheManager directly to
+  # pre-warm covers during metadata sync, so a cold-start home grid
+  # paints from disk on the very first scroll rather than firing a
+  # network round-trip per tile.
+  flutter_cache_manager: ^3.4.1
 
 dev_dependencies:
   flutter_test:
     sdk: flutter
   flutter_lints: ^6.0.0
   mocktail: ^1.0.4
+  drift_dev: ^2.18.0
+  build_runner: ^2.4.13
 
 flutter:
   uses-material-design: true

flutter_client/test/cache/adapters_test.dart

@@ -0,0 +1,70 @@
+import 'package:flutter_test/flutter_test.dart';
+
+import 'package:minstrel/cache/adapters.dart';
+import 'package:minstrel/models/album.dart';
+import 'package:minstrel/models/artist.dart';
+import 'package:minstrel/models/playlist.dart';
+import 'package:minstrel/models/track.dart';
+
+void main() {
+  test('ArtistRef.toDrift preserves id + name + sortName', () {
+    const ref = ArtistRef(id: 'a1', name: 'Boards of Canada', sortName: 'Boards of Canada');
+    final companion = ref.toDrift();
+    expect(companion.id.value, 'a1');
+    expect(companion.name.value, 'Boards of Canada');
+    expect(companion.sortName.value, 'Boards of Canada');
+  });
+
+  test('ArtistRef.toDrift falls back to name when sortName is empty', () {
+    const ref = ArtistRef(id: 'a1', name: 'The Album Leaf');
+    final companion = ref.toDrift();
+    expect(companion.sortName.value, 'The Album Leaf');
+  });
+
+  test('AlbumRef.toDrift preserves id + title + artistId', () {
+    const ref = AlbumRef(id: 'al1', title: 'Geogaddi', artistId: 'ar1');
+    final companion = ref.toDrift();
+    expect(companion.id.value, 'al1');
+    expect(companion.title.value, 'Geogaddi');
+    expect(companion.artistId.value, 'ar1');
+  });
+
+  test('TrackRef.toDrift converts seconds to ms + preserves track/disc', () {
+    const ref = TrackRef(
+      id: 't1',
+      title: 'Roygbiv',
+      albumId: 'al1',
+      artistId: 'ar1',
+      durationSec: 137,
+      trackNumber: 4,
+      discNumber: 1,
+    );
+    final companion = ref.toDrift();
+    expect(companion.id.value, 't1');
+    expect(companion.durationMs.value, 137 * 1000);
+    expect(companion.trackNumber.value, 4);
+    expect(companion.discNumber.value, 1);
+  });
+
+  test('Playlist.toDrift preserves id + userId + name', () {
+    const p = Playlist(
+      id: 'p1',
+      userId: 'u1',
+      name: 'My Mix',
+      description: 'a great mix',
+      isPublic: true,
+      systemVariant: null,
+      trackCount: 12,
+      coverUrl: '',
+      ownerUsername: 'alice',
+      createdAt: '',
+      updatedAt: '',
+    );
+    final companion = p.toDrift();
+    expect(companion.id.value, 'p1');
+    expect(companion.userId.value, 'u1');
+    expect(companion.name.value, 'My Mix');
+    expect(companion.isPublic.value, true);
+    expect(companion.trackCount.value, 12);
+  });
+}