diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..61f82b06
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - name: Set up Android SDK
+        uses: android-actions/setup-android@v3
+        with:
+          packages: >
+            tools
+            platform-tools
+            platforms;android-36
+            build-tools;36.0.0
+
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Build Android + desktop + unit tests
+        run: |
+          chmod +x ./gradlew
+          ./gradlew --no-daemon --stacktrace \
+            :core:compileKotlinJvm \
+            :core:jvmTest \
+            :components:compileKotlinJvm \
+            :desktop:compileKotlin \
+            :app:assembleDebug
diff --git a/.gitignore b/.gitignore
index c2edbf4f..ee1b2912 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,13 +8,18 @@
 /.idea/navEditor.xml
 /.idea/assetWizardSettings.xml
 .DS_Store
+build/
 /build
 /captures
 .externalNativeBuild
 .cxx
 local.properties
+.kotlin/
 
 # Signing (never commit secrets or keystores)
 keystore.properties
 *.jks
 *.keystore
+.aider*
+
+hs_err_pid*.log
\ No newline at end of file
diff --git a/.idea/.gitignore b/.idea/.gitignore
index 26d33521..55529824 100644
--- a/.idea/.gitignore
+++ b/.idea/.gitignore
@@ -1,3 +1,5 @@
 # Default ignored files
 /shelf/
 /workspace.xml
+/discord.xml
+/planningMode.xml
\ No newline at end of file
diff --git a/.idea/artifacts/components.xml b/.idea/artifacts/components.xml
new file mode 100644
index 00000000..1da95811
--- /dev/null
+++ b/.idea/artifacts/components.xml
@@ -0,0 +1,8 @@
+<component name="ArtifactManager">
+  <artifact type="jar" name="components">
+    <output-path>$PROJECT_DIR$/components/build/libs</output-path>
+    <root id="archive" name="components.jar">
+      <element id="module-output" name="Yuri_Player.components.androidMain" />
+    </root>
+  </artifact>
+</component>
\ No newline at end of file
diff --git a/.idea/artifacts/components_jvm.xml b/.idea/artifacts/components_jvm.xml
new file mode 100644
index 00000000..e9b6a24c
--- /dev/null
+++ b/.idea/artifacts/components_jvm.xml
@@ -0,0 +1,8 @@
+<component name="ArtifactManager">
+  <artifact type="jar" name="components-jvm">
+    <output-path>$PROJECT_DIR$/components/build/libs</output-path>
+    <root id="archive" name="components-jvm.jar">
+      <element id="module-output" name="Yuri_Player.components.jvmMain" />
+    </root>
+  </artifact>
+</component>
\ No newline at end of file
diff --git a/.idea/artifacts/core.xml b/.idea/artifacts/core.xml
new file mode 100644
index 00000000..c3439a25
--- /dev/null
+++ b/.idea/artifacts/core.xml
@@ -0,0 +1,8 @@
+<component name="ArtifactManager">
+  <artifact type="jar" name="core">
+    <output-path>$PROJECT_DIR$/core/build/libs</output-path>
+    <root id="archive" name="core.jar">
+      <element id="module-output" name="Yuri_Player.core.androidMain" />
+    </root>
+  </artifact>
+</component>
\ No newline at end of file
diff --git a/.idea/artifacts/core_jvm.xml b/.idea/artifacts/core_jvm.xml
new file mode 100644
index 00000000..c006f3c8
--- /dev/null
+++ b/.idea/artifacts/core_jvm.xml
@@ -0,0 +1,8 @@
+<component name="ArtifactManager">
+  <artifact type="jar" name="core-jvm">
+    <output-path>$PROJECT_DIR$/core/build/libs</output-path>
+    <root id="archive" name="core-jvm.jar">
+      <element id="module-output" name="Yuri_Player.core.jvmMain" />
+    </root>
+  </artifact>
+</component>
\ No newline at end of file
diff --git a/.idea/artifacts/mediasession_jvm.xml b/.idea/artifacts/mediasession_jvm.xml
new file mode 100644
index 00000000..779652f2
--- /dev/null
+++ b/.idea/artifacts/mediasession_jvm.xml
@@ -0,0 +1,8 @@
+<component name="ArtifactManager">
+  <artifact type="jar" name="mediasession-jvm">
+    <output-path>$PROJECT_DIR$/mediasession/build/libs</output-path>
+    <root id="archive" name="mediasession-jvm.jar">
+      <element id="module-output" name="Yuri_Player.mediasession.jvmMain" />
+    </root>
+  </artifact>
+</component>
\ No newline at end of file
diff --git a/.idea/compiler.xml b/.idea/compiler.xml
index bcf4711e..b589d56e 100644
--- a/.idea/compiler.xml
+++ b/.idea/compiler.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="CompilerConfiguration">
-    <bytecodeTargetLevel target="25" />
+    <bytecodeTargetLevel target="17" />
   </component>
 </project>
\ No newline at end of file
diff --git a/.idea/gradle.xml b/.idea/gradle.xml
index 02c4aa5e..e3ada731 100644
--- a/.idea/gradle.xml
+++ b/.idea/gradle.xml
@@ -10,6 +10,10 @@
           <set>
             <option value="$PROJECT_DIR$" />
             <option value="$PROJECT_DIR$/app" />
+            <option value="$PROJECT_DIR$/components" />
+            <option value="$PROJECT_DIR$/core" />
+            <option value="$PROJECT_DIR$/desktop" />
+            <option value="$PROJECT_DIR$/mediasession" />
           </set>
         </option>
       </GradleProjectSettings>
diff --git a/.idea/inspectionProfiles/Project_Default.xml b/.idea/inspectionProfiles/Project_Default.xml
index bd7dede3..157f4bf3 100644
--- a/.idea/inspectionProfiles/Project_Default.xml
+++ b/.idea/inspectionProfiles/Project_Default.xml
@@ -25,6 +25,12 @@
     <inspection_tool class="GlancePreviewNotSupportedInUnitTestFiles" enabled="true" level="ERROR" enabled_by_default="true">
       <option name="composableFile" value="true" />
     </inspection_tool>
+    <inspection_tool class="MultiplatformPreviewAnnotationInFunctionWithParameters" enabled="true" level="ERROR" enabled_by_default="true">
+      <option name="composableFile" value="true" />
+    </inspection_tool>
+    <inspection_tool class="MultiplatformPreviewMultipleParameterProviders" enabled="true" level="ERROR" enabled_by_default="true">
+      <option name="composableFile" value="true" />
+    </inspection_tool>
     <inspection_tool class="PreviewAnnotationInFunctionWithParameters" enabled="true" level="ERROR" enabled_by_default="true">
       <option name="composableFile" value="true" />
     </inspection_tool>
@@ -46,6 +52,5 @@
     <inspection_tool class="PreviewPickerAnnotation" enabled="true" level="ERROR" enabled_by_default="true">
       <option name="composableFile" value="true" />
     </inspection_tool>
-    <inspection_tool class="UsePropertyAccessSyntax" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
   </profile>
 </component>
\ No newline at end of file
diff --git a/.idea/kotlinc.xml b/.idea/kotlinc.xml
new file mode 100644
index 00000000..2e4da65a
--- /dev/null
+++ b/.idea/kotlinc.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="KotlinJpsPluginSettings">
+    <option name="externalSystemId" value="Gradle" />
+    <option name="version" value="2.3.21" />
+  </component>
+</project>
\ No newline at end of file
diff --git a/.idea/misc.xml b/.idea/misc.xml
index 29a5cc0c..ca6c843f 100644
--- a/.idea/misc.xml
+++ b/.idea/misc.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="ExternalStorageConfigurationManager" enabled="true" />
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_25" default="true" project-jdk-name="jbr-25" project-jdk-type="JavaSDK">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_17" project-jdk-name="jbr-25" project-jdk-type="JavaSDK">
     <output url="file://$PROJECT_DIR$/build/classes" />
   </component>
   <component name="ProjectType">
diff --git a/.idea/runConfigurations/YuriPlayer__buildFfmpeg_.xml b/.idea/runConfigurations/Build_ffmpeg.xml
similarity index 91%
rename from .idea/runConfigurations/YuriPlayer__buildFfmpeg_.xml
rename to .idea/runConfigurations/Build_ffmpeg.xml
index 3203d0b0..217d185c 100644
--- a/.idea/runConfigurations/YuriPlayer__buildFfmpeg_.xml
+++ b/.idea/runConfigurations/Build_ffmpeg.xml
@@ -1,5 +1,5 @@
 <component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="YuriPlayer [buildFfmpeg]" type="GradleRunConfiguration" factoryName="Gradle">
+  <configuration default="false" name="Build ffmpeg" type="GradleRunConfiguration" factoryName="Gradle">
     <ExternalSystemSettings>
       <option name="env">
         <map>
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..e71d2df0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,224 @@
+# AGENTS.md — Yuri Player
+
+Guidance for AI coding agents (and humans) working in this repository.
+
+## Project
+
+**Yuri Player** — a free, open-source (AGPL-3.0) music player built with
+**Jetpack Compose / Compose Multiplatform**. Targets: **Android** (shipping),
+**desktop** (shipping), **iOS** (planned, Darwin targets stubbed). Sources:
+local files, **Jellyfin**, and **Subsonic**/**Navidrome**.
+
+- Package base: `capital.yuri.yuriplayer`
+- Application id: `capital.yuri.yuriplayer`
+- Repo: `https://github.com/LizAinslie/yuriplayer`
+- License: [AGPL-3.0](LICENSE)
+
+## Module Layout
+
+| Module | Type | Responsibility |
+| --- | --- | --- |
+| `:core` | Kotlin Multiplatform (`commonMain`/`androidMain`/`jvmMain`) | Platform-agnostic domain: `PlaybackEngine` SPI, `PlayerSession` queue host, `Track` model, `OsMediaControls` SPI, path conventions, logging DSL. |
+| `:components` | Kotlin Multiplatform (Compose) | Shared Compose UI: cover art, album/artist pages, player bar, now-playing sidebar, context menus, theme. |
+| `:app` | Android application | Android client: activities, services, Koin DI, Room DB, Media3 + LibVLC engines, Jellyfin/Subsonic clients, metadata enrichment. |
+| `:desktop` | Compose Desktop (JVM) | Desktop client (Material 3). LibVLC via vlcj. Manual DI (no Koin). OS media-key/now-playing integrations. |
+| `:mediasession` | Kotlin Multiplatform (JVM target) | **Vendored fork** of `dev.toastbits:mediasession` (0.1.1): Linux MPRIS + Windows SMTC, with upstream bugs fixed (see MPRIS section). |
+
+### Source-set conventions
+
+- `commonMain` — shared logic/UI, no platform APIs. Use `expect`/`actual` for
+  anything platform-specific.
+- `androidMain` / `jvmMain` — platform `actual`s.
+- `:core` compiles to `android` (minSdk 27, compileSdk 37) and `jvm`
+  (JVM 11 target). `:components` mirrors this.
+- Android app code lives in `app/src/main/java/...` (not `kotlin/`).
+
+## Build
+
+Toolchain: **Kotlin 2.3.21**, **AGP 9.3.1**, **Compose Multiplatform 1.8.2**,
+Gradle with **configuration cache enabled** (`org.gradle.configuration-cache=true`).
+
+Common commands:
+
+```bash
+./gradlew :app:assembleDebug                 # build Android APK
+./gradlew :desktop:run                       # run desktop app
+./gradlew :desktop:packageDeb                # Linux .deb (Depends: vlc)
+./gradlew :desktop:packageRpm
+./gradlew :desktop:packageDistributionForCurrentOS
+./gradlew :core:jvmTest :components:jvmTest  # shared unit tests
+./gradlew :core:compileKotlinJvm :desktop:compileKotlin
+```
+
+### Configuration-cache rules
+
+CC is on, so **build scripts must be configuration-cache compatible**:
+
+- No bare `ProcessBuilder`/`exec` at configuration time. Use a Gradle
+  `ValueSource` with injected `ExecOperations` (see `GitCommandValueSource` in
+  `app/build.gradle.kts`).
+- Git metadata (commit, branch, tag, dirty) is read via `ValueSource` and
+  injected as `BuildConfig` fields, not via `System.getProperty`.
+
+## Architecture
+
+### Playback: engines vs. session
+
+- **`PlaybackEngine`** (`:core` `commonMain`) is the *audio backend only* — a
+  small SPI: `load/play/pause/stop/seekTo`, position/duration, volume, listener
+  callbacks. It does **not** own queue/identity.
+  - Android impls: `Media3PlaybackEngine`, `VlcPlaybackEngine`
+    (`app/.../player/engine/`), selected at runtime by `PlaybackEngineFactory`
+    (Settings → `PlaybackEngineId.MEDIA3|VLC|FFMPEG`). `FFMPEG` is reserved,
+    not wired.
+  - Desktop impl: `VlcjPlaybackEngine` (`:desktop`), LibVLC via vlcj.
+- **`PlayerSession`** (`:core` `commonMain`) is the *host-side* queue + now-playing.
+  Hot lane (user "add to queue") + cold lane (album/playlist/search context),
+  shuffle, repeat, history, volume. Engines only produce sound; the session
+  owns identity.
+
+Android wraps the session in `player/MusicService.kt` (foreground service,
+Media3 session/MediaStyle notification) plus `QueueManager`, `PlayerController`,
+`PlaybackStateStore`, `PlaybackHistoryStore`.
+
+### OS media integration
+
+- **`OsMediaControls`** SPI (`:core` `commonMain/os/OsMediaControls.kt`) abstracts
+  system "now playing" + media keys: `attach/update/release` + `Callbacks`.
+- Desktop impls (`:desktop` `os/`), selected by `createOsMediaControls()`:
+  - `MediasessionControls` — Linux MPRIS + Windows SMTC via
+    `dev.toastbits:mediasession` (wraps dbus-java internally, so no raw
+    `Variant` marshalling in-app).
+  - `mac/MacNowPlayingControls` — macOS Now Playing + media keys (JNA stubs);
+    the library returns `null` on macOS so this stays.
+  - `win/WindowsSmtcControls` — legacy media-keys impl (`RegisterHotKey`), now
+    superseded by `MediasessionControls` and left unused.
+  - `linux/MprisMediaControls` — the old hand-rolled dbus-java MPRIS impl, now
+    fully commented out and superseded by `MediasessionControls`.
+
+### Dependency injection
+
+- **Android** uses **Koin** (`app/di/AppModule.kt`, `koin-android`,
+  `koin-androidx-compose`). All repositories, clients, stores, and the DB are
+  wired there.
+- **Desktop** uses **manual constructor injection** — `DesktopSession` is built
+  with `remember { DesktopSession() }` in `desktop/Main.kt` and wires its own
+  stores/engines. No Koin on the JVM/desktop side.
+
+### Data layer (Android)
+
+- **Room** for persistence (`YuriDatabase`; KSP compiler). Schema dir is
+  `app/schemas/`. See the `room { schemaDirectory(...) }` block.
+- **Library sources** are behind `LibrarySource` / `LibrarySourceFactory` /
+  `LibrarySourceRegistry` (`app/.../data/source/`): `LocalLibrarySource`,
+  `JellyfinClient`, `SubsonicClient`, plus artist-image/metadata providers
+  (MusicBrainz, Discogs, Deezer, AudioDB, Bandsintown, Wikipedia, Wikidata).
+- **Metadata enrichment / tag editing** via jaudiotagger (`TagWriter.kt`,
+  `MetadataEditService`, `TagWritability`).
+- **FFmpeg** is bundled per-ABI (arm64-v8a, armeabi-v7a, x86_64) under
+  `app/src/main/assets/ffmpeg/`, built by `native/ffmpeg/build.sh` (NDK
+  cross-compile, wired to the `buildFfmpeg` Gradle task).
+
+### UI / Compose
+
+- Shared UI lives in `:components` under `components/` (album, artist, art,
+  dialog, layout, list, menu, model, player, settings, theme).
+- **Context menus** use the `buildContextMenu { }` DSL (`components/menu/MenuDsl.kt`)
+  with `item/submenu/divider`. Submenu hover uses a **prediction cone**
+  (`components/menu/PredictionCone.kt`) — the Amazon/macOS triangle heuristic so
+  the pointer can travel diagonally into an open submenu without losing the
+  highlighted parent.
+- Desktop theming/dark-mode uses `components/theme` + a manual `Choice` model
+  (system/light/dark); window background is set from `session.theme.choice`.
+
+## Conventions
+
+### Logging
+
+Use the `yuriLog` DSL (`:core` `commonMain/log/YuriLog.kt`). **Never** `println`
+or `Log.d` directly.
+
+```kotlin
+val log = yuriLog("Vlcj")          // short tag; platforms prefix "YuriPlayer."
+log.i { "play ${redactSecrets(mrl)}" }
+log.e(t) { "stream failed" }
+```
+
+- Tags are short (`Vlcj`, `Queue`, `Index`, `Mpris`). The `YuriPlayer.` prefix
+  is normalized away, so `yuriLog("YuriPlayer.Radio")` == `yuriLog("Radio")`.
+- Desktop → SLF4J/Logback, Android → logcat, Darwin → `os_log` (later).
+- **Always** wrap URLs/tokens in `redactSecrets(...)` before logging — it strips
+  query secrets (`t`, `s`, `api_key`, `access_token`, `password`, …) and
+  `Authorization:` headers.
+
+### `expect`/`actual` helpers (already provided)
+
+- `appDirectories(): AppDirectories` — OS-conventional config/cache/data dirs +
+  default music roots.
+- `hostOs(): HostOs` — `ANDROID | LINUX | MACOS | WINDOWS | UNKNOWN`.
+- `platformLog` / `platformLogEnabled` — logging backend.
+
+## Testing
+
+- **Unit tests:** `:core` and `:components` have `jvmTest` source sets
+  (`kotlin("test")`). Android has `test`/`androidTest` (Robolectric + Espresso +
+  Compose UI tests).
+- **Maestro** E2E flows live in `maestro/` (`smoke.yaml`, `skip.yaml`,
+  `engine-vlc.yaml`, `engine-media3.yaml`). They target test ids
+  (`tab_my_stuff`, `mini_player`, `np_skip_next`, `settings_playback_engine`, …)
+  and are **on-device smoke tests** that keep user library/logins
+  (`clearState: false`).
+- **CI** (`.github/workflows/ci.yml`): JDK 21 + Android SDK 37, runs
+  `:core:jvmTest`, `:core:compileKotlinJvm`, `:components:compileKotlinJvm`,
+  `:desktop:compileKotlin`, `:app:assembleDebug`.
+
+## Platform notes & gotchas
+
+### LibVLC (desktop)
+
+- `:desktop` bundles LibVLC for **Windows/macOS** installers; **Linux** `.deb`/
+  `.rpm` **depend on the distro `vlc`** package instead (see
+  `desktop/libvlc/README.md` and the `downloadLibVlc` / `copyLibVlcResources`
+  tasks in `desktop/build.gradle.kts`).
+- `VlcjPlaybackEngine.FACTORY_ARGS` passes `--no-http-h2` because **VLC's h2
+  stack breaks HTTPS streams** (Navidrome/Jellyfin) with "peer stream 1 error:
+  Protocol error". If a distro's older `vlc` rejects `--no-http-h2` ("unknown
+  option"), the bundled LibVLC version must be raised to match, or the flag
+  made conditional on the runtime VLC version.
+
+### MPRIS / dbus-java (Linux)
+
+- Linux MPRIS and Windows SMTC are handled by **`dev.toastbits:mediasession`**
+  (`MediasessionControls`). It wraps dbus-java internally, so the old
+  `Variant(...)` collection-type foot-gun (`Collections$SingletonList`,
+  `ArrayList`) is not something app code touches anymore.
+- The library only ships a JVM artifact (`mediasession-jvm`); it returns `null`
+  on macOS and has no Android target. Its dbus-java transitive deps are on the
+  **runtime** classpath, so `:desktop` must not import `org.freedesktop.dbus.*`
+  directly.
+- `linux/MprisMediaControls.kt` is the retired hand-rolled MPRIS impl
+  (commented out) kept only for reference.
+- Known quirk: the library names its `Seek`/`SetPosition` callback params in
+  milliseconds (`by_ms`/`to_ms`) but does not convert the incoming MPRIS
+  microsecond offsets — treat seek offsets as ms for now.
+
+### Android storage permissions
+
+- The manifest uses `READ_MEDIA_AUDIO`, `READ/WRITE_EXTERNAL_STORAGE` (≤32),
+  and `MANAGE_EXTERNAL_STORAGE` (30+) — justified for scanning the user's music
+  and **rewriting embedded tags** (title/artist/cover) in-place under `Music/`.
+  Keep those `tools:ignore="ScopedStorage"` justifications if you touch them.
+
+### Signing / secrets
+
+- `keystore.properties`, `*.jks`, `*.keystore` are git-ignored. Release signing
+  only activates when `keystore.properties` exists. Never commit secrets.
+
+## Style
+
+- Kotlin official code style (`kotlin.code.style=official`), 4-space indent.
+- Package structure mirrors feature area, not layer (e.g. `player/`,
+  `data/source/`, `components/menu/`).
+- Prefer `data class` + `StateFlow` for observable UI state; `expect`/`actual`
+  for platform seams; short, focused files with KDoc on non-obvious types
+  (especially the SPI boundaries in `:core`).
diff --git a/README.md b/README.md
index 5336f376..5355dff7 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,48 @@
 # Yuri Player (New Name SoonTM)
- A multi-platform (soon) Jetpack Compose music player for Android, iOS, and
- desktop. Supports libraries from your device, Jellyfin and (open)subsonic
- servers.
 
-## Screenshots:
+A multi-platform Jetpack Compose music player for Android and desktop
+(iOS later). Libraries from this device, Jellyfin, and (open)Subsonic.
+
+## Layout
+
+| Module | What |
+| --- | --- |
+| `:core` | Kotlin Multiplatform. Playback engine SPI, queue host, OS path conventions, local library scan (JVM). |
+| `:components` | Shared Compose Multiplatform UI: cover art, album page (phone/tablet/desktop), player bar, now-playing sidebar. |
+| `:app` | Android client. |
+| `:desktop` | Compose Desktop client (Material 3). LibVLC via vlcj. Spotify-style shell: album grid, right now-playing/queue/history, bottom transport. |
+
+## Desktop
+
+## Desktop
+
+Windows and macOS installers **bundle LibVLC**. Linux `.deb` / `.rpm` **depend on
+distro `vlc`** (system plugins, PipeWire/Pulse, updates). Details:
+[desktop/libvlc/README.md](desktop/libvlc/README.md).
+
+```bash
+./gradlew :desktop:run
+./gradlew :desktop:packageDeb          # Linux, Requires/Depends: vlc
+./gradlew :desktop:packageRpm
+./gradlew :desktop:packageDistributionForCurrentOS
+```
+
+Default music folders (scanned on start):
+
+- **Linux** — `$XDG_MUSIC_DIR` or `~/Music` (XDG config/cache/data for app files)
+- **macOS** — `~/Music` (app files under `~/Library/Application Support/YuriPlayer` and `~/Library/Caches/YuriPlayer`)
+- **Windows** — `%USERPROFILE%\Music` (app files under `%APPDATA%\YuriPlayer` and `%LOCALAPPDATA%\YuriPlayer`)
+
+Playback control:
+
+- **Linux** — MPRIS (`playerctl -p yuriplayer play-pause`)
+- **Windows** — media keys (`VK_MEDIA_*`)
+- **macOS** — Now Playing hook (media keys when accessibility allows)
+
+## Screenshots
+
 todo :P
- 
+
 ## License
-Licensed under the [AGPLv3](LICENSE). 
\ No newline at end of file
+
+Licensed under the [AGPLv3](LICENSE).
diff --git a/app/build.gradle.kts b/app/build.gradle.kts
index 467175bf..9374a913 100644
--- a/app/build.gradle.kts
+++ b/app/build.gradle.kts
@@ -11,6 +11,7 @@ plugins {
     alias(libs.plugins.kotlin.compose)
     alias(libs.plugins.kotlin.serialization)
     alias(libs.plugins.ksp)
+    alias(libs.plugins.androidx.room)
     alias(libs.plugins.aboutlibraries)
     alias(libs.plugins.aboutlibraries.android)
 }
@@ -61,13 +62,13 @@ val gitDirty: Provider<Boolean> = gitStatus.map { it != "unknown" && it.isNotBla
 android {
     namespace = "capital.yuri.yuriplayer"
     compileSdk {
-        version = release(37)
+        version = release(36)
     }
 
     defaultConfig {
         applicationId = "capital.yuri.yuriplayer"
         minSdk = 27
-        targetSdk = 37
+        targetSdk = 36
         versionCode = 1
         versionName = "0.1.0-local"
 
@@ -160,6 +161,10 @@ android {
     }
 }
 
+room {
+    schemaDirectory(layout.projectDirectory.dir("schemas").asFile.absolutePath)
+}
+
 aboutLibraries {
     library {
         duplicationMode.set(com.mikepenz.aboutlibraries.plugin.DuplicateMode.MERGE)
@@ -232,6 +237,8 @@ tasks.register<Exec>("buildFfmpeg") {
 }
 
 dependencies {
+    implementation(project(":core"))
+    implementation(project(":components"))
     implementation(platform(libs.androidx.compose.bom))
     implementation(libs.androidx.activity.compose)
     implementation(libs.androidx.appcompat)
@@ -266,6 +273,7 @@ dependencies {
 
     implementation(libs.androidx.room.runtime)
     implementation(libs.androidx.room.ktx)
+    implementation(libs.androidx.sqlite.bundled)
     ksp(libs.androidx.room.compiler)
 
     implementation(libs.jaudiotagger)
diff --git a/app/src/androidTest/java/capital/yuri/yuriplayer/DeviceUiTest.kt b/app/src/androidTest/java/capital/yuri/yuriplayer/DeviceUiTest.kt
index acc3f4a8..50139d25 100644
--- a/app/src/androidTest/java/capital/yuri/yuriplayer/DeviceUiTest.kt
+++ b/app/src/androidTest/java/capital/yuri/yuriplayer/DeviceUiTest.kt
@@ -37,19 +37,19 @@ class DeviceUiTest {
 
     @Test
     fun tabsAndCatalogOpen() {
-        rule.waitForTag(TestTags.TAB_MY_STUFF)
+        rule.waitForTag(TestTags.TAB_HOME)
+        rule.onNodeWithTag(TestTags.TAB_HOME).assertIsDisplayed()
         rule.onNodeWithTag(TestTags.TAB_MY_STUFF).assertIsDisplayed()
         rule.onNodeWithTag(TestTags.TAB_EXPLORE).assertIsDisplayed()
         rule.onNodeWithTag(TestTags.SETTINGS).assertIsDisplayed()
 
-        rule.onNodeWithTag(TestTags.MYSTUFF_CATALOG).performClick()
+        rule.onNodeWithTag(TestTags.TAB_MY_STUFF).performClick()
         rule.waitForTag(TestTags.CATALOG_TITLE)
-        rule.onNodeWithTag(TestTags.CATALOG_TITLE).assertTextContains("Catalog")
+        rule.onNodeWithTag(TestTags.CATALOG_TITLE).assertTextContains("My Stuff")
 
         rule.onNodeWithTag(TestTags.TAB_EXPLORE).performClick()
-        rule.onNodeWithTag(TestTags.TAB_MY_STUFF).performClick()
+        rule.onNodeWithTag(TestTags.TAB_HOME).performClick()
         rule.onNodeWithTag(TestTags.MYSTUFF_PINS).assertIsDisplayed()
-        rule.onNodeWithTag(TestTags.MYSTUFF_PLAYLISTS).assertIsDisplayed()
     }
 
     @Test
diff --git a/app/src/main/AndroidManifest.xml b/app/src/main/AndroidManifest.xml
index 028bbd02..7a88a714 100644
--- a/app/src/main/AndroidManifest.xml
+++ b/app/src/main/AndroidManifest.xml
@@ -71,6 +71,7 @@
         android:requestLegacyExternalStorage="true"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:supportsRtl="true"
+        android:enableOnBackInvokedCallback="true"
         android:theme="@style/Theme.YuriPlayer">
 
         <activity
@@ -80,6 +81,7 @@
             android:theme="@style/Theme.YuriPlayer"
             android:launchMode="singleTop"
             android:configChanges="orientation|screenSize|keyboardHidden|screenLayout"
+            android:enableOnBackInvokedCallback="true"
             android:windowSoftInputMode="adjustResize">
 
             <intent-filter>
diff --git a/app/src/main/java/capital/yuri/yuriplayer/YuriPlayerApp.kt b/app/src/main/java/capital/yuri/yuriplayer/YuriPlayerApp.kt
index e4a6466c..87163659 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/YuriPlayerApp.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/YuriPlayerApp.kt
@@ -1,10 +1,13 @@
 package capital.yuri.yuriplayer
 
+import capital.yuri.yuriplayer.core.log.yuriLog
+
 import android.app.Application
 import android.content.Intent
 import android.os.Handler
 import android.os.Looper
 import androidx.core.content.ContextCompat
+import capital.yuri.yuriplayer.core.platform.AndroidAppDirectories
 import capital.yuri.yuriplayer.data.LibraryIndex
 import capital.yuri.yuriplayer.data.LibrarySettings
 import capital.yuri.yuriplayer.di.appModule
@@ -30,6 +33,7 @@ import org.koin.core.qualifier.named
 class YuriPlayerApp : Application(), SingletonImageLoader.Factory {
     override fun onCreate() {
         super.onCreate()
+        AndroidAppDirectories.install(this)
 
         startKoin {
             androidLogger(Level.ERROR)
@@ -59,7 +63,7 @@ class YuriPlayerApp : Application(), SingletonImageLoader.Factory {
         ImageLoader.Builder(context)
             .coroutineContext(
                 SupervisorJob() + Dispatchers.IO + CoroutineExceptionHandler { _, t ->
-                    android.util.Log.w("Coil", "image load cancelled", t)
+                    yuriLog("Coil").w(t) { "image load cancelled" }
                 }
             )
             .components {
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/MainActivity.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/MainActivity.kt
index 0e41f37e..95f3254a 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/MainActivity.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/MainActivity.kt
@@ -11,8 +11,9 @@ import android.os.Environment
 import android.provider.Settings
 import android.view.WindowManager
 import android.widget.Toast
+import androidx.activity.BackEventCompat
 import androidx.activity.ComponentActivity
-import androidx.activity.compose.BackHandler
+import androidx.activity.compose.PredictiveBackHandler
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 import androidx.activity.result.contract.ActivityResultContracts
@@ -24,24 +25,33 @@ import androidx.compose.animation.slideInVertically
 import androidx.compose.animation.slideOutVertically
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.WindowInsets
 import androidx.compose.foundation.layout.WindowInsetsSides
+import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.only
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.systemBars
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.Favorite
+import androidx.compose.material.icons.filled.Home
 import androidx.compose.material.icons.filled.Search
 import androidx.compose.material.icons.filled.Settings
+import androidx.compose.material.icons.outlined.FavoriteBorder
+import androidx.compose.material.icons.outlined.Home
+import androidx.compose.material.icons.outlined.Search
 import androidx.compose.material3.AlertDialog
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.NavigationBar
+import androidx.compose.material3.NavigationBarItem
 import androidx.compose.material3.Scaffold
+import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBar
@@ -50,14 +60,18 @@ import androidx.compose.runtime.CompositionLocalProvider
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableIntStateOf
 import androidx.compose.runtime.mutableLongStateOf
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
-import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.graphics.TransformOrigin
+import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.testTag
 import androidx.compose.ui.unit.dp
@@ -73,11 +87,14 @@ import capital.yuri.yuriplayer.activities.ui.EditAlbumMetadataScreen
 import capital.yuri.yuriplayer.activities.ui.EditSongMetadataScreen
 import capital.yuri.yuriplayer.activities.ui.ExploreScanMenu
 import capital.yuri.yuriplayer.activities.ui.ExploreScreen
+import capital.yuri.yuriplayer.activities.ui.ExploreSearchTopBar
+import capital.yuri.yuriplayer.activities.ui.HomeFeedScreen
 import capital.yuri.yuriplayer.activities.ui.LocalAlbumNav
 import capital.yuri.yuriplayer.activities.ui.LocalArtistNav
 import capital.yuri.yuriplayer.activities.ui.LocalPlaylistNav
 import capital.yuri.yuriplayer.activities.ui.LocalSongNav
 import capital.yuri.yuriplayer.activities.ui.LocalStatusBarStack
+import capital.yuri.yuriplayer.activities.ui.LocalTabBackEnabled
 import capital.yuri.yuriplayer.activities.ui.MiniPlayerBar
 import capital.yuri.yuriplayer.activities.ui.MyStuffScreen
 import capital.yuri.yuriplayer.activities.ui.NowPlayingScreen
@@ -89,6 +106,8 @@ import capital.yuri.yuriplayer.activities.ui.SettingsScreen
 import capital.yuri.yuriplayer.activities.ui.SongNavActions
 import capital.yuri.yuriplayer.activities.ui.StatusBarColorStack
 import capital.yuri.yuriplayer.activities.ui.theme.YuriPlayerTheme
+import capital.yuri.yuriplayer.components.OfflineBanner
+import capital.yuri.yuriplayer.core.network.NetworkMonitor
 import capital.yuri.yuriplayer.ui.TestTags
 import capital.yuri.yuriplayer.data.ActivityTitleFormat
 import capital.yuri.yuriplayer.data.AlbumItem
@@ -122,6 +141,7 @@ import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 import org.koin.android.ext.android.inject
 import org.koin.compose.koinInject
+import androidx.core.net.toUri
 
 class MainActivity : ComponentActivity() {
 
@@ -191,7 +211,7 @@ class MainActivity : ComponentActivity() {
         try {
             val intent = Intent(
                 Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION,
-                Uri.parse("package:$packageName")
+                "package:$packageName".toUri()
             )
             startActivity(intent)
         } catch (_: Exception) {
@@ -298,9 +318,10 @@ class MainActivity : ComponentActivity() {
     }
 }
 
-private enum class TopTab(val label: String, val icon: ImageVector) {
-    MyStuff("My Stuff", Icons.Default.Favorite),
-    Explore("Explore", Icons.Default.Search)
+private enum class TopTab(val label: String) {
+    Home("Home"),
+    MyStuff("My Stuff"),
+    Explore("Explore")
 }
 
 private sealed class DetailRoute {
@@ -328,6 +349,7 @@ fun YuriApp(
     val playlistRepo: PlaylistRepository = koinInject()
     val pinStore: MyStuffPinStore = koinInject()
     val catalog: CatalogRepository = koinInject()
+    val networkMonitor: NetworkMonitor = koinInject()
     val scope = rememberCoroutineScope()
     val baseScheme = MaterialTheme.colorScheme
 
@@ -345,6 +367,7 @@ fun YuriApp(
     val songCount by library.songs.collectAsState()
     val loading by library.isLoading.collectAsState()
     val colorRev by settings.colorPrefsRevision.collectAsState()
+    val online by networkMonitor.isOnline.collectAsState()
 
     LaunchedEffect(songCount.size, loading, showNetworkPrompt) {
         if (!showNetworkPrompt &&
@@ -390,20 +413,46 @@ fun YuriApp(
         )
     }
 
-    var topTab by remember { mutableStateOf(TopTab.MyStuff) }
+    var topTab by remember { mutableStateOf(TopTab.Home) }
+    var exploreQuery by rememberSaveable { mutableStateOf("") }
     var playerExpanded by remember { mutableStateOf(false) }
-    var detailStack by remember { mutableStateOf<List<DetailRoute>>(emptyList()) }
+    var tabStacks by remember {
+        mutableStateOf(
+            mapOf(
+                TopTab.Home to emptyList<DetailRoute>(),
+                TopTab.MyStuff to emptyList<DetailRoute>(),
+                TopTab.Explore to emptyList<DetailRoute>()
+            )
+        )
+    }
     var npPlaylistSong by remember { mutableStateOf<Song?>(null) }
 
+    fun stackOf(tab: TopTab) = tabStacks[tab].orEmpty()
+
     fun pushDetail(route: DetailRoute) {
-        detailStack = detailStack + route
+        val tab = topTab
+        tabStacks = tabStacks + (tab to stackOf(tab) + route)
     }
 
     fun popDetail() {
-        if (detailStack.isNotEmpty()) detailStack = detailStack.dropLast(1)
+        val tab = topTab
+        val stack = stackOf(tab)
+        if (stack.isNotEmpty()) tabStacks = tabStacks + (tab to stack.dropLast(1))
     }
 
-    val detail = detailStack.lastOrNull()
+    fun selectTab(tab: TopTab) {
+        if (topTab == tab) {
+            if (stackOf(tab).isNotEmpty()) {
+                tabStacks = tabStacks + (tab to emptyList())
+            }
+        } else {
+            topTab = tab
+        }
+    }
+
+    val currentStack = stackOf(topTab)
+    val detail = currentStack.lastOrNull()
+    val previousDetail = currentStack.getOrNull(currentStack.lastIndex - 1)
     val edgeToEdgeDetail = detail is DetailRoute.Album ||
         detail is DetailRoute.Artist ||
         detail is DetailRoute.Playlist
@@ -460,8 +509,24 @@ fun YuriApp(
         themeStore.updateNeighbors(context, peekNext, peekPrev, baseScheme)
     }
 
-    BackHandler(enabled = playerExpanded) { playerExpanded = false }
-    BackHandler(enabled = !playerExpanded && detailStack.isNotEmpty()) { popDetail() }
+    PredictiveBackHandler(enabled = playerExpanded) { events ->
+        events.collect { }
+        playerExpanded = false
+    }
+
+    var backProgress by remember { mutableFloatStateOf(0f) }
+    var backSwipeEdge by remember { mutableIntStateOf(BackEventCompat.EDGE_LEFT) }
+    PredictiveBackHandler(enabled = !playerExpanded && currentStack.isNotEmpty()) { events ->
+        try {
+            events.collect { event ->
+                backProgress = event.progress
+                backSwipeEdge = event.swipeEdge
+            }
+            popDetail()
+        } finally {
+            backProgress = 0f
+        }
+    }
 
     fun playAlbumFrom(album: AlbumItem, songs: List<Song>, index: Int) {
         val key = albumKey(album.name, album.artist)
@@ -648,75 +713,149 @@ fun YuriApp(
                 modifier = Modifier.fillMaxSize(),
                 containerColor = if (edgeToEdgeDetail) Color.Transparent
                 else MaterialTheme.colorScheme.background,
-                contentWindowInsets = if (edgeToEdgeDetail) {
-                    WindowInsets(0, 0, 0, 0)
-                } else {
-                    WindowInsets.systemBars.only(
-                        WindowInsetsSides.Horizontal + WindowInsetsSides.Top
-                    )
-                },
-                topBar = {
-                    if (detail == null) {
-                        TopAppBar(
-                            title = {
-                                Row(
-                                    horizontalArrangement = Arrangement.spacedBy(4.dp),
-                                    verticalAlignment = androidx.compose.ui.Alignment.CenterVertically
+                contentWindowInsets = WindowInsets.systemBars.only(WindowInsetsSides.Horizontal),
+                bottomBar = {
+                    Column(Modifier.fillMaxWidth()) {
+                        MiniPlayerBar(
+                            song = currentSong,
+                            playing = playing,
+                            positionMs = positionMs,
+                            durationMs = durationMs,
+                            onToggle = { player.togglePlayPause() },
+                            onExpand = { playerExpanded = true }
+                        )
+                        NavigationBar {
+                            NavigationBarItem(
+                                selected = topTab == TopTab.Home,
+                                onClick = { selectTab(TopTab.Home) },
+                                modifier = Modifier.testTag(TestTags.TAB_HOME),
+                                icon = {
+                                    Icon(
+                                        if (topTab == TopTab.Home) Icons.Filled.Home else Icons.Outlined.Home,
+                                        contentDescription = "Home"
+                                    )
+                                },
+                                label = { Text("Home") }
+                            )
+                            NavigationBarItem(
+                                selected = topTab == TopTab.MyStuff,
+                                onClick = { selectTab(TopTab.MyStuff) },
+                                modifier = Modifier.testTag(TestTags.TAB_MY_STUFF),
+                                icon = {
+                                    Icon(
+                                        if (topTab == TopTab.MyStuff) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder,
+                                        contentDescription = "My Stuff"
+                                    )
+                                },
+                                label = { Text("My Stuff") }
+                            )
+                            NavigationBarItem(
+                                selected = topTab == TopTab.Explore,
+                                onClick = { selectTab(TopTab.Explore) },
+                                modifier = Modifier.testTag(TestTags.TAB_EXPLORE),
+                                icon = {
+                                    Icon(
+                                        if (topTab == TopTab.Explore) Icons.Filled.Search else Icons.Outlined.Search,
+                                        contentDescription = "Explore"
+                                    )
+                                },
+                                label = { Text("Explore") }
+                            )
+                        }
+                    }
+                }
+            ) { innerPadding ->
+                val contentPadding = PaddingValues(
+                    bottom = innerPadding.calculateBottomPadding()
+                )
+                Box(modifier = Modifier.fillMaxSize().padding(contentPadding)) {
+                    CompositionLocalProvider(
+                        LocalTabBackEnabled provides currentStack.isEmpty()
+                    ) {
+                        Column(Modifier.fillMaxSize()) {
+                            if (!online) {
+                                OfflineBanner()
+                            }
+                            if (topTab == TopTab.Explore) {
+                                ExploreSearchTopBar(
+                                    query = exploreQuery,
+                                    onQueryChange = { exploreQuery = it }
                                 ) {
-                                    TopTab.entries.forEach { tab ->
-                                        val selected = topTab == tab
-                                        val tag = when (tab) {
-                                            TopTab.MyStuff -> TestTags.TAB_MY_STUFF
-                                            TopTab.Explore -> TestTags.TAB_EXPLORE
-                                        }
+                                    ExploreScanMenu()
+                                    IconButton(
+                                        onClick = { pushDetail(DetailRoute.Settings) },
+                                        modifier = Modifier.testTag(TestTags.SETTINGS)
+                                    ) {
+                                        Icon(Icons.Default.Settings, contentDescription = "Settings")
+                                    }
+                                }
+                            } else {
+                                TopAppBar(
+                                    title = {
+                                        Text(
+                                            topTab.label,
+                                            modifier = if (topTab == TopTab.MyStuff) {
+                                                Modifier.testTag(TestTags.CATALOG_TITLE)
+                                            } else {
+                                                Modifier
+                                            }
+                                        )
+                                    },
+                                    actions = {
                                         IconButton(
-                                            onClick = { topTab = tab },
-                                            modifier = Modifier.testTag(tag)
+                                            onClick = { pushDetail(DetailRoute.Settings) },
+                                            modifier = Modifier.testTag(TestTags.SETTINGS)
                                         ) {
-                                            Icon(
-                                                imageVector = tab.icon,
-                                                contentDescription = tab.label,
-                                                tint = if (selected) MaterialTheme.colorScheme.primary
-                                                else MaterialTheme.colorScheme.onSurface.copy(alpha = 0.45f)
-                                            )
+                                            Icon(Icons.Default.Settings, contentDescription = "Settings")
                                         }
                                     }
+                                )
+                            }
+                            Box(Modifier.weight(1f).fillMaxWidth()) {
+                        when (topTab) {
+                            TopTab.Home -> HomeFeedScreen(
+                                library = library,
+                                onPlay = { songs, index -> player.playSource(songs, index) },
+                                onOpenAlbum = { openAlbumResolved(it) },
+                                onOpenArtist = { openArtistResolved(it) },
+                                onOpenPlaylist = { pl: Playlist ->
+                                    pushDetail(DetailRoute.Playlist(pl.id))
+                                },
+                                onOpenSongAlbum = { openAlbumForSong(it) }
+                            )
+                            TopTab.MyStuff -> MyStuffScreen(
+                                library = library,
+                                nowPlaying = currentSong,
+                                isPlaybackActive = playing,
+                                onPlay = { songs, index -> player.playSource(songs, index) },
+                                onAddToQueue = { player.addToHotQueue(it) },
+                                onOpenAlbum = { openAlbumResolved(it) },
+                                onOpenArtist = { openArtistResolved(it) },
+                                onOpenPlaylist = { pl: Playlist ->
+                                    pushDetail(DetailRoute.Playlist(pl.id))
+                                },
+                                onOpenSongAlbum = { openAlbumForSong(it) }
+                            )
+                            TopTab.Explore -> ExploreScreen(
+                                query = exploreQuery,
+                                onQueryChange = { exploreQuery = it },
+                                nowPlaying = currentSong,
+                                isPlaybackActive = playing,
+                                onPlay = { songs, index -> player.playSource(songs, index) },
+                                onAddToQueue = { player.addToHotQueue(it) },
+                                onOpenAlbum = { album -> openAlbumResolved(album) },
+                                onOpenArtist = { artist -> openArtistResolved(artist) },
+                                onOpenPlaylist = { pl: Playlist ->
+                                    pushDetail(DetailRoute.Playlist(pl.id))
                                 }
-                            },
-                            actions = {
-                                if (topTab == TopTab.Explore) {
-                                    // TravelExplore dropdown: scan / pause / stop per source.
-                                    // Never auto-starts on tab enter — only explicit menu actions.
-                                    ExploreScanMenu()
-                                }
-                                IconButton(
-                                    onClick = { pushDetail(DetailRoute.Settings) },
-                                    modifier = Modifier.testTag(TestTags.SETTINGS)
-                                ) {
-                                    Icon(Icons.Default.Settings, contentDescription = "Settings")
-                                }
+                            )
+                        }
                             }
-                        )
+                        }
                     }
-                },
-                bottomBar = {
-                    MiniPlayerBar(
-                        song = currentSong,
-                        playing = playing,
-                        positionMs = positionMs,
-                        durationMs = durationMs,
-                        onToggle = { player.togglePlayPause() },
-                        onExpand = { playerExpanded = true }
-                    )
-                }
-            ) { innerPadding ->
-                val contentPadding = if (edgeToEdgeDetail) {
-                    PaddingValues(bottom = innerPadding.calculateBottomPadding())
-                } else {
-                    innerPadding
-                }
-                Box(modifier = Modifier.fillMaxSize().padding(contentPadding)) {
-                    when (val d = detail) {
+
+                    val mediaDetailHost = @Composable { d: DetailRoute ->
+                    when (d) {
                         is DetailRoute.Album -> {
                             val key = albumKey(d.album.name, d.album.artist)
                             var resolvedAlbum by remember(key) { mutableStateOf(d.album) }
@@ -905,31 +1044,37 @@ fun YuriApp(
                             )
                         }
                         is DetailRoute.Settings -> SettingsScreen(onBack = { popDetail() })
-                        null -> when (topTab) {
-                            TopTab.MyStuff -> MyStuffScreen(
-                                library = library,
-                                nowPlaying = currentSong,
-                                isPlaybackActive = playing,
-                                onPlay = { songs, index -> player.playSource(songs, index) },
-                                onAddToQueue = { player.addToHotQueue(it) },
-                                onOpenAlbum = { openAlbumResolved(it) },
-                                onOpenArtist = { openArtistResolved(it) },
-                                onOpenPlaylist = { pl: Playlist ->
-                                    pushDetail(DetailRoute.Playlist(pl.id))
+                    }
+                    }
+
+                    if (previousDetail != null) {
+                        Surface(
+                            modifier = Modifier.fillMaxSize(),
+                            color = MaterialTheme.colorScheme.background
+                        ) {
+                            mediaDetailHost(previousDetail)
+                        }
+                    }
+                    if (detail != null) {
+                        val progress = backProgress
+                        val edge = backSwipeEdge
+                        Surface(
+                            modifier = Modifier
+                                .fillMaxSize()
+                                .graphicsLayer {
+                                    val dir = if (edge == BackEventCompat.EDGE_RIGHT) -1f else 1f
+                                    translationX = dir * progress * 48.dp.toPx()
+                                    val s = 1f - (0.06f * progress)
+                                    scaleX = s
+                                    scaleY = s
+                                    alpha = 1f - (0.12f * progress)
+                                    clip = true
+                                    shadowElevation = 16f * (1f - progress)
+                                    transformOrigin = TransformOrigin.Center
                                 },
-                                onOpenSongAlbum = { openAlbumForSong(it) }
-                            )
-                            TopTab.Explore -> ExploreScreen(
-                                nowPlaying = currentSong,
-                                isPlaybackActive = playing,
-                                onPlay = { songs, index -> player.playSource(songs, index) },
-                                onAddToQueue = { player.addToHotQueue(it) },
-                                onOpenAlbum = { album -> openAlbumResolved(album) },
-                                onOpenArtist = { artist -> openArtistResolved(artist) },
-                                onOpenPlaylist = { pl: Playlist ->
-                                    pushDetail(DetailRoute.Playlist(pl.id))
-                                }
-                            )
+                            color = MaterialTheme.colorScheme.background
+                        ) {
+                            mediaDetailHost(detail)
                         }
                     }
                 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumArt.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumArt.kt
index 62fa4530..899187fe 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumArt.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumArt.kt
@@ -3,6 +3,7 @@ package capital.yuri.yuriplayer.activities.ui
 import android.graphics.Bitmap
 import androidx.compose.foundation.Image
 import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.aspectRatio
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.size
@@ -89,7 +90,11 @@ fun AlbumArt(
     }
 
     val shape = RoundedCornerShape(corner)
-    val boxMod = if (size != null) modifier.size(size).clip(shape) else modifier.clip(shape)
+    val boxMod = if (size != null) {
+        modifier.size(size).clip(shape)
+    } else {
+        modifier.aspectRatio(1f).clip(shape)
+    }
 
     Box(
         modifier = boxMod.background(MaterialTheme.colorScheme.primaryContainer),
@@ -100,7 +105,8 @@ fun AlbumArt(
             Image(
                 bitmap = bmp.asImageBitmap(),
                 contentDescription = song?.displayAlbum,
-                contentScale = ContentScale.Crop,
+                contentScale = ContentScale.Fit,
+                alignment = Alignment.Center,
                 filterQuality = if (decodeSize >= AlbumArtCache.HERO_DECODE_SIZE) {
                     FilterQuality.High
                 } else {
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumDetailScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumDetailScreen.kt
index d2167702..df62dde0 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumDetailScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/AlbumDetailScreen.kt
@@ -52,10 +52,7 @@ import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.draw.clipToBounds
-import androidx.compose.ui.draw.drawBehind
 import androidx.compose.ui.geometry.Offset
-import androidx.compose.ui.geometry.Size
-import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.graphicsLayer
 import androidx.compose.ui.input.nestedscroll.NestedScrollConnection
@@ -76,6 +73,7 @@ import capital.yuri.yuriplayer.data.MetadataEnrichmentService
 import capital.yuri.yuriplayer.data.MyStuffPinStore
 import capital.yuri.yuriplayer.data.Song
 import capital.yuri.yuriplayer.data.StuffPinKind
+import capital.yuri.yuriplayer.components.theme.AlbumArtBackdrop
 import capital.yuri.yuriplayer.data.albumKey
 import capital.yuri.yuriplayer.data.albumTrackOrder
 import capital.yuri.yuriplayer.data.AlbumLog
@@ -94,7 +92,6 @@ import kotlin.math.sqrt
 
 private val ExpandedHeaderBody = 420.dp
 private val CollapsedBarHeight = 56.dp
-private val GradientFadeLength = 220.dp
 
 @Composable
 private fun CircularPlayButton(
@@ -187,10 +184,7 @@ fun AlbumDetailScreen(
         mutableIntStateOf(album.trackCount.coerceAtLeast(album.songs.size))
     }
     LaunchedEffect(stableKey) {
-        AlbumLog.i(
-            album.name,
-            "PAGE open stableKey='$stableKey' albumKey='$albumKeyStr' seed=${album.songs.size} artist='${album.artist}'"
-        )
+        AlbumLog.i(album.name, "PAGE open stableKey='$stableKey' albumKey='$albumKeyStr' seed=${album.songs.size} artist='${album.artist}'")
         var current = album
         fun publish(next: AlbumItem, stage: String) {
             val union = dedupeAlbumPageTracks(current.songs + next.songs + album.songs)
@@ -326,49 +320,107 @@ fun AlbumDetailScreen(
         else onPlayAlbum(liveAlbum.songs, 0)
     }
 
-    val fadePx = with(density) { GradientFadeLength.toPx() }
-
     ThemedStatusBar(color = albumBg, enabled = true)
 
     MaterialTheme(colorScheme = scheme) {
-        BoxWithConstraints(
+        AlbumArtBackdrop(
+            wash = albumBg,
+            accent = themeColors.accent,
             modifier = Modifier
                 .fillMaxSize()
                 .nestedScroll(nestedScroll)
                 .background(defaultBg)
-                .drawBehind {
-                    val headerEnd = headerBodyH.toPx()
-                    val solidEnd = headerEnd + with(density) { 48.dp.toPx() }
-                    val fadeEnd = solidEnd + fadePx
-
-                    drawRect(
-                        color = albumBg,
-                        topLeft = Offset.Zero,
-                        size = Size(size.width, solidEnd.coerceAtMost(size.height))
-                    )
-
-                    if (fadeEnd > solidEnd) {
-                        drawRect(
-                            brush = Brush.verticalGradient(
-                                colors = listOf(
-                                    albumBg,
-                                    albumBg.copy(alpha = 0.85f),
-                                    albumBg.copy(alpha = 0.45f),
-                                    albumBg.copy(alpha = 0.15f),
-                                    Color.Transparent
-                                ),
-                                startY = solidEnd,
-                                endY = fadeEnd
-                            ),
-                            topLeft = Offset(0f, solidEnd),
-                            size = Size(
-                                size.width,
-                                (fadeEnd - solidEnd).coerceAtMost(size.height - solidEnd)
+        ) {
+            BoxWithConstraints(Modifier.fillMaxSize()) {
+            val compact = maxWidth < 600.dp
+            if (!compact) {
+                Row(
+                    modifier = Modifier
+                        .fillMaxSize()
+                        .statusBarsPadding()
+                        .padding(start = 12.dp, end = 8.dp, top = 8.dp)
+                ) {
+                    Column(
+                        modifier = Modifier
+                            .width(300.dp)
+                            .padding(end = 16.dp)
+                    ) {
+                        IconButton(onClick = onBack) {
+                            Icon(
+                                Icons.AutoMirrored.Filled.ArrowBack,
+                                contentDescription = "Back",
+                                tint = scheme.onBackground
                             )
+                        }
+                        SpotifyAlbumHero(
+                            album = liveAlbum,
+                            metaLine = metaLine,
+                            showPause = showPause,
+                            shuffleEnabled = shuffleEnabled,
+                            albumSaved = albumSaved,
+                            onPrimary = onPrimary,
+                            onToggleShuffle = onToggleShuffle,
+                            onFavorite = {
+                                val now = pinStore.toggleAlbum(liveAlbum)
+                                Toast.makeText(
+                                    context,
+                                    if (now) "Album + tracks added to My Stuff"
+                                    else "Album removed from My Stuff",
+                                    Toast.LENGTH_SHORT
+                                ).show()
+                                onFavorite()
+                            },
+                            onMore = { showMenu = true },
+                            onOpenArtist = onOpenArtist,
+                            onCoverLongPress = { showCoverPicker = true }
                         )
                     }
+                    LazyColumn(
+                        state = listState,
+                        modifier = Modifier.weight(1f).fillMaxSize(),
+                        contentPadding = PaddingValues(top = 8.dp, bottom = 96.dp)
+                    ) {
+                        discs.forEach { (disc, tracks) ->
+                            if (multiDisc) {
+                                item(key = "disc-$disc") {
+                                    DiscSectionHeader(discNumber = disc ?: 1)
+                                }
+                            }
+                            itemsIndexed(
+                                tracks,
+                                key = { i, s -> "${s.songKey}#$i#${s.trackNumber}" }
+                            ) { _, song ->
+                                val globalIndex = liveAlbum.songs.indexOfFirst {
+                                    it.songKey == song.songKey ||
+                                        (it.path != null && it.path == song.path) ||
+                                        it.id == song.id
+                                }.coerceAtLeast(0)
+                                SwipeAddSongRow(
+                                    song = song,
+                                    onClick = { onPlayAlbum(liveAlbum.songs, globalIndex) },
+                                    onSwipeAdd = {
+                                        onAddSongToQueue(song)
+                                        Toast.makeText(context, "Added to queue", Toast.LENGTH_SHORT).show()
+                                    },
+                                    showTrackNumber = true,
+                                    isPlaying = song.isSameAs(nowPlaying),
+                                    isPlaybackActive = isPlaying,
+                                    isHighlighted = highlightSongKey != null &&
+                                        (song.songKey == highlightSongKey),
+                                    transparentSurface = true,
+                                    showHeart = true,
+                                    hideGoToAlbum = true,
+                                    onEditMetadata = { onEditSong(song) }
+                                )
+                            }
+                        }
+                        if (expanding && liveAlbum.songs.size < expectedTrackCount) {
+                            val extra = (expectedTrackCount - liveAlbum.songs.size).coerceIn(1, 16)
+                            items(extra) { SongRowSkeleton() }
+                        }
+                    }
                 }
-        ) {
+            } else {
             Column(modifier = Modifier.fillMaxSize()) {
                 Box(
                     modifier = Modifier
@@ -492,6 +544,7 @@ fun AlbumDetailScreen(
                     }
                 }
             }
+            }
 
             if (showMenu) {
                 AlbumContextSheet(
@@ -519,6 +572,7 @@ fun AlbumDetailScreen(
                 )
             }
         }
+        }
     }
 }
 
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/BrowseAllLibraryScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/BrowseAllLibraryScreen.kt
new file mode 100644
index 00000000..0779dee9
--- /dev/null
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/BrowseAllLibraryScreen.kt
@@ -0,0 +1,58 @@
+package capital.yuri.yuriplayer.activities.ui
+
+import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.statusBarsPadding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Modifier
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.ArtistItem
+import capital.yuri.yuriplayer.data.LibraryIndex
+import capital.yuri.yuriplayer.data.Playlist
+import capital.yuri.yuriplayer.data.PlaylistRepository
+import capital.yuri.yuriplayer.data.Song
+import org.koin.compose.koinInject
+
+@Composable
+fun BrowseAllLibraryScreen(
+    library: LibraryIndex,
+    nowPlaying: Song?,
+    onBack: () -> Unit,
+    onPlay: (List<Song>, Int) -> Unit,
+    onAddToQueue: (Song) -> Unit,
+    onOpenAlbum: (AlbumItem) -> Unit,
+    onOpenArtist: (ArtistItem) -> Unit,
+    onOpenPlaylist: (Playlist) -> Unit,
+    onOpenSongAlbum: (Song) -> Unit
+) {
+    BackHandler(enabled = LocalTabBackEnabled.current, onBack = onBack)
+    val playlistsRepo: PlaylistRepository = koinInject()
+    val songs by library.songs.collectAsState()
+    val playlists by playlistsRepo.observePlaylistsResolved().collectAsState(initial = emptyList())
+    val albums = remember(songs) { library.albums(taggedOnly = false) }
+    val artists = remember(songs) { library.artists(taggedOnly = false) }
+
+    Column(Modifier.fillMaxSize().statusBarsPadding()) {
+        SettingsTopBar(title = "All", onBack = onBack)
+        MediaBrowser(
+            lookup = mediaBrowserLookup(
+                songs = songs,
+                albums = albums,
+                artists = artists,
+                playlists = playlists
+            ),
+            nowPlaying = nowPlaying,
+            onPlay = onPlay,
+            onAddToQueue = onAddToQueue,
+            onOpenAlbum = onOpenAlbum,
+            onOpenArtist = onOpenArtist,
+            onOpenPlaylist = onOpenPlaylist,
+            onSongClick = onOpenSongAlbum
+        )
+    }
+}
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ExploreScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ExploreScreen.kt
index e3840a26..6c881ec0 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ExploreScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ExploreScreen.kt
@@ -7,6 +7,7 @@ import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.RowScope
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
@@ -17,19 +18,28 @@ import androidx.compose.foundation.layout.width
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.items
 import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.text.KeyboardActions
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.Clear
 import androidx.compose.material.icons.filled.Cloud
+import androidx.compose.material.icons.filled.FilterList
 import androidx.compose.material.icons.filled.Search
+import androidx.compose.material3.Checkbox
 import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
-import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.ModalBottomSheet
 import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.material3.TextField
+import androidx.compose.material3.TextFieldDefaults
+import androidx.compose.material3.TopAppBar
+import androidx.compose.material3.rememberModalBottomSheetState
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.collectAsState
@@ -41,6 +51,7 @@ import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalFocusManager
 import androidx.compose.ui.platform.LocalSoftwareKeyboardController
@@ -52,11 +63,16 @@ import capital.yuri.yuriplayer.data.AlbumItem
 import capital.yuri.yuriplayer.data.ArtistItem
 import capital.yuri.yuriplayer.data.CatalogRepository
 import capital.yuri.yuriplayer.data.ExploreSearchService
+import capital.yuri.yuriplayer.data.LibrarySettings
 import capital.yuri.yuriplayer.data.Playlist
 import capital.yuri.yuriplayer.data.PlaylistRepository
 import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.albumKey
+import capital.yuri.yuriplayer.data.db.CatalogSources
+import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
 import capital.yuri.yuriplayer.data.source.RemotePlaylist
 import capital.yuri.yuriplayer.data.source.RemotePlaylistService
+import capital.yuri.yuriplayer.data.source.SourceInstanceRepository
 import capital.yuri.yuriplayer.data.source.SourceOffering
 import capital.yuri.yuriplayer.ui.LoadingEstimates
 import capital.yuri.yuriplayer.ui.SongListSkeleton
@@ -68,6 +84,8 @@ import org.koin.compose.koinInject
 
 @Composable
 fun ExploreScreen(
+    query: String,
+    onQueryChange: (String) -> Unit,
     nowPlaying: Song? = null,
     isPlaybackActive: Boolean = false,
     onPlay: (List<Song>, Int) -> Unit,
@@ -80,13 +98,16 @@ fun ExploreScreen(
     val catalog: CatalogRepository = koinInject()
     val playlistsRepo: PlaylistRepository = koinInject()
     val remotePls: RemotePlaylistService = koinInject()
+    val sourcesRepo: SourceInstanceRepository = koinInject()
+    val settings: LibrarySettings = koinInject()
     val localPlaylists by playlistsRepo.observePlaylists().collectAsState(initial = emptyList())
+    val instances by sourcesRepo.observeAll().collectAsState(initial = emptyList())
+    val remotes = remember(instances) { instances.filter { it.enabled } }
     val context = LocalContext.current
-    val focusManager = LocalFocusManager.current
-    val keyboard = LocalSoftwareKeyboardController.current
     val scope = rememberCoroutineScope()
 
-    var query by remember { mutableStateOf("") }
+    var selectedKeys by remember { mutableStateOf(settings.getExploreLibraryKeys()) }
+    var showFilters by remember { mutableStateOf(false) }
 
     val scanning by explore.isScanning.collectAsState()
     val scanProgress by explore.scanProgress.collectAsState()
@@ -106,7 +127,7 @@ fun ExploreScreen(
         withContext(Dispatchers.IO) { remotePls.syncOwnedToMyStuff() }
     }
 
-    LaunchedEffect(query) {
+    LaunchedEffect(query, selectedKeys, remotes) {
         val q = query.trim()
         if (q.isEmpty()) {
             hits = emptyList()
@@ -121,29 +142,51 @@ fun ExploreScreen(
         delay(SEARCH_DEBOUNCE_MS)
         if (query.trim() != q) return@LaunchedEffect
 
+        val filters = exploreSourceFilters(selectedKeys, remotes)
         val songHits = withContext(Dispatchers.Default) {
-            explore.searchLive(q).take(SONG_HIT_LIMIT)
+            explore.searchLive(q, SONG_HIT_LIMIT, filters).take(SONG_HIT_LIMIT)
         }
         if (query.trim() != q) return@LaunchedEffect
 
         val albums = withContext(Dispatchers.IO) {
-            catalog.searchAlbumsAsItems(q, ALBUM_HIT_LIMIT)
+            val found = catalog.searchAlbumsAsItems(q, ALBUM_HIT_LIMIT)
+            if (filters == null) found
+            else {
+                val keys = songHits.map {
+                    albumKey(it.song.album, it.song.effectiveAlbumArtist ?: it.song.artist)
+                }.toHashSet()
+                found.filter { albumKey(it.name, it.artist) in keys }
+            }
         }
         if (query.trim() != q) return@LaunchedEffect
 
         val artists = withContext(Dispatchers.IO) {
-            catalog.searchArtistsAsItems(q, ARTIST_HIT_LIMIT)
+            val found = catalog.searchArtistsAsItems(q, ARTIST_HIT_LIMIT)
+            if (filters == null) found
+            else {
+                val names = songHits.map { it.song.displayArtist.lowercase() }.toHashSet()
+                found.filter { it.displayName.lowercase() in names }
+            }
         }
         if (query.trim() != q) return@LaunchedEffect
 
+        val includeLocal = filters == null || selectedKeys.isEmpty() || EXPLORE_LOCAL_KEY in selectedKeys
+        val remoteIds = selectedKeys.mapNotNull { it.removePrefix("i:").toLongOrNull() }.toHashSet()
+        val includeAllRemotes = filters == null || selectedKeys.isEmpty()
+
         val localIds = localPlaylists.map { it.id }.toHashSet()
         val remotePl = withContext(Dispatchers.IO) { remotePls.search(q) }
+            .filter { includeAllRemotes || it.sourceInstanceId in remoteIds }
             .filter { it.ownedByUser || it.stableId !in localIds }
             .take(12)
-        val remoteIds = remotePl.map { it.stableId }.toHashSet()
-        val localPl = localPlaylists
-            .filter { it.name.contains(q, true) && it.id !in remoteIds }
-            .take(12)
+        val remotePlIds = remotePl.map { it.stableId }.toHashSet()
+        val localPl = if (includeLocal) {
+            localPlaylists
+                .filter { it.name.contains(q, true) && it.id !in remotePlIds }
+                .take(12)
+        } else {
+            emptyList()
+        }
         if (query.trim() != q) return@LaunchedEffect
 
         hits = songHits
@@ -155,30 +198,43 @@ fun ExploreScreen(
     }
 
     Column(modifier = Modifier.fillMaxSize()) {
-        OutlinedTextField(
-            value = query,
-            onValueChange = { query = it },
+        val allSelected = selectedKeys.isEmpty() ||
+            (EXPLORE_LOCAL_KEY in selectedKeys && remotes.all { exploreInstanceKey(it.id) in selectedKeys })
+        val filterSummary = when {
+            allSelected -> "All libraries"
+            selectedKeys.size == 1 && EXPLORE_LOCAL_KEY in selectedKeys -> "On this device"
+            selectedKeys.size == 1 -> remotes.firstOrNull {
+                exploreInstanceKey(it.id) in selectedKeys
+            }?.name ?: "1 library"
+            else -> "${selectedKeys.size} libraries"
+        }
+        Row(
             modifier = Modifier
                 .fillMaxWidth()
-                .padding(horizontal = 12.dp, vertical = 8.dp),
-            singleLine = true,
-            leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
-            trailingIcon = {
-                if (query.isNotEmpty()) {
-                    IconButton(onClick = { query = "" }) {
-                        Icon(Icons.Default.Clear, contentDescription = "Clear search")
-                    }
-                }
-            },
-            placeholder = { Text("Search all libraries…") },
-            keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
-            keyboardActions = KeyboardActions(
-                onSearch = {
-                    focusManager.clearFocus()
-                    keyboard?.hide()
-                }
+                .clickable { showFilters = true }
+                .padding(horizontal = 16.dp, vertical = 8.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Text(
+                "Filters",
+                style = MaterialTheme.typography.titleSmall,
+                fontWeight = FontWeight.SemiBold,
+                modifier = Modifier.weight(1f)
             )
-        )
+            Text(
+                filterSummary,
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+            Icon(
+                Icons.Default.FilterList,
+                contentDescription = "Filter libraries",
+                modifier = Modifier
+                    .padding(start = 8.dp)
+                    .size(18.dp),
+                tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+        }
 
         val status = when {
             err != null && !scanning -> err!!
@@ -239,7 +295,7 @@ fun ExploreScreen(
                         )
                         Spacer(modifier = Modifier.height(12.dp))
                         Text(
-                            "Search across every library",
+                            "Explore every library",
                             style = MaterialTheme.typography.titleMedium,
                             color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
                         )
@@ -359,12 +415,203 @@ fun ExploreScreen(
             }
         }
     }
+
+    if (showFilters) {
+        ExploreFilterSheet(
+            remotes = remotes,
+            selectedKeys = selectedKeys,
+            onDismiss = { showFilters = false },
+            onChange = { next ->
+                selectedKeys = next
+                settings.setExploreLibraryKeys(next)
+            }
+        )
+    }
 }
 
 private const val SEARCH_DEBOUNCE_MS = 280L
 private const val SONG_HIT_LIMIT = 80
 private const val ALBUM_HIT_LIMIT = 12
 private const val ARTIST_HIT_LIMIT = 12
+private const val EXPLORE_LOCAL_KEY = "local"
+
+private fun exploreInstanceKey(id: Long) = "i:$id"
+
+/** Null means every library (no filter). */
+private fun exploreSourceFilters(
+    selectedKeys: Set<String>,
+    remotes: List<SourceInstanceEntity>
+): List<Pair<String, Long?>>? {
+    if (selectedKeys.isEmpty()) return null
+    val allKeys = buildSet {
+        add(EXPLORE_LOCAL_KEY)
+        remotes.forEach { add(exploreInstanceKey(it.id)) }
+    }
+    if (selectedKeys.containsAll(allKeys)) return null
+    return buildList {
+        if (EXPLORE_LOCAL_KEY in selectedKeys) add(CatalogSources.LOCAL to null)
+        remotes.forEach { row ->
+            if (exploreInstanceKey(row.id) in selectedKeys) add(row.type to row.id)
+        }
+    }.ifEmpty { null }
+}
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun ExploreSearchTopBar(
+    query: String,
+    onQueryChange: (String) -> Unit,
+    actions: @Composable RowScope.() -> Unit
+) {
+    TopAppBar(
+        title = { ExploreSearchField(query = query, onQueryChange = onQueryChange) },
+        actions = actions
+    )
+}
+
+@Composable
+private fun ExploreSearchField(
+    query: String,
+    onQueryChange: (String) -> Unit
+) {
+    val focusManager = LocalFocusManager.current
+    val keyboard = LocalSoftwareKeyboardController.current
+    val scheme = MaterialTheme.colorScheme
+    TextField(
+        value = query,
+        onValueChange = onQueryChange,
+        modifier = Modifier.fillMaxWidth(),
+        singleLine = true,
+        placeholder = { Text("Songs, albums, artists") },
+        leadingIcon = { Icon(Icons.Default.Search, contentDescription = null) },
+        trailingIcon = {
+            if (query.isNotEmpty()) {
+                IconButton(onClick = { onQueryChange("") }) {
+                    Icon(Icons.Default.Clear, contentDescription = "Clear search")
+                }
+            }
+        },
+        keyboardOptions = KeyboardOptions(imeAction = ImeAction.Search),
+        keyboardActions = KeyboardActions(
+            onSearch = {
+                focusManager.clearFocus()
+                keyboard?.hide()
+            }
+        ),
+        shape = CircleShape,
+        colors = TextFieldDefaults.colors(
+            focusedContainerColor = scheme.surfaceContainerHighest,
+            unfocusedContainerColor = scheme.surfaceContainerHigh,
+            disabledContainerColor = scheme.surfaceContainerHigh,
+            focusedIndicatorColor = Color.Transparent,
+            unfocusedIndicatorColor = Color.Transparent,
+            disabledIndicatorColor = Color.Transparent
+        )
+    )
+}
+
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+private fun ExploreFilterSheet(
+    remotes: List<SourceInstanceEntity>,
+    selectedKeys: Set<String>,
+    onDismiss: () -> Unit,
+    onChange: (Set<String>) -> Unit
+) {
+    val allKeys = remember(remotes) {
+        buildSet {
+            add(EXPLORE_LOCAL_KEY)
+            remotes.forEach { add(exploreInstanceKey(it.id)) }
+        }
+    }
+    val effective = if (selectedKeys.isEmpty()) allKeys else selectedKeys
+    ModalBottomSheet(
+        onDismissRequest = onDismiss,
+        sheetState = rememberModalBottomSheetState(skipPartiallyExpanded = true),
+        shape = RoundedCornerShape(topStart = 28.dp, topEnd = 28.dp)
+    ) {
+        Column(
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 8.dp, vertical = 4.dp)
+                .padding(bottom = 24.dp)
+        ) {
+            Row(
+                modifier = Modifier
+                    .fillMaxWidth()
+                    .padding(horizontal = 16.dp, vertical = 4.dp),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                Text(
+                    "Filters",
+                    style = MaterialTheme.typography.titleLarge,
+                    fontWeight = FontWeight.Bold,
+                    modifier = Modifier.weight(1f)
+                )
+                TextButton(onClick = { onChange(emptySet()) }) {
+                    Text("All")
+                }
+            }
+            Text(
+                "Libraries",
+                style = MaterialTheme.typography.titleSmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp)
+            )
+            FilterLibraryRow(
+                title = "On this device",
+                checked = EXPLORE_LOCAL_KEY in effective,
+                onToggle = {
+                    onChange(toggleExploreKey(effective, allKeys, EXPLORE_LOCAL_KEY))
+                }
+            )
+            remotes.forEach { row ->
+                val key = exploreInstanceKey(row.id)
+                FilterLibraryRow(
+                    title = row.name.ifBlank { row.type },
+                    subtitle = row.type.lowercase().replaceFirstChar { it.titlecase() },
+                    checked = key in effective,
+                    onToggle = { onChange(toggleExploreKey(effective, allKeys, key)) }
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun FilterLibraryRow(
+    title: String,
+    checked: Boolean,
+    onToggle: () -> Unit,
+    subtitle: String? = null
+) {
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable(onClick = onToggle)
+            .padding(horizontal = 8.dp, vertical = 4.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Checkbox(checked = checked, onCheckedChange = { onToggle() })
+        Column(Modifier.weight(1f).padding(end = 8.dp)) {
+            Text(title, style = MaterialTheme.typography.bodyLarge)
+            if (subtitle != null) {
+                Text(
+                    subtitle,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+                )
+            }
+        }
+    }
+}
+
+private fun toggleExploreKey(current: Set<String>, allKeys: Set<String>, key: String): Set<String> {
+    val next = current.toMutableSet()
+    if (key in next) next.remove(key) else next.add(key)
+    if (next.isEmpty() || next.containsAll(allKeys)) return emptySet()
+    return next
+}
 
 @Composable
 private fun SectionHeader(title: String) {
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/HomeFeedScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/HomeFeedScreen.kt
new file mode 100644
index 00000000..00edcc75
--- /dev/null
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/HomeFeedScreen.kt
@@ -0,0 +1,259 @@
+package capital.yuri.yuriplayer.activities.ui
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.horizontalScroll
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.RowScope
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.platform.testTag
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.ArtistItem
+import capital.yuri.yuriplayer.data.CatalogRepository
+import capital.yuri.yuriplayer.data.HomeRowId
+import capital.yuri.yuriplayer.data.LibraryIndex
+import capital.yuri.yuriplayer.data.LibrarySettings
+import capital.yuri.yuriplayer.data.MyStuffPinStore
+import capital.yuri.yuriplayer.data.Playlist
+import capital.yuri.yuriplayer.data.PlaylistRepository
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.StuffPinKind
+import capital.yuri.yuriplayer.player.PlaybackHistoryStore
+import capital.yuri.yuriplayer.ui.TestTags
+import kotlinx.coroutines.launch
+import org.koin.compose.koinInject
+
+@Composable
+fun HomeFeedScreen(
+    library: LibraryIndex,
+    onPlay: (List<Song>, Int) -> Unit,
+    onOpenAlbum: (AlbumItem) -> Unit,
+    onOpenArtist: (ArtistItem) -> Unit,
+    onOpenPlaylist: (Playlist) -> Unit,
+    onOpenSongAlbum: (Song) -> Unit
+) {
+    val pinStore: MyStuffPinStore = koinInject()
+    val playlistsRepo: PlaylistRepository = koinInject()
+    val catalog: CatalogRepository = koinInject()
+    val history: PlaybackHistoryStore = koinInject()
+    val settings: LibrarySettings = koinInject()
+    val pins by pinStore.pins.collectAsState()
+    val entries by pinStore.entries.collectAsState()
+    val playlists by playlistsRepo.observePlaylistsResolved().collectAsState(initial = emptyList())
+    val allSongs by library.songs.collectAsState()
+    val historyEntries by history.entries.collectAsState()
+    val colorRev by settings.colorPrefsRevision.collectAsState()
+    val rows = remember(colorRev) { settings.enabledHomeRows() }
+    val scope = rememberCoroutineScope()
+    val context = LocalContext.current
+    var showAddPin by remember { mutableStateOf(false) }
+
+    LaunchedEffect(playlistsRepo) {
+        playlistsRepo.observePlaylistsResolved().collect { list ->
+            pinStore.pruneMissingPlaylists(list.map { it.id }.toSet())
+        }
+    }
+
+    val stuffAlbums = remember(entries, allSongs) {
+        library.albums(taggedOnly = false).filter { album ->
+            entries.any { it.kind == StuffPinKind.ALBUM && it.title.equals(album.name, true) } ||
+                album.songs.any { song -> entries.any { it.kind == StuffPinKind.SONG && it.id == song.songKey } }
+        }.ifEmpty { library.albums(taggedOnly = false) }
+    }
+    val stuffArtists = remember(entries) {
+        library.artists(taggedOnly = false).filter { artist ->
+            entries.any { it.kind == StuffPinKind.ARTIST && it.title.equals(artist.name, true) }
+        }.ifEmpty { library.artists(taggedOnly = false) }
+    }
+
+    LazyColumn(Modifier.fillMaxSize().testTag(TestTags.MYSTUFF_PINS)) {
+        item {
+            MyStuffPinsHost(
+                pins = pins,
+                library = library,
+                playlists = playlists,
+                allSongs = allSongs,
+                onOpenPin = { pin ->
+                    scope.launch {
+                        openPin(
+                            pin, library, playlists, allSongs, catalog,
+                            onOpenAlbum, onOpenArtist, onOpenPlaylist, onOpenSongAlbum, context
+                        )
+                    }
+                },
+                onUnpin = { pinStore.unpin(it) },
+                onAddPinSlot = { showAddPin = true }
+            )
+        }
+        if (HomeRowId.RECENTS in rows && historyEntries.isNotEmpty()) {
+            item {
+                HomeRow(title = "Recents") {
+                    historyEntries.take(16).forEach { entry ->
+                        CoverTile(
+                            title = entry.song.displayTitle,
+                            subtitle = entry.song.displayArtist,
+                            onClick = { onOpenSongAlbum(entry.song) },
+                            art = { AlbumArt(song = entry.song, size = 112.dp, corner = 8.dp) }
+                        )
+                    }
+                }
+            }
+        }
+        if (HomeRowId.RANDOM_ALBUMS in rows && stuffAlbums.isNotEmpty()) {
+            item {
+                HomeRow(title = "Random albums") {
+                    stuffAlbums.shuffled().take(10).forEach { album ->
+                        CoverTile(
+                            title = album.displayName,
+                            subtitle = album.displayArtist,
+                            onClick = { onOpenAlbum(album) },
+                            art = { AlbumArt(song = album.songs.firstOrNull(), size = 112.dp, corner = 8.dp) }
+                        )
+                    }
+                }
+            }
+        }
+        if (HomeRowId.RANDOM_ARTISTS in rows && stuffArtists.isNotEmpty()) {
+            item {
+                HomeRow(title = "Random artists") {
+                    stuffArtists.shuffled().take(10).forEach { artist ->
+                        CoverTile(
+                            title = artist.displayName,
+                            subtitle = "${artist.albumCount} albums",
+                            onClick = { onOpenArtist(artist) },
+                            art = { ArtistArt(artistName = artist.displayName, size = 112.dp, circular = true) }
+                        )
+                    }
+                }
+            }
+        }
+        if (HomeRowId.RANDOM_PLAYLISTS in rows && playlists.isNotEmpty()) {
+            item {
+                HomeRow(title = "Random playlists") {
+                    playlists.shuffled().take(10).forEach { pl ->
+                        CoverTile(
+                            title = pl.name,
+                            subtitle = "Playlist",
+                            onClick = { onOpenPlaylist(pl) },
+                            art = { PlaylistCoverArt(pl, size = 112.dp) }
+                        )
+                    }
+                }
+            }
+        }
+        if (HomeRowId.RANDOM_SONGS in rows && allSongs.isNotEmpty()) {
+            item {
+                HomeRow(title = "Random songs") {
+                    allSongs.shuffled().take(12).forEach { song ->
+                        CoverTile(
+                            title = song.displayTitle,
+                            subtitle = song.displayArtist,
+                            onClick = { onPlay(listOf(song) + allSongs.shuffled().take(20), 0) },
+                            art = { AlbumArt(song = song, size = 112.dp, corner = 8.dp) }
+                        )
+                    }
+                }
+            }
+        }
+        item { Spacer(Modifier.height(24.dp)) }
+    }
+
+    if (showAddPin) {
+        AddPinFromCollectionSheet(
+            entries = entries,
+            playlists = playlists,
+            alreadyPinned = pins.map { it.key }.toSet(),
+            library = library,
+            allSongs = allSongs,
+            onDismiss = { showAddPin = false },
+            onPick = { pin ->
+                pinStore.pin(pin)
+                showAddPin = false
+            }
+        )
+    }
+}
+
+@Composable
+private fun HomeRow(
+    title: String,
+    content: @Composable RowScope.() -> Unit
+) {
+    Column(Modifier.fillMaxWidth().padding(top = 8.dp)) {
+        Text(
+            title,
+            style = MaterialTheme.typography.titleLarge,
+            fontWeight = FontWeight.Bold,
+            modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp)
+        )
+        Row(
+            Modifier
+                .fillMaxWidth()
+                .horizontalScroll(rememberScrollState())
+                .padding(horizontal = 16.dp),
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+            content = content
+        )
+    }
+}
+
+@Composable
+private fun CoverTile(
+    title: String,
+    subtitle: String,
+    onClick: () -> Unit,
+    art: @Composable () -> Unit
+) {
+    Column(
+        Modifier
+            .width(124.dp)
+            .clip(RoundedCornerShape(12.dp))
+            .clickable(onClick = onClick)
+    ) {
+        art()
+        Text(
+            title,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            style = MaterialTheme.typography.bodyMedium,
+            fontWeight = FontWeight.Medium,
+            modifier = Modifier.padding(top = 6.dp)
+        )
+        Text(
+            subtitle,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+        )
+    }
+}
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffCatalogTab.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffCatalogTab.kt
index 5853dbb4..d429d2ae 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffCatalogTab.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffCatalogTab.kt
@@ -41,7 +41,6 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.draw.clip
 import androidx.compose.ui.layout.ContentScale
 import androidx.compose.ui.platform.LocalContext
-import androidx.compose.ui.platform.testTag
 import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.style.TextOverflow
 import androidx.compose.ui.unit.dp
@@ -65,7 +64,6 @@ import capital.yuri.yuriplayer.ui.AlbumRowSkeleton
 import capital.yuri.yuriplayer.ui.ArtistRowSkeleton
 import capital.yuri.yuriplayer.ui.LoadingEstimates
 import capital.yuri.yuriplayer.ui.SongListSkeleton
-import capital.yuri.yuriplayer.ui.TestTags
 import capital.yuri.yuriplayer.ui.formatTrackCount
 import coil3.compose.AsyncImage
 import coil3.request.ImageRequest
@@ -149,7 +147,9 @@ fun MyStuffCatalogTab(
         withContext(Dispatchers.IO) { remotePlaylists.syncOwnedToMyStuff() }
     }
 
-    BackHandler(enabled = page !is CatalogPage.Hub) { page = CatalogPage.Hub }
+    BackHandler(enabled = LocalTabBackEnabled.current && page !is CatalogPage.Hub) {
+        page = CatalogPage.Hub
+    }
 
     when (val p = page) {
         CatalogPage.Hub -> CatalogHub(
@@ -300,18 +300,8 @@ private fun CatalogHub(
 ) {
     LazyColumn(
         modifier = Modifier.fillMaxSize(),
-        contentPadding = PaddingValues(bottom = 24.dp)
+        contentPadding = PaddingValues(top = 8.dp, bottom = 24.dp)
     ) {
-        item {
-            Text(
-                "Catalog",
-                style = MaterialTheme.typography.headlineMedium,
-                fontWeight = FontWeight.Bold,
-                modifier = Modifier
-                    .padding(horizontal = 16.dp, vertical = 12.dp)
-                    .testTag(TestTags.CATALOG_TITLE)
-            )
-        }
         item {
             LibraryChipsRow(
                 sources = sources,
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsHost.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsHost.kt
index a3310101..b073940e 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsHost.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsHost.kt
@@ -10,7 +10,6 @@ import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.BoxWithConstraints
 import androidx.compose.foundation.layout.Column
-import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.aspectRatio
@@ -19,15 +18,10 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
-import androidx.compose.foundation.lazy.grid.GridCells
-import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
-import androidx.compose.foundation.shape.CircleShape
 import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.Add
-import androidx.compose.material.icons.filled.PlayArrow
 import androidx.compose.material3.Icon
-import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
@@ -67,8 +61,7 @@ fun MyStuffPinsHost(
     allSongs: List<Song>,
     onOpenPin: (StuffPin) -> Unit,
     onUnpin: (StuffPin) -> Unit,
-    onAddPinSlot: () -> Unit,
-    onPlayAll: () -> Unit
+    onAddPinSlot: () -> Unit
 ) {
     var reorderMode by remember { mutableStateOf(false) }
     var pinForSheet by remember { mutableStateOf<StuffPin?>(null) }
@@ -89,60 +82,34 @@ fun MyStuffPinsHost(
         pins.map { HostPinCell.Filled(it) } + List(emptyCount) { HostPinCell.Empty }
     }
 
-    Column(modifier = Modifier.fillMaxSize()) {
-        Row(
+    Column(modifier = Modifier.fillMaxWidth()) {
+        Column(
             modifier = Modifier
                 .fillMaxWidth()
-                .padding(horizontal = 16.dp, vertical = 8.dp),
-            verticalAlignment = Alignment.CenterVertically
-        ) {
-            Text(
-                text = "My Stuff",
-                style = MaterialTheme.typography.headlineMedium,
-                fontWeight = FontWeight.Bold,
-                modifier = Modifier.weight(1f)
-            )
-            IconButton(
-                onClick = onPlayAll,
-                modifier = Modifier
-                    .size(48.dp)
-                    .clip(CircleShape)
-                    .border(1.5.dp, MaterialTheme.colorScheme.onSurface.copy(alpha = 0.35f), CircleShape)
-            ) {
-                Icon(
-                    Icons.Default.PlayArrow,
-                    contentDescription = "Start radio from My Stuff",
-                    modifier = Modifier.size(28.dp)
-                )
-            }
-        }
-
-        LazyVerticalGrid(
-            columns = GridCells.Fixed(2),
-            modifier = Modifier.fillMaxSize(),
-            contentPadding = PaddingValues(start = 20.dp, end = 20.dp, bottom = 8.dp, top = 4.dp),
-            horizontalArrangement = Arrangement.spacedBy(12.dp),
+                .padding(start = 20.dp, end = 20.dp, bottom = 8.dp, top = 4.dp),
             verticalArrangement = Arrangement.spacedBy(12.dp)
         ) {
-            items(
-                cells.size,
-                key = { i ->
-                    when (val c = cells[i]) {
-                        is HostPinCell.Filled -> c.pin.key
-                        is HostPinCell.Empty -> "empty-$i"
+            cells.chunked(2).forEach { pair ->
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(12.dp)
+                ) {
+                    pair.forEach { cell ->
+                        Box(Modifier.weight(1f)) {
+                            when (cell) {
+                                is HostPinCell.Filled -> HostPinCard(
+                                    pin = cell.pin,
+                                    library = library,
+                                    playlists = playlists,
+                                    allSongs = allSongs,
+                                    onClick = { onOpenPin(cell.pin) },
+                                    onLongClick = { pinForSheet = cell.pin }
+                                )
+                                is HostPinCell.Empty -> HostEmptyPin(onClick = onAddPinSlot)
+                            }
+                        }
                     }
-                }
-            ) { i ->
-                when (val cell = cells[i]) {
-                    is HostPinCell.Filled -> HostPinCard(
-                        pin = cell.pin,
-                        library = library,
-                        playlists = playlists,
-                        allSongs = allSongs,
-                        onClick = { onOpenPin(cell.pin) },
-                        onLongClick = { pinForSheet = cell.pin }
-                    )
-                    is HostPinCell.Empty -> HostEmptyPin(onClick = onAddPinSlot)
+                    if (pair.size == 1) Spacer(Modifier.weight(1f))
                 }
             }
         }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTab.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTab.kt
index f2559092..2b5e7db3 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTab.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTab.kt
@@ -21,8 +21,7 @@ fun MyStuffPinsTabWired(
     allSongs: List<Song>,
     onOpenPin: (StuffPin) -> Unit,
     onUnpin: (StuffPin) -> Unit,
-    onAddPinSlot: () -> Unit,
-    onPlayAll: () -> Unit
+    onAddPinSlot: () -> Unit
 ) = MyStuffPinsHost(
     pins = pins,
     library = library,
@@ -30,6 +29,5 @@ fun MyStuffPinsTabWired(
     allSongs = allSongs,
     onOpenPin = onOpenPin,
     onUnpin = onUnpin,
-    onAddPinSlot = onAddPinSlot,
-    onPlayAll = onPlayAll
+    onAddPinSlot = onAddPinSlot
 )
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTabDelegate.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTabDelegate.kt
index e490969f..89f6b5c9 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTabDelegate.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffPinsTabDelegate.kt
@@ -19,8 +19,7 @@ fun MyStuffPinsTabPublic(
     allSongs: List<Song>,
     onOpenPin: (StuffPin) -> Unit,
     onUnpin: (StuffPin) -> Unit,
-    onAddPinSlot: () -> Unit,
-    onPlayAll: () -> Unit
+    onAddPinSlot: () -> Unit
 ) {
     MyStuffPinsHost(
         pins = pins,
@@ -29,7 +28,6 @@ fun MyStuffPinsTabPublic(
         allSongs = allSongs,
         onOpenPin = onOpenPin,
         onUnpin = onUnpin,
-        onAddPinSlot = onAddPinSlot,
-        onPlayAll = onPlayAll
+        onAddPinSlot = onAddPinSlot
     )
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffScreen.kt
index 2d5121fb..5ba304f8 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/MyStuffScreen.kt
@@ -80,8 +80,6 @@ import kotlinx.coroutines.flow.first
 import kotlinx.coroutines.launch
 import org.koin.compose.koinInject
 
-private enum class MyStuffTab { Pins, Collection, Playlists }
-
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun MyStuffScreen(
@@ -97,18 +95,10 @@ fun MyStuffScreen(
 ) {
     val pinStore: MyStuffPinStore = koinInject()
     val playlistsRepo: PlaylistRepository = koinInject()
-    val catalog: CatalogRepository = koinInject()
-    val player: PlayerController = koinInject()
-    val pins by pinStore.pins.collectAsState()
     val entries by pinStore.entries.collectAsState()
     val playlists by playlistsRepo.observePlaylistsResolved().collectAsState(initial = emptyList())
-    val allSongs by library.songs.collectAsState()
-    val scope = rememberCoroutineScope()
-    val context = LocalContext.current
 
-    var tab by remember { mutableStateOf(MyStuffTab.Pins) }
-    var showAddPin by remember { mutableStateOf(false) }
-    var showCreatePlaylist by remember { mutableStateOf(false) }
+    var showBrowseAll by remember { mutableStateOf(false) }
 
     LaunchedEffect(playlistsRepo) {
         playlistsRepo.observePlaylistsResolved().collect { list ->
@@ -116,121 +106,47 @@ fun MyStuffScreen(
         }
     }
 
-    Column(modifier = Modifier.fillMaxSize()) {
-        Box(modifier = Modifier.weight(1f)) {
-            when (tab) {
-                MyStuffTab.Pins -> MyStuffPinsHost(
-                    pins = pins,
-                    library = library,
-                    playlists = playlists,
-                    allSongs = allSongs,
-                    onOpenPin = { pin ->
-                        scope.launch {
-                            openPin(
-                                pin, library, playlists, allSongs, catalog,
-                                onOpenAlbum, onOpenArtist, onOpenPlaylist, onOpenSongAlbum, context
-                            )
-                        }
-                    },
-                    onUnpin = { pinStore.unpin(it) },
-                    onAddPinSlot = { showAddPin = true },
-                    onPlayAll = {
-                        scope.launch {
-                            val songs = resolveCollectionSongs(entries, library, playlistsRepo)
-                            if (songs.isEmpty()) {
-                                Toast.makeText(context, "Nothing in My Stuff yet", Toast.LENGTH_SHORT).show()
-                            } else {
-                                player.startPlaylistRadio(songs, "My Stuff")
-                                Toast.makeText(context, "Radio · My Stuff", Toast.LENGTH_SHORT).show()
-                            }
-                        }
-                    }
-                )
-                MyStuffTab.Collection -> MyStuffCatalogTab(
-                    entries = entries.filter { it.kind != StuffPinKind.PLAYLIST },
-                    library = library,
-                    playlists = playlists,
-                    nowPlaying = nowPlaying,
-                    isPlaybackActive = isPlaybackActive,
-                    onOpenAlbum = onOpenAlbum,
-                    onOpenArtist = onOpenArtist,
-                    onOpenPlaylist = onOpenPlaylist,
-                    onOpenSongAlbum = onOpenSongAlbum,
-                    onPlay = onPlay,
-                    onAddToQueue = onAddToQueue
-                )
-                MyStuffTab.Playlists -> MyStuffPlaylistsList(
-                    playlists = playlists,
-                    onOpen = onOpenPlaylist,
-                    onCreate = { showCreatePlaylist = true }
-                )
-            }
-        }
-
-        NavigationBar(windowInsets = WindowInsets(0, 0, 0, 0)) {
-            NavigationBarItem(
-                selected = tab == MyStuffTab.Pins,
-                onClick = { tab = MyStuffTab.Pins },
-                modifier = Modifier.testTag(TestTags.MYSTUFF_PINS),
-                icon = {
-                    Icon(
-                        if (tab == MyStuffTab.Pins) Icons.Filled.PushPin else Icons.Outlined.PushPin,
-                        contentDescription = null
-                    )
-                },
-                label = { Text("Pins") }
-            )
-            NavigationBarItem(
-                selected = tab == MyStuffTab.Collection,
-                onClick = { tab = MyStuffTab.Collection },
-                modifier = Modifier.testTag(TestTags.MYSTUFF_CATALOG),
-                icon = {
-                    Icon(
-                        if (tab == MyStuffTab.Collection) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder,
-                        contentDescription = null
-                    )
-                },
-                label = { Text("Catalog") }
-            )
-            NavigationBarItem(
-                selected = tab == MyStuffTab.Playlists,
-                onClick = { tab = MyStuffTab.Playlists },
-                modifier = Modifier.testTag(TestTags.MYSTUFF_PLAYLISTS),
-                icon = {
-                    Icon(
-                        if (tab == MyStuffTab.Playlists) Icons.Filled.QueueMusic else Icons.Outlined.QueueMusic,
-                        contentDescription = null
-                    )
-                },
-                label = { Text("Playlists") }
-            )
-        }
-    }
-
-    if (showAddPin) {
-        AddPinFromCollectionSheet(
-            entries = entries,
-            playlists = playlists,
-            alreadyPinned = pins.map { it.key }.toSet(),
+    if (showBrowseAll) {
+        BrowseAllLibraryScreen(
             library = library,
-            allSongs = allSongs,
-            onDismiss = { showAddPin = false },
-            onPick = { pin ->
-                pinStore.pin(pin)
-                showAddPin = false
-                Toast.makeText(context, "Pinned ${pin.title}", Toast.LENGTH_SHORT).show()
-            }
+            nowPlaying = nowPlaying,
+            onBack = { showBrowseAll = false },
+            onPlay = onPlay,
+            onAddToQueue = onAddToQueue,
+            onOpenAlbum = onOpenAlbum,
+            onOpenArtist = onOpenArtist,
+            onOpenPlaylist = onOpenPlaylist,
+            onOpenSongAlbum = onOpenSongAlbum
         )
+        return
     }
 
-    if (showCreatePlaylist) {
-        CreatePlaylistSheet(
-            onDismiss = { showCreatePlaylist = false },
-            onCreated = {
-                showCreatePlaylist = false
-                tab = MyStuffTab.Playlists
-            }
-        )
+    Column(modifier = Modifier.fillMaxSize().testTag(TestTags.MYSTUFF_CATALOG)) {
+        Box(modifier = Modifier.weight(1f)) {
+            MyStuffCatalogTab(
+                entries = entries.filter { it.kind != StuffPinKind.PLAYLIST },
+                library = library,
+                playlists = playlists,
+                nowPlaying = nowPlaying,
+                isPlaybackActive = isPlaybackActive,
+                onOpenAlbum = onOpenAlbum,
+                onOpenArtist = onOpenArtist,
+                onOpenPlaylist = onOpenPlaylist,
+                onOpenSongAlbum = onOpenSongAlbum,
+                onPlay = onPlay,
+                onAddToQueue = onAddToQueue
+            )
+        }
+        androidx.compose.material3.Button(
+            onClick = { showBrowseAll = true },
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 16.dp, vertical = 12.dp)
+                .height(52.dp),
+            shape = RoundedCornerShape(28.dp)
+        ) {
+            Text("All")
+        }
     }
 }
 
@@ -438,7 +354,7 @@ private fun BrowseEntryRow(
 
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
-private fun AddPinFromCollectionSheet(
+internal fun AddPinFromCollectionSheet(
     entries: List<StuffPin>,
     playlists: List<Playlist>,
     alreadyPinned: Set<String>,
@@ -542,7 +458,7 @@ private fun AddPinFromCollectionSheet(
     }
 }
 
-private suspend fun openPin(
+internal suspend fun openPin(
     pin: StuffPin,
     library: LibraryIndex,
     playlists: List<Playlist>,
@@ -583,7 +499,7 @@ private suspend fun openPin(
     }
 }
 
-private suspend fun resolveCollectionSongs(
+internal suspend fun resolveCollectionSongs(
     entries: List<StuffPin>,
     library: LibraryIndex,
     playlistsRepo: PlaylistRepository
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingPreview.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingPreview.kt
index 9d09f88d..e484efda 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingPreview.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingPreview.kt
@@ -9,7 +9,6 @@ import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxWidth
-import androidx.compose.foundation.layout.navigationBarsPadding
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.foundation.layout.width
@@ -37,11 +36,9 @@ import capital.yuri.yuriplayer.ui.TestTags
 import org.koin.compose.koinInject
 
 /**
- * Compact now-playing strip (bottom of library / detail pages).
- *
- * Uses the **app default background** — not album art colors — so it stays
- * neutral across pages. Accents (progress + play) still come from current art.
- * Full Now Playing screen keeps the art-derived background.
+ * Compact now-playing chip. Background follows the current cover; it sits
+ * in the scaffold bottom bar so lists pad above it, visually floating over
+ * the tab bar.
  */
 @Composable
 fun NowPlayingPreview(
@@ -53,9 +50,8 @@ fun NowPlayingPreview(
     onOpen: () -> Unit,
     modifier: Modifier = Modifier,
     enableSwipeUp: Boolean = false,
-    edgeToEdgeBottom: Boolean = false,
-    tonalElevation: androidx.compose.ui.unit.Dp = 0.dp,
-    shadowElevation: androidx.compose.ui.unit.Dp = 4.dp
+    tonalElevation: androidx.compose.ui.unit.Dp = 2.dp,
+    shadowElevation: androidx.compose.ui.unit.Dp = 8.dp
 ) {
     val themeStore: PlayerThemeStore = koinInject()
     val ambient = MaterialTheme.colorScheme
@@ -69,15 +65,19 @@ fun NowPlayingPreview(
         peekPrev?.songKey == song.songKey -> peekPrev
         else -> null
     }
-    val accent = matched?.colors?.accent ?: ambient.primary
-    val onAccent = matched?.colors?.onAccent ?: ambient.onPrimary
-    val trackInactive = ambient.onBackground.copy(alpha = 0.2f)
+    val colors = matched?.colors
+    val container = colors?.container ?: ambient.surfaceVariant
+    val onContainer = colors?.onContainer ?: ambient.onSurface
+    val accent = colors?.accent ?: ambient.primary
+    val onAccent = colors?.onAccent ?: ambient.onPrimary
+    val trackInactive = onContainer.copy(alpha = 0.22f)
 
     Surface(
         tonalElevation = tonalElevation,
         shadowElevation = shadowElevation,
-        color = ambient.background,
-        contentColor = ambient.onBackground,
+        shape = RoundedCornerShape(16.dp),
+        color = container,
+        contentColor = onContainer,
         modifier = modifier
             .fillMaxWidth()
             .testTag(TestTags.MINI_PLAYER)
@@ -91,9 +91,7 @@ fun NowPlayingPreview(
                 } else Modifier
             )
     ) {
-        Column(
-            modifier = if (edgeToEdgeBottom) Modifier.navigationBarsPadding() else Modifier
-        ) {
+        Column {
             PlaybackProgress(
                 positionMs = positionMs,
                 durationMs = durationMs,
@@ -124,13 +122,13 @@ fun NowPlayingPreview(
                     MarqueeText(
                         text = song?.displayTitle ?: "Not playing",
                         style = MaterialTheme.typography.bodyMedium,
-                        color = ambient.onBackground,
+                        color = onContainer,
                         modifier = Modifier.testTag(TestTags.MINI_TITLE)
                     )
                     MarqueeText(
                         text = song?.displayArtist ?: "",
                         style = MaterialTheme.typography.bodySmall,
-                        color = ambient.onBackground.copy(alpha = 0.6f),
+                        color = onContainer.copy(alpha = 0.65f),
                         modifier = Modifier.testTag(TestTags.MINI_ARTIST)
                     )
                 }
@@ -163,7 +161,8 @@ fun MiniPlayerBar(
     positionMs: Long,
     durationMs: Long,
     onToggle: () -> Unit,
-    onExpand: () -> Unit
+    onExpand: () -> Unit,
+    modifier: Modifier = Modifier
 ) {
     NowPlayingPreview(
         song = song,
@@ -173,6 +172,6 @@ fun MiniPlayerBar(
         onToggle = onToggle,
         onOpen = onExpand,
         enableSwipeUp = true,
-        edgeToEdgeBottom = true
+        modifier = modifier.padding(start = 8.dp, end = 8.dp, top = 4.dp, bottom = 8.dp)
     )
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingScreen.kt
index cf30c6f4..18b1dc8c 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/NowPlayingScreen.kt
@@ -122,8 +122,8 @@ private fun RadioSettingsIcon(
 private fun radioSessionForSettings(snapshot: QueueSnapshot): RadioSession? {
     snapshot.radioSession?.takeIf { it.active || snapshot.coldSource?.type == ColdSourceType.RADIO }
         ?.let { return it }
-    if (snapshot.coldSource?.type != ColdSourceType.RADIO) return null
-    val src = snapshot.coldSource
+    val src = snapshot.coldSource ?: return null
+    if (src.type != ColdSourceType.RADIO) return null
     return RadioSession(
         kind = RadioSessionKind.CUSTOM,
         displayName = src.title?.takeIf { it.isNotBlank() } ?: "Radio",
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/PlaylistDetailScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/PlaylistDetailScreen.kt
index f7ccc275..f44d329e 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/PlaylistDetailScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/PlaylistDetailScreen.kt
@@ -171,7 +171,7 @@ fun PlaylistDetailScreen(
             themeService.themeFromUri(
                 context = context,
                 key = "playlist:${pl.id}:${uri}",
-                uri = uri,
+                uri = android.net.Uri.parse(uri),
                 base = base,
                 surface = ArtColorSurface.COVER,
                 loadBitmap = false
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ProvidersSettingsScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ProvidersSettingsScreen.kt
index 63b4a18a..5a0a9efc 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ProvidersSettingsScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/ProvidersSettingsScreen.kt
@@ -23,6 +23,7 @@ import androidx.compose.material3.DropdownMenuItem
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
@@ -39,6 +40,7 @@ import androidx.compose.ui.text.font.FontWeight
 import androidx.compose.ui.text.input.PasswordVisualTransformation
 import androidx.compose.ui.text.input.VisualTransformation
 import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.data.ExploreSearchService
 import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
 import capital.yuri.yuriplayer.data.SyncInterval
 import capital.yuri.yuriplayer.data.source.JellyfinClient
@@ -180,6 +182,7 @@ fun ProviderEditorScreen(
     val sourcesRepo: SourceInstanceRepository = koinInject()
     val jellyfin: JellyfinClient = koinInject()
     val subsonic: SubsonicClient = koinInject()
+    val explore: ExploreSearchService = koinInject()
     val scope = rememberCoroutineScope()
 
     var loaded by remember { mutableStateOf<SourceInstanceEntity?>(null) }
@@ -221,6 +224,31 @@ fun ProviderEditorScreen(
 
     val title = if (existingId == null) "Add provider" else "Edit provider"
 
+    fun runTest() {
+        if (testing) return
+        scope.launch {
+            testing = true
+            status = null
+            val result = withContext(Dispatchers.IO) {
+                when (type) {
+                    SourceType.JELLYFIN ->
+                        jellyfin.authenticate(url, username, password)
+                            .map { "Connected as user ${it.userId.take(8)}…" }
+                    else -> {
+                        val session = SubsonicClient.Session(
+                            baseUrl = SourceInstanceRepository.normalizeBaseUrl(url),
+                            username = username,
+                            password = password
+                        )
+                        subsonic.ping(session).map { "Ping ok" }
+                    }
+                }
+            }
+            status = result.getOrElse { e -> "Failed: ${e.message ?: e}" }
+            testing = false
+        }
+    }
+
     Column(
         modifier = Modifier
             .fillMaxSize()
@@ -305,6 +333,13 @@ fun ProviderEditorScreen(
                     },
                     modifier = Modifier.fillMaxWidth()
                 )
+                Spacer(modifier = Modifier.height(12.dp))
+                OutlinedButton(
+                    onClick = { runTest() },
+                    enabled = !testing && url.isNotBlank() && username.isNotBlank()
+                ) {
+                    Text(if (testing) "Testing…" else "Test connection")
+                }
             }
         }
 
@@ -354,30 +389,7 @@ fun ProviderEditorScreen(
             SettingsNavRow(
                 title = if (testing) "Testing…" else "Test connection",
                 subtitle = "Authenticate against the server",
-                onClick = {
-                    if (testing) return@SettingsNavRow
-                    scope.launch {
-                        testing = true
-                        status = null
-                        val result = withContext(Dispatchers.IO) {
-                            when (type) {
-                                SourceType.JELLYFIN ->
-                                    jellyfin.authenticate(url, username, password)
-                                        .map { "Connected as user ${it.userId.take(8)}…" }
-                                else -> {
-                                    val session = SubsonicClient.Session(
-                                        baseUrl = SourceInstanceRepository.normalizeBaseUrl(url),
-                                        username = username,
-                                        password = password
-                                    )
-                                    subsonic.ping(session).map { "Ping ok" }
-                                }
-                            }
-                        }
-                        status = result.getOrElse { e -> "Failed: ${e.message ?: e}" }
-                        testing = false
-                    }
-                }
+                onClick = { runTest() }
             )
             SettingsNavRow(
                 title = "Save",
@@ -393,12 +405,13 @@ fun ProviderEditorScreen(
                                 }
                             }
                             if (existingId == null) {
-                                when (type) {
+                                val newId = when (type) {
                                     SourceType.JELLYFIN ->
                                         sourcesRepo.addJellyfin(display, normalized, username, password)
                                     else ->
                                         sourcesRepo.addSubsonic(display, normalized, username, password)
                                 }
+                                explore.requestRemoteScan(force = true, sourceId = newId)
                             } else {
                                 val base = loaded ?: sourcesRepo.get(existingId) ?: return@withContext
                                 val interval = if (partialOverride == "default") {
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/QueuePanel.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/QueuePanel.kt
index ea3f9e9a..e93ab956 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/QueuePanel.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/QueuePanel.kt
@@ -248,9 +248,9 @@ private fun QueueTabContent(
     val autoScroll = rememberListDragAutoScroll(listState)
     var listTopInRoot by remember { mutableFloatStateOf(0f) }
 
-    val currentKey = nowPlaying?.let { it.path ?: it.contentUri.toString() }
+    val currentKey = nowPlaying?.let { it.path ?: it.contentUri }
     fun isCurrent(song: Song): Boolean {
-        val k = song.path ?: song.contentUri.toString()
+        val k = song.path ?: song.contentUri
         return currentKey != null && k == currentKey
     }
 
@@ -289,14 +289,14 @@ private fun QueueTabContent(
 
     Column(modifier = modifier) {
         AnimatedContent(
-            targetState = nowPlaying?.let { it.path ?: it.contentUri.toString() },
+            targetState = nowPlaying?.let { it.path ?: it.contentUri },
             transitionSpec = {
                 fadeIn(tween(220)) togetherWith fadeOut(tween(160))
             },
             label = "nowPlayingCard"
         ) { key ->
             val song = nowPlaying?.takeIf {
-                (it.path ?: it.contentUri.toString()) == key
+                (it.path ?: it.contentUri) == key
             }
             if (song != null) {
                 NowPlayingQueueCard(
@@ -479,7 +479,10 @@ private fun QueueTabContent(
 }
 
 @Composable
-private fun NowPlayingQueueCard(song: Song, radioLabel: String? = null) {
+private fun NowPlayingQueueCard(
+    song: Song,
+    radioLabel: String?
+) {
     Surface(
         modifier = Modifier
             .fillMaxWidth()
@@ -670,8 +673,7 @@ private fun SwipeableQueueRow(
                         },
                         onDragCancel = { swipeX = 0f },
                         onHorizontalDrag = { _, amount ->
-                            val max = swipeThreshold * 1.4f
-                            swipeX = (swipeX + amount).coerceIn(-max, max)
+                            swipeX = (swipeX + amount).coerceIn(-swipeThreshold * 2f, swipeThreshold * 2f)
                         }
                     )
                 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SettingsScreen.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SettingsScreen.kt
index 63935ca2..88bc695f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SettingsScreen.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SettingsScreen.kt
@@ -41,6 +41,9 @@ import androidx.compose.ui.Modifier
 import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.unit.dp
 import capital.yuri.yuriplayer.BuildConfig
+import capital.yuri.yuriplayer.components.theme.AccentPicker
+import capital.yuri.yuriplayer.components.theme.ThemeModePicker
+import capital.yuri.yuriplayer.data.HomeRowId
 import capital.yuri.yuriplayer.data.LibraryIndex
 import capital.yuri.yuriplayer.data.LibraryScanMode
 import capital.yuri.yuriplayer.data.LibrarySettings
@@ -62,6 +65,7 @@ private sealed class SettingsPage {
     data object StreamingQuality : SettingsPage()
     data object PlaybackHistory : SettingsPage()
     data object Appearance : SettingsPage()
+    data object HomeLayout : SettingsPage()
     data object Sync : SettingsPage()
     data class Organize(
         val rootKey: String,
@@ -92,7 +96,7 @@ fun SettingsScreen(onBack: () -> Unit) {
         if (stack.size > 1) stack = stack.dropLast(1) else onBack()
     }
 
-    BackHandler { pop() }
+    BackHandler(enabled = stack.size > 1) { pop() }
 
     when (val p = page) {
         SettingsPage.Hub -> SettingsHubScreen(
@@ -103,6 +107,7 @@ fun SettingsScreen(onBack: () -> Unit) {
             onOpenStreamingQuality = { push(SettingsPage.StreamingQuality) },
             onOpenPlaybackHistory = { push(SettingsPage.PlaybackHistory) },
             onOpenAppearance = { push(SettingsPage.Appearance) },
+            onOpenHomeLayout = { push(SettingsPage.HomeLayout) },
             onOpenSync = { push(SettingsPage.Sync) },
             onOpenLicenses = { push(SettingsPage.OpenSourceLicenses) },
             onOpenVersion = { push(SettingsPage.VersionInfo) }
@@ -123,6 +128,7 @@ fun SettingsScreen(onBack: () -> Unit) {
         SettingsPage.StreamingQuality -> StreamingQualitySettingsScreen(onBack = { pop() })
         SettingsPage.PlaybackHistory -> PlaybackHistorySettingsScreen(onBack = { pop() })
         SettingsPage.Appearance -> AppearanceSettingsScreen(onBack = { pop() })
+        SettingsPage.HomeLayout -> HomeLayoutSettingsScreen(onBack = { pop() })
         SettingsPage.Sync -> SyncSettingsScreen(onBack = { pop() })
         is SettingsPage.Organize -> OrganizeLayoutScreen(
             rootKey = p.rootKey,
@@ -148,6 +154,7 @@ private fun SettingsHubScreen(
     onOpenStreamingQuality: () -> Unit,
     onOpenPlaybackHistory: () -> Unit,
     onOpenAppearance: () -> Unit,
+    onOpenHomeLayout: () -> Unit,
     onOpenSync: () -> Unit,
     onOpenLicenses: () -> Unit,
     onOpenVersion: () -> Unit
@@ -294,10 +301,16 @@ private fun SettingsHubScreen(
         SettingsGroup {
             SettingsNavRow(
                 title = "Appearance",
-                subtitle = "Cover · ${coverVariant.displayName}  ·  Header · ${bannerVariant.displayName}",
+                subtitle = "Theme, accent, cover colors",
                 icon = Icons.Default.ColorLens,
                 onClick = onOpenAppearance
             )
+            SettingsNavRow(
+                title = "Home rows",
+                subtitle = "Recents, random albums, and more",
+                icon = Icons.Default.LibraryMusic,
+                onClick = onOpenHomeLayout
+            )
             SettingsNavRow(
                 title = "Library browser",
                 subtitle = "Tabs, sort defaults",
@@ -353,6 +366,10 @@ private fun PlaybackEngineSettingsScreen(onBack: () -> Unit) {
             .verticalScroll(rememberScrollState())
     ) {
         SettingsTopBar(title = "Advanced playback", onBack = onBack)
+        TextNote(
+            "This list is Android-only. Desktop always uses LibVLC. " +
+                "The choice applies the next time a song starts."
+        )
 
         SettingsSectionTitle("Decoder")
         TextNote(
@@ -490,6 +507,9 @@ private fun AppearanceSettingsScreen(onBack: () -> Unit) {
     val settings: LibrarySettings = koinInject()
     var coverVariant by remember { mutableStateOf(settings.getCoverColorVariant()) }
     var bannerVariant by remember { mutableStateOf(settings.getBannerColorVariant()) }
+    var systemColors by remember { mutableStateOf(settings.useSystemColors()) }
+    var themeMode by remember { mutableStateOf(settings.getThemeMode()) }
+    var accentId by remember { mutableStateOf(settings.getAccentId()) }
 
     Column(
         modifier = Modifier
@@ -500,10 +520,41 @@ private fun AppearanceSettingsScreen(onBack: () -> Unit) {
         SettingsTopBar(title = "Appearance", onBack = onBack)
 
         TextNote(
-            text = "Colors come from your artwork. Album covers and artist headers " +
-                "can use different palettes."
+            text = "Light, dark, or follow the system. Pick an accent for the Material 3 " +
+                "primary. On Android 12+, system colors use your wallpaper palette instead."
         )
 
+        SettingsSectionTitle("Theme")
+        SettingsGroup {
+            androidx.compose.foundation.layout.Box(Modifier.padding(16.dp)) {
+                ThemeModePicker(
+                    mode = themeMode,
+                    onMode = {
+                        settings.setThemeMode(it)
+                        themeMode = it
+                    }
+                )
+            }
+            androidx.compose.foundation.layout.Box(Modifier.padding(16.dp)) {
+                AccentPicker(
+                    selectedId = accentId,
+                    onSelect = {
+                        settings.setAccentId(it)
+                        accentId = it
+                    }
+                )
+            }
+            SettingsSwitchRow(
+                title = "Use system colors",
+                subtitle = "Material You on Android 12 and newer. Accent still applies when this is off.",
+                checked = systemColors,
+                onCheckedChange = {
+                    settings.setUseSystemColors(it)
+                    systemColors = it
+                }
+            )
+        }
+
         SettingsSectionTitle("Cover")
         SettingsGroup {
             ArtColorVariant.entries.forEach { variant ->
@@ -533,7 +584,35 @@ private fun AppearanceSettingsScreen(onBack: () -> Unit) {
                 )
             }
         }
+        Spacer(modifier = Modifier.height(48.dp))
+    }
+}
 
+@Composable
+private fun HomeLayoutSettingsScreen(onBack: () -> Unit) {
+    val settings: LibrarySettings = koinInject()
+    var enabled by remember { mutableStateOf(settings.enabledHomeRows()) }
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .statusBarsPadding()
+            .verticalScroll(rememberScrollState())
+    ) {
+        SettingsTopBar(title = "Home rows", onBack = onBack)
+        TextNote("Pins stay at the top. Turn rows on or off below.")
+        SettingsGroup {
+            HomeRowId.entries.forEach { row ->
+                SettingsSwitchRow(
+                    title = row.label,
+                    subtitle = row.subtitle,
+                    checked = row in enabled,
+                    onCheckedChange = { on ->
+                        settings.setHomeRowEnabled(row, on)
+                        enabled = settings.enabledHomeRows()
+                    }
+                )
+            }
+        }
         Spacer(modifier = Modifier.height(48.dp))
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SwipeableAlbumArt.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SwipeableAlbumArt.kt
index 3431edc5..57bd03c9 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SwipeableAlbumArt.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/SwipeableAlbumArt.kt
@@ -384,7 +384,8 @@ private fun ArtCard(bitmap: Bitmap?, modifier: Modifier = Modifier) {
             Image(
                 bitmap = bitmap.asImageBitmap(),
                 contentDescription = null,
-                contentScale = ContentScale.Crop,
+                contentScale = ContentScale.Fit,
+                alignment = Alignment.Center,
                 filterQuality = FilterQuality.High,
                 modifier = Modifier.fillMaxSize()
             )
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/TabBack.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/TabBack.kt
new file mode 100644
index 00000000..ba2db288
--- /dev/null
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/TabBack.kt
@@ -0,0 +1,10 @@
+package capital.yuri.yuriplayer.activities.ui
+
+import androidx.compose.runtime.staticCompositionLocalOf
+
+/**
+ * Nested tab screens (catalog pages, browse-all) register [androidx.activity.compose.BackHandler]
+ * callbacks. Those must disable while a per-tab album/artist/playlist overlay is showing so
+ * predictive back pops the overlay instead of the tab's inner page.
+ */
+val LocalTabBackEnabled = staticCompositionLocalOf { true }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/theme/Theme.kt b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/theme/Theme.kt
index 86797d96..8a9c6a81 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/activities/ui/theme/Theme.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/activities/ui/theme/Theme.kt
@@ -1,45 +1,50 @@
 package capital.yuri.yuriplayer.activities.ui.theme
 
 import android.app.Activity
+import android.os.Build
+import androidx.compose.foundation.isSystemInDarkTheme
 import androidx.compose.material3.MaterialTheme
-import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.dynamicDarkColorScheme
+import androidx.compose.material3.dynamicLightColorScheme
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.SideEffect
-import androidx.compose.ui.graphics.Color
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
 import androidx.compose.ui.graphics.luminance
 import androidx.compose.ui.graphics.toArgb
+import androidx.compose.ui.platform.LocalContext
 import androidx.compose.ui.platform.LocalView
 import androidx.core.view.WindowCompat
-
-private val ColorBlackish = Color(0xFF1A1224)
-
-/** Always-dark purple theme. Accent customization lands in Settings later. */
-private val YuriDarkPurple = darkColorScheme(
-    primary = YuriPurple,
-    onPrimary = ColorBlackish,
-    primaryContainer = YuriPurpleDim,
-    onPrimaryContainer = YuriOnBg,
-    secondary = PurpleGrey80,
-    onSecondary = ColorBlackish,
-    tertiary = Pink80,
-    onTertiary = ColorBlackish,
-    background = YuriBg,
-    onBackground = YuriOnBg,
-    surface = YuriSurface,
-    onSurface = YuriOnBg,
-    surfaceVariant = YuriSurfaceVariant,
-    onSurfaceVariant = YuriMuted,
-    outline = YuriMuted.copy(alpha = 0.5f)
-)
+import capital.yuri.yuriplayer.components.theme.ThemeChoice
+import capital.yuri.yuriplayer.components.theme.YuriShapes
+import capital.yuri.yuriplayer.components.theme.colorScheme
+import capital.yuri.yuriplayer.components.theme.isDark
+import capital.yuri.yuriplayer.data.LibrarySettings
+import org.koin.compose.koinInject
 
 @Composable
 fun YuriPlayerTheme(
     content: @Composable () -> Unit
 ) {
-    val scheme = YuriDarkPurple
+    val settings: LibrarySettings = koinInject()
+    val colorRev by settings.colorPrefsRevision.collectAsState()
+    val context = LocalContext.current
+    val systemDark = isSystemInDarkTheme()
+    val choice = ThemeChoice(
+        mode = settings.getThemeMode(),
+        accentId = settings.getAccentId()
+    )
+    val dark = choice.isDark(systemDark)
+    val dynamic = if (colorRev >= 0 &&
+        settings.useSystemColors() &&
+        Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
+    ) {
+        if (dark) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)
+    } else {
+        null
+    }
+    val scheme = choice.colorScheme(systemDark, dynamic)
 
-    // Keep system status-bar *icons* readable against the app chrome.
-    // Light theme later: same rule (luminance of surface) flips icons automatically.
     val view = LocalView.current
     if (!view.isInEditMode) {
         SideEffect {
@@ -54,6 +59,7 @@ fun YuriPlayerTheme(
 
     MaterialTheme(
         colorScheme = scheme,
+        shapes = YuriShapes,
         typography = Typography,
         content = content
     )
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtCache.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtCache.kt
index 36cb2691..9055408c 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtCache.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtCache.kt
@@ -3,7 +3,7 @@ package capital.yuri.yuriplayer.data
 import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.BitmapFactory
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
@@ -32,7 +32,7 @@ class AlbumArtCache(
     private val thumbs = object : LinkedHashMap<String, Bitmap>(MAX_THUMB_MEMORY + 1, 0.75f, true) {
         override fun removeEldestEntry(eldest: MutableMap.MutableEntry<String, Bitmap>?): Boolean {
             val drop = size > MAX_THUMB_MEMORY
-            if (drop) Log.d(TAG, "thumb-evict ${eldest?.key}")
+            if (drop) log.d { "thumb-evict ${eldest?.key}" }
             return drop
         }
     }
@@ -40,7 +40,7 @@ class AlbumArtCache(
     private val heroes = object : LinkedHashMap<String, Bitmap>(MAX_HERO_MEMORY + 1, 0.75f, true) {
         override fun removeEldestEntry(eldest: MutableMap.MutableEntry<String, Bitmap>?): Boolean {
             val drop = size > MAX_HERO_MEMORY
-            if (drop) Log.d(TAG, "hero-evict ${eldest?.key}")
+            if (drop) log.d { "hero-evict ${eldest?.key}" }
             return drop
         }
     }
@@ -48,7 +48,7 @@ class AlbumArtCache(
     private val hq = object : LinkedHashMap<String, Bitmap>(MAX_HQ_MEMORY + 1, 0.75f, true) {
         override fun removeEldestEntry(eldest: MutableMap.MutableEntry<String, Bitmap>?): Boolean {
             val drop = size > MAX_HQ_MEMORY
-            if (drop) Log.d(TAG, "hq-evict ${eldest?.key}")
+            if (drop) log.d { "hq-evict ${eldest?.key}" }
             return drop
         }
     }
@@ -151,7 +151,7 @@ class AlbumArtCache(
                     markers.any { m -> k.contains(m, ignoreCase = true) }
                 }
                 keys.forEach { map.remove(it) }
-                if (keys.isNotEmpty()) Log.d(TAG, "invalidate album=$albumKeyStr keys=$keys")
+                if (keys.isNotEmpty()) log.d { "invalidate album=$albumKeyStr keys=$keys" }
             }
             purge(thumbs)
             purge(heroes)
@@ -163,7 +163,7 @@ class AlbumArtCache(
         thumbs.clear()
         heroes.clear()
         hq.clear()
-        Log.d(TAG, "mem-clear")
+        log.d { "mem-clear" }
     }
 
     private fun diskFile(key: String): File {
@@ -181,14 +181,14 @@ class AlbumArtCache(
             val bmp = BitmapFactory.decodeFile(f.absolutePath)?.takeIf { !it.isRecycled }
             if (bmp == null) return null
             if (minDim > 0 && maxOf(bmp.width, bmp.height) < minDim) {
-                Log.d(TAG, "disk-stale $key ${bmp.width}x${bmp.height} < $minDim")
+                log.d { "disk-stale $key ${bmp.width}x${bmp.height} < $minDim" }
                 f.delete()
                 null
             } else {
                 bmp
             }
         } catch (e: Exception) {
-            Log.w(TAG, "disk-read failed $key", e)
+            log.w(e) { "disk-read failed $key" }
             null
         }
     }
@@ -208,7 +208,7 @@ class AlbumArtCache(
             }
             trimDiskIfNeeded()
         } catch (e: Exception) {
-            Log.w(TAG, "disk-write failed $key", e)
+            log.w(e) { "disk-write failed $key" }
         }
     }
 
@@ -242,7 +242,7 @@ class AlbumArtCache(
             lock.withLock {
                 map[key]?.takeIf { !it.isRecycled }?.let { return it }
                 map[key] = fromDisk
-                Log.d(TAG, "disk-hit $key mem=${map.size}")
+                log.d { "disk-hit $key mem=${map.size}" }
             }
             return fromDisk
         }
@@ -289,7 +289,7 @@ class AlbumArtCache(
         lock.withLock {
             map[key]?.takeIf { !it.isRecycled }?.let { return it }
             map[key] = bmp
-            Log.d(TAG, "decode-put $key mem=${map.size}")
+            log.d { "decode-put $key mem=${map.size}" }
         }
         return bmp
     }
@@ -314,7 +314,7 @@ class AlbumArtCache(
             try {
                 get(context, song, tier)
             } catch (e: Exception) {
-                Log.w(TAG, "prefetch failed $key", e)
+                log.w(e) { "prefetch failed $key" }
             }
         }
     }
@@ -337,7 +337,7 @@ class AlbumArtCache(
     }
 
     companion object {
-        private const val TAG = "YuriPlayer.ArtCache"
+        private val log = yuriLog("ArtCache")
         const val THUMB_DECODE_SIZE = 128
         const val HERO_DECODE_SIZE = 512
         /** Now-playing cover. Stylo 4 NP art is ~680px; 512 looked soft. */
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtResolver.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtResolver.kt
index 82fafad3..aff28c29 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtResolver.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumArtResolver.kt
@@ -5,7 +5,7 @@ import android.graphics.Bitmap
 import android.graphics.BitmapFactory
 import android.media.MediaMetadataRetriever
 import android.net.Uri
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.documentfile.provider.DocumentFile
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.sync.Mutex
@@ -30,7 +30,7 @@ import java.util.concurrent.ConcurrentHashMap
  */
 object AlbumArtResolver {
 
-    private const val TAG = "AlbumArtResolver"
+    private val log = yuriLog("AlbumArtResolver")
     private const val MAX_SAF_EXTRACT_BYTES = 80L * 1024L * 1024L
     /** Master cover stored under filesDir/covers — big enough for now-playing. */
     private const val PERSISTENT_COVER_SIZE = 1024
@@ -64,7 +64,7 @@ object AlbumArtResolver {
                 return@withContext scaleDown(it, maxSize)
             }
 
-            loadImageUri(context, song.albumArtUri, maxSize)?.also {
+            loadImageUri(context, song.albumArtUri?.let { Uri.parse(it) }, maxSize)?.also {
                 cacheToDisk(context, song, it)
                 return@withContext scaleDown(it, maxSize)
             }
@@ -93,29 +93,29 @@ object AlbumArtResolver {
                 // Stream FLAC picture first (SAF-friendly, no full-file copy)
                 loadStreamEmbedded(context, song, maxSize)?.also {
                     cacheToDisk(context, song, it)
-                    Log.i(TAG, "stream art ok album=$aKey")
+                    log.i { "stream art ok album=$aKey" }
                     return@withContext scaleDown(it, maxSize)
                 }
 
                 loadEmbeddedMmr(context, song, maxSize)?.also {
                     cacheToDisk(context, song, it)
-                    Log.i(TAG, "MMR art ok album=$aKey")
+                    log.i { "MMR art ok album=$aKey" }
                     return@withContext scaleDown(it, maxSize)
                 }
 
                 loadEmbeddedJaudio(context, song, maxSize)?.also {
                     cacheToDisk(context, song, it)
-                    Log.i(TAG, "jaudio art ok album=$aKey")
+                    log.i { "jaudio art ok album=$aKey" }
                     return@withContext scaleDown(it, maxSize)
                 }
 
                 // Last resort: an undersized cached cover beats a blank now-playing card.
                 loadDiskAlbumCache(context, song, maxSize, minDim = 0)?.let {
-                    Log.w(TAG, "undersized cache art album=$aKey ${it.width}x${it.height} want=$maxSize")
+                    log.w { "undersized cache art album=$aKey ${it.width}x${it.height} want=$maxSize" }
                     return@withContext scaleDown(it, maxSize)
                 }
 
-                Log.w(TAG, "no art for album=$aKey path=${song.path} uri=${song.contentUri}")
+                log.w { "no art for album=$aKey path=${song.path} uri=${song.contentUri}" }
             }
 
             null
@@ -136,7 +136,7 @@ object AlbumArtResolver {
                 if (!bmp.isRecycled) runCatching { bmp.recycle() }
                 true
             } catch (e: Exception) {
-                Log.w(TAG, "downloadToFile failed $url", e)
+                log.w(e) { "downloadToFile failed $url" }
                 false
             }
         }
@@ -213,7 +213,7 @@ object AlbumArtResolver {
             }
             dest.isFile && dest.length() > 0L
         } catch (e: Exception) {
-            Log.w(TAG, "writeBitmapFile failed", e)
+            log.w(e) { "writeBitmapFile failed" }
             false
         }
     }
@@ -301,8 +301,8 @@ object AlbumArtResolver {
         }
 
         val uri = when {
-            song.contentUri.scheme.equals("content", true) -> song.contentUri
-            song.contentUri.scheme.equals("file", true) -> song.contentUri
+            Uri.parse(song.contentUri).scheme.equals("content", true) -> Uri.parse(song.contentUri)
+            Uri.parse(song.contentUri).scheme.equals("file", true) -> Uri.parse(song.contentUri)
             !path.isNullOrBlank() && path.contains("://") -> Uri.parse(path)
             else -> null
         } ?: return null
@@ -312,7 +312,7 @@ object AlbumArtResolver {
                 streamEmbeddedFrom(input, uri.toString(), maxSize)
             }
         } catch (e: Exception) {
-            Log.d(TAG, "stream open failed: ${e.message}")
+            log.d { "stream open failed: ${e.message}" }
             null
         }
     }
@@ -340,7 +340,7 @@ object AlbumArtResolver {
             else -> null
         }
         if (bytes == null) {
-            Log.d(TAG, "stream no picture for $label flac=$isFlac id3=$isId3")
+            log.d { "stream no picture for $label flac=$isFlac id3=$isId3" }
             return null
         }
         return decodeBytesSampled(bytes, maxSize)
@@ -395,7 +395,7 @@ object AlbumArtResolver {
             }
             null
         } catch (e: Exception) {
-            Log.d(TAG, "FLAC picture parse failed: ${e.message}")
+            log.d { "FLAC picture parse failed: ${e.message}" }
             null
         }
     }
@@ -451,7 +451,7 @@ object AlbumArtResolver {
             }
             null
         } catch (e: Exception) {
-            Log.d(TAG, "ID3 APIC parse failed: ${e.message}")
+            log.d { "ID3 APIC parse failed: ${e.message}" }
             null
         }
     }
@@ -491,7 +491,7 @@ object AlbumArtResolver {
             val bytes = retriever.embeddedPicture ?: return null
             decodeBytesSampled(bytes, maxSize)
         } catch (e: Exception) {
-            Log.d(TAG, "MMR embedded failed: ${e.message}")
+            log.d { "MMR embedded failed: ${e.message}" }
             null
         } finally {
             try {
@@ -517,7 +517,7 @@ object AlbumArtResolver {
             } catch (_: Exception) {
             }
         }
-        val uri = song.contentUri
+        val uri = Uri.parse(song.contentUri)
         val scheme = uri.scheme?.lowercase()
         if (scheme == "content" || scheme == "file") {
             try {
@@ -540,8 +540,8 @@ object AlbumArtResolver {
             }
         }
 
-        if (song.contentUri.scheme.equals("file", true)) {
-            val p = song.contentUri.path
+        if (Uri.parse(song.contentUri).scheme.equals("file", true)) {
+            val p = Uri.parse(song.contentUri).path
             if (!p.isNullOrBlank()) {
                 val f = File(p)
                 if (f.isFile && f.canRead()) {
@@ -550,8 +550,8 @@ object AlbumArtResolver {
             }
         }
 
-        if (song.contentUri.scheme.equals("content", true)) {
-            return extractJaudioFromContentUri(context, song.contentUri, maxSize)
+        if (Uri.parse(song.contentUri).scheme.equals("content", true)) {
+            return extractJaudioFromContentUri(context, Uri.parse(song.contentUri), maxSize)
         }
 
         return null
@@ -566,7 +566,7 @@ object AlbumArtResolver {
             if (bytes.isEmpty()) return null
             decodeBytesSampled(bytes, maxSize)
         } catch (t: Throwable) {
-            Log.w(TAG, "jaudio art failed ${file.name}: ${t.javaClass.simpleName}: ${t.message}")
+            log.w { "jaudio art failed ${file.name}: ${t.javaClass.simpleName}: ${t.message}" }
             null
         }
     }
@@ -574,7 +574,7 @@ object AlbumArtResolver {
     private fun extractJaudioFromContentUri(context: Context, uri: Uri, maxSize: Int): Bitmap? {
         val size = querySize(context, uri)
         if (size != null && size > MAX_SAF_EXTRACT_BYTES) {
-            Log.w(TAG, "skip jaudio SAF extract size=$size")
+            log.w { "skip jaudio SAF extract size=$size" }
             return null
         }
 
@@ -587,7 +587,7 @@ object AlbumArtResolver {
             if (tmp.length() == 0L) return null
             extractJaudioArtwork(tmp, maxSize)
         } catch (t: Throwable) {
-            Log.w(TAG, "jaudio SAF art failed: ${t.javaClass.simpleName}: ${t.message}")
+            log.w { "jaudio SAF art failed: ${t.javaClass.simpleName}: ${t.message}" }
             null
         } finally {
             runCatching { tmp.delete() }
@@ -648,7 +648,7 @@ object AlbumArtResolver {
     }
 
     private fun loadSafFolderCover(context: Context, song: Song, maxSize: Int): Bitmap? {
-        val uri = song.contentUri
+        val uri = Uri.parse(song.contentUri)
         if (!uri.scheme.equals("content", true)) return null
         return try {
             val doc = DocumentFile.fromSingleUri(context, uri) ?: return null
@@ -663,7 +663,7 @@ object AlbumArtResolver {
             }
             null
         } catch (e: Exception) {
-            Log.d(TAG, "SAF folder cover failed: ${e.message}")
+            log.d { "SAF folder cover failed: ${e.message}" }
             null
         }
     }
@@ -680,7 +680,7 @@ object AlbumArtResolver {
     private fun loadImageUri(context: Context, uri: Uri?, maxSize: Int): Bitmap? {
         if (uri == null) return null
         if (!isLikelyImageUri(context, uri)) {
-            Log.d(TAG, "skip non-image uri $uri")
+            log.d { "skip non-image uri $uri" }
             return null
         }
         val scheme = uri.scheme?.lowercase()
@@ -699,7 +699,7 @@ object AlbumArtResolver {
                     decodeStreamSampled(input, maxSize)
                 }
             } catch (e: Exception) {
-                Log.d(TAG, "loadImageUri failed: ${e.message}")
+                log.d { "loadImageUri failed: ${e.message}" }
                 null
             }
         }
@@ -766,13 +766,13 @@ object AlbumArtResolver {
             }
             val code = conn.responseCode
             if (code !in 200..299) {
-                Log.w(TAG, "HTTP $code for $url")
+                log.w { "HTTP $code for $url" }
                 conn.disconnect()
                 return null
             }
             conn.inputStream
         } catch (e: Exception) {
-            Log.w(TAG, "openHttp failed $url", e)
+            log.w(e) { "openHttp failed $url" }
             null
         }
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumCoverPrefs.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumCoverPrefs.kt
index 4860f0d3..861fde38 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumCoverPrefs.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumCoverPrefs.kt
@@ -34,13 +34,4 @@ class AlbumCoverPrefs(context: Context) {
     }
 }
 
-/** One selectable cover for an album (local tags, folder, remote HTTP, etc.). */
-data class CoverCandidate(
-    val id: String,
-    val label: String,
-    /** Content/file/http URI used for decode + preference storage. */
-    val uri: String,
-    /** Optional local song used to pull embedded/folder art. */
-    val seedSong: Song? = null,
-    val isLocal: Boolean = false
-)
+// CoverCandidate moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumLog.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumLog.kt
index 30fc84e0..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumLog.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumLog.kt
@@ -1,94 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-import android.util.Log
-import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
-
-/**
- * Album expand / merge diagnostics.
- *
- * Tag is always [TAG] = `YuriAlbum`. Every line starts with `[album title]` so you
- * can grep Clancy / self-titled without knowing the code path.
- *
- * Logcat (VERBOSE = TRACE):
- * ```
- * adb shell setprop log.tag.YuriAlbum VERBOSE
- * adb logcat -v time YuriAlbum:V *:S
- * adb logcat -v time YuriAlbum:V *:S | grep -i clancy
- * adb logcat -v time YuriAlbum:V *:S | grep -i 'twenty one pilots'
- * ```
- *
- * Android Studio Logcat: package `capital.yuri.yuriplayer`, tag `YuriAlbum`,
- * level **Verbose**.
- *
- * Levels:
- * - V / TRACE — every track, every identity group member
- * - D         — query step counts, grouping
- * - I         — path summaries (seed → expand → merge → page)
- * - W         — collapse / identity collision / never-shrink
- */
-internal object AlbumLog {
-    const val TAG = "YuriAlbum"
-
-    fun i(album: String?, msg: String) = Log.i(TAG, line(album, msg))
-    fun d(album: String?, msg: String) = Log.d(TAG, line(album, msg))
-    fun v(album: String?, msg: String) = Log.v(TAG, line(album, msg))
-    fun w(album: String?, msg: String) = Log.w(TAG, line(album, msg))
-
-    fun step(album: String?, name: String, count: Int, extra: String = "") {
-        val suffix = if (extra.isNotEmpty()) " $extra" else ""
-        Log.d(TAG, line(album, "step $name n=$count$suffix"))
-    }
-
-    fun songs(album: String?, label: String, tracks: List<Song>) {
-        Log.d(TAG, line(album, "$label n=${tracks.size}"))
-        tracks.forEachIndexed { i, s ->
-            Log.v(TAG, line(album, "  $label[$i] ${songLine(s)}"))
-        }
-    }
-
-    fun entities(album: String?, label: String, rows: Collection<CatalogTrackEntity>) {
-        Log.d(TAG, line(album, "$label n=${rows.size}"))
-        rows.forEachIndexed { i, r ->
-            Log.v(TAG, line(album, "  $label[$i] ${entityLine(r)}"))
-        }
-    }
-
-    fun identityGroups(album: String?, groups: Map<String, List<Song>>) {
-        Log.d(TAG, line(album, "identity groups=${groups.size}"))
-        groups.forEach { (id, members) ->
-            if (members.size > 1) {
-                Log.w(
-                    TAG,
-                    line(
-                        album,
-                        "COLLIDE identity=$id n=${members.size} titles=${members.joinToString(" | ") { it.displayTitle }}"
-                    )
-                )
-                members.forEachIndexed { i, s ->
-                    Log.v(TAG, line(album, "    collide[$i] ${songLine(s)}"))
-                }
-            } else {
-                Log.v(TAG, line(album, "  id=$id → ${members.firstOrNull()?.displayTitle}"))
-            }
-        }
-    }
-
-    fun songLine(s: Song): String {
-        val src = CatalogRepository.sourceTypeForSong(s)
-        return "title='${s.title}' tn=${s.trackNumber} disc=${s.discNumber} " +
-            "album='${s.album}' aa='${s.albumArtist}' ar='${s.artist}' " +
-            "src=$src key=${s.songKey} path=${s.path} " +
-            "aKey=${albumKey(s.album, s.effectiveAlbumArtist)} id=${albumPageIdentity(s)}"
-    }
-
-    fun entityLine(r: CatalogTrackEntity): String =
-        "title='${r.title}' tn=${r.trackNumber} disc=${r.discNumber} " +
-            "album='${r.album}' aa='${r.albumArtist}' ar='${r.artist}' " +
-            "src=${r.sourceType} songKey=${r.songKey} aKey=${r.albumKey} " +
-            "artistKey=${r.artistKey} ext=${r.externalId}"
-
-    private fun line(album: String?, msg: String): String {
-        val label = album?.trim().orEmpty().ifBlank { "?" }
-        return "[$label] $msg"
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumMerge.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumMerge.kt
index dd627793..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumMerge.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumMerge.kt
@@ -1,132 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-/**
- * Union every known copy of a release. Multi-source = one logical track with
- * offerings, NOT duplicate album cards. Never replaces a rich list with a thinner one.
- */
-fun mergeAlbumSources(
-    seed: AlbumItem,
-    fromCatalog: AlbumItem?,
-    fromLocal: AlbumItem?
-): AlbumItem {
-    val album = seed.name ?: fromCatalog?.name ?: fromLocal?.name
-    AlbumLog.i(
-        album,
-        "merge seed=${seed.songs.size} catalog=${fromCatalog?.songs?.size ?: 0} local=${fromLocal?.songs?.size ?: 0} " +
-            "seedName='${seed.name}' catName='${fromCatalog?.name}' localName='${fromLocal?.name}'"
-    )
-    AlbumLog.songs(album, "merge.seed", seed.songs)
-    AlbumLog.songs(album, "merge.catalog", fromCatalog?.songs.orEmpty())
-    AlbumLog.songs(album, "merge.local", fromLocal?.songs.orEmpty())
-
-    val merged = dedupeAlbumPageTracks(
-        buildList {
-            addAll(fromCatalog?.songs.orEmpty())
-            addAll(fromLocal?.songs.orEmpty())
-            addAll(seed.songs)
-        }
-    )
-    if (merged.isEmpty()) {
-        AlbumLog.w(album, "merge empty → keep seed")
-        return seed
-    }
-
-    // Absolute never-shrink against every input
-    val richest = listOfNotNull(
-        fromCatalog?.songs?.size,
-        fromLocal?.songs?.size,
-        seed.songs.size,
-        merged.size
-    ).maxOrNull() ?: merged.size
-
-    val songs = if (merged.size < richest && seed.songs.size >= richest) {
-        dedupeAlbumPageTracks(seed.songs + merged)
-    } else if (merged.size < richest && (fromCatalog?.songs?.size ?: 0) >= richest) {
-        dedupeAlbumPageTracks(fromCatalog!!.songs + merged)
-    } else if (merged.size < richest && (fromLocal?.songs?.size ?: 0) >= richest) {
-        dedupeAlbumPageTracks(fromLocal!!.songs + merged)
-    } else {
-        merged
-    }
-
-    if (songs.size < richest) {
-        AlbumLog.w(album, "merge SHRANK richest=$richest → ${songs.size}")
-        AlbumLog.songs(album, "merge.out", songs)
-    } else {
-        AlbumLog.i(album, "merge out n=${songs.size} richest=$richest")
-    }
-
-    return AlbumItem(
-        name = seed.name
-            ?: fromLocal?.name
-            ?: fromCatalog?.name
-            ?: songs.firstOrNull()?.album,
-        artist = fromCatalog?.artist
-            ?: fromLocal?.artist
-            ?: seed.artist
-            ?: songs.firstOrNull()?.effectiveAlbumArtist,
-        trackCount = songs.size.coerceAtLeast(
-            listOfNotNull(
-                fromCatalog?.trackCount,
-                fromLocal?.trackCount,
-                seed.trackCount,
-                songs.size
-            ).maxOrNull() ?: 0
-        ),
-        songs = songs
-    )
-}
-
-fun findLocalAlbum(
-    library: LibraryIndex,
-    name: String?,
-    artist: String?
-): AlbumItem? {
-    if (name.isNullOrBlank()) return null
-    val key = albumKey(name, artist)
-
-    library.albums(taggedOnly = false).firstOrNull {
-        albumKey(it.name, it.artist) == key
-    }?.let {
-        AlbumLog.i(name, "findLocalAlbum exact key='$key' n=${it.songs.size}")
-        return it
-    }
-
-    library.albums(taggedOnly = false).firstOrNull {
-        TrackIdentity.albumsMatch(it.name, name) &&
-            (artist.isNullOrBlank() || TrackIdentity.albumArtistsMatch(it.artist, artist))
-    }?.let {
-        AlbumLog.i(name, "findLocalAlbum fuzzy n=${it.songs.size} artist='${it.artist}'")
-        return it
-    }
-
-    library.albums(taggedOnly = false).firstOrNull {
-        TrackIdentity.albumsNearlyMatch(it.name, name) &&
-            (artist.isNullOrBlank() || TrackIdentity.albumArtistsMatch(it.artist, artist))
-    }?.let {
-        AlbumLog.i(name, "findLocalAlbum typo n=${it.songs.size} local='${it.name}'")
-        return it
-    }
-
-    val nameFolded = TrackIdentity.normalizeToken(name)
-    val artistFolded = TrackIdentity.normalizeToken(artist)
-    val matches = library.songs.value.filter { song ->
-        TrackIdentity.albumsMatch(song.album, name) ||
-            TrackIdentity.normalizeToken(song.album) == nameFolded
-    }.filter { song ->
-        if (artistFolded.isEmpty()) return@filter true
-        val aa = TrackIdentity.normalizeToken(song.effectiveAlbumArtist)
-        if (aa.isEmpty()) return@filter true
-        aa == artistFolded || aa.contains(artistFolded) || artistFolded.contains(aa)
-    }
-    if (matches.isEmpty()) return null
-    AlbumLog.i(name, "findLocalAlbum matches=${matches.size} key='$key'")
-    AlbumLog.songs(name, "findLocal", matches)
-    val deduped = dedupeAlbumPageTracks(matches)
-    return AlbumItem(
-        name = name,
-        artist = artist ?: deduped.firstOrNull()?.effectiveAlbumArtist,
-        trackCount = deduped.size,
-        songs = deduped
-    )
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumResolve.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumResolve.kt
index fdde8278..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumResolve.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumResolve.kt
@@ -1,52 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-import capital.yuri.yuriplayer.data.db.CatalogDao
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.withContext
-
-/**
- * Full [AlbumItem] for the album page from catalog + optional seed + local index.
- * Never returns fewer songs than a multi-track seed.
- */
-suspend fun resolveAlbumItem(
-    dao: CatalogDao,
-    name: String?,
-    artist: String?,
-    seedSongs: List<Song> = emptyList(),
-    library: LibraryIndex? = null
-): AlbumItem? = withContext(Dispatchers.IO) {
-    if (name.isNullOrBlank() && seedSongs.isEmpty()) return@withContext null
-    val albumName = name ?: seedSongs.firstOrNull()?.album
-    val artistName = artist ?: seedSongs.firstOrNull()?.effectiveAlbumArtist
-    if (albumName.isNullOrBlank()) return@withContext null
-
-    val key = albumKey(albumName, artistName)
-    AlbumLog.i(albumName, "resolve artist='$artistName' key='$key' seed=${seedSongs.size}")
-    AlbumLog.songs(albumName, "resolve.seed", seedSongs)
-
-    val expanded = expandAlbumTracksByName(
-        dao = dao,
-        albumName = albumName,
-        artistName = artistName,
-        seedKey = key,
-        extraSeedSongs = seedSongs
-    )
-    AlbumLog.songs(albumName, "resolve.expanded", expanded)
-
-    val localSongs = library?.let { findLocalAlbum(it, albumName, artistName)?.songs }.orEmpty()
-    AlbumLog.songs(albumName, "resolve.local", localSongs)
-
-    val songs = dedupeAlbumPageTracks(expanded + seedSongs + localSongs)
-    AlbumLog.i(albumName, "resolve done n=${songs.size} expanded=${expanded.size} seed=${seedSongs.size} local=${localSongs.size}")
-    if (songs.size < seedSongs.size && seedSongs.size > 1) {
-        AlbumLog.w(albumName, "RESOLVE SHRANK seed=${seedSongs.size} → ${songs.size}")
-    }
-    if (songs.isEmpty()) return@withContext null
-
-    AlbumItem(
-        name = albumName,
-        artist = artistName ?: songs.firstOrNull()?.effectiveAlbumArtist,
-        trackCount = songs.size,
-        songs = songs
-    )
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt
index ccacae65..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt
@@ -1,338 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-import capital.yuri.yuriplayer.data.db.CatalogDao
-import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
-
-/**
- * Full release resolution for the album page.
- *
- * Strategy (in order):
- *  1. Every catalog row whose album tag equals the name (any albumKey / source)
- *  2. Every albumKey that shares that album name, then all rows under those keys
- *  3. Seed / navigation tracks
- *  4. Artist filter (strict when artist known — keeps "Let Them Talk" artists apart)
- *  5. Dedupe **sources of the same song** via disc+track#+title — never collapse
- *     different songs on the same album (Clancy = 14 rows, not 1).
- */
-suspend fun expandAlbumTracks(
-    dao: CatalogDao,
-    albumKey: String
-): List<Song> {
-    if (albumKey.isBlank()) return emptyList()
-
-    val direct = dao.getTracksForAlbum(albumKey)
-    val row = dao.getAlbum(albumKey)
-    val albumName = row?.name
-        ?: direct.firstOrNull()?.album
-        ?: albumKey.substringAfter('|', missingDelimiterValue = "").takeIf { it.isNotBlank() }
-    val artistName = row?.artist
-        ?: direct.firstOrNull()?.let { it.albumArtist ?: it.artist }
-        ?: albumKey.substringBefore('|').takeIf { it.isNotBlank() }
-
-    AlbumLog.i(albumName, "expand key='$albumKey' artist='$artistName' direct=${direct.size} row=${row != null}")
-    AlbumLog.entities(albumName, "direct", direct)
-
-    return expandAlbumTracksByName(
-        dao = dao,
-        albumName = albumName,
-        artistName = artistName,
-        seedKey = albumKey,
-        seedRows = direct
-    )
-}
-
-/** Two SQL lookups, no search. Enough to paint the album page immediately. */
-suspend fun fastExpandAlbumTracks(
-    dao: CatalogDao,
-    albumName: String?,
-    artistName: String?,
-    seedKey: String? = null,
-    extraSeedSongs: List<Song> = emptyList()
-): List<Song> {
-    val name = albumName?.trim().orEmpty()
-    val artist = artistName?.trim().orEmpty()
-    if (name.isEmpty() && seedKey.isNullOrBlank() && extraSeedSongs.isEmpty()) return emptyList()
-
-    val bySongKey = LinkedHashMap<String, CatalogTrackEntity>()
-    fun put(row: CatalogTrackEntity) { bySongKey.putIfAbsent(row.songKey, row) }
-
-    if (!seedKey.isNullOrBlank()) {
-        dao.getTracksForAlbum(seedKey).forEach { put(it) }
-    }
-    if (name.isNotEmpty()) {
-        dao.getTracksForAlbumNameArtist(name, artist, limit = 400).forEach { put(it) }
-        if (bySongKey.size < 4) {
-            dao.getTracksByAlbumName(name, limit = 400).forEach { put(it) }
-        }
-    }
-
-    val artistFolded = foldTagToken(primaryArtistName(artistName) ?: artistName ?: "")
-    val songs = bySongKey.values.filter { row ->
-        val albumOk = name.isEmpty() ||
-            TrackIdentity.albumsMatch(row.album, name) ||
-            TrackIdentity.albumsNearlyMatch(row.album, name) ||
-            (!seedKey.isNullOrBlank() && row.albumKey == seedKey)
-        if (!albumOk) return@filter false
-        if (artistFolded.isEmpty()) return@filter true
-        val aa = foldTagToken(
-            primaryArtistName(row.albumArtist ?: row.artist) ?: row.albumArtist ?: row.artist ?: ""
-        )
-        val ta = foldTagToken(primaryArtistName(row.artist) ?: row.artist ?: "")
-        aa.isEmpty() || aa == artistFolded || ta == artistFolded ||
-            aa.contains(artistFolded) || artistFolded.contains(aa)
-    }.map { it.toSong() }
-
-    val deduped = dedupeAlbumPageTracks(songs + extraSeedSongs)
-    AlbumLog.i(name, "fast expand n=${deduped.size} raw=${bySongKey.size}")
-    return deduped.sortedWith(albumTrackOrder())
-}
-
-suspend fun expandAlbumTracksByName(
-    dao: CatalogDao,
-    albumName: String?,
-    artistName: String?,
-    seedKey: String? = null,
-    seedRows: List<CatalogTrackEntity> = emptyList(),
-    extraSeedSongs: List<Song> = emptyList()
-): List<Song> {
-    if (albumName.isNullOrBlank() && seedKey.isNullOrBlank() && seedRows.isEmpty() && extraSeedSongs.isEmpty()) {
-        return emptyList()
-    }
-
-    val bySongKey = LinkedHashMap<String, CatalogTrackEntity>()
-    val name = albumName?.trim().orEmpty()
-    val artist = artistName?.trim().orEmpty()
-
-    fun put(row: CatalogTrackEntity) {
-        bySongKey.putIfAbsent(row.songKey, row)
-    }
-
-    seedRows.forEach { put(it) }
-    AlbumLog.step(name.ifEmpty { albumName }, "seedRows", seedRows.size)
-
-    if (!seedKey.isNullOrBlank()) {
-        val keyed = dao.getTracksForAlbum(seedKey)
-        keyed.forEach { put(it) }
-        AlbumLog.step(name.ifEmpty { albumName }, "seedKey", keyed.size, "key=$seedKey")
-    }
-
-    if (name.isNotEmpty()) {
-        // Primary: album tag + artist SQL
-        dao.getTracksForAlbumNameArtist(name, artist, limit = 1500).forEach { put(it) }
-        AlbumLog.step(name, "name+artist SQL", bySongKey.size, "artist='$artist'")
-
-        dao.getTracksByAlbumName(name, limit = 1500).forEach { put(it) }
-        AlbumLog.step(name, "name-only SQL", bySongKey.size)
-
-        val keys = dao.albumKeysForAlbumName(name).toMutableSet()
-        if (!seedKey.isNullOrBlank()) keys += seedKey
-        keys += albumKey(name, artistName)
-        if (artist.isNotEmpty()) {
-            keys += albumKey(name, null)
-        }
-        AlbumLog.d(name, "albumKeys=${keys.size} ${keys.joinToString()}")
-        for (k in keys) {
-            if (k.isBlank()) continue
-            val rows = dao.getTracksForAlbum(k)
-            rows.forEach { put(it) }
-            AlbumLog.v(name, "  key '$k' → ${rows.size}")
-        }
-        AlbumLog.step(name, "after keys", bySongKey.size)
-
-        if (name.length >= 16) {
-            val needle = name.take(28)
-            val hits = dao.searchTracks(needle, limit = 400)
-            var added = 0
-            hits.forEach { t ->
-                if (TrackIdentity.albumsNearlyMatch(t.album, name)) {
-                    val before = bySongKey.size
-                    put(t)
-                    if (bySongKey.size > before) added++
-                }
-            }
-            AlbumLog.step(name, "near-name search", bySongKey.size, "hits=${hits.size} added=$added")
-        }
-
-        if (bySongKey.size < 3) {
-            val needle = name.take(48)
-            if (needle.length >= 2) {
-                val hits = dao.searchTracks(needle, limit = 600)
-                var added = 0
-                hits.forEach { t ->
-                    if (TrackIdentity.albumsMatch(t.album, name)) {
-                        val before = bySongKey.size
-                        put(t)
-                        if (bySongKey.size > before) added++
-                    }
-                }
-                AlbumLog.step(name, "search fallback", bySongKey.size, "hits=${hits.size} added=$added")
-            }
-        }
-    }
-
-    val artistFolded = foldTagToken(primaryArtistName(artistName) ?: artistName ?: "")
-
-    fun artistOk(t: CatalogTrackEntity): Boolean {
-        if (artistFolded.isEmpty()) return true
-        val aa = foldTagToken(
-            primaryArtistName(t.albumArtist ?: t.artist) ?: t.albumArtist ?: t.artist ?: ""
-        )
-        val ta = foldTagToken(primaryArtistName(t.artist) ?: t.artist ?: "")
-        if (aa.isEmpty() && ta.isEmpty()) return true
-        if (aa == artistFolded || ta == artistFolded) return true
-        return aa.contains(artistFolded) || artistFolded.contains(aa) ||
-            ta.contains(artistFolded) || artistFolded.contains(ta)
-    }
-
-    fun albumOk(t: CatalogTrackEntity): Boolean {
-        if (name.isEmpty()) return true
-        if (TrackIdentity.albumsMatch(t.album, name)) return true
-        if (TrackIdentity.albumsNearlyMatch(t.album, name)) return true
-        if (!seedKey.isNullOrBlank() && t.albumKey == seedKey) return true
-        return false
-    }
-
-    extraSeedSongs.take(4).forEach { seed ->
-        val q = seed.title?.trim().orEmpty()
-        if (q.length < 3) return@forEach
-        dao.searchTracks(q.take(48), limit = 80).forEach { t ->
-            if (!artistOk(t)) return@forEach
-            val titleHit = TrackIdentity.titlesNearlyMatch(t.title, seed.title, minLen = 6)
-            val albumHit = TrackIdentity.albumsNearlyMatch(t.album, name)
-            if (!titleHit && !albumHit) return@forEach
-            put(t)
-            if (!t.albumKey.isNullOrBlank()) {
-                dao.getTracksForAlbum(t.albumKey).forEach { put(it) }
-            }
-        }
-    }
-
-    val filtered = bySongKey.values.filter { albumOk(it) && artistOk(it) }
-    val dropped = bySongKey.size - filtered.size
-    if (dropped > 0) {
-        AlbumLog.w(name, "filter dropped $dropped/${bySongKey.size} artistFold='$artistFolded'")
-        bySongKey.values.filter { !albumOk(it) || !artistOk(it) }.forEach {
-            AlbumLog.v(
-                name,
-                "  DROP albumOk=${albumOk(it)} artistOk=${artistOk(it)} ${AlbumLog.entityLine(it)}"
-            )
-        }
-    }
-    AlbumLog.entities(name, "filtered", filtered)
-
-    val fromDb = filtered.map { it.toSong() }
-    val combined = fromDb + extraSeedSongs
-    AlbumLog.songs(name, "extraSeed", extraSeedSongs)
-
-    val groups = combined.groupBy { albumPageIdentity(it) }
-    AlbumLog.identityGroups(name, groups)
-
-    val deduped = dedupeAlbumPageTracks(combined)
-
-    AlbumLog.i(
-        name,
-        "expand done artist='$artist' raw=${combined.size} deduped=${deduped.size} keys=${bySongKey.size} filtered=${filtered.size}"
-    )
-    AlbumLog.songs(name, "deduped", deduped)
-
-    return deduped.sortedWith(albumTrackOrder())
-}
-
-/**
- * Collapse multi-source copies of the *same* song on one release.
- * Prefer disc|trackNumber|title when track # is present so Clancy's 14 tracks
- * never merge into one. Fall back to [TrackIdentity] when numbers are missing.
- */
-fun dedupeAlbumPageTracks(tracks: List<Song>): List<Song> {
-    if (tracks.isEmpty()) return emptyList()
-    val unique = tracks.distinctBy { it.songKey }
-    val groups = collapseNearTitleGroups(unique.groupBy { albumPageIdentity(it) })
-    val albumHint = tracks.firstOrNull()?.album
-    if (groups.any { it.value.size > 1 } || groups.size != tracks.size) {
-        AlbumLog.identityGroups(albumHint, groups)
-    }
-    return groups.values
-        .map { group ->
-            val preferred = group.minByOrNull {
-                CatalogRepository.sourceTypeForSong(it).rank
-            } ?: group.first()
-            TrackIdentity.withRichestDisplay(preferred, group)
-        }
-        .sortedWith(albumTrackOrder())
-}
-
-fun albumTrackOrder(): Comparator<Song> =
-    compareBy<Song> { it.discNumber ?: 1 }
-        .thenBy { it.trackNumber ?: filenameTrackHint(it) }
-        .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
-
-private fun filenameTrackHint(song: Song): Int {
-    val parsed = FilenameMetadataParser.parse(song.path ?: song.contentUri.toString())
-    return parsed.trackNumber ?: Int.MAX_VALUE
-}
-
-private fun collapseNearTitleGroups(
-    groups: Map<String, List<Song>>
-): Map<String, List<Song>> {
-    if (groups.size <= 1) return groups
-    val entries = groups.entries.toList()
-    val used = BooleanArray(entries.size)
-    val out = LinkedHashMap<String, List<Song>>()
-    for (i in entries.indices) {
-        if (used[i]) continue
-        used[i] = true
-        val bucket = entries[i].value.toMutableList()
-        val sample = bucket.first()
-        val disc = sample.discNumber ?: 1
-        val tn = sample.trackNumber
-        for (j in i + 1 until entries.size) {
-            if (used[j]) continue
-            val other = entries[j].value.first()
-            val sameSlot = tn != null && tn > 0 &&
-                other.trackNumber == tn &&
-                (other.discNumber ?: 1) == disc
-            val minLen = if (sameSlot) 6 else 16
-            if (!TrackIdentity.titlesNearlyMatch(sample.title, other.title, minLen = minLen)) {
-                continue
-            }
-            if (!sameSlot && tn != null && other.trackNumber != null && other.trackNumber != tn) {
-                continue
-            }
-            used[j] = true
-            bucket += entries[j].value
-        }
-        out[entries[i].key] = bucket
-    }
-    return out
-}
-
-internal fun albumPageIdentity(song: Song): String {
-    val disc = song.discNumber ?: 1
-    val tn = song.trackNumber
-    val title = TrackIdentity.normalizeTitle(song.title)
-    // Always include title so missing/duplicate track numbers cannot collapse
-    // a whole release onto one row (Clancy / The Craving).
-    return if (tn != null && tn > 0 && title.isNotEmpty()) {
-        "n:$disc|$tn|$title"
-    } else if (title.isNotEmpty()) {
-        TrackIdentity.of(song)
-    } else {
-        "path:${song.songKey}"
-    }
-}
-
-private fun CatalogTrackEntity.toSong(): Song = Song(
-    id = id,
-    title = title,
-    artist = artist,
-    albumArtist = albumArtist,
-    album = album,
-    durationMs = durationMs,
-    contentUri = android.net.Uri.parse(contentUri),
-    albumArtUri = albumArtUri?.let { android.net.Uri.parse(it) },
-    trackNumber = trackNumber,
-    discNumber = discNumber,
-    year = year,
-    path = path,
-    mimeType = mimeType
-)
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt b/app/src/main/java/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt
index cf4d7126..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt
@@ -1,189 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-import android.net.Uri
-import capital.yuri.yuriplayer.data.db.CatalogAlbumEntity
-import capital.yuri.yuriplayer.data.db.CatalogDao
-import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.withContext
-import java.io.File
-
-/**
- * Fast discography for the artist page.
- *
- * Prefer [catalog_albums] + one seed track per release. Full track scans and
- * LIKE-mention queries are a fallback when the album table is empty.
- */
-suspend fun lightAlbumItemsForArtist(
-    dao: CatalogDao,
-    artistKey: String,
-    displayName: String? = null
-): List<AlbumItem> = withContext(Dispatchers.IO) {
-    if (artistKey.isBlank()) return@withContext emptyList()
-    val keys = ArtistAliasResolver.identityKeys(artistKey)
-    val rows = dao.getAlbumsForArtists(keys)
-        .filter { !isCombinedArtistName(it.artist) }
-    if (rows.isNotEmpty()) {
-        val seeds = rows.map { it.albumKey }.chunked(400).flatMap { chunk ->
-            if (chunk.isEmpty()) emptyList() else dao.oneTrackPerAlbum(chunk)
-        }.associateBy { it.albumKey }
-        val items = rows.map { row ->
-            row.toLightAlbum(seeds[row.albumKey]?.toLightSong())
-        }
-        AlbumLog.i(
-            displayName,
-            "light discography from album rows n=${items.size} keys=${keys.size}"
-        )
-        return@withContext clusterNearDuplicateAlbums(items).sortedWith(lightAlbumOrder())
-    }
-
-    val songs = LinkedHashMap<String, Song>()
-    dao.getTracksForArtists(keys).forEach { songs[it.songKey] = it.toLightSong() }
-    dao.getTracksByCreditRoles(keys, ArtistRole.PRIMARY.name).forEach {
-        songs.putIfAbsent(it.songKey, it.toLightSong())
-    }
-
-    val fromTracks = songs.values
-        .groupBy { albumKey(it.album, it.effectiveAlbumArtist) }
-        .map { (key, tracks) ->
-            val sorted = CatalogRepository.dedupeLogicalTracks(tracks)
-            AlbumItem(
-                name = sorted.firstOrNull()?.album,
-                artist = primaryArtistName(sorted.firstOrNull()?.effectiveAlbumArtist)
-                    ?: sorted.firstOrNull()?.effectiveAlbumArtist,
-                trackCount = sorted.size,
-                songs = sorted.take(1)
-            )
-        }
-    AlbumLog.i(displayName, "light discography from tracks n=${fromTracks.size}")
-    clusterNearDuplicateAlbums(fromTracks).sortedWith(lightAlbumOrder())
-}
-
-suspend fun lightAppearsOnForArtist(
-    dao: CatalogDao,
-    artistKey: String,
-    displayName: String? = null
-): List<AlbumItem> = withContext(Dispatchers.IO) {
-    if (artistKey.isBlank()) return@withContext emptyList()
-    val keys = ArtistAliasResolver.identityKeys(artistKey)
-    val canonical = ArtistAliasResolver.resolve(artistKey)
-    val songs = LinkedHashMap<String, Song>()
-    dao.getTracksByCreditRoles(keys, ArtistRole.FEATURED.name).forEach {
-        songs[it.songKey] = it.toLightSong()
-    }
-    if (songs.isEmpty()) return@withContext emptyList()
-
-    songs.values
-        .groupBy { albumKey(it.album, it.effectiveAlbumArtist) }
-        .mapNotNull { (_, tracks) ->
-            val primary = primaryArtistName(tracks.first().effectiveAlbumArtist)
-                ?: tracks.first().effectiveAlbumArtist
-            if (artistKey(primary) == canonical) return@mapNotNull null
-            val sorted = CatalogRepository.dedupeLogicalTracks(tracks)
-            AlbumItem(
-                name = sorted.firstOrNull()?.album,
-                artist = primary,
-                trackCount = sorted.size,
-                songs = sorted.take(1)
-            )
-        }
-        .let { clusterNearDuplicateAlbums(it) }
-        .sortedWith(lightAlbumOrder())
-}
-
-internal fun CatalogAlbumEntity.toLightAlbum(seed: Song?): AlbumItem {
-    val art = seed?.albumArtUri
-        ?: coverUrl?.takeIf { it.isNotBlank() }?.let { Uri.parse(it) }
-        ?: coverPath?.takeIf { it.isNotBlank() }?.let { path ->
-            val f = File(path)
-            if (f.isFile) Uri.fromFile(f) else runCatching { Uri.parse(path) }.getOrNull()
-        }
-    val song = when {
-        seed != null && seed.albumArtUri == null && art != null -> seed.copy(albumArtUri = art)
-        seed != null -> seed
-        else -> Song(
-            id = albumKey.hashCode().toLong(),
-            title = name,
-            artist = artist,
-            albumArtist = artist,
-            album = name,
-            durationMs = null,
-            contentUri = Uri.EMPTY,
-            albumArtUri = art,
-            year = year,
-            path = "album:$albumKey"
-        )
-    }.let { if (year != null && it.year == null) it.copy(year = year) else it }
-    return AlbumItem(
-        name = name,
-        artist = artist,
-        trackCount = trackCount,
-        songs = listOf(song)
-    )
-}
-
-private fun lightAlbumOrder() =
-    compareByDescending<AlbumItem> { it.songs.firstOrNull()?.year ?: Int.MIN_VALUE }
-        .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayName }
-
-private fun clusterNearDuplicateAlbums(items: List<AlbumItem>): List<AlbumItem> {
-    val exact = items.groupBy { albumKey(it.name, it.artist) }.map { (key, group) ->
-        val pick = group.maxByOrNull { it.trackCount } ?: group.first()
-        if (group.size > 1) {
-            AlbumLog.d(
-                pick.name,
-                "light merge cards=${group.size} key='$key' counts=${group.map { it.trackCount }}"
-            )
-        }
-        pick
-    }
-    val used = BooleanArray(exact.size)
-    val out = ArrayList<AlbumItem>(exact.size)
-    for (i in exact.indices) {
-        if (used[i]) continue
-        val a = exact[i]
-        val members = mutableListOf(a)
-        used[i] = true
-        val artistA = artistKey(a.artist)
-        for (j in i + 1 until exact.size) {
-            if (used[j]) continue
-            val b = exact[j]
-            if (artistKey(b.artist) != artistA) continue
-            if (!sameRelease(a, b)) continue
-            used[j] = true
-            members += b
-        }
-        val pick = members.maxByOrNull { it.trackCount } ?: a
-        out += pick.copy(trackCount = members.maxOf { it.trackCount })
-    }
-    return out
-}
-
-private fun sameRelease(a: AlbumItem, b: AlbumItem): Boolean {
-    if (!TrackIdentity.albumsNearlyMatch(a.name, b.name)) return false
-    val sa = a.songs.firstOrNull()
-    val sb = b.songs.firstOrNull()
-    if (sa == null || sb == null) return true
-    if (albumPageIdentity(sa) == albumPageIdentity(sb)) return true
-    if (TrackIdentity.titlesNearlyMatch(sa.title, sb.title, minLen = 6)) return true
-    val sameSlot = (sa.trackNumber ?: 0) > 0 &&
-        sa.trackNumber == sb.trackNumber &&
-        (sa.discNumber ?: 1) == (sb.discNumber ?: 1)
-    return sameSlot && TrackIdentity.titlesNearlyMatch(sa.title, sb.title, minLen = 4)
-}
-
-internal fun CatalogTrackEntity.toLightSong(): Song = Song(
-    id = id,
-    title = title,
-    artist = artist,
-    albumArtist = albumArtist,
-    album = album,
-    durationMs = durationMs,
-    contentUri = Uri.parse(contentUri),
-    albumArtUri = albumArtUri?.let { Uri.parse(it) },
-    trackNumber = trackNumber,
-    discNumber = discNumber,
-    year = year,
-    path = path,
-    mimeType = mimeType
-)
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/ArtistCredits.kt b/app/src/main/java/capital/yuri/yuriplayer/data/ArtistCredits.kt
index 402f2f5f..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/ArtistCredits.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/ArtistCredits.kt
@@ -1,171 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-/**
- * Split a raw artist tag into primary vs featured credits.
- *
- * Separators:
- *  - `;` always splits peers
- *  - `feat.` / `ft.` / `featuring` starts the featured list
- *  - commas/`&` in the *primary* blob stay inside names ("Earth, Wind & Fire")
- *  - commas/`&`/`x` in a *feat.* blob split guest lists ("Miku, Rin & Luka")
- */
-enum class ArtistRole {
-    PRIMARY,
-    FEATURED
-}
-
-data class ArtistCredit(
-    val name: String,
-    val role: ArtistRole,
-    val position: Int
-)
-
-private val FEAT_SPLIT = Regex(
-    """(?i)(?:\p{Zs}+|[\(\[\{]\p{Zs}*)(?:feat\.?|ft\.?|featuring)\.?\p{Zs}*"""
-)
-private val FEAT_IN_PARENS = Regex(
-    """(?i)[\(\[\{]\p{Zs}*(?:feat\.?|ft\.?|featuring)\.?\p{Zs}*([^\)\]\}]+)[\)\]\}]"""
-)
-private val FEAT_SUFFIX = Regex(
-    """(?i)\p{Zs}+(?:feat\.?|ft\.?|featuring)\.?\p{Zs}*(.+)$"""
-)
-private val FEAT_BLOB_SPLIT = Regex("""\s*(?:;|,|&|×)\s+|\s+(?:and|x)\s+""", RegexOption.IGNORE_CASE)
-private val TRAILING_OPEN = Regex("""[\(\[\{]\p{Zs}*$""")
-
-fun parseArtistCreditList(raw: String?): List<ArtistCredit> {
-    if (raw.isNullOrBlank()) return emptyList()
-    val parenFeats = ArrayList<String>()
-    var cleaned = raw.trim()
-    FEAT_IN_PARENS.findAll(cleaned).forEach { parenFeats += splitFeatBlob(it.groupValues[1]) }
-    cleaned = cleaned.replace(FEAT_IN_PARENS, " ").replace(Regex("""\s+"""), " ").trim()
-    cleaned = cleaned.replace(TRAILING_OPEN, "").trim()
-
-    val parts = cleaned.split(FEAT_SPLIT, limit = 2)
-    val out = ArrayList<ArtistCredit>()
-    fun addPrimary(blob: String) {
-        blob.split(';').map { it.trim().trim('(', ')', '[', ']', '{', '}') }.filter { it.isNotEmpty() }.forEach { name ->
-            if (out.none { it.name.equals(name, ignoreCase = true) }) {
-                out += ArtistCredit(name = name, role = ArtistRole.PRIMARY, position = out.size)
-            }
-        }
-    }
-    fun addFeatured(blob: String) {
-        splitFeatBlob(blob).forEach { name ->
-            if (out.none { it.name.equals(name, ignoreCase = true) }) {
-                out += ArtistCredit(name = name, role = ArtistRole.FEATURED, position = out.size)
-            }
-        }
-    }
-    addPrimary(parts[0])
-    parts.getOrNull(1)?.let { addFeatured(it) }
-    parenFeats.forEach { addFeatured(it) }
-    return out
-}
-
-fun splitFeatBlob(blob: String): List<String> {
-    var t = blob.trim()
-    t = t.replace(Regex("""[\(\[\{].*$"""), "").trim()
-    return t.split(FEAT_BLOB_SPLIT)
-        .map { it.trim().trim('.', '-', '/') }
-        .filter { it.length >= 2 }
-        .distinctBy { it.lowercase() }
-}
-
-fun featuredFromText(text: String?): List<String> {
-    if (text.isNullOrBlank()) return emptyList()
-    val found = LinkedHashSet<String>()
-    FEAT_IN_PARENS.findAll(text).forEach { found += splitFeatBlob(it.groupValues[1]) }
-    FEAT_SUFFIX.find(text)?.let { found += splitFeatBlob(it.groupValues[1]) }
-    return found.toList()
-}
-
-/**
- * Full credit list for a song: album-artist primaries, extra track artists as
- * featured, plus `feat.` parsed from the title and album title.
- */
-fun allCreditsForSong(song: Song): List<ArtistCredit> {
-    val albumParsed = parseArtistCreditList(song.albumArtist)
-    val artistParsed = parseArtistCreditList(song.artist)
-    val titleFeats = featuredFromText(song.title)
-    val albumFeats = featuredFromText(song.album)
-    val artistFieldFeats = featuredFromText(song.artist) + featuredFromText(song.albumArtist)
-
-    val primaries = LinkedHashSet<String>()
-    albumParsed.filter { it.role == ArtistRole.PRIMARY }.forEach { primaries += it.name }
-    if (primaries.isEmpty()) {
-        artistParsed.firstOrNull { it.role == ArtistRole.PRIMARY }?.let { primaries += it.name }
-    }
-    if (primaries.isEmpty()) {
-        primaryArtistName(song.effectiveAlbumArtist)?.let { primaries += it }
-    }
-
-    fun isPrimary(name: String) = primaries.any { it.equals(name, ignoreCase = true) }
-
-    val featured = LinkedHashSet<String>()
-    fun addFeat(name: String) {
-        val n = name.trim()
-        if (n.length >= 2 && !isPrimary(n)) featured += n
-    }
-    albumParsed.filter { it.role == ArtistRole.FEATURED }.forEach { addFeat(it.name) }
-    artistParsed.forEach { c ->
-        if (c.role == ArtistRole.FEATURED || !isPrimary(c.name)) addFeat(c.name)
-    }
-    titleFeats.forEach { addFeat(it) }
-    albumFeats.forEach { addFeat(it) }
-    artistFieldFeats.forEach { addFeat(it) }
-
-    val out = ArrayList<ArtistCredit>(primaries.size + featured.size)
-    primaries.forEach { n -> out += ArtistCredit(n, ArtistRole.PRIMARY, out.size) }
-    featured.forEach { n -> out += ArtistCredit(n, ArtistRole.FEATURED, out.size) }
-    return out
-}
-
-fun isCombinedArtistName(name: String?): Boolean {
-    if (name.isNullOrBlank()) return false
-    if (name.contains(';')) return true
-    if (FEAT_IN_PARENS.containsMatchIn(name)) return true
-    if (FEAT_SPLIT.containsMatchIn(name)) return true
-    return false
-}
-
-/** Names only (primary then featured) — for linking. */
-fun parseArtistCredits(raw: String?): List<String> =
-    parseArtistCreditList(raw).map { it.name }
-
-fun primaryArtistName(raw: String?): String? =
-    parseArtistCreditList(raw).firstOrNull { it.role == ArtistRole.PRIMARY }?.name
-        ?: parseArtistCreditList(raw).firstOrNull()?.name
-
-fun featuredArtistNames(raw: String?): List<String> =
-    parseArtistCreditList(raw).filter { it.role == ArtistRole.FEATURED }.map { it.name }
-
-enum class ReleaseType {
-    SINGLE,
-    EP,
-    ALBUM,
-    COMPILATION,
-    OTHER;
-
-    val label: String
-        get() = when (this) {
-            SINGLE -> "Single"
-            EP -> "EP"
-            ALBUM -> "Album"
-            COMPILATION -> "Compilation"
-            OTHER -> "Release"
-        }
-}
-
-/**
- * Heuristic release classification until MusicBrainz / Jellyfin types land.
- * Track-count based (Spotify-adjacent).
- */
-fun guessReleaseType(trackCount: Int): ReleaseType = when {
-    trackCount <= 3 -> ReleaseType.SINGLE
-    trackCount <= 8 -> ReleaseType.EP
-    else -> ReleaseType.ALBUM
-}
-
-fun AlbumItem.releaseYear(): Int? = songs.mapNotNull { it.year }.maxOrNull()
-
-fun AlbumItem.releaseType(): ReleaseType = guessReleaseType(trackCount)
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/CatalogRepository.kt b/app/src/main/java/capital/yuri/yuriplayer/data/CatalogRepository.kt
index 6faa9d35..12a890e0 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/CatalogRepository.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/CatalogRepository.kt
@@ -1,1054 +1,27 @@
 package capital.yuri.yuriplayer.data
 
-import android.util.Log
-import capital.yuri.yuriplayer.data.db.ArtistAliasEntity
-import capital.yuri.yuriplayer.data.db.CatalogAlbumEntity
-import capital.yuri.yuriplayer.data.db.CatalogArtistEntity
-import capital.yuri.yuriplayer.data.db.CatalogCreditEntity
+// Moved to :core (commonMain), same package. The Android client wires the
+// shared `CatalogRepository` with a platform [LocalScanner] (MusicRepository)
+// and a [CoverCandidateBuilder] (the Android filesystem/SAF-aware builder).
+
+import capital.yuri.yuriplayer.data.CoverCandidateBuilder
+import capital.yuri.yuriplayer.data.LocalScanner
 import capital.yuri.yuriplayer.data.db.CatalogDao
-import capital.yuri.yuriplayer.data.db.CatalogSources
-import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
 import capital.yuri.yuriplayer.data.source.SourceInstanceRepository
-import capital.yuri.yuriplayer.data.source.SourceOffering
-import capital.yuri.yuriplayer.data.source.SourceType
-import kotlinx.coroutines.Dispatchers
-import kotlinx.coroutines.flow.Flow
-import kotlinx.coroutines.flow.map
-import kotlinx.coroutines.withContext
-
-class CatalogRepository(
-    private val dao: CatalogDao,
-    private val musicRepository: MusicRepository,
-    private val sourceInstances: SourceInstanceRepository
-) {
-    private val lightAlbumsCache = object : LinkedHashMap<String, List<AlbumItem>>(32, 0.75f, true) {
-        override fun removeEldestEntry(eldest: MutableMap.MutableEntry<String, List<AlbumItem>>?): Boolean =
-            size > 48
-    }
-
-    fun observeTracks(): Flow<List<Song>> =
-        dao.observeTracks().map { rows -> rows.map { it.toSong() } }
-
-    fun observeAlbums(): Flow<List<CatalogAlbumEntity>> = dao.observeAlbums()
-
-    fun observeArtists(): Flow<List<CatalogArtistEntity>> = dao.observeArtists()
-
-    suspend fun getAllSongs(): List<Song> = withContext(Dispatchers.IO) {
-        dao.getAllTracks().map { it.toSong() }
-    }
-
-    suspend fun getLocalSongs(): List<Song> = withContext(Dispatchers.IO) {
-        dao.getTracksBySource(CatalogSources.LOCAL).map { it.toSong() }
-    }
-
-    suspend fun getSongsByKeys(keys: List<String>): List<Song> = withContext(Dispatchers.IO) {
-        if (keys.isEmpty()) return@withContext emptyList()
-        keys.chunked(400).flatMap { chunk ->
-            dao.getTracksByKeys(chunk).map { it.toSong() }
-        }
-    }
-
-    suspend fun searchSongs(query: String, limit: Int = 80): List<Song> =
-        withContext(Dispatchers.IO) {
-            val q = query.trim()
-            if (q.isEmpty()) return@withContext emptyList()
-            dao.searchTracks(q, limit).map { it.toSong() }
-        }
-
-    suspend fun searchAlbumRows(query: String, limit: Int = 12): List<CatalogAlbumEntity> =
-        withContext(Dispatchers.IO) {
-            val q = query.trim()
-            if (q.isEmpty()) return@withContext emptyList()
-            dao.searchAlbums(q, limit)
-        }
-
-    suspend fun searchArtistRows(query: String, limit: Int = 12): List<CatalogArtistEntity> =
-        withContext(Dispatchers.IO) {
-            val q = query.trim()
-            if (q.isEmpty()) return@withContext emptyList()
-            dao.searchArtists(q, limit)
-        }
-
-    suspend fun searchAlbumsAsItems(query: String, limit: Int = 12): List<AlbumItem> =
-        withContext(Dispatchers.IO) {
-            val q = query.trim()
-            if (q.isEmpty()) return@withContext emptyList()
-            val rows = dao.searchAlbums(q, limit)
-            val seen = LinkedHashSet<String>()
-            val out = ArrayList<AlbumItem>(rows.size)
-            for (row in rows) {
-                val item = lightAlbumItemLocked(row.albumKey) ?: continue
-                val mergeKey = albumKey(item.name, item.artist)
-                if (!seen.add(mergeKey)) continue
-                out += item
-            }
-            out.take(limit)
-        }
-
-    suspend fun searchArtistsAsItems(query: String, limit: Int = 12): List<ArtistItem> =
-        withContext(Dispatchers.IO) {
-            val q = query.trim()
-            if (q.isEmpty()) return@withContext emptyList()
-            val aliasKeys = dao.getAllAliases().map { it.aliasKey }.toHashSet()
-            val seen = LinkedHashSet<String>()
-            val out = ArrayList<ArtistItem>()
-            for (row in dao.searchArtists(q, limit * 3)) {
-                if (row.artistKey in aliasKeys) continue
-                if (ArtistAliasResolver.isAlias(row.artistKey)) continue
-                if (isCombinedArtistName(row.displayName)) continue
-                val name = primaryArtistName(row.displayName) ?: row.displayName
-                val key = artistKey(name) ?: continue
-                if (!seen.add(key)) continue
-                out += ArtistItem(
-                    name = name,
-                    trackCount = row.trackCount,
-                    albumCount = row.albumCount,
-                    songs = emptyList()
-                )
-                if (out.size >= limit) break
-            }
-            out
-        }
-
-    suspend fun tracksForAlbum(albumKey: String): List<Song> = withContext(Dispatchers.IO) {
-        if (albumKey.isBlank()) return@withContext emptyList()
-        expandAlbumTracksLocked(albumKey)
-    }
-
-    suspend fun tracksForArtist(artistKey: String): List<Song> = withContext(Dispatchers.IO) {
-        if (artistKey.isBlank()) return@withContext emptyList()
-        dedupeLogicalTracks(primaryTracksForArtistLocked(artistKey))
-    }
-
-    /** Releases this artist owns (primary). Local + remote copies merge by albumKey. */
-    suspend fun albumItemsForArtist(artistKey: String, displayName: String? = null): List<AlbumItem> =
-        withContext(Dispatchers.IO) {
-            synchronized(lightAlbumsCache) { lightAlbumsCache[artistKey] }?.let { return@withContext it }
-            val items = lightAlbumItemsForArtist(dao, artistKey, displayName)
-            synchronized(lightAlbumsCache) { lightAlbumsCache[artistKey] = items }
-            items
-        }
-
-    suspend fun lightAlbumItemForKey(albumKey: String): AlbumItem? = withContext(Dispatchers.IO) {
-        lightAlbumItemLocked(albumKey)
-    }
-
-    private suspend fun lightAlbumItemLocked(albumKey: String): AlbumItem? {
-        if (albumKey.isBlank()) return null
-        val row = dao.getAlbum(albumKey)
-        if (row != null) {
-            val seed = dao.getOneTrackForAlbum(albumKey)
-            return row.toLightAlbum(seed?.toLightSong())
-        }
-        val seed = dao.getOneTrackForAlbum(albumKey) ?: return null
-        return AlbumItem(
-            name = seed.album,
-            artist = seed.albumArtist ?: seed.artist,
-            trackCount = 1,
-            songs = listOf(seed.toLightSong())
-        )
-    }
-
-    /** Guest appearances on other artists' releases. */
-    suspend fun appearsOnAlbumItems(artistKey: String, displayName: String? = null): List<AlbumItem> =
-        withContext(Dispatchers.IO) {
-            lightAppearsOnForArtist(dao, artistKey, displayName)
-        }
-
-    suspend fun fastAlbumItem(
-        name: String?,
-        artist: String?,
-        albumKey: String?,
-        seed: List<Song> = emptyList()
-    ): AlbumItem? = withContext(Dispatchers.IO) {
-        val songs = fastExpandAlbumTracks(dao, name, artist, albumKey, seed)
-        if (songs.isEmpty() && seed.isEmpty()) return@withContext null
-        val row = albumKey?.takeIf { it.isNotBlank() }?.let { dao.getAlbum(it) }
-        val merged = dedupeAlbumPageTracks(songs + seed)
-        AlbumItem(
-            name = name ?: row?.name ?: merged.firstOrNull()?.album,
-            artist = artist ?: row?.artist ?: merged.firstOrNull()?.effectiveAlbumArtist,
-            trackCount = merged.size.coerceAtLeast(row?.trackCount ?: 0),
-            songs = merged
-        )
-    }
-
-    suspend fun albumTrackCount(albumKey: String): Int? = withContext(Dispatchers.IO) {
-        if (albumKey.isBlank()) return@withContext null
-        dao.getAlbum(albumKey)?.trackCount
-    }
-
-    suspend fun albumItemForKey(albumKey: String): AlbumItem? = withContext(Dispatchers.IO) {
-        albumItemForKeyLocked(albumKey)
-    }
-
-    private suspend fun albumItemForKeyLocked(albumKey: String): AlbumItem? {
-        if (albumKey.isBlank()) return null
-        val row = dao.getAlbum(albumKey)
-        AlbumLog.d(row?.name, "albumItemForKey '$albumKey' row=${row != null} count=${row?.trackCount}")
-        val tracks = expandAlbumTracksLocked(albumKey)
-        if (row == null && tracks.isEmpty()) return null
-        AlbumLog.i(row?.name ?: tracks.firstOrNull()?.album, "albumItemForKey '$albumKey' tracks=${tracks.size}")
-        return AlbumItem(
-            name = row?.name ?: tracks.firstOrNull()?.album,
-            artist = row?.artist ?: tracks.firstOrNull()?.effectiveAlbumArtist,
-            trackCount = if (tracks.isNotEmpty()) tracks.size else (row?.trackCount ?: 0),
-            songs = tracks
-        )
-    }
-
-    private suspend fun expandAlbumTracksLocked(albumKey: String): List<Song> =
-        expandAlbumTracks(dao, albumKey)
-
-    suspend fun artistItemForKey(artistKey: String, hintName: String? = null): ArtistItem? = withContext(Dispatchers.IO) {
-        if (artistKey.isBlank()) return@withContext null
-        val key = ArtistAliasResolver.resolve(artistKey)
-        val row = dao.getArtist(key)?.takeUnless { isCombinedArtistName(it.displayName) }
-            ?: dao.getArtist(artistKey)?.takeUnless { isCombinedArtistName(it.displayName) }
-        val tracks = dedupeLogicalTracks(primaryTracksForArtistLocked(key, hintName ?: row?.displayName))
-        if (row == null && tracks.isEmpty()) return@withContext null
-        val albums = tracks.mapNotNull { TrackIdentity.normalizeToken(it.album).takeIf { n -> n.isNotEmpty() } }.toSet()
-        val name = primaryArtistName(row?.displayName)
-            ?: row?.displayName
-            ?: primaryArtistName(hintName)
-            ?: hintName
-            ?: primaryArtistName(tracks.firstOrNull()?.effectiveAlbumArtist)
-            ?: tracks.firstOrNull()?.effectiveAlbumArtist
-        ArtistItem(
-            name = name,
-            trackCount = if (tracks.isNotEmpty()) tracks.size else (row?.trackCount ?: 0),
-            albumCount = if (albums.isNotEmpty()) albums.size else (row?.albumCount ?: 0),
-            songs = tracks
-        )
-    }
-
-    suspend fun coverCandidatesForAlbum(albumKey: String, tracks: List<Song> = emptyList()): List<CoverCandidate> =
-        withContext(Dispatchers.IO) {
-            val songs = tracks.ifEmpty { expandAlbumTracksLocked(albumKey) }
-            val row = dao.getAlbum(albumKey)
-            CoverCandidates.build(songs, row?.coverPath, row?.coverUrl)
-        }
-
-    suspend fun countRemoteTracks(): Int = withContext(Dispatchers.IO) {
-        dao.countNonLocalTracks()
-    }
-
-    suspend fun getAlbum(albumKey: String): CatalogAlbumEntity? = withContext(Dispatchers.IO) {
-        dao.getAlbum(albumKey)
-    }
-
-    suspend fun getArtist(artistKey: String): CatalogArtistEntity? = withContext(Dispatchers.IO) {
-        dao.getArtist(artistKey)
-    }
-
-    suspend fun countTracksForSource(sourceType: String, sourceInstanceId: Long?): Int =
-        withContext(Dispatchers.IO) {
-            dao.countTracksForSource(sourceType, sourceInstanceId)
-        }
-
-    suspend fun songsForSource(sourceType: String, sourceInstanceId: Long?): List<Song> =
-        withContext(Dispatchers.IO) {
-            dao.getTracksForSourceInstance(sourceType, sourceInstanceId).map { it.toSong() }
-        }
-
-    suspend fun searchSongsForSource(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        query: String,
-        limit: Int = 80
-    ): List<Song> = withContext(Dispatchers.IO) {
-        val q = query.trim()
-        if (q.isEmpty()) return@withContext emptyList()
-        dao.searchTracksForSource(sourceType, sourceInstanceId, q, limit).map { it.toSong() }
-    }
-
-    suspend fun songsByExternalIds(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        ids: List<String>
-    ): Map<String, Song> = withContext(Dispatchers.IO) {
-        if (ids.isEmpty()) return@withContext emptyMap()
-        val out = HashMap<String, Song>(ids.size)
-        ids.chunked(400).forEach { chunk ->
-            dao.tracksByExternalIds(sourceType, sourceInstanceId, chunk).forEach { row ->
-                val id = row.externalId ?: return@forEach
-                out[id] = row.toSong()
-            }
-        }
-        out
-    }
-
-    suspend fun offeringsMatchingSong(song: Song, limit: Int = 12): List<SourceOffering> =
-        withContext(Dispatchers.IO) {
-            val title = song.title?.trim().orEmpty()
-            val album = song.album?.trim().orEmpty()
-            val candidates = LinkedHashMap<String, CatalogTrackEntity>()
-
-            if (title.isNotEmpty() || album.isNotEmpty()) {
-                dao.findTracksMatching(
-                    title,
-                    song.effectiveAlbumArtist?.trim().orEmpty(),
-                    album,
-                    limit
-                ).forEach { candidates[it.songKey] = it }
-            }
-
-            val needle = TrackIdentity.normalizeTitle(title).ifEmpty { title }
-            if (needle.isNotEmpty()) {
-                dao.searchTracks(needle.take(48), limit = 80).forEach { row ->
-                    if (candidates.size >= limit) return@forEach
-                    if (TrackIdentity.matches(song, row.toSong()) ||
-                        TrackIdentity.titlesMatch(song.title, row.title) &&
-                        TrackIdentity.albumsMatch(song.album, row.album)
-                    ) {
-                        candidates.putIfAbsent(row.songKey, row)
-                    }
-                }
-            }
-
-            val names = sourceInstanceNames()
-            val fromDb = candidates.values
-                .map { offeringFor(it, names) }
-                .distinctBy { "${it.sourceType.name}:${it.sourceId}:${it.song.songKey}" }
-                .sortedBy { it.sourceType.rank }
-                .take(limit)
-
-            if (fromDb.isNotEmpty()) return@withContext fromDb
-
-            listOf(
-                SourceOffering(
-                    sourceType = sourceTypeForSong(song),
-                    sourceId = null,
-                    sourceName = if (sourceTypeForSong(song) == SourceType.LOCAL) {
-                        "On this device"
-                    } else {
-                        sourceTypeForSong(song).displayName()
-                    },
-                    song = song
-                )
-            )
-        }
-
-    suspend fun patchTrackTags(
-        songKey: String,
-        title: String? = null,
-        artist: String? = null,
-        album: String? = null,
-        albumArtist: String? = null,
-        year: Int? = null,
-        genre: String? = null
-    ) = withContext(Dispatchers.IO) {
-        val row = dao.getTrack(songKey) ?: return@withContext
-        val nextTitle = title?.trim()?.takeIf { it.isNotEmpty() } ?: row.title
-        val nextArtist = artist?.trim()?.takeIf { it.isNotEmpty() } ?: row.artist
-        val nextAlbumArtist = albumArtist?.trim()?.takeIf { it.isNotEmpty() } ?: row.albumArtist
-        val nextAlbum = album?.trim()?.takeIf { it.isNotEmpty() } ?: row.album
-        val nextYear = year?.takeIf { it in 1000..2100 } ?: row.year
-        val effectiveArtist = nextAlbumArtist ?: nextArtist
-        val nextAlbumKey = if (nextAlbum != null) albumKey(nextAlbum, effectiveArtist) else row.albumKey
-        val nextArtistKey = artistKey(effectiveArtist) ?: row.artistKey
-        @Suppress("UNUSED_VARIABLE")
-        val ignoredGenre = genre
-        dao.upsertTrack(
-            row.copy(
-                title = nextTitle,
-                artist = nextArtist,
-                albumArtist = nextAlbumArtist,
-                album = nextAlbum,
-                year = nextYear,
-                albumKey = nextAlbumKey,
-                artistKey = nextArtistKey,
-                isTagged = true,
-                updatedAtMs = System.currentTimeMillis()
-            )
-        )
-        Log.i(TAG, "patchTrackTags $songKey")
-    }
-
-    suspend fun syncLocalLibrary(): List<Song> = withContext(Dispatchers.IO) {
-        val scanned = musicRepository.scanLibrary()
-        val seenAt = System.currentTimeMillis()
-        val trackEntities = scanned.map { it.toLocalTrackEntity(seenAt) }
-
-        dao.upsertTracks(trackEntities)
-        persistCreditsLocked(scanned)
-        dao.pruneStaleTracks(CatalogSources.LOCAL, null, seenAt)
-        rebuildRollupsLocked()
-
-        val local = dao.getTracksBySource(CatalogSources.LOCAL).map { it.toSong() }
-        Log.i(TAG, "local sync: ${local.size} local tracks")
-        local
-    }
-
-    suspend fun ingestRemoteBatch(
-        songs: List<Song>,
-        sourceType: String,
-        sourceInstanceId: Long?,
-        seenAt: Long = System.currentTimeMillis()
-    ): IngestStats = withContext(Dispatchers.IO) {
-        ingestRemoteDeltaLocked(songs, sourceType, sourceInstanceId, seenAt)
-    }
-
-    data class IngestStats(
-        val inserted: Int = 0,
-        val updated: Int = 0,
-        val unchanged: Int = 0
-    ) {
-        val changed: Int get() = inserted + updated
-        val seen: Int get() = inserted + updated + unchanged
-        operator fun plus(other: IngestStats) = IngestStats(
-            inserted = inserted + other.inserted,
-            updated = updated + other.updated,
-            unchanged = unchanged + other.unchanged
-        )
-    }
-
-    private suspend fun ingestRemoteDeltaLocked(
-        songs: List<Song>,
-        sourceType: String,
-        sourceInstanceId: Long?,
-        seenAt: Long
-    ): IngestStats {
-        if (songs.isEmpty()) return IngestStats()
-        val incoming = songs.map { song ->
-            song.toTrackEntity(
-                sourceType = sourceType,
-                sourceInstanceId = sourceInstanceId,
-                externalId = song.path ?: song.contentUri.toString(),
-                seenAt = seenAt
-            )
-        }
-        val ids = incoming.mapNotNull { it.externalId }
-        val existing = HashMap<String, CatalogTrackEntity>(ids.size)
-        ids.chunked(400).forEach { chunk ->
-            dao.tracksByExternalIds(sourceType, sourceInstanceId, chunk).forEach { row ->
-                val key = row.externalId ?: return@forEach
-                existing[key] = row
-            }
-        }
-        val upsert = ArrayList<CatalogTrackEntity>()
-        val patchSongs = ArrayList<Song>()
-        val touch = ArrayList<String>()
-        var inserted = 0
-        var updated = 0
-        incoming.forEachIndexed { i, ent ->
-            val id = ent.externalId
-            val prev = id?.let { existing[it] }
-            when {
-                prev == null -> {
-                    upsert += ent
-                    patchSongs += songs[i]
-                    inserted++
-                }
-                prev.sameRemoteMeta(ent) -> {
-                    if (id != null) touch += id
-                }
-                else -> {
-                    upsert += ent.copy(id = prev.id, songKey = prev.songKey)
-                    patchSongs += songs[i]
-                    updated++
-                }
-            }
-        }
-        if (touch.isNotEmpty()) {
-            touch.chunked(400).forEach { chunk ->
-                dao.touchLastSeenByExternalIds(sourceType, sourceInstanceId, chunk, seenAt)
-            }
-        }
-        if (upsert.isNotEmpty()) {
-            dao.upsertTracks(upsert)
-            persistCreditsLocked(patchSongs)
-        }
-        return IngestStats(
-            inserted = inserted,
-            updated = updated,
-            unchanged = touch.size
-        )
-    }
 
-    suspend fun externalIdsForSource(sourceType: String, sourceInstanceId: Long?): Set<String> =
-        withContext(Dispatchers.IO) {
-            dao.externalIdsForSource(sourceType, sourceInstanceId).toHashSet()
+/**
+ * Android-specific construction of the shared [capital.yuri.yuriplayer.data.CatalogRepository].
+ */
+fun androidCatalogRepository(
+    dao: CatalogDao,
+    musicRepository: MusicRepository,
+    sourceInstances: SourceInstanceRepository
+): capital.yuri.yuriplayer.data.CatalogRepository =
+    capital.yuri.yuriplayer.data.CatalogRepository(
+        dao = dao,
+        sourceInstances = sourceInstances,
+        localScanner = LocalScanner { musicRepository.scanLibrary() },
+        coverCandidateBuilder = CoverCandidateBuilder { songs, coverPath, coverUrl ->
+            CoverCandidates.build(songs, coverPath, coverUrl)
         }
-
-    /**
-     * Drop rows for this source whose [externalId] is not in [liveIds].
-     * Incomplete scans must not call this.
-     */
-    suspend fun pruneMissingExternalIds(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        liveIds: Set<String>,
-        keepSongKeys: Set<String>
-    ): Int = withContext(Dispatchers.IO) {
-        val existing = dao.externalIdsForSource(sourceType, sourceInstanceId)
-        val gone = existing.filter { it !in liveIds }
-        if (gone.isEmpty()) return@withContext 0
-        var deleted = 0
-        gone.chunked(400).forEach { chunk ->
-            val keys = dao.songKeysForExternalIds(sourceType, sourceInstanceId, chunk)
-                .filter { it !in keepSongKeys }
-            if (keys.isEmpty()) return@forEach
-            dao.deleteCreditsForTracks(keys)
-            deleted += dao.deleteTracksByKeys(keys)
-        }
-        if (deleted > 0) {
-            dao.deleteOrphanAlbums()
-            dao.deleteOrphanArtists()
-            Log.i(TAG, "pruned $deleted missing $sourceType rows (live=${liveIds.size})")
-        }
-        deleted
-    }
-
-    suspend fun ensureTracksPresent(songs: List<Song>) = withContext(Dispatchers.IO) {
-        if (songs.isEmpty()) return@withContext
-        val now = System.currentTimeMillis()
-        val keys = songs.map { it.songKey }.distinct()
-        val existing = keys.chunked(400).flatMap { dao.getTracksByKeys(it) }.map { it.songKey }.toHashSet()
-        val missing = songs.filter { it.songKey !in existing }
-        if (missing.isEmpty()) return@withContext
-        val entities = missing.map { song ->
-            val type = when {
-                song.path?.startsWith("jellyfin:", true) == true -> CatalogSources.JELLYFIN
-                song.path?.startsWith("subsonic:", true) == true -> CatalogSources.SUBSONIC
-                song.path?.startsWith("navidrome:", true) == true -> CatalogSources.NAVIDROME
-                else -> CatalogSources.LOCAL
-            }
-            song.toTrackEntity(
-                sourceType = type,
-                sourceInstanceId = null,
-                externalId = song.path ?: song.contentUri.toString(),
-                seenAt = now
-            )
-        }
-        dao.upsertTracks(entities)
-        Log.i(TAG, "ensureTracksPresent: upserted ${entities.size}")
-    }
-
-    suspend fun rebuildRollups() = withContext(Dispatchers.IO) {
-        rebuildRollupsLocked()
-    }
-
-    private suspend fun rebuildRollupsLocked() {
-        loadAliasesLocked()
-        applyMbidAliasesLocked()
-        normalizeTrackIdentityLocked()
-        persistCreditsLocked(dao.getAllTracks().map { it.toSong() }, replaceAll = true)
-
-        val prevAlbums = dao.getAllAlbums().associateBy { it.albumKey }
-        val prevArtists = dao.getAllArtists().associateBy { it.artistKey }
-
-        val albumRows = dao.aggregateAlbums()
-        val albums = albumRows.map { row ->
-            val existing = prevAlbums[row.albumKey]
-            val aKey = artistKey(row.artist)
-            CatalogAlbumEntity(
-                albumKey = row.albumKey,
-                name = row.name,
-                artist = primaryArtistName(row.artist) ?: row.artist,
-                artistKey = aKey,
-                year = row.year,
-                trackCount = row.trackCount,
-                releaseType = guessReleaseType(row.trackCount).name,
-                mbid = existing?.mbid,
-                coverPath = existing?.coverPath,
-                coverUrl = row.coverUrl ?: existing?.coverUrl,
-                primarySourceType = row.primarySourceType.ifBlank { CatalogSources.LOCAL },
-                updatedAtMs = System.currentTimeMillis()
-            )
-        }
-        dao.upsertAlbums(albums)
-
-        val artistRows = dao.aggregateArtists()
-        val artists = artistRows.map { row ->
-            val existing = prevArtists[row.artistKey]
-            CatalogArtistEntity(
-                artistKey = row.artistKey,
-                displayName = existing?.displayName?.takeUnless { isCombinedArtistName(it) }
-                    ?: primaryArtistName(row.displayName)
-                    ?: row.displayName.ifBlank { row.artistKey },
-                trackCount = row.trackCount,
-                albumCount = row.albumCount,
-                bio = existing?.bio,
-                imageUri = existing?.imageUri,
-                websiteUrl = existing?.websiteUrl,
-                linksJson = existing?.linksJson,
-                mbid = existing?.mbid,
-                updatedAtMs = System.currentTimeMillis()
-            )
-        }
-        dao.upsertArtists(artists)
-
-        dao.deleteOrphanAlbums()
-        dao.deleteOrphanArtists()
-        Log.i(TAG, "rollups rebuilt (SQL): albums=${albums.size} artists=${artists.size}")
-    }
-
-    suspend fun loadAliases() = withContext(Dispatchers.IO) {
-        loadAliasesLocked()
-    }
-
-    private suspend fun loadAliasesLocked() {
-        val rows = dao.getAllAliases()
-        ArtistAliasResolver.replace(rows.associate { it.aliasKey to it.canonicalKey })
-    }
-
-    /**
-     * Remember [fromName] as an alias of [intoName]. Track rows stay as-is;
-     * lookups expand through [ArtistAliasResolver].
-     */
-    suspend fun mergeArtists(fromName: String, intoName: String): ArtistItem? =
-        withContext(Dispatchers.IO) {
-            val fromKey = rawArtistKey(fromName) ?: return@withContext null
-            val intoKey = ArtistAliasResolver.resolve(rawArtistKey(intoName) ?: return@withContext null)
-            if (fromKey == intoKey) return@withContext artistItemForKey(intoKey, intoName)
-            dao.upsertAlias(
-                ArtistAliasEntity(
-                    aliasKey = fromKey,
-                    canonicalKey = intoKey,
-                    aliasName = fromName.trim(),
-                    source = ArtistAliasEntity.SOURCE_USER
-                )
-            )
-            dao.retargetAliases(fromKey, intoKey)
-            loadAliasesLocked()
-            artistItemForKey(intoKey, intoName)
-        }
-
-    suspend fun unmergeArtist(aliasKey: String) = withContext(Dispatchers.IO) {
-        dao.deleteAlias(aliasKey)
-        loadAliasesLocked()
-    }
-
-    suspend fun aliasesForArtist(artistKey: String): List<ArtistAliasEntity> =
-        withContext(Dispatchers.IO) {
-            val canonical = ArtistAliasResolver.resolve(artistKey)
-            dao.aliasesForCanonical(canonical)
-        }
-
-    private suspend fun applyMbidAliasesLocked() {
-        val groups = dao.artistsWithMbid().groupBy { it.mbid.orEmpty() }
-        var changed = false
-        for ((mbid, rows) in groups) {
-            if (mbid.isBlank() || rows.size < 2) continue
-            val canonical = rows.maxWith(
-                compareBy<CatalogArtistEntity> { it.trackCount }.thenBy { it.displayName }
-            )
-            for (other in rows) {
-                if (other.artistKey == canonical.artistKey) continue
-                if (ArtistAliasResolver.resolve(other.artistKey) == canonical.artistKey) continue
-                dao.upsertAlias(
-                    ArtistAliasEntity(
-                        aliasKey = other.artistKey,
-                        canonicalKey = canonical.artistKey,
-                        aliasName = other.displayName,
-                        source = ArtistAliasEntity.SOURCE_MBID
-                    )
-                )
-                changed = true
-            }
-        }
-        if (changed) loadAliasesLocked()
-    }
-
-    suspend fun pruneRemoteSource(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        beforeMs: Long,
-        keepSongKeys: Set<String>
-    ) = withContext(Dispatchers.IO) {
-        val deleted = if (keepSongKeys.isEmpty()) {
-            dao.pruneStaleTracks(sourceType, sourceInstanceId, beforeMs)
-        } else {
-            val keep = keepSongKeys.toList()
-            if (keep.size <= 400) {
-                dao.pruneStaleTracksExcept(sourceType, sourceInstanceId, beforeMs, keep)
-            } else {
-                val stale = dao.getTracksBySource(sourceType)
-                    .asSequence()
-                    .filter {
-                        (sourceInstanceId == null || it.sourceInstanceId == sourceInstanceId) &&
-                            it.lastSeenAtMs < beforeMs &&
-                            it.songKey !in keepSongKeys
-                    }
-                    .map { it.songKey }
-                    .toList()
-                stale.forEach { dao.deleteTrack(it) }
-                stale.size
-            }
-        }
-        if (deleted > 0) {
-            dao.deleteOrphanAlbums()
-            dao.deleteOrphanArtists()
-            Log.i(TAG, "pruned $deleted stale $sourceType rows (kept ${keepSongKeys.size} My Stuff keys)")
-        }
-    }
-
-    suspend fun getRemoteOfferings(limit: Int = 64): List<SourceOffering> =
-        withContext(Dispatchers.IO) {
-            val per = (limit.coerceAtLeast(1) / 3).coerceAtLeast(1)
-            val jelly = dao.getTracksBySourceLimited(CatalogSources.JELLYFIN, per)
-            val sub = dao.getTracksBySourceLimited(CatalogSources.SUBSONIC, per)
-            val navi = dao.getTracksBySourceLimited(CatalogSources.NAVIDROME, per)
-            val names = sourceInstanceNames()
-            (jelly + sub + navi).asSequence().take(limit).map { offeringFor(it, names) }.toList()
-        }
-
-    suspend fun importToMyStuff(song: Song, sourceType: String, sourceInstanceId: Long?, externalId: String?) =
-        withContext(Dispatchers.IO) {
-            val now = System.currentTimeMillis()
-            dao.upsertTrack(
-                song.toTrackEntity(
-                    sourceType = sourceType,
-                    sourceInstanceId = sourceInstanceId,
-                    externalId = externalId,
-                    seenAt = now
-                )
-            )
-            Log.i(TAG, "imported to My Stuff: ${song.songKey} from $sourceType")
-        }
-
-    suspend fun applyAlbumYear(albumKey: String, year: Int) = withContext(Dispatchers.IO) {
-        if (year !in 1000..2100) return@withContext
-        val album = dao.getAlbum(albumKey) ?: return@withContext
-        dao.upsertAlbum(album.copy(year = year, updatedAtMs = System.currentTimeMillis()))
-        val tracks = expandAlbumTracksLocked(albumKey).mapNotNull { song ->
-            dao.getTrack(song.songKey)?.let { t ->
-                if (t.year == null || t.year <= 0) t.copy(year = year) else t
-            }
-        }
-        if (tracks.isNotEmpty()) dao.upsertTracks(tracks)
-    }
-
-    suspend fun applyAlbumCover(albumKey: String, coverPath: String?, coverUrl: String?, mbid: String?) =
-        withContext(Dispatchers.IO) {
-            val album = dao.getAlbum(albumKey) ?: return@withContext
-            dao.upsertAlbum(
-                album.copy(
-                    coverPath = coverPath ?: album.coverPath,
-                    coverUrl = coverUrl ?: album.coverUrl,
-                    mbid = mbid ?: album.mbid,
-                    updatedAtMs = System.currentTimeMillis()
-                )
-            )
-        }
-
-    suspend fun applyArtistImage(artistKey: String, imageUri: String?) = withContext(Dispatchers.IO) {
-        val artist = dao.getArtist(artistKey) ?: return@withContext
-        if (imageUri.isNullOrBlank()) return@withContext
-        dao.upsertArtist(artist.copy(imageUri = imageUri, updatedAtMs = System.currentTimeMillis()))
-    }
-
-    suspend fun coverPathForAlbum(albumKey: String): String? =
-        dao.getAlbum(albumKey)?.coverPath
-
-    private suspend fun persistCreditsLocked(songs: List<Song>, replaceAll: Boolean = false) {
-        if (songs.isEmpty()) return
-        if (replaceAll) dao.deleteAllCredits()
-        val credits = ArrayList<CatalogCreditEntity>()
-        val albumSeen = HashSet<String>()
-        val artistStubs = LinkedHashMap<String, CatalogArtistEntity>()
-        val existingArtists = dao.getAllArtists().associateBy { it.artistKey }.toMutableMap()
-        for (song in songs) {
-            if (!replaceAll) dao.deleteCredits("TRACK", song.songKey)
-            allCreditsForSong(song).forEach { c ->
-                val key = artistKey(c.name) ?: return@forEach
-                credits += CatalogCreditEntity(
-                    subjectType = "TRACK",
-                    subjectKey = song.songKey,
-                    artistKey = key,
-                    displayName = c.name,
-                    role = c.role.name,
-                    position = c.position
-                )
-                if (key !in existingArtists && key !in artistStubs) {
-                    artistStubs[key] = CatalogArtistEntity(
-                        artistKey = key,
-                        displayName = c.name,
-                        trackCount = 0,
-                        albumCount = 0,
-                        updatedAtMs = System.currentTimeMillis()
-                    )
-                }
-            }
-            val aKey = albumKey(song.album, song.effectiveAlbumArtist)
-            if (aKey.isNotBlank() && albumSeen.add(aKey)) {
-                if (!replaceAll) dao.deleteCredits("ALBUM", aKey)
-                parseArtistCreditList(song.albumArtist ?: song.effectiveAlbumArtist).forEach { c ->
-                    val key = artistKey(c.name) ?: return@forEach
-                    credits += CatalogCreditEntity(
-                        subjectType = "ALBUM",
-                        subjectKey = aKey,
-                        artistKey = key,
-                        displayName = c.name,
-                        role = c.role.name,
-                        position = c.position
-                    )
-                }
-            }
-            song.musicBrainzArtistId?.takeIf { it.isNotBlank() }?.let { mbid ->
-                listOfNotNull(
-                    artistKey(song.effectiveAlbumArtist),
-                    artistKey(song.artist)
-                ).distinct().forEach { key ->
-                    val existing = existingArtists[key] ?: dao.getArtist(key)
-                    if (existing != null && existing.mbid.isNullOrBlank()) {
-                        val next = existing.copy(mbid = mbid, updatedAtMs = System.currentTimeMillis())
-                        dao.upsertArtist(next)
-                        existingArtists[key] = next
-                    }
-                }
-            }
-        }
-        if (artistStubs.isNotEmpty()) dao.upsertArtists(artistStubs.values.toList())
-        if (credits.isNotEmpty()) credits.chunked(500).forEach { dao.upsertCredits(it) }
-    }
-
-    private suspend fun normalizeTrackIdentityLocked() {
-        val tracks = dao.getAllTracks()
-        val changed = ArrayList<CatalogTrackEntity>()
-        for (row in tracks) {
-            val song = row.toSong()
-            val newAlbum = albumKey(song.album, song.effectiveAlbumArtist).takeIf { !song.album.isNullOrBlank() }
-            val newArtist = artistKey(song.effectiveAlbumArtist)
-            if (row.albumKey != newAlbum || row.artistKey != newArtist) {
-                changed += row.copy(albumKey = newAlbum, artistKey = newArtist)
-            }
-        }
-        val byKey = HashMap<String, CatalogTrackEntity>(tracks.size)
-        tracks.forEach { byKey[it.songKey] = it }
-        changed.forEach { byKey[it.songKey] = it }
-        coalesceSplitAlbums(byKey.values.toList()).forEach { row ->
-            val prev = byKey[row.songKey]
-            if (prev == null || prev != row) {
-                byKey[row.songKey] = row
-                val idx = changed.indexOfFirst { it.songKey == row.songKey }
-                if (idx >= 0) changed[idx] = row else changed += row
-            }
-        }
-        if (changed.isEmpty()) return
-        changed.chunked(400).forEach { dao.upsertTracks(it) }
-        Log.i(TAG, "normalized identity on ${changed.size} tracks")
-    }
-
-    /**
-     * Same remote library + same album title + unique disc/track slots =
-     * one release (Navidrome VA / split-artist albums). Do not merge when
-     * two albums share a title and collide on track numbers (Greatest Hits).
-     */
-    private fun coalesceSplitAlbums(tracks: List<CatalogTrackEntity>): List<CatalogTrackEntity> {
-        val out = ArrayList<CatalogTrackEntity>()
-        val groups = tracks
-            .filter { !it.album.isNullOrBlank() && it.sourceType != CatalogSources.LOCAL }
-            .groupBy { Triple(it.sourceType, it.sourceInstanceId, foldTagToken(it.album.orEmpty())) }
-        for ((_, group) in groups) {
-            if (group.size < 2) continue
-            val keys = group.mapNotNull { it.albumKey }.toHashSet()
-            if (keys.size <= 1) continue
-            if (hasCollidingTrackSlots(group)) continue
-            val canonicalArtist = pickCanonicalAlbumArtist(group) ?: continue
-            val canonicalKey = albumKey(group.first().album, canonicalArtist)
-            val canonicalArtistKey = artistKey(canonicalArtist)
-            for (row in group) {
-                val stamp = row.albumArtist.isNullOrBlank() ||
-                    row.albumArtist.equals(row.artist, ignoreCase = true)
-                val next = row.copy(
-                    albumArtist = if (stamp) canonicalArtist else row.albumArtist,
-                    albumKey = canonicalKey,
-                    artistKey = canonicalArtistKey
-                )
-                if (next != row) out += next
-            }
-        }
-        return out
-    }
-
-    private fun hasCollidingTrackSlots(group: List<CatalogTrackEntity>): Boolean {
-        data class Slot(val disc: Int, val track: Int)
-        val titles = HashMap<Slot, String>()
-        for (t in group) {
-            val tn = t.trackNumber ?: continue
-            val slot = Slot(t.discNumber ?: 1, tn)
-            val title = TrackIdentity.normalizeTitle(t.title)
-            if (title.isEmpty()) continue
-            val existing = titles[slot]
-            if (existing != null && existing != title) return true
-            titles[slot] = title
-        }
-        return false
-    }
-
-    private fun pickCanonicalAlbumArtist(group: List<CatalogTrackEntity>): String? {
-        val tagged = group.mapNotNull { row ->
-            val aa = row.albumArtist?.trim()?.takeIf { it.isNotEmpty() } ?: return@mapNotNull null
-            val ta = row.artist?.trim().orEmpty()
-            if (aa.equals(ta, ignoreCase = true)) null else primaryArtistName(aa) ?: aa
-        }
-        val pool = if (tagged.isNotEmpty()) {
-            tagged
-        } else {
-            group.mapNotNull {
-                primaryArtistName(it.albumArtist) ?: it.albumArtist?.trim()?.takeIf { n -> n.isNotEmpty() }
-                    ?: primaryArtistName(it.artist) ?: it.artist?.trim()?.takeIf { n -> n.isNotEmpty() }
-            }
-        }
-        if (pool.isEmpty()) return null
-        return pool.groupingBy { it }.eachCount()
-            .entries
-            .sortedWith(compareByDescending<Map.Entry<String, Int>> { it.value }.thenBy { it.key.lowercase() })
-            .first()
-            .key
-    }
-
-    private suspend fun primaryTracksForArtistLocked(artistKey: String, hintName: String? = null): List<Song> {
-        val keys = ArtistAliasResolver.identityKeys(artistKey)
-        val out = LinkedHashMap<String, Song>()
-        dao.getTracksForArtists(keys).map { it.toSong() }.forEach { out[it.songKey] = it }
-        dao.getTracksByCreditRoles(keys, ArtistRole.PRIMARY.name)
-            .map { it.toSong() }
-            .forEach { out.putIfAbsent(it.songKey, it) }
-        val names = buildList {
-            dao.getArtist(keys.first())?.displayName?.let { add(it) }
-            hintName?.let { add(it) }
-            dao.aliasesForCanonical(keys.first()).forEach { add(it.aliasName) }
-        }.distinct()
-        names.filter { it.length >= 3 }.forEach { name ->
-            dao.getTracksMentioning(name).forEach { entity ->
-                val song = entity.toSong()
-                val hit = allCreditsForSong(song).any {
-                    it.role == ArtistRole.PRIMARY &&
-                        ArtistAliasResolver.resolve(artistKey(it.name) ?: "") ==
-                        ArtistAliasResolver.resolve(artistKey)
-                }
-                if (hit) out.putIfAbsent(entity.songKey, song)
-            }
-        }
-        return out.values.toList()
-    }
-
-    private fun Song.toLocalTrackEntity(seenAt: Long) = toTrackEntity(
-        sourceType = CatalogSources.LOCAL,
-        sourceInstanceId = null,
-        externalId = null,
-        seenAt = seenAt
-    )
-
-    private fun Song.toTrackEntity(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        externalId: String?,
-        seenAt: Long
-    ): CatalogTrackEntity {
-        val aKey = albumKey(album, effectiveAlbumArtist)
-        val rKey = artistKey(effectiveAlbumArtist)
-        return CatalogTrackEntity(
-            songKey = songKey,
-            sourceType = sourceType,
-            sourceInstanceId = sourceInstanceId,
-            externalId = externalId,
-            title = title,
-            artist = artist,
-            albumArtist = albumArtist,
-            album = album,
-            year = year,
-            trackNumber = trackNumber,
-            discNumber = discNumber,
-            durationMs = durationMs,
-            albumKey = aKey.takeIf { album != null },
-            artistKey = rKey,
-            contentUri = contentUri.toString(),
-            path = path,
-            albumArtUri = albumArtUri?.toString(),
-            mimeType = mimeType,
-            isTagged = isTagged,
-            updatedAtMs = seenAt,
-            lastSeenAtMs = seenAt
-        )
-    }
-
-    private fun CatalogTrackEntity.sameRemoteMeta(incoming: CatalogTrackEntity): Boolean {
-        if (!incoming.title.isNullOrBlank() && title != incoming.title) return false
-        if (!incoming.artist.isNullOrBlank() && artist != incoming.artist) return false
-        if (!incoming.albumArtist.isNullOrBlank() && albumArtist != incoming.albumArtist) return false
-        if (!incoming.album.isNullOrBlank() && album != incoming.album) return false
-        if (incoming.year != null && year != incoming.year) return false
-        if (incoming.trackNumber != null && trackNumber != incoming.trackNumber) return false
-        if (incoming.discNumber != null && discNumber != incoming.discNumber) return false
-        if (incoming.durationMs != null && incoming.durationMs > 0 && durationMs != incoming.durationMs) return false
-        if (incoming.albumArtUri != null && albumArtUri != incoming.albumArtUri) return false
-        if (incoming.mimeType != null && mimeType != incoming.mimeType) return false
-        return true
-    }
-
-    private suspend fun sourceInstanceNames(): Map<Long, String> =
-        sourceInstances.getAll().associate { it.id to it.name }
-
-    private fun offeringFor(
-        row: CatalogTrackEntity,
-        names: Map<Long, String>
-    ): SourceOffering {
-        val type = SourceType.from(row.sourceType)
-        val label = names[row.sourceInstanceId]?.takeIf { it.isNotBlank() }
-            ?: if (type == SourceType.LOCAL) "On this device" else type.displayName()
-        return SourceOffering(
-            sourceType = type,
-            sourceId = row.sourceInstanceId,
-            sourceName = label,
-            song = row.toSong()
-        )
-    }
-
-    private fun CatalogTrackEntity.toSong(): Song = Song(
-        id = id,
-        title = title,
-        artist = artist,
-        albumArtist = albumArtist,
-        album = album,
-        durationMs = durationMs,
-        contentUri = android.net.Uri.parse(contentUri),
-        albumArtUri = albumArtUri?.let { android.net.Uri.parse(it) },
-        trackNumber = trackNumber,
-        discNumber = discNumber,
-        year = year,
-        path = path,
-        mimeType = mimeType
     )
-
-    companion object {
-        private const val TAG = "CatalogRepo"
-
-        fun sourceTypeForSong(song: Song): SourceType {
-            val p = song.path.orEmpty()
-            return when {
-                p.startsWith("jellyfin:", true) -> SourceType.JELLYFIN
-                p.startsWith("navidrome:", true) -> SourceType.NAVIDROME
-                p.startsWith("subsonic:", true) -> SourceType.SUBSONIC
-                else -> SourceType.LOCAL
-            }
-        }
-
-        fun friendlySourceName(raw: String): String =
-            raw.lowercase().replaceFirstChar { it.titlecase() }
-
-        fun isMultiSource(offerings: List<SourceOffering>): Boolean =
-            offerings.map { "${it.sourceType.name}:${it.sourceId}" }.toSet().size > 1
-
-        fun dedupeLogicalTracks(tracks: List<Song>): List<Song> {
-            if (tracks.isEmpty()) return emptyList()
-            return tracks
-                .groupBy { TrackIdentity.of(it) }
-                .values
-                .map { group ->
-                    val preferred = group.minByOrNull { sourceTypeForSong(it).rank } ?: group.first()
-                    TrackIdentity.withRichestDisplay(preferred, group)
-                }
-                .sortedWith(albumTrackOrder())
-        }
-
-        private fun guessReleaseType(trackCount: Int): ReleaseType = when {
-            trackCount <= 3 -> ReleaseType.SINGLE
-            trackCount <= 8 -> ReleaseType.EP
-            else -> ReleaseType.ALBUM
-        }
-    }
-}
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/CoverCandidates.kt b/app/src/main/java/capital/yuri/yuriplayer/data/CoverCandidates.kt
index cc0a7577..e42ba60d 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/CoverCandidates.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/CoverCandidates.kt
@@ -41,8 +41,8 @@ object CoverCandidates {
                     )
                 }
                 // SAF / content:// — embedded art only available via seedSong
-                isContentPath || song.contentUri.scheme.equals("content", true) -> {
-                    val key = song.contentUri.toString()
+                isContentPath || android.net.Uri.parse(song.contentUri).scheme.equals("content", true) -> {
+                    val key = song.contentUri
                     add(
                         CoverCandidate(
                             id = "saf:$key",
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/ExploreSearchService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/ExploreSearchService.kt
index 7eb10288..2eb106d8 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/ExploreSearchService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/ExploreSearchService.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.db.CatalogSources
 import capital.yuri.yuriplayer.data.source.JellyfinClient
 import capital.yuri.yuriplayer.data.source.LibrarySourceFactory
@@ -102,24 +102,24 @@ class ExploreSearchService(
 
     fun requestPauseAll() {
         pauseAll.set(true)
-        Log.i(TAG, "pause all requested")
+        log.i { "pause all requested" }
     }
 
     fun requestStopAll() {
         stopAll.set(true)
         pauseAll.set(true)
-        Log.i(TAG, "stop all requested")
+        log.i { "stop all requested" }
     }
 
     fun requestPauseSource(sourceInstanceId: Long) {
         pausedSources.add(sourceInstanceId)
-        Log.i(TAG, "pause source $sourceInstanceId")
+        log.i { "pause source $sourceInstanceId" }
     }
 
     fun requestStopSource(sourceInstanceId: Long) {
         stoppedSources.add(sourceInstanceId)
         pausedSources.add(sourceInstanceId)
-        Log.i(TAG, "stop source $sourceInstanceId")
+        log.i { "stop source $sourceInstanceId" }
     }
 
     fun clearControlFlags() {
@@ -145,13 +145,13 @@ class ExploreSearchService(
             hydrated = true
             if (count > 0) cacheAtMs = System.currentTimeMillis()
             refreshCheckpointSnapshot()
-            Log.i(TAG, "hydrated remote count=$count (no full list loaded)")
+            log.i { "hydrated remote count=$count (no full list loaded)" }
         }
     }
 
     fun requestRemoteScan(force: Boolean = false, sourceId: Long? = null) {
         if (!force && _isScanning.value) {
-            Log.i(TAG, "requestRemoteScan ignored — already scanning")
+            log.i { "requestRemoteScan ignored — already scanning" }
             return
         }
         val age = System.currentTimeMillis() - cacheAtMs
@@ -160,7 +160,7 @@ class ExploreSearchService(
                 it.status == SourceScanStatus.PAUSED || it.status == SourceScanStatus.STOPPED
             }
             if (!hasPaused) {
-                Log.i(TAG, "requestRemoteScan skipped — cache warm (${_indexedCount.value})")
+                log.i { "requestRemoteScan skipped — cache warm (${_indexedCount.value})" }
                 return
             }
         }
@@ -168,13 +168,13 @@ class ExploreSearchService(
         if (!NetworkPolicy.allowsRemoteSync(context, settings)) {
             val reason = NetworkPolicy.blockedReason(context, settings)
                 ?: "Remote sync blocked on this network"
-            Log.i(TAG, "requestRemoteScan blocked: $reason")
+            log.i { "requestRemoteScan blocked: $reason" }
             _lastError.value = reason
             return
         }
 
         if (force) clearControlFlags()
-        Log.i(TAG, "requestRemoteScan force=$force sourceId=$sourceId indexed=${_indexedCount.value}")
+        log.i { "requestRemoteScan force=$force sourceId=$sourceId indexed=${_indexedCount.value}" }
         LibraryScanService.startRemote(context.applicationContext, force, sourceId)
     }
 
@@ -204,15 +204,30 @@ class ExploreSearchService(
     suspend fun searchWithPrefer(query: String, forceRescan: Boolean = false): List<Hit> =
         search(query, forceRescan)
 
-    suspend fun searchLive(query: String, limit: Int = 80): List<Hit> =
+    suspend fun searchLive(
+        query: String,
+        limit: Int = 80,
+        sourceFilters: List<Pair<String, Long?>>? = null
+    ): List<Hit> =
         withContext(Dispatchers.IO) {
             val q = query.trim()
             if (q.isEmpty()) return@withContext emptyList()
-            buildHitsFromDb(q, limit = limit)
+            val songs = if (sourceFilters.isNullOrEmpty()) {
+                catalog.searchSongs(q, limit = limit * 3)
+            } else {
+                sourceFilters.flatMap { (type, instanceId) ->
+                    catalog.searchSongsForSource(type, instanceId, q, limit)
+                }.distinctBy { it.songKey }
+            }
+            hitsFromSongs(songs, limit)
         }
 
     private suspend fun buildHitsFromDb(needle: String, limit: Int): List<Hit> {
         val songs = catalog.searchSongs(needle, limit = limit * 3)
+        return hitsFromSongs(songs, limit)
+    }
+
+    private suspend fun hitsFromSongs(songs: List<Song>, limit: Int): List<Hit> {
         if (songs.isEmpty()) return emptyList()
 
         val grouped = songs.groupBy { TrackIdentity.of(it) }
@@ -276,7 +291,7 @@ class ExploreSearchService(
             ?: "Remote sync blocked on this network"
         _lastError.value = reason
         progress(reason)
-        Log.i(TAG, "sync paused: $reason")
+        log.i { "sync paused: $reason" }
         return false
     }
 
@@ -293,15 +308,15 @@ class ExploreSearchService(
         progress("Building album / artist index…")
         runCatching {
             catalog.rebuildRollups()
-            Log.i(TAG, "rollups rebuilt ($reason)")
+            log.i { "rollups rebuilt ($reason)" }
         }.onFailure {
-            Log.w(TAG, "rollups failed ($reason): ${it.message}")
+            log.w { "rollups failed ($reason): ${it.message}" }
         }
     }
 
     private suspend fun runRemoteScan(force: Boolean, onlySourceId: Long? = null) {
         if (!mutex.tryLock()) {
-            Log.i(TAG, "scan already running — skip")
+            log.i { "scan already running — skip" }
             return
         }
         try {
@@ -315,7 +330,7 @@ class ExploreSearchService(
             _lastError.value = null
             pageCounter.set(0)
             notifier.update("Syncing libraries", "Connecting…")
-            Log.i(TAG, "remote scan start force=$force sourceId=$onlySourceId")
+            log.i { "remote scan start force=$force sourceId=$onlySourceId" }
 
             val rows = instances.getAll().filter { it.enabled }
                 .filter { onlySourceId == null || it.id == onlySourceId }
@@ -484,13 +499,13 @@ class ExploreSearchService(
                 }
             }
 
-            Log.i(TAG, "remote index ready: count=$finalCount")
+            log.i { "remote index ready: count=$finalCount" }
         } catch (e: CancellationException) {
-            Log.i(TAG, "remote scan cancelled")
+            log.i { "remote scan cancelled" }
             throw e
         } catch (e: Exception) {
             _lastError.value = e.message ?: "Scan failed"
-            Log.e(TAG, "remote index failed", e)
+            log.e(e) { "remote index failed" }
         } finally {
             _isScanning.value = false
             _scanProgress.value = null
@@ -517,7 +532,7 @@ class ExploreSearchService(
         totalHint: Int?
     ): RemoteScanResult {
         val remoteTotal = jellyfinClient.audioItemCount(session).getOrElse {
-            Log.w(TAG, "delta count failed $sourceName: ${it.message}")
+            log.w { "delta count failed $sourceName: ${it.message}" }
             _lastError.value = "$sourceName: ${it.message}"
             return RemoteScanResult()
         }
@@ -526,13 +541,13 @@ class ExploreSearchService(
             checkpoints.markDone(rowId, sourceName, known, remoteTotal)
             refreshCheckpointSnapshot()
             progress("$sourceName: up to date ($remoteTotal)")
-            Log.i(TAG, "jellyfin delta skip $sourceName known=$known remote=$remoteTotal")
+            log.i { "jellyfin delta skip $sourceName known=$known remote=$remoteTotal" }
             return RemoteScanResult(delivered = 0)
         }
         val grow = remoteTotal - known
         val cap = (grow + 64).coerceIn(1, 2_000)
         progress("$sourceName: $grow new tracks")
-        Log.i(TAG, "jellyfin delta $sourceName +$grow known=$known remote=$remoteTotal cap=$cap")
+        log.i { "jellyfin delta $sourceName +$grow known=$known remote=$remoteTotal cap=$cap" }
 
         var inserted = 0
         var updated = 0
@@ -560,13 +575,13 @@ class ExploreSearchService(
             val n = total ?: remoteTotal
             progress("$sourceName: +$inserted new · $n on server")
         }.onFailure {
-            Log.w(TAG, "jellyfin delta fetch failed $sourceName: ${it.message}")
+            log.w { "jellyfin delta fetch failed $sourceName: ${it.message}" }
             _lastError.value = "$sourceName: ${it.message}"
         }
 
         checkpoints.markDone(rowId, sourceName, knownCount + delivered, remoteTotal)
         refreshCheckpointSnapshot()
-        Log.i(TAG, "jellyfin delta done $sourceName +$inserted ~$updated of $grow")
+        log.i { "jellyfin delta done $sourceName +$inserted ~$updated of $grow" }
         return RemoteScanResult(
             delivered = delivered,
             inserted = inserted,
@@ -594,7 +609,7 @@ class ExploreSearchService(
         val session = jellyfinSessions[rowId] ?: jellyfinClient.authenticate(url, user, pass)
             .getOrElse {
                 if (it is CancellationException) throw it
-                Log.w(TAG, "jellyfin auth failed: ${it.message}")
+                log.w { "jellyfin auth failed: ${it.message}" }
                 _lastError.value = "$sourceName: ${it.message}"
                 return RemoteScanResult()
             }.also { jellyfinSessions[rowId] = it }
@@ -686,16 +701,16 @@ class ExploreSearchService(
             when {
                 it is CancellationException && paused -> {
                     checkpoints.markPaused(rowId, sourceName, cursor, delivered, totalHint)
-                    Log.i(TAG, "jellyfin paused $sourceName at cursor=$cursor delivered=$delivered")
+                    log.i { "jellyfin paused $sourceName at cursor=$cursor delivered=$delivered" }
                 }
                 it is CancellationException && aborted -> {
                     checkpoints.markStopped(rowId, sourceName, cursor, delivered, totalHint)
-                    Log.i(TAG, "jellyfin stopped $sourceName at cursor=$cursor")
+                    log.i { "jellyfin stopped $sourceName at cursor=$cursor" }
                 }
                 it is CancellationException -> throw it
                 else -> {
                     jellyfinSessions.remove(rowId)
-                    Log.w(TAG, "jellyfin scan failed: ${it.message}")
+                    log.w { "jellyfin scan failed: ${it.message}" }
                     _lastError.value = "$sourceName: ${it.message}"
                 }
             }
@@ -717,10 +732,7 @@ class ExploreSearchService(
         }
         checkpoints.markDone(rowId, sourceName, delivered, totalHint)
         refreshCheckpointSnapshot()
-        Log.i(
-            TAG,
-            "jellyfin $sourceName done delivered=$delivered +$inserted ~$updated -$removed incremental=$incremental"
-        )
+        log.i { "jellyfin $sourceName done delivered=$delivered +$inserted ~$updated -$removed incremental=$incremental" }
         return RemoteScanResult(
             delivered = delivered,
             inserted = inserted,
@@ -760,7 +772,7 @@ class ExploreSearchService(
             attempted++
             budget.yieldBetweenArt()
         }
-        Log.i(TAG, "passive art pass: attempted=$attempted cached=${cachedAlbumArtKeys.size}")
+        log.i { "passive art pass: attempted=$attempted cached=${cachedAlbumArtKeys.size}" }
     }
 
     private suspend fun scanSubsonicNewest(
@@ -777,7 +789,7 @@ class ExploreSearchService(
             pageSize = 20,
             type = "newest"
         ).getOrElse {
-            Log.w(TAG, "subsonic newest failed $sourceName: ${it.message}")
+            log.w { "subsonic newest failed $sourceName: ${it.message}" }
             return RemoteScanResult()
         }
         var inserted = 0
@@ -798,7 +810,7 @@ class ExploreSearchService(
         }
         checkpoints.markDone(instanceId, sourceName, delivered, null)
         refreshCheckpointSnapshot()
-        Log.i(TAG, "subsonic newest $sourceName albums=${page.albums.size} +$inserted ~$updated")
+        log.i { "subsonic newest $sourceName albums=${page.albums.size} +$inserted ~$updated" }
         progress("$sourceName: +$inserted new")
         return RemoteScanResult(delivered = delivered, inserted = inserted, updated = updated)
     }
@@ -833,7 +845,7 @@ class ExploreSearchService(
 
         val session = subsonicClient.ping(baseSession).getOrElse {
             if (it is CancellationException) throw it
-            Log.w(TAG, "subsonic ping failed: ${it.message}")
+            log.w { "subsonic ping failed: ${it.message}" }
             _lastError.value = "$sourceName: ${it.message}"
             return RemoteScanResult()
         }
@@ -916,15 +928,15 @@ class ExploreSearchService(
             when {
                 it is CancellationException && paused -> {
                     checkpoints.markPaused(instanceId, sourceName, albumOffset, delivered, null)
-                    Log.i(TAG, "subsonic paused $sourceName at albumOffset=$albumOffset delivered=$delivered")
+                    log.i { "subsonic paused $sourceName at albumOffset=$albumOffset delivered=$delivered" }
                 }
                 it is CancellationException && aborted -> {
                     checkpoints.markStopped(instanceId, sourceName, albumOffset, delivered, null)
-                    Log.i(TAG, "subsonic stopped $sourceName at albumOffset=$albumOffset")
+                    log.i { "subsonic stopped $sourceName at albumOffset=$albumOffset" }
                 }
                 it is CancellationException -> throw it
                 else -> {
-                    Log.w(TAG, "subsonic scan failed: ${it.message}")
+                    log.w { "subsonic scan failed: ${it.message}" }
                     _lastError.value = "$sourceName: ${it.message}"
                 }
             }
@@ -946,10 +958,7 @@ class ExploreSearchService(
         }
         checkpoints.markDone(instanceId, sourceName, delivered, delivered)
         refreshCheckpointSnapshot()
-        Log.i(
-            TAG,
-            "subsonic $sourceName done delivered=$delivered +$inserted ~$updated -$removed"
-        )
+        log.i { "subsonic $sourceName done delivered=$delivered +$inserted ~$updated -$removed" }
         return RemoteScanResult(
             delivered = delivered,
             inserted = inserted,
@@ -976,7 +985,7 @@ class ExploreSearchService(
     }
 
     companion object {
-        private const val TAG = "ExploreSearch"
+        private val log = yuriLog("ExploreSearch")
         private const val SCOPE_TRACK = "track"
         private const val CACHE_TTL_MS = 15L * 60 * 1000
         private const val WARM_SOURCE_MIN_TRACKS = 50
@@ -984,8 +993,8 @@ class ExploreSearchService(
         fun trackIdentity(song: Song): String = TrackIdentity.of(song)
 
         fun isLocalFilesystemSong(song: Song): Boolean {
-            val p = song.path ?: return song.contentUri.scheme == "content" ||
-                song.contentUri.scheme == "file"
+            val p = song.path ?: return android.net.Uri.parse(song.contentUri).scheme == "content" ||
+                android.net.Uri.parse(song.contentUri).scheme == "file"
             if (p.startsWith("jellyfin:", ignoreCase = true)) return false
             if (p.startsWith("subsonic:", ignoreCase = true)) return false
             if (p.startsWith("navidrome:", ignoreCase = true)) return false
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/FilenameMetadata.kt b/app/src/main/java/capital/yuri/yuriplayer/data/FilenameMetadata.kt
index 8b1f67f0..839424e5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/FilenameMetadata.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/FilenameMetadata.kt
@@ -1,80 +1,3 @@
 package capital.yuri.yuriplayer.data
 
-/**
- * Tags inferred from a file name / parent folder when the embedded tag is empty.
- *
- * Patterns:
- *  - `08. Title` / `08 - Title` / `08_Title`
- *  - `1-08 Title` / `01-08. Title` (disc-track)
- *  - `CD2 - 08 Title` / `Disc 2 - 08. Title`
- *  - parent folder `CD2` / `Disc 2`
- */
-data class FilenameMetadata(
-    val trackNumber: Int? = null,
-    val discNumber: Int? = null,
-    val title: String? = null
-) {
-    val isEmpty: Boolean
-        get() = trackNumber == null && discNumber == null && title.isNullOrBlank()
-}
-
-object FilenameMetadataParser {
-
-    private val DISC_TRACK_TITLE = Regex(
-        """^(?:(?:CD|Disc|Disk)\s*)?(\d{1,2})\s*[-.]\s*(\d{1,3})\s*[-._)\s]+\s*(.+)$""",
-        RegexOption.IGNORE_CASE
-    )
-    private val CD_PREFIX_TRACK = Regex(
-        """^(?:CD|Disc|Disk)\s*(\d{1,2})\s*[-._ ]+\s*(\d{1,3})\s*[-._)\s]+\s*(.+)$""",
-        RegexOption.IGNORE_CASE
-    )
-    private val TRACK_TITLE = Regex(
-        """^(\d{1,3})\s*[-._)\s]+\s*(.+)$"""
-    )
-    private val DISC_FOLDER = Regex(
-        """^(?:CD|Disc|Disk)\s*(\d{1,2})$""",
-        RegexOption.IGNORE_CASE
-    )
-
-    fun parse(path: String?): FilenameMetadata {
-        if (path.isNullOrBlank()) return FilenameMetadata()
-        val slash = path.replace('\\', '/')
-        val fileName = slash.substringAfterLast('/').substringBeforeLast('.')
-        val parent = slash.substringBeforeLast('/').substringAfterLast('/')
-
-        var disc: Int? = null
-        var track: Int? = null
-        var title: String? = null
-
-        CD_PREFIX_TRACK.matchEntire(fileName)?.let { m ->
-            disc = m.groupValues[1].toIntOrNull()
-            track = m.groupValues[2].toIntOrNull()?.takeIf { it > 0 }
-            title = cleanTitle(m.groupValues[3])
-        } ?: DISC_TRACK_TITLE.matchEntire(fileName)?.let { m ->
-            val a = m.groupValues[1].toIntOrNull()
-            val b = m.groupValues[2].toIntOrNull()?.takeIf { it > 0 }
-            if (a != null && a in 1..99 && b != null) {
-                disc = a
-                track = b
-                title = cleanTitle(m.groupValues[3])
-            }
-        } ?: TRACK_TITLE.matchEntire(fileName)?.let { m ->
-            track = m.groupValues[1].toIntOrNull()?.takeIf { it in 1..999 }
-            title = cleanTitle(m.groupValues[2])
-        }
-
-        if (disc == null) {
-            disc = DISC_FOLDER.matchEntire(parent.trim())?.groupValues?.getOrNull(1)?.toIntOrNull()
-        }
-        return FilenameMetadata(
-            trackNumber = track,
-            discNumber = disc?.takeIf { it > 0 },
-            title = title
-        )
-    }
-
-    private fun cleanTitle(raw: String): String? {
-        val t = raw.trim().trim('.', '-', '_').trim()
-        return t.takeIf { it.length >= 1 }
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/HomeRowId.kt b/app/src/main/java/capital/yuri/yuriplayer/data/HomeRowId.kt
new file mode 100644
index 00000000..7b92d399
--- /dev/null
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/HomeRowId.kt
@@ -0,0 +1,9 @@
+package capital.yuri.yuriplayer.data
+
+enum class HomeRowId(val id: String, val label: String, val subtitle: String) {
+    RECENTS("recents", "Recents", "Recently played, newest first"),
+    RANDOM_ALBUMS("random_albums", "Random albums", "A handful from My Stuff"),
+    RANDOM_SONGS("random_songs", "Random songs", "A handful from My Stuff"),
+    RANDOM_PLAYLISTS("random_playlists", "Random playlists", "A handful from My Stuff"),
+    RANDOM_ARTISTS("random_artists", "Random artists", "A handful from My Stuff")
+}
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryCache.kt b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryCache.kt
index 1209f985..ea7b89a5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryCache.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryCache.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.json.AppJson
 import kotlinx.serialization.Serializable
 import java.io.File
@@ -20,7 +20,7 @@ class LibraryCache(context: Context) {
             val songs = dto.songs.map { it.cleaned() }
             CachedLibrary(songs, dto.scannedAt)
         } catch (e: Exception) {
-            Log.w(TAG, "Failed to load library cache", e)
+            log.w(e) { "Failed to load library cache" }
             null
         }
     }
@@ -39,7 +39,7 @@ class LibraryCache(context: Context) {
                 tmpFile.delete()
             }
         } catch (e: Exception) {
-            Log.e(TAG, "Failed to save library cache", e)
+            log.e(e) { "Failed to save library cache" }
             try { tmpFile.delete() } catch (_: Exception) {}
         }
     }
@@ -54,7 +54,7 @@ class LibraryCache(context: Context) {
     fun cacheFilePath(): String = file.absolutePath
 
     companion object {
-        private const val TAG = "LibraryCache"
+        private val log = yuriLog("LibraryCache")
         private const val FILE_NAME = "library_index.json"
         private const val CACHE_VERSION = 3
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryIndex.kt b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryIndex.kt
index 352eab3a..fe5ca520 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryIndex.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryIndex.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -27,7 +27,7 @@ class LibraryIndex(
     private val cache: LibraryCache,
     private val catalog: CatalogRepository,
     private val notifier: LibraryScanNotifier
-) {
+) : LocalLibrary {
 
     // Default dispatcher: never block Main while loading large lists
     private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
@@ -35,6 +35,8 @@ class LibraryIndex(
     private val _songs = MutableStateFlow<List<Song>>(emptyList())
     val songs: StateFlow<List<Song>> = _songs.asStateFlow()
 
+    override fun songs(): List<Song> = _songs.value
+
     private val _isLoading = MutableStateFlow(false)
     val isLoading: StateFlow<Boolean> = _isLoading.asStateFlow()
 
@@ -65,7 +67,7 @@ class LibraryIndex(
             if (hadCache) {
                 _songs.value = cached!!.songs
                 _lastScannedAt.value = cached.scannedAt
-                Log.i(TAG, "bootstrap from cache: ${cached.songs.size} tracks")
+                log.i { "bootstrap from cache: ${cached.songs.size} tracks" }
             }
 
             // 2) Room only when cache missed — avoid loading large local tables
@@ -75,7 +77,7 @@ class LibraryIndex(
                 if (fromDb.isNotEmpty()) {
                     _songs.value = fromDb
                     _lastScannedAt.value = System.currentTimeMillis()
-                    Log.i(TAG, "bootstrap from Room local: ${fromDb.size} tracks")
+                    log.i { "bootstrap from Room local: ${fromDb.size} tracks" }
                 }
             }
 
@@ -85,7 +87,7 @@ class LibraryIndex(
                 _songs.value.isEmpty() -> {
                     delay(COLD_EMPTY_RESCAN_DELAY_MS)
                     if (_songs.value.isEmpty() && !_isLoading.value) {
-                        Log.i(TAG, "bootstrap: empty after delay → local rescan")
+                        log.i { "bootstrap: empty after delay → local rescan" }
                         refresh()
                     }
                 }
@@ -98,7 +100,7 @@ class LibraryIndex(
                         if (stillStale && !_isLoading.value) {
                             delay(STALE_RESCAN_DELAY_MS)
                             if (!_isLoading.value) {
-                                Log.i(TAG, "bootstrap: stale after reconcile → deferred local rescan")
+                                log.i { "bootstrap: stale after reconcile → deferred local rescan" }
                                 refresh()
                             }
                         }
@@ -108,11 +110,11 @@ class LibraryIndex(
                 age > staleAfterMs -> {
                     delay(STALE_RESCAN_DELAY_MS)
                     if (!_isLoading.value) {
-                        Log.i(TAG, "bootstrap: stale (${age}ms) → deferred local rescan")
+                        log.i { "bootstrap: stale (${age}ms) → deferred local rescan" }
                         refresh()
                     }
                 }
-                else -> Log.i(TAG, "bootstrap: warm local index, skip auto-rescan")
+                else -> log.i { "bootstrap: warm local index, skip auto-rescan" }
             }
         }
     }
@@ -122,7 +124,7 @@ class LibraryIndex(
         val local = withContext(Dispatchers.IO) { catalog.getLocalSongs() }
         _songs.value = local
         _lastScannedAt.value = System.currentTimeMillis()
-        Log.i(TAG, "reloadFromCatalog (local): ${local.size} tracks")
+        log.i { "reloadFromCatalog (local): ${local.size} tracks" }
     }
 
     fun refresh() {
@@ -150,7 +152,6 @@ class LibraryIndex(
             notifier.finish("Library scan", "Storage permission required")
         } catch (e: Exception) {
             _error.value = e.message ?: "Scan failed"
-            Log.e(TAG, "Refresh failed", e)
             _events.tryEmit(LibraryEvent.ScanFailed(e.message ?: "Scan failed"))
             notifier.finish("Library scan", e.message ?: "Scan failed")
         } finally {
@@ -167,14 +168,14 @@ class LibraryIndex(
         var changed = false
         val next = current.map { song ->
             val key = albumKey(song.album, song.effectiveAlbumArtist)
-            if (key == albumKey && (song.year == null || song.year <= 0)) {
+            if (key == albumKey && (song.year ?: 0) <= 0) {
                 changed = true
                 song.copy(year = year)
             } else song
         }
         if (changed) {
             _songs.value = next
-            Log.i(TAG, "applied year $year to albumKey=$albumKey")
+            log.i { "applied year $year to albumKey=$albumKey" }
         }
     }
 
@@ -194,6 +195,9 @@ class LibraryIndex(
         return base.filter { songMatches(it, q) }
     }
 
+    override fun albums(taggedOnly: Boolean): List<AlbumItem> =
+        albums(query = "", taggedOnly = taggedOnly)
+
     fun albums(query: String = "", taggedOnly: Boolean = true): List<AlbumItem> {
         val q = query.trim()
         val source = if (taggedOnly) {
@@ -241,7 +245,7 @@ class LibraryIndex(
                     ?: tracks.firstOrNull()?.album
 
                 val deduped = tracks.distinctBy {
-                    it.path?.lowercase() ?: it.contentUri.toString()
+                    it.path?.lowercase() ?: it.contentUri
                 }
 
                 AlbumItem(
@@ -283,7 +287,7 @@ class LibraryIndex(
                     ?.key
                 if (isCombinedArtistName(displayName)) return@mapNotNull null
                 val deduped = tracks.distinctBy {
-                    it.path?.lowercase() ?: it.contentUri.toString()
+                    it.path?.lowercase() ?: it.contentUri
                 }
                 val albumKeys = deduped.mapNotNull { albumKey(it.album, it.effectiveAlbumArtist) }.toSet()
                 ArtistItem(
@@ -304,7 +308,7 @@ class LibraryIndex(
     fun untaggedCount(): Int = _songs.value.count { !it.isTagged }
 
     companion object {
-        private const val TAG = "LibraryIndex"
+        private val log = yuriLog("LibraryIndex")
         const val DEFAULT_STALE_MS = 12L * 60 * 60 * 1000
         /** Wait so MusicService can restore + user can hit Play first. */
         private const val COLD_EMPTY_RESCAN_DELAY_MS = 5_000L
@@ -313,8 +317,7 @@ class LibraryIndex(
         private const val ROOM_RECONCILE_DELAY_MS = 8_000L
 
         fun normalizeKey(value: String?): String? {
-            if (value == null) return null
-            val t = value.trim().replace(Regex("\\s+"), " ").lowercase()
+            val t = value.orEmpty().trim().replace(Regex("\\s+"), " ").lowercase()
             return t.takeIf { it.isNotEmpty() }
         }
 
@@ -355,23 +358,3 @@ class LibraryIndex(
         }
     }
 }
-
-data class AlbumItem(
-    val name: String?,
-    val artist: String?,
-    val trackCount: Int,
-    val songs: List<Song>
-) {
-    val displayName: String get() = name ?: "Unknown Album"
-    val displayArtist: String
-        get() = primaryArtistName(artist) ?: artist ?: "Unknown Artist"
-}
-
-data class ArtistItem(
-    val name: String?,
-    val trackCount: Int,
-    val albumCount: Int,
-    val songs: List<Song>
-) {
-    val displayName: String get() = primaryArtistName(name) ?: name ?: "Unknown Artist"
-}
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanNotifier.kt b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanNotifier.kt
index 2b503e62..ff5854bf 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanNotifier.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanNotifier.kt
@@ -1,5 +1,7 @@
 package capital.yuri.yuriplayer.data
 
+import capital.yuri.yuriplayer.core.log.yuriLog
+
 import android.app.Notification
 import android.app.NotificationChannel
 import android.app.NotificationManager
@@ -95,7 +97,7 @@ class LibraryScanNotifier(
             nm.notify(NOTIFICATION_ID, build(title, text, progress, max))
         } catch (e: SecurityException) {
             // POST_NOTIFICATIONS denied — FGS may still hold the service notification
-            android.util.Log.w(TAG, "notify blocked: ${e.message}")
+            log.w { "notify blocked: ${e.message}" }
         }
     }
 
@@ -121,7 +123,7 @@ class LibraryScanNotifier(
                 .build()
             nm.notify(NOTIFICATION_ID, done)
         } catch (e: SecurityException) {
-            android.util.Log.w(TAG, "finish notify blocked: ${e.message}")
+            log.w { "finish notify blocked: ${e.message}" }
         }
     }
 
@@ -130,7 +132,7 @@ class LibraryScanNotifier(
     }
 
     companion object {
-        private const val TAG = "LibraryScanNotifier"
+        private val log = yuriLog("LibraryScanNotifier")
         const val CHANNEL_ID = "yuri_library_scan"
         const val NOTIFICATION_ID = 4201
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanService.kt
index dacf9d8d..18004261 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/LibraryScanService.kt
@@ -7,7 +7,7 @@ import android.content.pm.ServiceInfo
 import android.os.Build
 import android.os.IBinder
 import android.os.Process
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.core.app.ServiceCompat
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
@@ -33,6 +33,8 @@ class LibraryScanService : Service() {
     private val scanDispatcher = Dispatchers.IO.limitedParallelism(1)
     private val scope = CoroutineScope(SupervisorJob() + scanDispatcher)
     private var work: Job? = null
+    @Volatile private var queuedForce = false
+    @Volatile private var queuedSourceId: Long? = null
 
     override fun onBind(intent: Intent?): IBinder? = null
 
@@ -43,14 +45,14 @@ class LibraryScanService : Service() {
 
         when (action) {
             ACTION_STOP -> {
-                Log.i(TAG, "stop requested sourceId=$sourceId")
+                log.i { "stop requested sourceId=$sourceId" }
                 if (sourceId != null) explore.requestStopSource(sourceId)
                 else explore.requestStopAll()
                 // Let the worker finish cleanly via cooperative cancel flags
                 return START_NOT_STICKY
             }
             ACTION_PAUSE -> {
-                Log.i(TAG, "pause requested sourceId=$sourceId")
+                log.i { "pause requested sourceId=$sourceId" }
                 if (sourceId != null) explore.requestPauseSource(sourceId)
                 else explore.requestPauseAll()
                 return START_NOT_STICKY
@@ -58,9 +60,17 @@ class LibraryScanService : Service() {
         }
 
         // Already scanning — do not cancel unless this is an explicit full force-rescan.
+        // A newly added source always queues so its first index still runs.
         if (action == ACTION_REMOTE && work?.isActive == true) {
-            if (!force || sourceId != null) {
-                Log.i(TAG, "remote scan already active — ignore duplicate start")
+            if (sourceId != null) {
+                queuedForce = true
+                queuedSourceId = sourceId
+                log.i { "queue initial index sourceId=$sourceId" }
+                startAsForeground("Syncing libraries", explore.scanProgress.value ?: "Working…")
+                return START_NOT_STICKY
+            }
+            if (!force) {
+                log.i { "remote scan already active — ignore duplicate start" }
                 startAsForeground("Syncing libraries", explore.scanProgress.value ?: "Working…")
                 return START_NOT_STICKY
             }
@@ -95,11 +105,20 @@ class LibraryScanService : Service() {
                     }
                 }
             } catch (e: Exception) {
-                Log.e(TAG, "scan service failed", e)
+                log.e(e) { "scan service failed" }
                 notifier.finish("Scan failed", e.message ?: "Unknown error")
             } finally {
-                stopForegroundCompat()
-                stopSelf(startId)
+                val nextId = queuedSourceId
+                val nextForce = queuedForce
+                queuedSourceId = null
+                queuedForce = false
+                if (nextId != null) {
+                    log.i { "start queued index sourceId=$nextId" }
+                    startRemote(applicationContext, nextForce, nextId)
+                } else {
+                    stopForegroundCompat()
+                    stopSelf(startId)
+                }
             }
         }
         return START_NOT_STICKY
@@ -136,7 +155,7 @@ class LibraryScanService : Service() {
     }
 
     companion object {
-        private const val TAG = "LibraryScanService"
+        private val log = yuriLog("LibraryScanService")
         const val ACTION_REMOTE = "capital.yuri.yuriplayer.action.SCAN_REMOTE"
         const val ACTION_LOCAL = "capital.yuri.yuriplayer.action.SCAN_LOCAL"
         const val ACTION_STOP = "capital.yuri.yuriplayer.action.SCAN_STOP"
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySettings.kt b/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySettings.kt
index 11bff554..b14821d9 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySettings.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySettings.kt
@@ -2,6 +2,8 @@ package capital.yuri.yuriplayer.data
 
 import android.content.Context
 import android.os.Environment
+import capital.yuri.yuriplayer.components.theme.AccentCatalog
+import capital.yuri.yuriplayer.components.theme.ThemeMode
 import capital.yuri.yuriplayer.data.theme.ArtColorSurface
 import capital.yuri.yuriplayer.data.theme.ArtColorVariant
 import capital.yuri.yuriplayer.player.engine.PlaybackEngineId
@@ -39,6 +41,14 @@ class LibrarySettings(context: Context) {
     /** Ticks when cover/banner color variants change so themed pages re-resolve once. */
     val colorPrefsRevision: StateFlow<Long> = _colorPrefsRevision.asStateFlow()
 
+    fun useSystemColors(): Boolean = prefs.getBoolean(KEY_SYSTEM_COLORS, true)
+
+    fun setUseSystemColors(enabled: Boolean) {
+        if (enabled == useSystemColors()) return
+        prefs.edit().putBoolean(KEY_SYSTEM_COLORS, enabled).apply()
+        bumpColorPrefs()
+    }
+
     // ── local scan mode ───────────────────────────────────────────────────
 
     fun getScanMode(): LibraryScanMode {
@@ -241,6 +251,49 @@ class LibrarySettings(context: Context) {
             ArtColorSurface.BANNER -> getBannerColorVariant()
         }
 
+    fun getThemeMode(): ThemeMode = ThemeMode.fromId(prefs.getString(KEY_THEME_MODE, ThemeMode.DARK.id))
+
+    fun setThemeMode(mode: ThemeMode) {
+        if (mode == getThemeMode()) return
+        prefs.edit().putString(KEY_THEME_MODE, mode.id).apply()
+        bumpColorPrefs()
+    }
+
+    fun getAccentId(): String = prefs.getString(KEY_ACCENT, AccentCatalog.yuri.id) ?: AccentCatalog.yuri.id
+
+    fun setAccentId(id: String) {
+        val next = AccentCatalog.byId(id).id
+        if (next == getAccentId()) return
+        prefs.edit().putString(KEY_ACCENT, next).apply()
+        bumpColorPrefs()
+    }
+
+    fun enabledHomeRows(): Set<HomeRowId> {
+        val raw = prefs.getString(KEY_HOME_ROWS, null)
+        if (raw.isNullOrBlank()) return HomeRowId.entries.toSet()
+        val ids = raw.split(',').map { it.trim() }.toSet()
+        val parsed = HomeRowId.entries.filter { it.id in ids }.toSet()
+        return parsed.ifEmpty { HomeRowId.entries.toSet() }
+    }
+
+    fun setHomeRowEnabled(id: HomeRowId, enabled: Boolean) {
+        val next = enabledHomeRows().toMutableSet()
+        if (enabled) next.add(id) else next.remove(id)
+        prefs.edit().putString(KEY_HOME_ROWS, next.joinToString(",") { it.id }).apply()
+        bumpColorPrefs()
+    }
+
+    /**
+     * Explore library filter keys. Empty means every library.
+     * `local` = on this device; `i:{id}` = a [SourceInstanceEntity] id.
+     */
+    fun getExploreLibraryKeys(): Set<String> =
+        prefs.getStringSet(KEY_EXPLORE_LIBS, emptySet())?.toSet().orEmpty()
+
+    fun setExploreLibraryKeys(keys: Set<String>) {
+        prefs.edit().putStringSet(KEY_EXPLORE_LIBS, keys).apply()
+    }
+
     private fun bumpColorPrefs() {
         _colorPrefsRevision.value = System.currentTimeMillis()
     }
@@ -284,6 +337,11 @@ class LibrarySettings(context: Context) {
         private const val KEY_STREAM_QUALITY = "stream_quality"
         private const val KEY_COVER_COLOR_VARIANT = "cover_color_variant"
         private const val KEY_BANNER_COLOR_VARIANT = "banner_color_variant"
+        private const val KEY_SYSTEM_COLORS = "system_colors"
+        private const val KEY_THEME_MODE = "theme_mode"
+        private const val KEY_ACCENT = "accent_id"
+        private const val KEY_HOME_ROWS = "home_rows"
+        private const val KEY_EXPLORE_LIBS = "explore_library_keys"
 
         val DEFAULT_ROOTS = listOf(
             "Music",
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySyncScheduler.kt b/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySyncScheduler.kt
index 33628ef3..7bc26d62 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySyncScheduler.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/LibrarySyncScheduler.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.source.RemotePlaylistService
 import capital.yuri.yuriplayer.data.source.SourceInstanceRepository
 import capital.yuri.yuriplayer.data.source.SourceType
@@ -33,11 +33,11 @@ class LibrarySyncScheduler(
             delay(BOOT_DELAY_MS)
             while (isActive) {
                 runCatching { tick() }
-                    .onFailure { Log.w(TAG, "tick failed: ${it.message}") }
+                    .onFailure { log.w { "tick failed: ${it.message}" } }
                 delay(POLL_MS)
             }
         }
-        Log.i(TAG, "started")
+        log.i { "started" }
     }
 
     private suspend fun tick() = withContext(Dispatchers.IO) {
@@ -55,7 +55,7 @@ class LibrarySyncScheduler(
         if (last > 0L && now - last < interval.millis) return
         val n = playlists.syncOwnedToMyStuff()
         settings.markProfileSynced(now)
-        Log.i(TAG, "profile sync imported=$n interval=${interval.id}")
+        log.i { "profile sync imported=$n interval=${interval.id}" }
     }
 
     private suspend fun maybePartial(now: Long) {
@@ -72,7 +72,7 @@ class LibrarySyncScheduler(
             if (last > 0L && now - last < interval.millis) continue
             val cp = checkpoints.get(row.id)
             if (cp?.status == SourceScanStatus.RUNNING) {
-                Log.i(TAG, "skip partial ${row.name} — scan already running")
+                log.i { "skip partial ${row.name} — scan already running" }
                 continue
             }
             val type = when (SourceType.from(row.type)) {
@@ -83,10 +83,10 @@ class LibrarySyncScheduler(
             val indexed = catalog.countTracksForSource(type, row.id)
             val scanned = checkpoints.get(row.id)?.status == SourceScanStatus.DONE
             if (indexed <= 0 && !scanned) {
-                Log.i(TAG, "skip partial ${row.name} — no index yet")
+                log.i { "skip partial ${row.name} — no index yet" }
                 continue
             }
-            Log.i(TAG, "partial sync '${row.name}' interval=${interval.id} indexed=$indexed")
+            log.i { "partial sync '${row.name}' interval=${interval.id} indexed=$indexed" }
             LibraryScanService.startRemote(
                 context.applicationContext,
                 force = false,
@@ -98,7 +98,7 @@ class LibrarySyncScheduler(
     }
 
     companion object {
-        private const val TAG = "LibrarySync"
+        private val log = yuriLog("LibrarySync")
         private const val BOOT_DELAY_MS = 20_000L
         private const val POLL_MS = 60_000L
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEditService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEditService.kt
index 6ec0de2b..270b335a 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEditService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEditService.kt
@@ -7,7 +7,7 @@ import android.net.Uri
 import android.os.Build
 import android.os.ParcelFileDescriptor
 import android.provider.MediaStore
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.source.SourceType
 import capital.yuri.yuriplayer.player.engine.isNetworkUri
 import capital.yuri.yuriplayer.player.engine.isVirtualLibraryPath
@@ -47,7 +47,7 @@ class MetadataEditService(
         runCatching {
             TagOptionSingleton.getInstance().isAndroid = true
         }.onFailure {
-            Log.w(TAG, "Could not set TagOptionSingleton.isAndroid", it)
+            log.w(it) { "Could not set TagOptionSingleton.isAndroid" }
         }
     }
 
@@ -123,7 +123,7 @@ class MetadataEditService(
             libraryIndex.reloadFromCatalog()
             Result(1, 0, "Saved")
         } catch (e: Exception) {
-            Log.e(TAG, "saveSong failed key=${song.songKey}", e)
+            log.e(e) { "saveSong failed key=${song.songKey}" }
             Result(0, 1, e.message ?: "Write failed — need storage permission?")
         }
     }
@@ -160,7 +160,7 @@ class MetadataEditService(
                     mbid = null
                 )
             }
-            Log.i(TAG, "app cover cached $appCoverPath")
+            log.i { "app cover cached $appCoverPath" }
         }
 
         val coverFile = edit.coverBytes?.let { bytes ->
@@ -175,7 +175,7 @@ class MetadataEditService(
                     scanned += out.absolutePath
                     out
                 } catch (e: Exception) {
-                    Log.d(TAG, "folder cover.jpg write skipped: ${e.message}")
+                    log.d { "folder cover.jpg write skipped: ${e.message}" }
                     null
                 }
             } else null
@@ -208,7 +208,7 @@ class MetadataEditService(
                 )
                 ok++
             } catch (e: Exception) {
-                Log.e(TAG, "saveAlbum track failed key=${song.songKey}", e)
+                log.e(e) { "saveAlbum track failed key=${song.songKey}" }
                 failed++
             }
         }
@@ -247,7 +247,7 @@ class MetadataEditService(
             }
             if (dest.isFile && dest.length() > 0L) dest.absolutePath else null
         } catch (e: Exception) {
-            Log.w(TAG, "persistAppCover failed", e)
+            log.w(e) { "persistAppCover failed" }
             null
         }
     }
@@ -255,7 +255,7 @@ class MetadataEditService(
     private fun notWritableMessage(song: Song): String {
         val path = song.path.orEmpty()
         return when {
-            isVirtualLibraryPath(path) || isNetworkUri(song.contentUri) ->
+            isVirtualLibraryPath(path) || isNetworkUri(Uri.parse(song.contentUri)) ->
                 "This track is from a streaming server (e.g. Jellyfin). " +
                     "Edit metadata on a local or cloud file copy."
             else ->
@@ -267,28 +267,28 @@ class MetadataEditService(
     fun resolveWritableTarget(song: Song): WritableTarget? {
         val path = song.path
         if (isVirtualLibraryPath(path)) return null
-        if (isNetworkUri(song.contentUri)) return null
+        if (isNetworkUri(Uri.parse(song.contentUri))) return null
 
         if (!path.isNullOrBlank() && !path.contains("://")) {
             val f = File(path)
             if (f.isFile) return WritableTarget.FilePath(f)
         }
 
-        if (song.contentUri.scheme.equals("file", ignoreCase = true)) {
-            val p = song.contentUri.path
+        if (Uri.parse(song.contentUri).scheme.equals("file", ignoreCase = true)) {
+            val p = Uri.parse(song.contentUri).path
             if (!p.isNullOrBlank()) {
                 val f = File(p)
                 if (f.isFile) return WritableTarget.FilePath(f)
             }
         }
 
-        if (song.contentUri.scheme.equals("content", ignoreCase = true)) {
-            queryMediaStorePath(song.contentUri)?.let { dataPath ->
+        if (Uri.parse(song.contentUri).scheme.equals("content", ignoreCase = true)) {
+            queryMediaStorePath(Uri.parse(song.contentUri))?.let { dataPath ->
                 val f = File(dataPath)
                 if (f.isFile) return WritableTarget.FilePath(f)
             }
-            if (canOpenContent(song.contentUri)) {
-                return WritableTarget.ContentUri(song.contentUri)
+            if (canOpenContent(Uri.parse(song.contentUri))) {
+                return WritableTarget.ContentUri(Uri.parse(song.contentUri))
             }
         }
 
@@ -313,7 +313,7 @@ class MetadataEditService(
                 c.getString(idx)?.takeIf { it.isNotBlank() && File(it).isFile }
             }
         } catch (e: Exception) {
-            Log.d(TAG, "DATA query failed for $uri: ${e.message}")
+            log.d { "DATA query failed for $uri: ${e.message}" }
             null
         }
 
@@ -358,7 +358,7 @@ class MetadataEditService(
                 return true
             }
         } catch (e: Exception) {
-            Log.d(TAG, "openOutputStream wt failed for $uri: ${e.message}")
+            log.d { "openOutputStream wt failed for $uri: ${e.message}" }
         }
         try {
             context.contentResolver.openFileDescriptor(uri, "rwt")?.use { pfd ->
@@ -368,7 +368,7 @@ class MetadataEditService(
                 return true
             }
         } catch (e: Exception) {
-            Log.d(TAG, "openFileDescriptor rwt failed for $uri: ${e.message}")
+            log.d { "openFileDescriptor rwt failed for $uri: ${e.message}" }
         }
         try {
             context.contentResolver.openFileDescriptor(uri, "rw")?.use { pfd ->
@@ -378,7 +378,7 @@ class MetadataEditService(
                 return true
             }
         } catch (e: Exception) {
-            Log.d(TAG, "openFileDescriptor rw failed for $uri: ${e.message}")
+            log.d { "openFileDescriptor rw failed for $uri: ${e.message}" }
         }
         return false
     }
@@ -433,10 +433,7 @@ class MetadataEditService(
                 tag.setField(art)
             } catch (t: Throwable) {
                 // FLAC embed often fails on Android; app cover cache still holds the image.
-                Log.d(
-                    TAG,
-                    "embedded art skipped for ${file.name}: ${t.javaClass.simpleName}: ${t.message}"
-                )
+                log.d { "embedded art skipped for ${file.name}: ${t.javaClass.simpleName}: ${t.message}" }
             }
         }
         audio.commit()
@@ -483,7 +480,7 @@ class MetadataEditService(
     }
 
     private fun updateMediaStoreSong(song: Song, edit: SongEdit) {
-        if (!isMediaStoreAudioUri(song.contentUri)) return
+        if (!isMediaStoreAudioUri(Uri.parse(song.contentUri))) return
         val values = ContentValues().apply {
             edit.title?.let { put(MediaStore.Audio.Media.TITLE, it) }
             edit.artist?.let { put(MediaStore.Audio.Media.ARTIST, it) }
@@ -493,14 +490,14 @@ class MetadataEditService(
         }
         if (values.size() == 0) return
         runCatching {
-            context.contentResolver.update(song.contentUri, values, null, null)
+            context.contentResolver.update(Uri.parse(song.contentUri), values, null, null)
         }.onFailure {
-            Log.d(TAG, "MediaStore song update skipped: ${it.message}")
+            log.d { "MediaStore song update skipped: ${it.message}" }
         }
     }
 
     private fun updateMediaStoreAlbumFields(song: Song, edit: AlbumEdit) {
-        if (!isMediaStoreAudioUri(song.contentUri)) return
+        if (!isMediaStoreAudioUri(Uri.parse(song.contentUri))) return
         val values = ContentValues().apply {
             edit.albumName?.let { put(MediaStore.Audio.Media.ALBUM, it) }
             edit.year?.let { put(MediaStore.Audio.Media.YEAR, it) }
@@ -510,9 +507,9 @@ class MetadataEditService(
         }
         if (values.size() == 0) return
         runCatching {
-            context.contentResolver.update(song.contentUri, values, null, null)
+            context.contentResolver.update(Uri.parse(song.contentUri), values, null, null)
         }.onFailure {
-            Log.d(TAG, "MediaStore album update skipped: ${it.message}")
+            log.d { "MediaStore album update skipped: ${it.message}" }
         }
     }
 
@@ -533,13 +530,13 @@ class MetadataEditService(
                 ?: return@withContext null
             bytes to mime
         } catch (e: Exception) {
-            Log.e(TAG, "readImageBytes failed", e)
+            log.e(e) { "readImageBytes failed" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "MetadataEdit"
+        private val log = yuriLog("MetadataEdit")
         private const val FRONT_COVER_PICTURE_TYPE = 3
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEnrichmentService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEnrichmentService.kt
index 19705613..9bd4900f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEnrichmentService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/MetadataEnrichmentService.kt
@@ -2,7 +2,7 @@ package capital.yuri.yuriplayer.data
 
 import android.content.Context
 import android.media.MediaMetadataRetriever
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.db.AlbumMetadataDao
 import capital.yuri.yuriplayer.data.db.AlbumMetadataEntity
 import capital.yuri.yuriplayer.data.source.MusicBrainzClient
@@ -51,15 +51,16 @@ class MetadataEnrichmentService(
     suspend fun applyCachedToLibrary() = withContext(Dispatchers.IO) {
         val all = dao.getAll()
         for (row in all) {
-            if (row.year != null) {
-                library.applyAlbumYear(row.albumKey, row.year)
+            val y = row.year
+            if (y != null) {
+                library.applyAlbumYear(row.albumKey, y)
             }
         }
     }
 
     fun enrichLibraryAsync(maxAlbums: Int = 80) {
         if (!settings.isAutomaticMetadataEnabled()) {
-            Log.i(TAG, "skip auto enrich — automatic metadata disabled")
+            log.i { "skip auto enrich — automatic metadata disabled" }
             return
         }
         scope.launch {
@@ -71,11 +72,11 @@ class MetadataEnrichmentService(
                     val albums = library.albums(taggedOnly = false)
                         .filter { needsWorkCheap(it) }
                         .take(maxAlbums)
-                    Log.i(TAG, "auto enrich queue size=${albums.size}")
+                    log.i { "auto enrich queue size=${albums.size}" }
                     var done = 0
                     for (album in albums) {
                         if (!settings.isAutomaticMetadataEnabled()) {
-                            Log.i(TAG, "auto enrich cancelled mid-run")
+                            log.i { "auto enrich cancelled mid-run" }
                             break
                         }
                         enrichAlbum(album, force = false, probeEmbeddedArt = false)
@@ -86,7 +87,7 @@ class MetadataEnrichmentService(
                     }
                     _statusMessage.value = if (done > 0) "Updated $done albums" else null
                 } catch (e: Exception) {
-                    Log.e(TAG, "enrichLibrary failed", e)
+                    log.e(e) { "enrichLibrary failed" }
                     _statusMessage.value = "Couldn't look up artwork"
                 } finally {
                     _busy.value = false
@@ -103,7 +104,7 @@ class MetadataEnrichmentService(
                 enrichAlbum(album, force = force, probeEmbeddedArt = true)
                 _statusMessage.value = "Updated ${album.displayName}"
             } catch (e: Exception) {
-                Log.w(TAG, "enrichAlbum failed ${album.displayName}", e)
+                log.w(e) { "enrichAlbum failed ${album.displayName}" }
                 _statusMessage.value = "Couldn't update ${album.displayName}"
             } finally {
                 _busy.value = false
@@ -123,7 +124,7 @@ class MetadataEnrichmentService(
                     }
                     _statusMessage.value = "Updated ${albums.size} albums"
                 } catch (e: Exception) {
-                    Log.e(TAG, "enrichAlbums failed", e)
+                    log.e(e) { "enrichAlbums failed" }
                     _statusMessage.value = "Couldn't look up artwork"
                 } finally {
                     _busy.value = false
@@ -176,7 +177,7 @@ class MetadataEnrichmentService(
                 return
             }
 
-            Log.i(TAG, "lookup \"${album.displayName}\" / \"${album.displayArtist}\" force=$force")
+            log.i { "lookup \"${album.displayName}\" / \"${album.displayArtist}\" force=$force" }
             var hit = client.searchRelease(
                 artist = album.artist,
                 album = album.name,
@@ -204,7 +205,7 @@ class MetadataEnrichmentService(
                         updatedAtMs = System.currentTimeMillis()
                     )
                 )
-                Log.w(TAG, "no MB hit for $key")
+                log.w { "no MB hit for $key" }
                 return
             }
 
@@ -229,9 +230,9 @@ class MetadataEnrichmentService(
             if (client.downloadFrontCover(hit.mbid, dest)) {
                 coverPath = dest.absolutePath
                 coverChanged = true
-                Log.i(TAG, "cover saved $coverPath for ${album.displayName}")
+                log.i { "cover saved $coverPath for ${album.displayName}" }
             } else {
-                Log.w(TAG, "cover download failed mbid=${hit.mbid}")
+                log.w { "cover download failed mbid=${hit.mbid}" }
             }
         }
 
@@ -291,8 +292,7 @@ class MetadataEnrichmentService(
     }
 
     companion object {
-        private const val TAG = "MetaEnrich"
-
+        private val log = yuriLog("MetaEnrich")
         fun sanitizeFileName(key: String): String =
             key.lowercase()
                 .replace(Regex("[^a-z0-9._-]+"), "_")
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/MusicRepository.kt b/app/src/main/java/capital/yuri/yuriplayer/data/MusicRepository.kt
index d412eebd..7f3f61dd 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/MusicRepository.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/MusicRepository.kt
@@ -6,7 +6,7 @@ import android.media.MediaMetadataRetriever
 import android.media.MediaScannerConnection
 import android.net.Uri
 import android.provider.MediaStore
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import android.webkit.MimeTypeMap
 import androidx.documentfile.provider.DocumentFile
 import kotlinx.coroutines.Dispatchers
@@ -25,7 +25,7 @@ class MusicRepository(
 ) {
 
     companion object {
-        private const val TAG = "YuriPlayer.Library"
+        private val log = yuriLog("Library")
         private val AUDIO_EXTENSIONS = setOf(
             "flac", "mp3", "ogg", "opus", "m4a", "mp4", "aac",
             "wav", "aiff", "aif", "wma", "alac"
@@ -56,7 +56,7 @@ class MusicRepository(
 
         val byKey = LinkedHashMap<String, Song>()
         queryMediaStore().forEach { song ->
-            val key = song.path?.lowercase() ?: song.contentUri.toString()
+            val key = song.path?.lowercase() ?: song.contentUri
             byKey[key] = song
         }
         scanFilesystem().forEach { song ->
@@ -64,7 +64,7 @@ class MusicRepository(
             if (!byKey.containsKey(key)) byKey[key] = song
         }
         val withYear = byKey.values.count { it.year != null }
-        Log.i(TAG, "mediastore scan: ${byKey.size} tracks ($withYear with year)")
+        log.i { "mediastore scan: ${byKey.size} tracks ($withYear with year)" }
         return byKey.values.toList()
     }
 
@@ -75,7 +75,7 @@ class MusicRepository(
     private fun scanManualTrees(): List<Song> {
         val trees = settings.getManualTreeUris()
         if (trees.isEmpty()) {
-            Log.w(TAG, "manual scan: no SAF trees configured")
+            log.w { "manual scan: no SAF trees configured" }
             return emptyList()
         }
         val byKey = LinkedHashMap<String, Song>()
@@ -83,10 +83,10 @@ class MusicRepository(
             val treeUri = runCatching { Uri.parse(uriString) }.getOrNull() ?: continue
             val root = DocumentFile.fromTreeUri(context, treeUri)
             if (root == null || !root.isDirectory) {
-                Log.w(TAG, "manual scan: invalid tree $uriString")
+                log.w { "manual scan: invalid tree $uriString" }
                 continue
             }
-            Log.i(TAG, "manual scan tree $uriString")
+            log.i { "manual scan tree $uriString" }
             walkDocumentTree(root, depth = 0, maxDepth = 12) { doc, parent ->
                 val name = doc.name ?: return@walkDocumentTree
                 if (!isAudioFileName(name)) return@walkDocumentTree
@@ -102,8 +102,8 @@ class MusicRepository(
                     albumArtist = tags.albumArtist,
                     album = tags.album,
                     durationMs = tags.durationMs,
-                    contentUri = uri,
-                    albumArtUri = coverUri,
+                    contentUri = uri.toString(),
+                    albumArtUri = coverUri?.toString(),
                     trackNumber = tags.trackNumber,
                     discNumber = tags.discNumber,
                     year = tags.year,
@@ -113,7 +113,7 @@ class MusicRepository(
                 )
             }
         }
-        Log.i(TAG, "manual scan complete: ${byKey.size} tracks")
+        log.i { "manual scan complete: ${byKey.size} tracks" }
         return byKey.values.toList()
     }
 
@@ -142,7 +142,7 @@ class MusicRepository(
         val children = try {
             dir.listFiles()
         } catch (e: Exception) {
-            Log.w(TAG, "listFiles failed for ${dir.uri}: ${e.message}")
+            log.w { "listFiles failed for ${dir.uri}: ${e.message}" }
             return
         }
         for (child in children) {
@@ -170,13 +170,13 @@ class MusicRepository(
                     .filter { it.isFile && isAudioPath(it.absolutePath) }
                     .forEach { paths += it.absolutePath }
             } catch (e: Exception) {
-                Log.w(TAG, "walk failed ${root.absolutePath}", e)
+                log.w(e) { "walk failed ${root.absolutePath}" }
             }
         }
         if (paths.isEmpty()) return
 
         val unique = paths.distinct()
-        Log.i(TAG, "media-scan ${unique.size} paths")
+        log.i { "media-scan ${unique.size} paths" }
         suspendCancellableCoroutine { cont ->
             val left = AtomicInteger(unique.size)
             fun done() {
@@ -188,11 +188,11 @@ class MusicRepository(
                     unique.toTypedArray(),
                     null
                 ) { path, uri ->
-                    Log.d(TAG, "scanned $path → $uri")
+                    log.d { "scanned $path → $uri" }
                     done()
                 }
             } catch (e: Exception) {
-                Log.w(TAG, "media-scan failed", e)
+                log.w(e) { "media-scan failed" }
                 if (cont.isActive) cont.resume(Unit)
             }
         }
@@ -320,8 +320,8 @@ class MusicRepository(
                     albumArtist = albumArtist,
                     album = album,
                     durationMs = duration,
-                    contentUri = contentUri,
-                    albumArtUri = albumArtUri,
+                    contentUri = contentUri.toString(),
+                    albumArtUri = albumArtUri?.toString(),
                     trackNumber = track,
                     discNumber = disc,
                     year = year,
@@ -340,13 +340,13 @@ class MusicRepository(
         val seen = HashSet<String>()
         roots.forEach { root ->
             if (!root.exists()) {
-                Log.w(TAG, "scan root missing: ${root.absolutePath}")
+                log.w { "scan root missing: ${root.absolutePath}" }
                 return@forEach
             }
-            Log.i(TAG, "fs-scan ${root.absolutePath}")
+            log.i { "fs-scan ${root.absolutePath}" }
             try {
                 root.walkTopDown().maxDepth(8).onFail { f, e ->
-                    Log.w(TAG, "walk fail $f: ${e.message}")
+                    log.w { "walk fail $f: ${e.message}" }
                 }
                     .filter { it.isFile && isAudioPath(it.absolutePath) }
                     .forEach { file ->
@@ -361,7 +361,7 @@ class MusicRepository(
                             albumArtist = tags.albumArtist,
                             album = tags.album,
                             durationMs = tags.durationMs,
-                            contentUri = Uri.fromFile(file),
+                            contentUri = Uri.fromFile(file).toString(),
                             trackNumber = tags.trackNumber,
                             discNumber = tags.discNumber,
                             year = tags.year,
@@ -371,9 +371,9 @@ class MusicRepository(
                         )
                     }
             } catch (e: SecurityException) {
-                Log.e(TAG, "fs-scan permission denied for ${root.absolutePath}", e)
+                log.e(e) { "fs-scan permission denied for ${root.absolutePath}" }
             } catch (e: Exception) {
-                Log.e(TAG, "fs-scan failed ${root.absolutePath}", e)
+                log.e(e) { "fs-scan failed ${root.absolutePath}" }
             }
         }
         return songs
@@ -549,7 +549,7 @@ class MusicRepository(
                 pathHint = path
             )
         } catch (e: Exception) {
-            Log.d(TAG, "jaudio tags failed for $path: ${e.message}")
+            log.d { "jaudio tags failed for $path: ${e.message}" }
             FileTags()
         }
     }
@@ -573,9 +573,9 @@ class MusicRepository(
             if (disc != null) tag.setField(FieldKey.DISC_NO, disc.toString())
             if (!title.isNullOrBlank()) tag.setField(FieldKey.TITLE, title)
             audio.commit()
-            Log.i(TAG, "wrote inferred tags track=$track disc=$disc title='$title' for ${file.name}")
+            log.i { "wrote inferred tags track=$track disc=$disc title='$title' for ${file.name}" }
         } catch (e: Exception) {
-            Log.d(TAG, "inferred tag write skipped for $path: ${e.message}")
+            log.d { "inferred tag write skipped for $path: ${e.message}" }
         }
     }
 
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/PlaylistRepository.kt b/app/src/main/java/capital/yuri/yuriplayer/data/PlaylistRepository.kt
index da357c94..56969d85 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/PlaylistRepository.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/PlaylistRepository.kt
@@ -10,6 +10,7 @@ import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.combine
 import kotlinx.coroutines.flow.flowOn
 import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.mapLatest
 import kotlinx.coroutines.withContext
 import java.util.UUID
 
@@ -42,8 +43,8 @@ data class PlaylistCoverSlot(
  * 4. else empty (placeholder in UI)
  */
 data class PlaylistCover(
-    val customUri: Uri? = null,
-    val artUris: List<Uri> = emptyList()
+    val customUri: String? = null,
+    val artUris: List<String> = emptyList()
 ) {
     val mode: CoverMode
         get() = when {
@@ -72,7 +73,24 @@ class PlaylistRepository(
             entities.map { e -> e.toPlaylist(countMap[e.id] ?: 0, emptyList()) }
         }.flowOn(Dispatchers.Default)
 
-    fun observePlaylistsResolved(): Flow<List<Playlist>> = observePlaylists()
+    fun observePlaylistsResolved(): Flow<List<Playlist>> =
+        combine(dao.observeAll(), dao.observeTrackCounts(), dao.observeAllTracks()) { entities, counts, allTracks ->
+            Triple(entities, counts, allTracks)
+        }.mapLatest { (entities, counts, allTracks) ->
+            val countMap = counts.associate { it.playlistId to it.trackCount }
+            val byPl = allTracks.groupBy { it.playlistId }
+            val seedKeys = byPl.values.flatMap { tracks ->
+                tracks.sortedBy { it.position }.take(4).map { it.songKey }
+            }.distinct()
+            val songs = catalog.getSongsByKeys(seedKeys).associateBy { it.songKey }
+            entities.map { e ->
+                val seed = byPl[e.id].orEmpty()
+                    .sortedBy { it.position }
+                    .take(4)
+                    .mapNotNull { songs[it.songKey] }
+                e.toPlaylist(countMap[e.id] ?: 0, seed)
+            }
+        }.flowOn(Dispatchers.IO)
 
     fun observePlaylist(id: String): Flow<Playlist?> =
         combine(dao.observe(id), dao.observeTracks(id)) { entity, tracks ->
@@ -417,9 +435,9 @@ class PlaylistRepository(
     companion object {
         fun coverFor(playlist: Playlist): PlaylistCover {
             playlist.customImageUri?.let {
-                return PlaylistCover(customUri = Uri.parse(it))
+                return PlaylistCover(customUri = it)
             }
-            val unique = LinkedHashMap<String, Uri>()
+            val unique = LinkedHashMap<String, String>()
             for (song in playlist.songs) {
                 val art = song.albumArtUri ?: continue
                 val key = albumKey(song.album, song.effectiveAlbumArtist)
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/Song.kt b/app/src/main/java/capital/yuri/yuriplayer/data/Song.kt
index 59809932..88508abd 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/Song.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/Song.kt
@@ -1,419 +1,4 @@
 package capital.yuri.yuriplayer.data
 
-import android.net.Uri
-import capital.yuri.yuriplayer.data.json.UriAsStringSerializer
-import capital.yuri.yuriplayer.data.text.StringSimilarity
-import kotlinx.serialization.Serializable
-import java.io.File
-import java.text.Normalizer
-
-/**
- * All tag fields are nullable — missing tags stay null rather than "Unknown …".
- * Use [displayTitle] / [displayArtist] / [displayAlbum] only for UI strings.
- */
-@Serializable
-data class Song(
-    val id: Long,
-    val title: String? = null,
-    val artist: String? = null,
-    val albumArtist: String? = null,
-    val album: String? = null,
-    val durationMs: Long? = null,
-    @Serializable(with = UriAsStringSerializer::class)
-    val contentUri: Uri,
-    @Serializable(with = UriAsStringSerializer::class)
-    val albumArtUri: Uri? = null,
-    val trackNumber: Int? = null,
-    /** Disc / media set number (1-based). Null = single-disc or unknown. */
-    val discNumber: Int? = null,
-    val year: Int? = null,
-    /** Genre tag (may be semicolon-separated). */
-    val genre: String? = null,
-    val path: String? = null,
-    val mimeType: String? = null,
-    /** Explicit content flag when known from tags / remote metadata. */
-    val explicit: Boolean = false,
-    /** MusicBrainz artist id when the source publishes one (Navidrome / OpenSubsonic). */
-    val musicBrainzArtistId: String? = null
-) {
-    val displayTitle: String
-        get() = title?.takeIf { it.isNotBlank() }
-            ?: path?.let { File(it).nameWithoutExtension }
-            ?: "Unknown"
-
-    val displayArtist: String
-        get() = artist?.takeIf { it.isMeaningfulTag() }
-            ?: albumArtist?.takeIf { it.isMeaningfulTag() }
-            ?: "Unknown Artist"
-
-    /** Album cards / explore — never includes feat. credits. */
-    val primaryArtist: String
-        get() = primaryArtistName(effectiveAlbumArtist)
-            ?: primaryArtistName(artist)
-            ?: displayArtist
-
-    val displayAlbum: String
-        get() = album?.takeIf { it.isMeaningfulTag() } ?: "Unknown Album"
-
-    val effectiveAlbumArtist: String?
-        get() = albumArtist?.takeIf { it.isMeaningfulTag() }
-            ?: artist?.takeIf { it.isMeaningfulTag() }
-
-    val displayAlbumArtist: String
-        get() = effectiveAlbumArtist ?: "Unknown Artist"
-
-    val genres: List<String>
-        get() = genre.orEmpty()
-            .split(';', '/', ',', '|')
-            .map { it.trim() }
-            .filter { it.isNotEmpty() }
-            .distinctBy { it.lowercase() }
-
-    val creditArtists: List<String>
-        get() = allCreditsForSong(this).map { it.name }
-
-    val isTagged: Boolean
-        get() = artist.isMeaningfulTag() ||
-            albumArtist.isMeaningfulTag() ||
-            album.isMeaningfulTag()
-
-    val hasAlbum: Boolean get() = album.isMeaningfulTag()
-    val hasArtist: Boolean get() = artist.isMeaningfulTag() || albumArtist.isMeaningfulTag()
-    val hasTitle: Boolean get() = title.isMeaningfulTag()
-
-    val isExplicit: Boolean
-        get() {
-            if (explicit) return true
-            val t = title.orEmpty()
-            val g = genre.orEmpty()
-            return t.contains("explicit", ignoreCase = true) ||
-                t.contains("[e]", ignoreCase = true) ||
-                Regex("\\(e\\)", RegexOption.IGNORE_CASE).containsMatchIn(t) ||
-                g.contains("explicit", ignoreCase = true)
-        }
-
-    val songKey: String
-        get() = path?.lowercase() ?: contentUri.toString()
-
-    fun isSameAs(other: Song?): Boolean {
-        if (other == null) return false
-        if (path != null && other.path != null) return path == other.path
-        return id == other.id && contentUri == other.contentUri
-    }
-}
-
-private fun String?.isMeaningfulTag(): Boolean {
-    if (this == null) return false
-    val t = trim()
-    if (t.isEmpty()) return false
-    if (t.equals("<unknown>", true)) return false
-    if (t.equals("Unknown", true)) return false
-    if (t.equals("Unknown Artist", true)) return false
-    if (t.equals("Unknown Album", true)) return false
-    return true
-}
-
-enum class SortMode {
-    TITLE,
-    ARTIST,
-    ALBUM,
-    TRACK
-}
-
-fun SortMode.label(): String = when (this) {
-    SortMode.TITLE -> "Title"
-    SortMode.ARTIST -> "Artist"
-    SortMode.ALBUM -> "Album"
-    SortMode.TRACK -> "Track #"
-}
-
-/**
- * Fold stylized / accented music tags so "Twenty Øne Piløts" and
- * "Twenty One Pilots" share the same catalog keys.
- */
-fun foldTagToken(value: String): String {
-    var t = value.trim().replace(Regex("\\s+"), " ").lowercase()
-    t = Normalizer.normalize(t, Normalizer.Form.NFKD)
-        .replace(Regex("\\p{M}+"), "")
-    // Multi-char replacements MUST be Strings (Char literals only hold one code unit).
-    t = t
-        .replace('ø', 'o')
-        .replace("æ", "ae")
-        .replace("œ", "oe")
-        .replace('ł', 'l')
-        .replace('đ', 'd')
-        .replace("ß", "ss")
-    // Jenna's vs Jenna's (U+2019) split Clancy track 7 into two rows.
-    t = t.replace(APOSTROPHE_LIKE, "")
-    return t
-}
-
-/** Title identity: "Oh, Ms. Believer" and "Oh Ms. Believer" are the same song. */
-fun foldTitleToken(value: String): String {
-    var t = foldTagToken(value)
-    t = t.replace(TITLE_DECORATIVE_PUNCT, " ")
-    return t.replace(Regex("\\s+"), " ").trim()
-}
-
-private val APOSTROPHE_LIKE = Regex(
-    "[\u0027\u0060\u00B4\u2018\u2019\u201A\u201B\u2032\u02BB\u02BC\uFF07]"
-)
-
-private val TITLE_DECORATIVE_PUNCT = Regex("[,.:;!?]")
-
-/** Banded Levenshtein; returns [max] + 1 when the titles are farther than [max]. */
-fun editDistanceAtMost(a: String, b: String, max: Int): Int {
-    if (a == b) return 0
-    if (kotlin.math.abs(a.length - b.length) > max) return max + 1
-    val m = b.length
-    var prev = IntArray(m + 1) { it }
-    var cur = IntArray(m + 1)
-    for (i in 1..a.length) {
-        cur[0] = i
-        var rowMin = i
-        val ca = a[i - 1]
-        for (j in 1..m) {
-            val cost = if (ca == b[j - 1]) 0 else 1
-            cur[j] = minOf(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
-            if (cur[j] < rowMin) rowMin = cur[j]
-        }
-        if (rowMin > max) return max + 1
-        val tmp = prev
-        prev = cur
-        cur = tmp
-    }
-    return prev[m]
-}
-
-fun albumKey(name: String?, artist: String?): String {
-    val a = artistKey(artist) ?: foldTagToken(primaryArtistName(artist) ?: artist ?: "")
-    val n = foldTagToken(name ?: "")
-    return "$a|$n"
-}
-
-/** Folded artist key before user / MBID aliases. */
-fun rawArtistKey(name: String?): String? {
-    val primary = primaryArtistName(name) ?: name ?: return null
-    val t = foldTagToken(primary)
-    return t.takeIf { it.isNotEmpty() }
-}
-
-fun artistKey(name: String?): String? {
-    val raw = rawArtistKey(name) ?: return null
-    return ArtistAliasResolver.resolve(raw)
-}
-
-/**
- * In-memory alias map (Nightcord → 25時、ナイトコードで。).
- * CatalogRepository loads Room rows into this at start / after merge.
- */
-object ArtistAliasResolver {
-    @Volatile
-    private var map: Map<String, String> = emptyMap()
-
-    @Volatile
-    private var reverse: Map<String, List<String>> = emptyMap()
-
-    fun replace(aliases: Map<String, String>) {
-        map = aliases
-        reverse = aliases.entries.groupBy({ it.value }, { it.key })
-    }
-
-    fun resolve(key: String): String {
-        if (map.isEmpty()) return key
-        var cur = key
-        val seen = HashSet<String>(4)
-        while (true) {
-            val next = map[cur] ?: return cur
-            if (next == cur || !seen.add(cur)) return next
-            cur = next
-        }
-    }
-
-    fun isAlias(key: String): Boolean = map.containsKey(key)
-
-    fun aliasKeysOf(canonicalKey: String): List<String> = reverse[canonicalKey].orEmpty()
-
-    /** Canonical key plus every alias that redirects here. */
-    fun identityKeys(key: String): List<String> {
-        val canonical = resolve(key)
-        val aliases = aliasKeysOf(canonical)
-        if (aliases.isEmpty()) return listOf(canonical)
-        return buildList(aliases.size + 1) {
-            add(canonical)
-            addAll(aliases)
-        }
-    }
-}
-
-/**
- * Cross-source track identity.
- *
- * Titles match with or without `(feat. …)` / `ft.` / `featuring …`.
- * Track artist may differ so long as album + album artist line up.
- */
-object TrackIdentity {
-    private val FEAT_IN_PARENS = Regex(
-        """(?i)[\(\[\{]\s*(feat\.?|ft\.?|featuring)\s+[^\)\]\}]+[\)\]\}]"""
-    )
-    private val FEAT_SUFFIX = Regex(
-        """(?i)\s+(feat\.?|ft\.?|featuring)\s+.+$"""
-    )
-    private val WS = Regex("\\s+")
-
-    fun normalizeTitle(title: String?): String {
-        if (title == null) return ""
-        var t = title.trim()
-        t = FEAT_IN_PARENS.replace(t, "")
-        t = FEAT_SUFFIX.replace(t, "")
-        return foldTitleToken(t)
-    }
-
-    fun normalizeToken(value: String?): String {
-        if (value == null) return ""
-        return foldTagToken(value)
-    }
-
-    fun of(song: Song): String {
-        val title = normalizeTitle(song.title)
-        val album = normalizeToken(song.album)
-        val albumArtist = foldTagToken(
-            primaryArtistName(song.effectiveAlbumArtist) ?: song.effectiveAlbumArtist ?: ""
-        )
-        return when {
-            title.isNotEmpty() && (album.isNotEmpty() || albumArtist.isNotEmpty()) ->
-                "$title|$albumArtist|$album"
-            title.isNotEmpty() ->
-                "$title|${normalizeToken(song.artist)}|$album"
-            else -> song.songKey
-        }
-    }
-
-    fun titlesMatch(a: String?, b: String?): Boolean {
-        val na = normalizeTitle(a)
-        val nb = normalizeTitle(b)
-        return na.isNotEmpty() && na == nb
-    }
-
-    fun titlesNearlyMatch(
-        a: String?,
-        b: String?,
-        maxDist: Int = 2,
-        minLen: Int = 10
-    ): Boolean {
-        if (titlesMatch(a, b)) return true
-        if (a.isNullOrBlank() || b.isNullOrBlank()) return false
-        if (StringSimilarity.likelySame(a, b, StringSimilarity.Kind.TITLE)) return true
-        val na = normalizeTitle(a)
-        val nb = normalizeTitle(b)
-        if (na.length < minLen || nb.length < minLen) return false
-        if (kotlin.math.abs(na.length - nb.length) > maxDist) return false
-        return editDistanceAtMost(na, nb, maxDist) <= maxDist
-    }
-
-    fun albumsMatch(a: String?, b: String?): Boolean {
-        val na = normalizeToken(a)
-        val nb = normalizeToken(b)
-        return na.isNotEmpty() && na == nb
-    }
-
-    /**
-     * Same release with a one-letter server typo
-     * ("…Fray" vs "…Frat"). Short titles stay exact so Trench/Breach don't merge.
-     */
-    fun albumsNearlyMatch(a: String?, b: String?): Boolean {
-        if (albumsMatch(a, b)) return true
-        if (a.isNullOrBlank() || b.isNullOrBlank()) return false
-        return StringSimilarity.likelySame(a, b, StringSimilarity.Kind.ALBUM)
-    }
-
-    fun albumArtistsMatch(a: String?, b: String?): Boolean {
-        val pa = foldTagToken(primaryArtistName(a) ?: a ?: "")
-        val pb = foldTagToken(primaryArtistName(b) ?: b ?: "")
-        if (pa.isNotEmpty() && pb.isNotEmpty()) return pa == pb
-        return normalizeToken(a) == normalizeToken(b)
-    }
-
-    fun matches(a: Song, b: Song): Boolean {
-        if (!titlesMatch(a.title, b.title)) return false
-        val albumA = normalizeToken(a.album)
-        val albumB = normalizeToken(b.album)
-        if (albumA.isNotEmpty() && albumB.isNotEmpty() && albumA != albumB) return false
-        if (!albumArtistsMatch(a.effectiveAlbumArtist, b.effectiveAlbumArtist)) {
-            val aaA = foldTagToken(primaryArtistName(a.effectiveAlbumArtist) ?: "")
-            val aaB = foldTagToken(primaryArtistName(b.effectiveAlbumArtist) ?: "")
-            if (aaA.isNotEmpty() && aaB.isNotEmpty()) return false
-        }
-        if (albumA.isEmpty() && albumB.isEmpty()) {
-            val ta = foldTagToken(primaryArtistName(a.artist) ?: a.artist ?: "")
-            val tb = foldTagToken(primaryArtistName(b.artist) ?: b.artist ?: "")
-            if (ta.isNotEmpty() && tb.isNotEmpty() && ta != tb) return false
-        }
-        return true
-    }
-
-    fun titleDetailScore(title: String?): Int {
-        if (title.isNullOrBlank()) return -1
-        val t = title.trim()
-        var score = t.length
-        if (FEAT_IN_PARENS.containsMatchIn(t) || FEAT_SUFFIX.containsMatchIn(t)) {
-            score += 100
-        } else {
-            val lower = t.lowercase()
-            if (lower.contains("feat.") || lower.contains("ft.") || lower.contains("featuring")) {
-                score += 80
-            }
-        }
-        return score
-    }
-
-    fun artistDetailScore(artist: String?): Int {
-        if (artist.isNullOrBlank()) return -1
-        val a = artist.trim()
-        var score = a.length
-        val lower = a.lowercase()
-        if (lower.contains("feat") || lower.contains("ft.")) score += 40
-        if (a.contains(',') || a.contains('&') || a.contains(';')) score += 20
-        return score
-    }
-
-    fun withRichestDisplay(playback: Song, candidates: List<Song>): Song {
-        if (candidates.isEmpty()) return playback
-        val all = candidates + playback
-        val bestTitle = all.mapNotNull { it.title?.takeIf { t -> t.isNotBlank() } }
-            .maxByOrNull { titleDetailScore(it) }
-        val bestArtist = all.mapNotNull { it.artist?.takeIf { t -> t.isNotBlank() } }
-            .maxByOrNull { artistDetailScore(it) }
-        val bestAlbumArtist = all.mapNotNull { it.albumArtist?.takeIf { t -> t.isNotBlank() } }
-            .maxByOrNull { artistDetailScore(it) }
-        val bestAlbum = all.mapNotNull { it.album?.takeIf { t -> t.isNotBlank() } }
-            .maxByOrNull { it.length }
-        val anyExplicit = all.any { it.explicit || it.isExplicit }
-
-        return playback.copy(
-            title = when {
-                bestTitle != null && titleDetailScore(bestTitle) > titleDetailScore(playback.title) ->
-                    bestTitle
-                else -> playback.title
-            },
-            artist = when {
-                bestArtist != null && artistDetailScore(bestArtist) > artistDetailScore(playback.artist) ->
-                    bestArtist
-                else -> playback.artist
-            },
-            albumArtist = when {
-                bestAlbumArtist != null &&
-                    artistDetailScore(bestAlbumArtist) > artistDetailScore(playback.albumArtist) ->
-                    bestAlbumArtist
-                else -> playback.albumArtist
-            },
-            album = when {
-                bestAlbum != null &&
-                    (playback.album.isNullOrBlank() || bestAlbum.length > playback.album.length) ->
-                    bestAlbum
-                else -> playback.album
-            },
-            explicit = playback.explicit || anyExplicit
-        )
-    }
-}
+// Moved to :core (commonMain), same package: capital.yuri.yuriplayer.data.Song
+// (plus albumKey/artistKey/foldTagToken/TrackIdentity/ArtistAliasResolver/SortMode).
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogDao.kt b/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogDao.kt
index 58d3b2f5..f8b6020f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogDao.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogDao.kt
@@ -1,454 +1,3 @@
 package capital.yuri.yuriplayer.data.db
 
-import androidx.room.Dao
-import androidx.room.Insert
-import androidx.room.OnConflictStrategy
-import androidx.room.Query
-import androidx.room.Transaction
-import kotlinx.coroutines.flow.Flow
-
-/** Light album rollup row produced entirely in SQLite (no full-track load). */
-data class AlbumAggregateRow(
-    val albumKey: String,
-    val name: String?,
-    val artist: String?,
-    val year: Int?,
-    val trackCount: Int,
-    val coverUrl: String?,
-    val primarySourceType: String
-)
-
-/** Light artist rollup row produced entirely in SQLite. */
-data class ArtistAggregateRow(
-    val artistKey: String,
-    val displayName: String,
-    val trackCount: Int,
-    val albumCount: Int
-)
-
-/**
- * Persistent catalog = local library + remote-indexed tracks (Jellyfin / Subsonic).
- * Search and key lookups must stay SQL — never load the full table onto Main.
- */
-@Dao
-interface CatalogDao {
-
-    @Query("SELECT * FROM catalog_tracks ORDER BY title COLLATE NOCASE")
-    fun observeTracks(): Flow<List<CatalogTrackEntity>>
-
-    @Query("SELECT * FROM catalog_tracks ORDER BY title COLLATE NOCASE")
-    suspend fun getAllTracks(): List<CatalogTrackEntity>
-
-    @Query("SELECT * FROM catalog_tracks WHERE sourceType = :sourceType")
-    suspend fun getTracksBySource(sourceType: String): List<CatalogTrackEntity>
-
-    @Query(
-        "SELECT * FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "ORDER BY album COLLATE NOCASE, discNumber, trackNumber, title COLLATE NOCASE"
-    )
-    suspend fun getTracksForSourceInstance(
-        sourceType: String,
-        sourceInstanceId: Long?
-    ): List<CatalogTrackEntity>
-
-    @Query("SELECT * FROM catalog_tracks WHERE sourceType = :sourceType LIMIT :limit")
-    suspend fun getTracksBySourceLimited(sourceType: String, limit: Int): List<CatalogTrackEntity>
-
-    @Query(
-        "SELECT COUNT(*) FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL))"
-    )
-    suspend fun countTracksForSource(sourceType: String, sourceInstanceId: Long?): Int
-
-    @Query(
-        "SELECT externalId FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND externalId IS NOT NULL"
-    )
-    suspend fun externalIdsForSource(sourceType: String, sourceInstanceId: Long?): List<String>
-
-    @Query(
-        "SELECT * FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND externalId IN (:ids)"
-    )
-    suspend fun tracksByExternalIds(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        ids: List<String>
-    ): List<CatalogTrackEntity>
-
-    @Query(
-        "SELECT songKey FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND externalId IN (:ids)"
-    )
-    suspend fun songKeysForExternalIds(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        ids: List<String>
-    ): List<String>
-
-    @Query(
-        "UPDATE catalog_tracks SET lastSeenAtMs = :seenAt WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND externalId IN (:ids)"
-    )
-    suspend fun touchLastSeenByExternalIds(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        ids: List<String>,
-        seenAt: Long
-    ): Int
-
-    @Query("DELETE FROM catalog_tracks WHERE songKey IN (:keys)")
-    suspend fun deleteTracksByKeys(keys: List<String>): Int
-
-    @Query("DELETE FROM catalog_credits WHERE subjectType = 'TRACK' AND subjectKey IN (:keys)")
-    suspend fun deleteCreditsForTracks(keys: List<String>)
-
-    @Query("SELECT COUNT(*) FROM catalog_tracks WHERE sourceType != :localType")
-    suspend fun countNonLocalTracks(localType: String = CatalogSources.LOCAL): Int
-
-    @Query("SELECT * FROM catalog_tracks WHERE songKey = :songKey LIMIT 1")
-    suspend fun getTrack(songKey: String): CatalogTrackEntity?
-
-    @Query("SELECT * FROM catalog_tracks WHERE songKey IN (:keys)")
-    suspend fun getTracksByKeys(keys: List<String>): List<CatalogTrackEntity>
-
-    @Query(
-        """
-        SELECT * FROM catalog_tracks
-        WHERE IFNULL(title, '') = :title COLLATE NOCASE
-          AND IFNULL(COALESCE(albumArtist, artist), '') = :artist COLLATE NOCASE
-          AND IFNULL(album, '') = :album COLLATE NOCASE
-        LIMIT :limit
-        """
-    )
-    suspend fun findTracksMatching(
-        title: String,
-        artist: String,
-        album: String,
-        limit: Int = 12
-    ): List<CatalogTrackEntity>
-
-    @Query(
-        "SELECT * FROM catalog_tracks WHERE " +
-            "title LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR artist LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR albumArtist LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR album LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "LIMIT :limit"
-    )
-    suspend fun searchTracks(q: String, limit: Int): List<CatalogTrackEntity>
-
-    @Query(
-        "SELECT * FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND (title LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR artist LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR albumArtist LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR album LIKE '%' || :q || '%' COLLATE NOCASE) " +
-            "LIMIT :limit"
-    )
-    suspend fun searchTracksForSource(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        q: String,
-        limit: Int
-    ): List<CatalogTrackEntity>
-
-    @Query("SELECT * FROM catalog_tracks WHERE albumKey = :albumKey ORDER BY discNumber, trackNumber, title")
-    suspend fun getTracksForAlbum(albumKey: String): List<CatalogTrackEntity>
-
-    /** Exact album tag match, any source / albumKey. */
-    @Query(
-        "SELECT * FROM catalog_tracks WHERE album = :album COLLATE NOCASE " +
-            "ORDER BY discNumber, trackNumber, title LIMIT :limit"
-    )
-    suspend fun getTracksByAlbumName(album: String, limit: Int = 500): List<CatalogTrackEntity>
-
-    /**
-     * Album page primary query: album tag equals [album] AND artist loosely matches.
-     * Empty [artist] means any artist (caller filters further if needed).
-     */
-    @Query(
-        """
-        SELECT * FROM catalog_tracks
-        WHERE album = :album COLLATE NOCASE
-          AND (
-            :artist = ''
-            OR IFNULL(albumArtist, '') = :artist COLLATE NOCASE
-            OR IFNULL(artist, '') = :artist COLLATE NOCASE
-            OR IFNULL(albumArtist, '') LIKE '%' || :artist || '%' COLLATE NOCASE
-            OR IFNULL(artist, '') LIKE '%' || :artist || '%' COLLATE NOCASE
-          )
-        ORDER BY discNumber, trackNumber, title
-        LIMIT :limit
-        """
-    )
-    suspend fun getTracksForAlbumNameArtist(
-        album: String,
-        artist: String,
-        limit: Int = 1000
-    ): List<CatalogTrackEntity>
-
-    /** All albumKeys that share this album title (case-insensitive). */
-    @Query(
-        "SELECT DISTINCT albumKey FROM catalog_tracks " +
-            "WHERE album = :album COLLATE NOCASE AND albumKey IS NOT NULL AND albumKey != ''"
-    )
-    suspend fun albumKeysForAlbumName(album: String): List<String>
-
-    @Query(
-        "SELECT * FROM catalog_tracks WHERE albumKey = :albumKey " +
-            "ORDER BY CASE WHEN sourceType = 'LOCAL' THEN 0 ELSE 1 END, " +
-            "CASE WHEN albumArtUri IS NOT NULL AND albumArtUri != '' THEN 0 ELSE 1 END, " +
-            "discNumber, trackNumber LIMIT 1"
-    )
-    suspend fun getOneTrackForAlbum(albumKey: String): CatalogTrackEntity?
-
-    @Query(
-        """
-        SELECT * FROM catalog_tracks WHERE rowid IN (
-            SELECT MIN(rowid) FROM catalog_tracks
-            WHERE albumKey IN (:albumKeys)
-            GROUP BY albumKey
-        )
-        """
-    )
-    suspend fun oneTrackPerAlbum(albumKeys: List<String>): List<CatalogTrackEntity>
-
-    @Query("SELECT * FROM catalog_tracks WHERE artistKey IN (:keys) ORDER BY album, trackNumber, title")
-    suspend fun getTracksForArtists(keys: List<String>): List<CatalogTrackEntity>
-
-    @Query("SELECT * FROM catalog_tracks WHERE artistKey = :artistKey ORDER BY album, trackNumber, title")
-    suspend fun getTracksForArtist(artistKey: String): List<CatalogTrackEntity>
-
-    @Query(
-        """
-        SELECT t.* FROM catalog_tracks t
-        INNER JOIN catalog_credits c
-          ON c.subjectType = 'TRACK' AND c.subjectKey = t.songKey
-        WHERE c.artistKey IN (:keys) AND c.role = :role
-        ORDER BY t.album, t.trackNumber, t.title
-        """
-    )
-    suspend fun getTracksByCreditRoles(keys: List<String>, role: String): List<CatalogTrackEntity>
-
-    @Query(
-        """
-        SELECT t.* FROM catalog_tracks t
-        INNER JOIN catalog_credits c
-          ON c.subjectType = 'TRACK' AND c.subjectKey = t.songKey
-        WHERE c.artistKey = :artistKey AND c.role = :role
-        ORDER BY t.album, t.trackNumber, t.title
-        """
-    )
-    suspend fun getTracksByCreditRole(artistKey: String, role: String): List<CatalogTrackEntity>
-
-    @Query(
-        """
-        SELECT * FROM catalog_tracks
-        WHERE IFNULL(artist, '') LIKE '%' || :name || '%' COLLATE NOCASE
-           OR IFNULL(albumArtist, '') LIKE '%' || :name || '%' COLLATE NOCASE
-           OR IFNULL(title, '') LIKE '%' || :name || '%' COLLATE NOCASE
-           OR IFNULL(album, '') LIKE '%' || :name || '%' COLLATE NOCASE
-        LIMIT :limit
-        """
-    )
-    suspend fun getTracksMentioning(name: String, limit: Int = 8000): List<CatalogTrackEntity>
-
-    @Query("DELETE FROM catalog_credits")
-    suspend fun deleteAllCredits()
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertTracks(tracks: List<CatalogTrackEntity>)
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertTrack(track: CatalogTrackEntity): Long
-
-    @Query(
-        "DELETE FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND lastSeenAtMs < :beforeMs"
-    )
-    suspend fun pruneStaleTracks(sourceType: String, sourceInstanceId: Long?, beforeMs: Long): Int
-
-    @Query(
-        "DELETE FROM catalog_tracks WHERE sourceType = :sourceType " +
-            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
-            "AND lastSeenAtMs < :beforeMs " +
-            "AND songKey NOT IN (:keepKeys)"
-    )
-    suspend fun pruneStaleTracksExcept(
-        sourceType: String,
-        sourceInstanceId: Long?,
-        beforeMs: Long,
-        keepKeys: List<String>
-    ): Int
-
-    @Query("DELETE FROM catalog_tracks WHERE songKey = :songKey")
-    suspend fun deleteTrack(songKey: String)
-
-    @Query(
-        """
-        SELECT albumKey AS albumKey,
-               MAX(album) AS name,
-               MAX(COALESCE(albumArtist, artist)) AS artist,
-               MAX(year) AS year,
-               COUNT(DISTINCT lower(IFNULL(title, '')) || '|' ||
-                     IFNULL(CAST(trackNumber AS TEXT), '') || '|' ||
-                     IFNULL(CAST(discNumber AS TEXT), '1')) AS trackCount,
-               MAX(CASE WHEN albumArtUri LIKE 'http%' THEN albumArtUri ELSE NULL END) AS coverUrl,
-               MIN(sourceType) AS primarySourceType
-        FROM catalog_tracks
-        WHERE albumKey IS NOT NULL AND albumKey != ''
-        GROUP BY albumKey
-        """
-    )
-    suspend fun aggregateAlbums(): List<AlbumAggregateRow>
-
-    @Query(
-        """
-        SELECT artistKey AS artistKey,
-               MAX(COALESCE(albumArtist, artist, artistKey)) AS displayName,
-               COUNT(DISTINCT lower(IFNULL(title, '')) || '|' ||
-                     IFNULL(CAST(trackNumber AS TEXT), '') || '|' ||
-                     lower(IFNULL(album, ''))) AS trackCount,
-               COUNT(DISTINCT albumKey) AS albumCount
-        FROM catalog_tracks
-        WHERE artistKey IS NOT NULL AND artistKey != ''
-        GROUP BY artistKey
-        """
-    )
-    suspend fun aggregateArtists(): List<ArtistAggregateRow>
-
-    @Query("SELECT * FROM catalog_albums ORDER BY artist COLLATE NOCASE, name COLLATE NOCASE")
-    fun observeAlbums(): Flow<List<CatalogAlbumEntity>>
-
-    @Query("SELECT * FROM catalog_albums ORDER BY artist COLLATE NOCASE, name COLLATE NOCASE")
-    suspend fun getAllAlbums(): List<CatalogAlbumEntity>
-
-    @Query("SELECT * FROM catalog_albums WHERE albumKey = :albumKey LIMIT 1")
-    suspend fun getAlbum(albumKey: String): CatalogAlbumEntity?
-
-    @Query("SELECT * FROM catalog_albums WHERE artistKey IN (:keys) ORDER BY year DESC, name COLLATE NOCASE")
-    suspend fun getAlbumsForArtists(keys: List<String>): List<CatalogAlbumEntity>
-
-    @Query("SELECT * FROM catalog_albums WHERE artistKey = :artistKey ORDER BY year DESC, name COLLATE NOCASE")
-    suspend fun getAlbumsForArtist(artistKey: String): List<CatalogAlbumEntity>
-
-    @Query(
-        "SELECT * FROM catalog_albums WHERE " +
-            "name LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "OR artist LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "LIMIT :limit"
-    )
-    suspend fun searchAlbums(q: String, limit: Int): List<CatalogAlbumEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertAlbum(album: CatalogAlbumEntity)
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertAlbums(albums: List<CatalogAlbumEntity>)
-
-    @Query("DELETE FROM catalog_albums WHERE albumKey = :albumKey")
-    suspend fun deleteAlbum(albumKey: String)
-
-    @Query("SELECT * FROM catalog_artists ORDER BY displayName COLLATE NOCASE")
-    fun observeArtists(): Flow<List<CatalogArtistEntity>>
-
-    @Query("SELECT * FROM catalog_artists ORDER BY displayName COLLATE NOCASE")
-    suspend fun getAllArtists(): List<CatalogArtistEntity>
-
-    @Query("SELECT * FROM catalog_artists WHERE artistKey = :artistKey LIMIT 1")
-    suspend fun getArtist(artistKey: String): CatalogArtistEntity?
-
-    @Query(
-        "SELECT * FROM catalog_artists WHERE " +
-            "displayName LIKE '%' || :q || '%' COLLATE NOCASE " +
-            "LIMIT :limit"
-    )
-    suspend fun searchArtists(q: String, limit: Int): List<CatalogArtistEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertArtist(artist: CatalogArtistEntity)
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertArtists(artists: List<CatalogArtistEntity>)
-
-    @Query("DELETE FROM catalog_artists WHERE artistKey = :artistKey")
-    suspend fun deleteArtist(artistKey: String)
-
-    @Transaction
-    suspend fun replaceLocalCatalog(
-        tracks: List<CatalogTrackEntity>,
-        albums: List<CatalogAlbumEntity>,
-        artists: List<CatalogArtistEntity>,
-        seenAtMs: Long
-    ) {
-        upsertTracks(tracks)
-        upsertAlbums(albums)
-        upsertArtists(artists)
-        pruneStaleTracks(CatalogSources.LOCAL, null, seenAtMs)
-        deleteOrphanAlbums()
-        deleteOrphanArtists()
-    }
-
-    @Query(
-        "DELETE FROM catalog_albums WHERE albumKey NOT IN " +
-            "(SELECT DISTINCT albumKey FROM catalog_tracks WHERE albumKey IS NOT NULL)"
-    )
-    suspend fun deleteOrphanAlbums()
-
-    @Query(
-        "DELETE FROM catalog_artists WHERE artistKey NOT IN " +
-            "(SELECT DISTINCT artistKey FROM catalog_tracks WHERE artistKey IS NOT NULL " +
-            "UNION SELECT DISTINCT artistKey FROM catalog_credits WHERE artistKey IS NOT NULL)"
-    )
-    suspend fun deleteOrphanArtists()
-
-    @Query("DELETE FROM catalog_credits WHERE subjectType = :subjectType AND subjectKey = :subjectKey")
-    suspend fun deleteCredits(subjectType: String, subjectKey: String)
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertCredits(credits: List<CatalogCreditEntity>)
-
-    @Query("SELECT * FROM catalog_credits WHERE subjectType = :subjectType AND subjectKey = :subjectKey ORDER BY position")
-    suspend fun creditsFor(subjectType: String, subjectKey: String): List<CatalogCreditEntity>
-
-    @Query("SELECT * FROM artist_aliases")
-    suspend fun getAllAliases(): List<ArtistAliasEntity>
-
-    @Query("SELECT * FROM artist_aliases WHERE canonicalKey = :canonicalKey ORDER BY aliasName COLLATE NOCASE")
-    suspend fun aliasesForCanonical(canonicalKey: String): List<ArtistAliasEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertAlias(alias: ArtistAliasEntity)
-
-    @Query("DELETE FROM artist_aliases WHERE aliasKey = :aliasKey")
-    suspend fun deleteAlias(aliasKey: String)
-
-    @Query("DELETE FROM artist_aliases WHERE canonicalKey = :canonicalKey OR aliasKey = :canonicalKey")
-    suspend fun deleteAliasesInvolving(canonicalKey: String)
-
-    @Query("UPDATE artist_aliases SET canonicalKey = :intoKey WHERE canonicalKey = :fromKey")
-    suspend fun retargetAliases(fromKey: String, intoKey: String)
-
-    @Query("UPDATE catalog_tracks SET artistKey = :intoKey WHERE artistKey = :fromKey")
-    suspend fun retargetTrackArtistKey(fromKey: String, intoKey: String)
-
-    @Query("UPDATE catalog_credits SET artistKey = :intoKey WHERE artistKey = :fromKey")
-    suspend fun retargetCreditArtistKey(fromKey: String, intoKey: String)
-
-    @Query("UPDATE catalog_albums SET artistKey = :intoKey WHERE artistKey = :fromKey")
-    suspend fun retargetAlbumArtistKey(fromKey: String, intoKey: String)
-
-    @Query(
-        "SELECT * FROM catalog_artists WHERE mbid IS NOT NULL AND mbid != '' " +
-            "ORDER BY mbid, trackCount DESC"
-    )
-    suspend fun artistsWithMbid(): List<CatalogArtistEntity>
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogEntities.kt b/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogEntities.kt
index 78e8d20e..f8b6020f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogEntities.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/db/CatalogEntities.kt
@@ -1,173 +1,3 @@
 package capital.yuri.yuriplayer.data.db
 
-import androidx.room.Entity
-import androidx.room.Index
-import androidx.room.PrimaryKey
-
-/**
- * Built-in source type strings. Remote instances also live in [SourceInstanceEntity];
- * local files use [SOURCE_TYPE_LOCAL] with [sourceInstanceId] = null.
- */
-object CatalogSources {
-    const val LOCAL = "LOCAL"
-    const val JELLYFIN = "JELLYFIN"
-    const val SUBSONIC = "SUBSONIC"
-    /** Legacy alias — treat as [SUBSONIC] protocol. */
-    const val NAVIDROME = "NAVIDROME"
-    const val WEBDAV = "WEBDAV"
-    const val MUSICBRAINZ = "MUSICBRAINZ" // enrichment-only, not a playable source
-}
-
-/**
- * One playable track from one source.
- *
- * Explore unions rows across sources; playback picks a row (local preferred
- * unless a [SourceOverrideEntity] says otherwise). My Stuff / playlists
- * reference [songKey].
- */
-@Entity(
-    tableName = "catalog_tracks",
-    indices = [
-        Index(value = ["songKey"], unique = true),
-        Index(value = ["sourceType", "sourceInstanceId"]),
-        Index(value = ["sourceType", "sourceInstanceId", "externalId"]),
-        Index(value = ["albumKey"]),
-        Index(value = ["artistKey"]),
-        Index(value = ["title"]),
-        Index(value = ["lastSeenAtMs"])
-    ]
-)
-data class CatalogTrackEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    /** Stable identity: lowercase path, or content URI, or "source:externalId". */
-    val songKey: String,
-    /** LOCAL | JELLYFIN | SUBSONIC | … */
-    val sourceType: String,
-    /** FK-ish to source_instances.id; null for built-in local scanner. */
-    val sourceInstanceId: Long? = null,
-    /** Remote library id when source is not local. */
-    val externalId: String? = null,
-
-    val title: String? = null,
-    val artist: String? = null,
-    val albumArtist: String? = null,
-    val album: String? = null,
-    val year: Int? = null,
-    val trackNumber: Int? = null,
-    val discNumber: Int? = null,
-    val durationMs: Long? = null,
-
-    /** Normalized keys for joining albums / artists in Explore. */
-    val albumKey: String? = null,
-    val artistKey: String? = null,
-
-    val contentUri: String,
-    val path: String? = null,
-    val albumArtUri: String? = null,
-    val mimeType: String? = null,
-
-    val isTagged: Boolean = false,
-    val updatedAtMs: Long = System.currentTimeMillis(),
-    /** Bumped each successful sync; rows not seen can be pruned for that source. */
-    val lastSeenAtMs: Long = System.currentTimeMillis()
-)
-
-/**
- * Normalized album identity shared across sources.
- * Tracks point here via [CatalogTrackEntity.albumKey].
- * Year / cover may be filled by MusicBrainz enrichment or a remote library.
- */
-@Entity(
-    tableName = "catalog_albums",
-    indices = [
-        Index(value = ["albumKey"], unique = true),
-        Index(value = ["artistKey"]),
-        Index(value = ["year"])
-    ]
-)
-data class CatalogAlbumEntity(
-    @PrimaryKey val albumKey: String,
-    val name: String? = null,
-    val artist: String? = null,
-    val artistKey: String? = null,
-    val year: Int? = null,
-    val trackCount: Int = 0,
-    val releaseType: String? = null, // SINGLE | EP | ALBUM | …
-    val mbid: String? = null,
-    val coverPath: String? = null,
-    val coverUrl: String? = null,
-    /** Which source last contributed structural fields (name/artist/count). */
-    val primarySourceType: String = CatalogSources.LOCAL,
-    val updatedAtMs: Long = System.currentTimeMillis()
-)
-
-/**
- * Normalized artist identity (one Explore page per name).
- * Profile fields may come from local tags, MusicBrainz, Jellyfin, etc.
- */
-@Entity(
-    tableName = "catalog_artists",
-    indices = [Index(value = ["artistKey"], unique = true)]
-)
-data class CatalogArtistEntity(
-    @PrimaryKey val artistKey: String,
-    val displayName: String,
-    val trackCount: Int = 0,
-    val albumCount: Int = 0,
-    val bio: String? = null,
-    val imageUri: String? = null,
-    val websiteUrl: String? = null,
-    val linksJson: String? = null,
-    val mbid: String? = null,
-    val updatedAtMs: Long = System.currentTimeMillis()
-)
-
-/**
- * Redirects one folded artistKey to another. User merges (Nightcord → 25時)
- * and MusicBrainz-id collapses both write rows here.
- */
-@Entity(
-    tableName = "artist_aliases",
-    indices = [Index(value = ["canonicalKey"])]
-)
-data class ArtistAliasEntity(
-    @PrimaryKey val aliasKey: String,
-    val canonicalKey: String,
-    val aliasName: String,
-    val source: String = SOURCE_USER,
-    val createdAtMs: Long = System.currentTimeMillis()
-) {
-    companion object {
-        const val SOURCE_USER = "USER"
-        const val SOURCE_MBID = "MBID"
-    }
-}
-
-enum class CreditSubject {
-    TRACK,
-    ALBUM
-}
-
-/**
- * Primary vs featured credits for a track or album.
- * Album cards / explore show [ArtistRole.PRIMARY] only.
- */
-@Entity(
-    tableName = "catalog_credits",
-    indices = [
-        Index(value = ["subjectType", "subjectKey"]),
-        Index(value = ["artistKey"])
-    ]
-)
-data class CatalogCreditEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    /** TRACK | ALBUM */
-    val subjectType: String,
-    /** songKey or albumKey */
-    val subjectKey: String,
-    val artistKey: String,
-    val displayName: String,
-    /** PRIMARY | FEATURED */
-    val role: String,
-    val position: Int = 0
-)
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/db/Daos.kt b/app/src/main/java/capital/yuri/yuriplayer/data/db/Daos.kt
index 2c5b497b..f8b6020f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/db/Daos.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/db/Daos.kt
@@ -1,221 +1,3 @@
 package capital.yuri.yuriplayer.data.db
 
-import androidx.room.Dao
-import androidx.room.Insert
-import androidx.room.OnConflictStrategy
-import androidx.room.Query
-import androidx.room.Transaction
-import androidx.room.Update
-import kotlinx.coroutines.flow.Flow
-
-@Dao
-interface AlbumPrefsDao {
-    @Query("SELECT * FROM album_prefs WHERE albumKey = :key LIMIT 1")
-    suspend fun get(key: String): AlbumPrefsEntity?
-
-    @Query("SELECT * FROM album_prefs WHERE albumKey = :key LIMIT 1")
-    fun observe(key: String): Flow<AlbumPrefsEntity?>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: AlbumPrefsEntity): Long
-
-    @Query("SELECT * FROM album_prefs WHERE pinnedToMyStuff = 1")
-    fun observePinned(): Flow<List<AlbumPrefsEntity>>
-}
-
-@Dao
-interface AlbumMetadataDao {
-    @Query("SELECT * FROM album_metadata WHERE albumKey = :key LIMIT 1")
-    suspend fun get(key: String): AlbumMetadataEntity?
-
-    @Query("SELECT * FROM album_metadata WHERE albumKey = :key LIMIT 1")
-    fun observe(key: String): Flow<AlbumMetadataEntity?>
-
-    @Query("SELECT * FROM album_metadata")
-    suspend fun getAll(): List<AlbumMetadataEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: AlbumMetadataEntity): Long
-
-    @Query("DELETE FROM album_metadata WHERE albumKey = :key")
-    suspend fun delete(key: String)
-}
-
-@Dao
-interface PlaylistPrefsDao {
-    @Query("SELECT * FROM playlist_prefs WHERE playlistId = :id LIMIT 1")
-    suspend fun get(id: String): PlaylistPrefsEntity?
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: PlaylistPrefsEntity): Long
-}
-
-/** Row from GROUP BY count query. */
-data class PlaylistTrackCount(
-    val playlistId: String,
-    val trackCount: Int
-)
-
-@Dao
-interface PlaylistDao {
-    @Query("SELECT * FROM playlists ORDER BY updatedAtMs DESC")
-    fun observeAll(): Flow<List<PlaylistEntity>>
-
-    @Query("SELECT * FROM playlists WHERE id = :id LIMIT 1")
-    fun observe(id: String): Flow<PlaylistEntity?>
-
-    @Query("SELECT * FROM playlists WHERE id = :id LIMIT 1")
-    suspend fun get(id: String): PlaylistEntity?
-
-    @Query("SELECT * FROM playlists")
-    suspend fun getAll(): List<PlaylistEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: PlaylistEntity)
-
-    @Query("DELETE FROM playlists WHERE id = :id")
-    suspend fun delete(id: String)
-
-    @Query("SELECT * FROM playlist_tracks WHERE playlistId = :playlistId ORDER BY position ASC")
-    fun observeTracks(playlistId: String): Flow<List<PlaylistTrackEntity>>
-
-    @Query("SELECT * FROM playlist_tracks WHERE playlistId = :playlistId ORDER BY position ASC")
-    suspend fun getTracks(playlistId: String): List<PlaylistTrackEntity>
-
-    @Query("SELECT playlistId, COUNT(*) AS trackCount FROM playlist_tracks GROUP BY playlistId")
-    fun observeTrackCounts(): Flow<List<PlaylistTrackCount>>
-
-    @Query("SELECT * FROM playlist_tracks")
-    fun observeAllTracks(): Flow<List<PlaylistTrackEntity>>
-
-    @Query("SELECT playlistId FROM playlist_tracks WHERE songKey = :songKey")
-    suspend fun playlistIdsContaining(songKey: String): List<String>
-
-    @Query("DELETE FROM playlist_tracks WHERE playlistId = :playlistId")
-    suspend fun clearTracks(playlistId: String)
-
-    @Query("DELETE FROM playlist_tracks WHERE playlistId = :playlistId AND songKey = :songKey")
-    suspend fun deleteTrackByKey(playlistId: String, songKey: String)
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun insertTracks(tracks: List<PlaylistTrackEntity>)
-
-    @Query("DELETE FROM playlist_tracks WHERE playlistId = :playlistId AND position = :position")
-    suspend fun deleteTrackAt(playlistId: String, position: Int)
-
-    @Transaction
-    suspend fun replaceTracks(playlistId: String, songKeys: List<String>) {
-        clearTracks(playlistId)
-        if (songKeys.isEmpty()) return
-        insertTracks(
-            songKeys.mapIndexed { index, key ->
-                PlaylistTrackEntity(playlistId = playlistId, position = index, songKey = key)
-            }
-        )
-    }
-
-    // ── multi covers ──────────────────────────────────────────────────────
-
-    @Query("SELECT * FROM playlist_covers WHERE playlistId = :playlistId ORDER BY sortOrder ASC, createdAtMs ASC")
-    fun observeCovers(playlistId: String): Flow<List<PlaylistCoverEntity>>
-
-    @Query("SELECT * FROM playlist_covers WHERE playlistId = :playlistId ORDER BY sortOrder ASC, createdAtMs ASC")
-    suspend fun getCovers(playlistId: String): List<PlaylistCoverEntity>
-
-    @Query("SELECT * FROM playlist_covers WHERE id = :coverId LIMIT 1")
-    suspend fun getCover(coverId: String): PlaylistCoverEntity?
-
-    /** Covers currently marked active that are secret (session-only art). */
-    @Query(
-        """
-        SELECT c.* FROM playlist_covers c
-        INNER JOIN playlists p ON p.activeCoverId = c.id
-        WHERE c.isSecret = 1
-        """
-    )
-    suspend fun getActiveSecretCovers(): List<PlaylistCoverEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsertCover(entity: PlaylistCoverEntity)
-
-    @Query("DELETE FROM playlist_covers WHERE id = :coverId")
-    suspend fun deleteCover(coverId: String)
-
-    @Query("DELETE FROM playlist_covers WHERE playlistId = :playlistId")
-    suspend fun clearCovers(playlistId: String)
-
-    @Query("SELECT COALESCE(MAX(sortOrder), -1) FROM playlist_covers WHERE playlistId = :playlistId")
-    suspend fun maxCoverSortOrder(playlistId: String): Int
-}
-
-@Dao
-interface ArtistProfileDao {
-    @Query("SELECT * FROM artist_profiles WHERE artistKey = :key LIMIT 1")
-    suspend fun get(key: String): ArtistProfileEntity?
-
-    @Query("SELECT * FROM artist_profiles WHERE artistKey = :key LIMIT 1")
-    fun observe(key: String): Flow<ArtistProfileEntity?>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: ArtistProfileEntity)
-
-    @Query("DELETE FROM artist_profiles WHERE artistKey = :key")
-    suspend fun delete(key: String)
-}
-
-@Dao
-interface SourceOverrideDao {
-    @Query("SELECT * FROM source_overrides WHERE scope = :scope AND scopeKey = :scopeKey LIMIT 1")
-    suspend fun get(scope: String, scopeKey: String): SourceOverrideEntity?
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: SourceOverrideEntity): Long
-
-    @Query("DELETE FROM source_overrides WHERE scope = :scope AND scopeKey = :scopeKey")
-    suspend fun delete(scope: String, scopeKey: String)
-}
-
-@Dao
-interface AppSettingsDao {
-    @Query("SELECT * FROM app_settings WHERE `key` = :key LIMIT 1")
-    suspend fun get(key: String): AppSettingEntity?
-
-    @Query("SELECT * FROM app_settings")
-    fun observeAll(): Flow<List<AppSettingEntity>>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: AppSettingEntity)
-
-    @Query("DELETE FROM app_settings WHERE `key` = :key")
-    suspend fun delete(key: String)
-}
-
-@Dao
-interface SourceInstanceDao {
-    @Query("SELECT * FROM source_instances ORDER BY sortOrder, id")
-    fun observeAll(): Flow<List<SourceInstanceEntity>>
-
-    @Query("SELECT * FROM source_instances ORDER BY sortOrder, id")
-    suspend fun getAll(): List<SourceInstanceEntity>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: SourceInstanceEntity): Long
-
-    @Update
-    suspend fun update(entity: SourceInstanceEntity)
-
-    @Query("DELETE FROM source_instances WHERE id = :id")
-    suspend fun delete(id: Long)
-}
-
-@Dao
-interface ScrobblerInstanceDao {
-    @Query("SELECT * FROM scrobbler_instances ORDER BY id")
-    fun observeAll(): Flow<List<ScrobblerInstanceEntity>>
-
-    @Insert(onConflict = OnConflictStrategy.REPLACE)
-    suspend fun upsert(entity: ScrobblerInstanceEntity): Long
-
-    @Query("DELETE FROM scrobbler_instances WHERE id = :id")
-    suspend fun delete(id: Long)
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/db/Entities.kt b/app/src/main/java/capital/yuri/yuriplayer/data/db/Entities.kt
index 444d8b49..f8b6020f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/db/Entities.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/db/Entities.kt
@@ -1,156 +1,3 @@
 package capital.yuri.yuriplayer.data.db
 
-import androidx.room.Entity
-import androidx.room.Index
-import androidx.room.PrimaryKey
-
-@Entity(
-    tableName = "album_prefs",
-    indices = [Index(value = ["albumKey"], unique = true)]
-)
-data class AlbumPrefsEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    val albumKey: String,
-    val shuffleDefault: Boolean = false,
-    val repeatMode: String = "ALL",
-    val pinnedToMyStuff: Boolean = false,
-    val updatedAtMs: Long = System.currentTimeMillis()
-)
-
-@Entity(
-    tableName = "album_metadata",
-    indices = [Index(value = ["albumKey"], unique = true)]
-)
-data class AlbumMetadataEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    val albumKey: String,
-    val year: Int? = null,
-    val mbid: String? = null,
-    val coverPath: String? = null,
-    val coverUrl: String? = null,
-    /** JSON string array of genre names from remote enrichment. */
-    val genresJson: String? = null,
-    val source: String = "musicbrainz",
-    val updatedAtMs: Long = System.currentTimeMillis(),
-    val lookupFailed: Boolean = false
-)
-
-@Entity(
-    tableName = "playlist_prefs",
-    indices = [Index(value = ["playlistId"], unique = true)]
-)
-data class PlaylistPrefsEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    val playlistId: String,
-    val shuffleDefault: Boolean = false,
-    val repeatMode: String = "ALL",
-    val pinnedToMyStuff: Boolean = false,
-    val updatedAtMs: Long = System.currentTimeMillis()
-)
-
-@Entity(tableName = "playlists")
-data class PlaylistEntity(
-    @PrimaryKey val id: String,
-    val name: String,
-    val description: String? = null,
-    /**
-     * Legacy single custom image. Prefer [activeCoverId] + [PlaylistCoverEntity]
-     * when present; this remains the fast list-thumb path and migration fallback.
-     */
-    val customImageUri: String? = null,
-    /** Active [PlaylistCoverEntity.id] for public display. */
-    val activeCoverId: String? = null,
-    val createdAtMs: Long = System.currentTimeMillis(),
-    val updatedAtMs: Long = System.currentTimeMillis()
-)
-
-/**
- * One custom cover image for a playlist. Multiple rows per playlist are allowed.
- * [isSecret] covers are kept out of the default active slot unless the user
- * explicitly sets them active (handy for private / alternate art).
- */
-@Entity(
-    tableName = "playlist_covers",
-    indices = [
-        Index(value = ["playlistId"]),
-        Index(value = ["playlistId", "sortOrder"])
-    ]
-)
-data class PlaylistCoverEntity(
-    @PrimaryKey val id: String,
-    val playlistId: String,
-    val uri: String,
-    val isSecret: Boolean = false,
-    val sortOrder: Int = 0,
-    val createdAtMs: Long = System.currentTimeMillis()
-)
-
-@Entity(
-    tableName = "playlist_tracks",
-    primaryKeys = ["playlistId", "position"],
-    indices = [
-        Index(value = ["playlistId"]),
-        Index(value = ["songKey"])
-    ]
-)
-data class PlaylistTrackEntity(
-    val playlistId: String,
-    val position: Int,
-    val songKey: String
-)
-
-@Entity(tableName = "artist_profiles")
-data class ArtistProfileEntity(
-    @PrimaryKey val artistKey: String,
-    val displayName: String,
-    val bio: String? = null,
-    val imageUri: String? = null,
-    val websiteUrl: String? = null,
-    val linksJson: String? = null,
-    val genresJson: String? = null,
-    val source: String = "local",
-    val updatedAtMs: Long = System.currentTimeMillis()
-)
-
-@Entity(
-    tableName = "source_overrides",
-    indices = [Index(value = ["scope", "scopeKey"], unique = true)]
-)
-data class SourceOverrideEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    val scope: String,
-    val scopeKey: String,
-    val preferredSourceId: Long? = null,
-    val preferredSourceType: String? = null
-)
-
-@Entity(tableName = "app_settings")
-data class AppSettingEntity(
-    @PrimaryKey val key: String,
-    val value: String
-)
-
-@Entity(tableName = "source_instances")
-data class SourceInstanceEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    val type: String,
-    val name: String,
-    val baseUrl: String? = null,
-    val username: String? = null,
-    val secret: String? = null,
-    val enabled: Boolean = true,
-    val sortOrder: Int = 0,
-    val extraJson: String? = null
-)
-
-@Entity(tableName = "scrobbler_instances")
-data class ScrobblerInstanceEntity(
-    @PrimaryKey(autoGenerate = true) val id: Long = 0,
-    val type: String,
-    val name: String,
-    val baseUrl: String? = null,
-    val username: String? = null,
-    val token: String? = null,
-    val enabled: Boolean = false,
-    val extraJson: String? = null
-)
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriDatabase.kt b/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriDatabase.kt
index da2f7045..f8b6020f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriDatabase.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriDatabase.kt
@@ -1,54 +1,3 @@
 package capital.yuri.yuriplayer.data.db
 
-import android.content.Context
-import androidx.room.Database
-import androidx.room.Room
-import androidx.room.RoomDatabase
-
-@Database(
-    entities = [
-        AlbumPrefsEntity::class,
-        AlbumMetadataEntity::class,
-        CatalogTrackEntity::class,
-        CatalogAlbumEntity::class,
-        CatalogArtistEntity::class,
-        CatalogCreditEntity::class,
-        ArtistAliasEntity::class,
-        PlaylistPrefsEntity::class,
-        PlaylistEntity::class,
-        PlaylistCoverEntity::class,
-        PlaylistTrackEntity::class,
-        ArtistProfileEntity::class,
-        SourceOverrideEntity::class,
-        AppSettingEntity::class,
-        SourceInstanceEntity::class,
-        ScrobblerInstanceEntity::class
-    ],
-    version = 10,
-    exportSchema = false
-)
-abstract class YuriDatabase : RoomDatabase() {
-    abstract fun albumPrefs(): AlbumPrefsDao
-    abstract fun albumMetadata(): AlbumMetadataDao
-    abstract fun catalog(): CatalogDao
-    abstract fun playlistPrefs(): PlaylistPrefsDao
-    abstract fun playlists(): PlaylistDao
-    abstract fun artistProfiles(): ArtistProfileDao
-    abstract fun sourceOverrides(): SourceOverrideDao
-    abstract fun appSettings(): AppSettingsDao
-    abstract fun sources(): SourceInstanceDao
-    abstract fun scrobblers(): ScrobblerInstanceDao
-
-    companion object {
-        fun create(context: Context): YuriDatabase =
-            Room.databaseBuilder(
-                context.applicationContext,
-                YuriDatabase::class.java,
-                "yuriplayer.db"
-            )
-                // Never wipe user data on schema change. When bumping [version],
-                // add a Migration in YuriMigrations and register it here.
-                .addMigrations(*YuriMigrations.ALL)
-                .build()
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriMigrations.kt b/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriMigrations.kt
index 1b803d11..f8b6020f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriMigrations.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/db/YuriMigrations.kt
@@ -1,115 +1,3 @@
 package capital.yuri.yuriplayer.data.db
 
-import androidx.room.migration.Migration
-import androidx.sqlite.db.SupportSQLiteDatabase
-
-/**
- * Additive Room migrations. Register every new Migration here and bump
- * [YuriDatabase] version — never use fallbackToDestructiveMigration.
- */
-object YuriMigrations {
-
-    val MIGRATION_6_7 = object : Migration(6, 7) {
-        override fun migrate(db: SupportSQLiteDatabase) {
-            db.execSQL(
-                """
-                CREATE TABLE IF NOT EXISTS playlist_covers (
-                    id TEXT NOT NULL PRIMARY KEY,
-                    playlistId TEXT NOT NULL,
-                    uri TEXT NOT NULL,
-                    isSecret INTEGER NOT NULL DEFAULT 0,
-                    sortOrder INTEGER NOT NULL DEFAULT 0,
-                    createdAtMs INTEGER NOT NULL
-                )
-                """.trimIndent()
-            )
-            db.execSQL(
-                "CREATE INDEX IF NOT EXISTS index_playlist_covers_playlistId ON playlist_covers(playlistId)"
-            )
-            db.execSQL(
-                "CREATE INDEX IF NOT EXISTS index_playlist_covers_playlistId_sortOrder ON playlist_covers(playlistId, sortOrder)"
-            )
-            db.execSQL(
-                "ALTER TABLE playlists ADD COLUMN activeCoverId TEXT"
-            )
-            // Seed cover rows from legacy customImageUri so existing art is kept.
-            db.execSQL(
-                """
-                INSERT INTO playlist_covers (id, playlistId, uri, isSecret, sortOrder, createdAtMs)
-                SELECT
-                    id || '-legacy',
-                    id,
-                    customImageUri,
-                    0,
-                    0,
-                    COALESCE(updatedAtMs, createdAtMs, 0)
-                FROM playlists
-                WHERE customImageUri IS NOT NULL AND length(customImageUri) > 0
-                """.trimIndent()
-            )
-            db.execSQL(
-                """
-                UPDATE playlists
-                SET activeCoverId = id || '-legacy'
-                WHERE customImageUri IS NOT NULL AND length(customImageUri) > 0
-                """.trimIndent()
-            )
-        }
-    }
-
-    val MIGRATION_7_8 = object : Migration(7, 8) {
-        override fun migrate(db: SupportSQLiteDatabase) {
-            db.execSQL("ALTER TABLE catalog_artists ADD COLUMN mbid TEXT")
-            db.execSQL(
-                """
-                CREATE TABLE IF NOT EXISTS catalog_credits (
-                    id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
-                    subjectType TEXT NOT NULL,
-                    subjectKey TEXT NOT NULL,
-                    artistKey TEXT NOT NULL,
-                    displayName TEXT NOT NULL,
-                    role TEXT NOT NULL,
-                    position INTEGER NOT NULL DEFAULT 0
-                )
-                """.trimIndent()
-            )
-            db.execSQL(
-                "CREATE INDEX IF NOT EXISTS index_catalog_credits_subjectType_subjectKey ON catalog_credits(subjectType, subjectKey)"
-            )
-            db.execSQL(
-                "CREATE INDEX IF NOT EXISTS index_catalog_credits_artistKey ON catalog_credits(artistKey)"
-            )
-        }
-    }
-
-    val MIGRATION_8_9 = object : Migration(8, 9) {
-        override fun migrate(db: SupportSQLiteDatabase) {
-            db.execSQL(
-                "CREATE INDEX IF NOT EXISTS " +
-                    "index_catalog_tracks_sourceType_sourceInstanceId_externalId " +
-                    "ON catalog_tracks(sourceType, sourceInstanceId, externalId)"
-            )
-        }
-    }
-
-    val MIGRATION_9_10 = object : Migration(9, 10) {
-        override fun migrate(db: SupportSQLiteDatabase) {
-            db.execSQL(
-                """
-                CREATE TABLE IF NOT EXISTS artist_aliases (
-                    aliasKey TEXT NOT NULL PRIMARY KEY,
-                    canonicalKey TEXT NOT NULL,
-                    aliasName TEXT NOT NULL,
-                    source TEXT NOT NULL,
-                    createdAtMs INTEGER NOT NULL
-                )
-                """.trimIndent()
-            )
-            db.execSQL(
-                "CREATE INDEX IF NOT EXISTS index_artist_aliases_canonicalKey ON artist_aliases(canonicalKey)"
-            )
-        }
-    }
-
-    val ALL: Array<Migration> = arrayOf(MIGRATION_6_7, MIGRATION_7_8, MIGRATION_8_9, MIGRATION_9_10)
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/organize/LibraryOrganizeService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/organize/LibraryOrganizeService.kt
index 0e3af526..1b8ded24 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/organize/LibraryOrganizeService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/organize/LibraryOrganizeService.kt
@@ -2,7 +2,7 @@ package capital.yuri.yuriplayer.data.organize
 
 import android.content.Context
 import android.net.Uri
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.documentfile.provider.DocumentFile
 import capital.yuri.yuriplayer.data.LibraryIndex
 import capital.yuri.yuriplayer.data.Song
@@ -64,7 +64,7 @@ class LibraryOrganizeService(
             if (!songBelongsToRoot(song, rootKey)) continue
             val rel = PathTemplate.relativePathFor(layout, song)
             val fromLabel = song.path?.substringAfterLast('/')
-                ?: song.contentUri.lastPathSegment
+                ?: Uri.parse(song.contentUri).lastPathSegment
                 ?: song.displayTitle
             val currentRel = relativeUnderRoot(song, rootKey)
             val already = currentRel != null && currentRel.equals(rel, ignoreCase = true)
@@ -122,7 +122,7 @@ class LibraryOrganizeService(
             _status.value = msg
             ApplyResult(moved, skipped, failed, msg)
         } catch (e: Exception) {
-            Log.e(TAG, "apply failed", e)
+            log.e(e) { "apply failed" }
             _status.value = e.message
             ApplyResult(0, 0, 1, e.message ?: "Organize failed")
         } finally {
@@ -131,7 +131,7 @@ class LibraryOrganizeService(
     }
 
     private fun songBelongsToRoot(song: Song, rootKey: String): Boolean {
-        val uri = song.contentUri.toString()
+        val uri = song.contentUri
         if (uri.startsWith(rootKey) || rootKey in uri) return true
         val path = song.path.orEmpty()
         // Document path form: /tree/primary:Music/document/...
@@ -143,7 +143,7 @@ class LibraryOrganizeService(
     }
 
     private fun relativeUnderRoot(song: Song, rootKey: String): String? {
-        val decoded = Uri.decode(song.contentUri.toString())
+        val decoded = Uri.decode(song.contentUri)
         val marker = "/document/"
         val idx = decoded.indexOf(marker)
         if (idx < 0) return null
@@ -163,7 +163,7 @@ class LibraryOrganizeService(
         collision: OrganizeLayout.CollisionPolicy
     ): Boolean {
         return try {
-            val src = DocumentFile.fromSingleUri(context, song.contentUri) ?: return false
+            val src = DocumentFile.fromSingleUri(context, Uri.parse(song.contentUri)) ?: return false
             if (!src.isFile) return false
 
             val segments = relative.split('/').filter { it.isNotEmpty() }
@@ -177,7 +177,7 @@ class LibraryOrganizeService(
                 dir = when {
                     existing != null && existing.isDirectory -> existing
                     existing != null && existing.isFile -> {
-                        Log.w(TAG, "path collision with file $seg")
+                        log.w { "path collision with file $seg" }
                         return false
                     }
                     else -> dir.createDirectory(seg) ?: return false
@@ -220,7 +220,7 @@ class LibraryOrganizeService(
             src.delete()
             true
         } catch (e: Exception) {
-            Log.w(TAG, "move failed ${song.songKey}: ${e.message}")
+            log.w { "move failed ${song.songKey}: ${e.message}" }
             false
         }
     }
@@ -238,6 +238,6 @@ class LibraryOrganizeService(
     }
 
     companion object {
-        private const val TAG = "LibraryOrganize"
+        private val log = yuriLog("LibraryOrganize")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/organize/OrganizeLayout.kt b/app/src/main/java/capital/yuri/yuriplayer/data/organize/OrganizeLayout.kt
index d8bec8be..eb9e2078 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/organize/OrganizeLayout.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/organize/OrganizeLayout.kt
@@ -54,7 +54,7 @@ object PathTemplate {
     fun expand(pattern: String, song: Song, extOverride: String? = null): String {
         val ext = extOverride
             ?: song.path?.substringAfterLast('.', "")?.lowercase(Locale.US)
-            ?: song.contentUri.lastPathSegment
+            ?: android.net.Uri.parse(song.contentUri).lastPathSegment
                 ?.substringAfterLast('.', "")
                 ?.substringAfterLast('%')
                 ?.lowercase(Locale.US)
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/AudioDbArtistImageSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/AudioDbArtistImageSource.kt
index 947be0de..8848d836 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/AudioDbArtistImageSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/AudioDbArtistImageSource.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.artistKey
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
@@ -95,7 +95,7 @@ class AudioDbArtistImageSource(
         return try {
             JSONObject(body).optJSONArray("artists")?.optJSONObject(0)
         } catch (e: Exception) {
-            Log.w(TAG, "parse failed", e)
+            log.w(e) { "parse failed" }
             null
         }
     }
@@ -105,13 +105,13 @@ class AudioDbArtistImageSource(
             val response = http.get(url)
             if (!response.status.isSuccess()) null else response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "GET $url", e)
+            log.w(e) { "GET $url" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "AudioDbArtist"
+        private val log = yuriLog("AudioDbArtist")
         private const val API_KEY = "2"
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/BandsintownClient.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/BandsintownClient.kt
index 0d8dec81..b14649ea 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/BandsintownClient.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/BandsintownClient.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
 import io.ktor.client.request.get
@@ -30,7 +30,7 @@ class BandsintownClient(
         if (name.isEmpty()) return@withContext emptyList()
         val id = appId?.trim().orEmpty()
         if (id.isEmpty()) {
-            Log.i(TAG, "skip events for $name — no partner app_id configured")
+            log.i { "skip events for $name — no partner app_id configured" }
             return@withContext emptyList()
         }
         val requestUrl = url("https://rest.bandsintown.com") {
@@ -41,20 +41,17 @@ class BandsintownClient(
         val body = try {
             val response = http.get(requestUrl)
             if (response.status.value == 403) {
-                Log.w(
-                    TAG,
-                    "403 for $name — app_id is not partner-approved. " +
-                        "Request access at API@bandsintown.com or use a Bandsintown-for-Artists key."
-                )
+                log.w { "403 for $name — app_id is not partner-approved. " +
+                        "Request access at API@bandsintown.com or use a Bandsintown-for-Artists key." }
                 return@withContext emptyList()
             }
             if (!response.status.isSuccess()) {
-                Log.w(TAG, "events ${response.status} for $name")
+                log.w { "events ${response.status} for $name" }
                 return@withContext emptyList()
             }
             response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "events failed for $name", e)
+            log.w(e) { "events failed for $name" }
             return@withContext emptyList()
         }
         // API returns [] or error object
@@ -83,14 +80,13 @@ class BandsintownClient(
                 }
             }
         } catch (e: Exception) {
-            Log.w(TAG, "parse events failed", e)
+            log.w(e) { "parse events failed" }
             emptyList()
         }
     }
 
     companion object {
-        private const val TAG = "Bandsintown"
-
+        private val log = yuriLog("Bandsintown")
         /** Deep-link fallback when API access is unavailable. */
         fun publicArtistUrl(artistName: String): String {
             return url("https://www.bandsintown.com") {
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/DeezerArtistImageSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/DeezerArtistImageSource.kt
index 45f7152b..2eb37424 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/DeezerArtistImageSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/DeezerArtistImageSource.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
 import io.ktor.client.request.get
@@ -95,7 +95,7 @@ class DeezerArtistImageSource(
                 )
             }
         } catch (e: Exception) {
-            Log.w(TAG, "parse failed", e)
+            log.w(e) { "parse failed" }
             emptyList()
         }
     }
@@ -105,12 +105,12 @@ class DeezerArtistImageSource(
             val response = http.get(url)
             if (!response.status.isSuccess()) null else response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "GET $url", e)
+            log.w(e) { "GET $url" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "DeezerArtistImg"
+        private val log = yuriLog("DeezerArtistImg")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/DiscogsClient.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/DiscogsClient.kt
index 78214e9b..bb4db6fc 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/DiscogsClient.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/DiscogsClient.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.http.UrlScope
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
@@ -64,7 +64,7 @@ class DiscogsClient(
             }
             hits.sortedByDescending { ArtistNameMatch.score(wanted, it.title) }
         } catch (e: Exception) {
-            Log.w(TAG, "search parse failed", e)
+            log.w(e) { "search parse failed" }
             emptyList()
         }
     }
@@ -78,7 +78,7 @@ class DiscogsClient(
         return try {
             JSONObject(body)
         } catch (e: Exception) {
-            Log.w(TAG, "json parse failed ${path.joinToString("/")}", e)
+            log.w(e) { "json parse failed ${path.joinToString("/")}" }
             null
         }
     }
@@ -107,18 +107,18 @@ class DiscogsClient(
                 }
             }
             if (!response.status.isSuccess()) {
-                Log.w(TAG, "GET $requestUrl → ${response.status}")
+                log.w { "GET $requestUrl → ${response.status}" }
                 return@withLock null
             }
             response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "GET failed $requestUrl", e)
+            log.w(e) { "GET failed $requestUrl" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "Discogs"
+        private val log = yuriLog("Discogs")
         private const val API = "https://api.discogs.com"
         private const val MIN_INTERVAL_MS = 1_100L
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinArtistImageSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinArtistImageSource.kt
index 8e5209bd..42e1ac9c 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinArtistImageSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinArtistImageSource.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -70,7 +70,7 @@ class JellyfinArtistImageSource(
             username = user,
             password = secret
         ).getOrElse {
-            Log.w(TAG, "auth failed for ${server.name}: ${it.message}")
+            log.w { "auth failed for ${server.name}: ${it.message}" }
             null
         }
     }
@@ -116,12 +116,12 @@ class JellyfinArtistImageSource(
                 )
             }
         } catch (e: Exception) {
-            Log.w(TAG, "searchArtists failed: ${e.message}")
+            log.w { "searchArtists failed: ${e.message}" }
             emptyList()
         }
     }
 
     companion object {
-        private const val TAG = "JellyfinArtistImg"
+        private val log = yuriLog("JellyfinArtistImg")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinClient.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinClient.kt
index caf53563..beed9956 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinClient.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/JellyfinClient.kt
@@ -2,7 +2,7 @@ package capital.yuri.yuriplayer.data.source
 
 import android.content.Context
 import android.net.Uri
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.Song
 import capital.yuri.yuriplayer.http.url
 import org.jellyfin.sdk.Jellyfin
@@ -44,7 +44,7 @@ class JellyfinClient(
         val user = username.trim()
         require(user.isNotEmpty()) { "Username is empty" }
 
-        Log.i(TAG, "authenticate → $root user=$user (official SDK)")
+        log.i { "authenticate → $root user=$user (official SDK)" }
 
         val api = jellyfin.createApi(baseUrl = root)
         try {
@@ -59,10 +59,7 @@ class JellyfinClient(
 
             api.update(accessToken = token)
 
-            Log.i(
-                TAG,
-                "auth ok server=${authenticationResult.serverId} userId=${userId.take(8)}…"
-            )
+            log.i { "auth ok server=${authenticationResult.serverId} userId=${userId.take(8)}…" }
             Session(
                 baseUrl = root,
                 userId = userId,
@@ -78,7 +75,7 @@ class JellyfinClient(
         } catch (e: ApiClientException) {
             error(e.message ?: "Jellyfin API error")
         }
-    }.onFailure { Log.w(TAG, "authenticate failed: ${it.message}") }
+    }.onFailure { log.w { "authenticate failed: ${it.message}" } }
 
     suspend fun listAudioItems(session: Session, limit: Int = 50_000): Result<List<Song>> =
         runCatching {
@@ -87,7 +84,7 @@ class JellyfinClient(
                 out += page
             }.getOrThrow()
             out
-        }.onFailure { Log.w(TAG, "listAudioItems failed: ${it.message}") }
+        }.onFailure { log.w { "listAudioItems failed: ${it.message}" } }
 
     enum class ListingMode { FULL, LIGHT }
 
@@ -105,7 +102,7 @@ class JellyfinClient(
             startIndex = 0
         )
         result.totalRecordCount ?: 0
-    }.onFailure { Log.w(TAG, "audioItemCount failed: ${it.message}") }
+    }.onFailure { log.w { "audioItemCount failed: ${it.message}" } }
 
     suspend fun listAudioItemsPaged(
         session: Session,
@@ -127,7 +124,7 @@ class JellyfinClient(
         val wantImages = true
 
         if (start > 0) {
-            Log.i(TAG, "resume paging from startIndex=$start mode=$mode")
+            log.i { "resume paging from startIndex=$start mode=$mode" }
         }
 
         while (delivered < maxItems) {
@@ -149,24 +146,21 @@ class JellyfinClient(
             totalHint = result.totalRecordCount ?: totalHint
             val raw = result.items.orEmpty()
             if (raw.isEmpty()) {
-                Log.i(TAG, "empty page start=$start totalHint=$totalHint page=$pageNum")
+                log.i { "empty page start=$start totalHint=$totalHint page=$pageNum" }
                 break
             }
 
             val page = raw.mapNotNull { item ->
                 runCatching { item.toSong(session) }
-                    .onFailure { e -> Log.w(TAG, "toSong failed for '${item.name}': ${e.message}") }
+                    .onFailure { e -> log.w { "toSong failed for '${item.name}': ${e.message}" } }
                     .getOrNull()
             }
             val liveIds = raw.mapNotNull { item ->
                 item.id?.toString()?.let { "jellyfin:$it" }
             }
             pageNum++
-            Log.i(
-                TAG,
-                "page#$pageNum start=$start raw=${raw.size} mapped=${page.size} " +
-                    "delivered=$delivered totalHint=$totalHint mode=$mode sort=$sortBy"
-            )
+            log.i { "page#$pageNum start=$start raw=${raw.size} mapped=${page.size} " +
+                    "delivered=$delivered totalHint=$totalHint mode=$mode sort=$sortBy" }
             onPage(page, start, totalHint, liveIds)
             delivered += raw.size
 
@@ -175,9 +169,9 @@ class JellyfinClient(
             if (totalHint != null && start >= totalHint) break
         }
 
-        Log.i(TAG, "listAudioItemsPaged done delivered=$delivered totalHint=$totalHint pages=$pageNum")
+        log.i { "listAudioItemsPaged done delivered=$delivered totalHint=$totalHint pages=$pageNum" }
         delivered
-    }.onFailure { Log.w(TAG, "listAudioItemsPaged failed: ${it.message}") }
+    }.onFailure { log.w { "listAudioItemsPaged failed: ${it.message}" } }
 
     /**
      * Jellyfin Instant Mix — similar tracks from a seed item (song / album / artist id).
@@ -202,7 +196,7 @@ class JellyfinClient(
             enableImageTypes = listOf(ImageType.PRIMARY)
         )
         result.items.orEmpty().mapNotNull { it.toSong(session) }
-    }.onFailure { Log.w(TAG, "instantMixFromItem failed: ${it.message}") }
+    }.onFailure { log.w { "instantMixFromItem failed: ${it.message}" } }
 
     data class PlaylistRef(
         val id: String,
@@ -237,7 +231,7 @@ class JellyfinClient(
                 owned = item.canDelete == true
             )
         }
-    }.onFailure { Log.w(TAG, "listPlaylists failed: ${it.message}") }
+    }.onFailure { log.w { "listPlaylists failed: ${it.message}" } }
 
     suspend fun playlistSongs(session: Session, playlistId: String): Result<List<Song>> =
         runCatching {
@@ -257,7 +251,7 @@ class JellyfinClient(
                 limit = 2_000
             )
             result.items.orEmpty().mapNotNull { it.toSong(session) }
-        }.onFailure { Log.w(TAG, "playlistSongs failed: ${it.message}") }
+        }.onFailure { log.w { "playlistSongs failed: ${it.message}" } }
 
     suspend fun searchAudio(
         session: Session,
@@ -327,7 +321,7 @@ class JellyfinClient(
             limit = limit.coerceIn(1, 100)
         )
         result.items.orEmpty().mapNotNull(map)
-    }.onFailure { Log.w(TAG, "search $kind failed: ${it.message}") }
+    }.onFailure { log.w { "search $kind failed: ${it.message}" } }
 
     fun streamUrl(session: Session, itemId: String, container: String? = null): String =
         url(session.baseUrl) {
@@ -408,8 +402,8 @@ class JellyfinClient(
             albumArtist = albumArtistName ?: trackArtistName,
             album = album?.takeIf { it.isNotBlank() },
             durationMs = durationMs,
-            contentUri = Uri.parse(stream),
-            albumArtUri = art,
+            contentUri = stream,
+            albumArtUri = art?.toString(),
             trackNumber = indexNumber,
             discNumber = parentIndexNumber,
             year = productionYear,
@@ -421,7 +415,7 @@ class JellyfinClient(
     }
 
     companion object {
-        private const val TAG = "JellyfinClient"
+        private val log = yuriLog("JellyfinClient")
         private const val PREFS = "jellyfin_client"
         private const val KEY_DEVICE_ID = "device_id"
 
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/LibraryFaviconStore.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/LibraryFaviconStore.kt
index 4402175b..bdc28086 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/LibraryFaviconStore.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/LibraryFaviconStore.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data.source
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
@@ -41,7 +41,7 @@ class LibraryFaviconStore(
             }.getOrNull() ?: continue
             val dest = File(dir, "${instance.id}.bin")
             dest.writeBytes(bytes)
-            Log.i(TAG, "favicon ${instance.name} ← $url ${bytes.size}B")
+            log.i { "favicon ${instance.name} ← $url ${bytes.size}B" }
             return@withContext dest
         }
         null
@@ -53,6 +53,6 @@ class LibraryFaviconStore(
     }
 
     companion object {
-        private const val TAG = "LibraryFavicon"
+        private val log = yuriLog("LibraryFavicon")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzArtistProfileProvider.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzArtistProfileProvider.kt
index ddf2bf7d..6eb247d4 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzArtistProfileProvider.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzArtistProfileProvider.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data.source
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.artistKey
 import capital.yuri.yuriplayer.data.db.CatalogDao
 import kotlinx.coroutines.Dispatchers
@@ -42,7 +42,7 @@ class MusicBrainzArtistProfileProvider(
             if (ok && dest.isFile && dest.length() > 0L) {
                 imagePath = dest.absolutePath
             } else {
-                Log.w(TAG, "Failed to download artist image for $artistName from $imageUrl")
+                log.w { "Failed to download artist image for $artistName from $imageUrl" }
             }
         }
 
@@ -74,6 +74,6 @@ class MusicBrainzArtistProfileProvider(
     }
 
     companion object {
-        private const val TAG = "MBArtist"
+        private val log = yuriLog("MBArtist")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzClient.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzClient.kt
index 2df745bb..f809bc26 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzClient.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicBrainzClient.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
 import io.ktor.client.request.get
@@ -168,7 +168,7 @@ class MusicBrainzClient(
                 }
             }
         } catch (e: Exception) {
-            Log.w(TAG, "allWikidataP18 $qid", e)
+            log.w(e) { "allWikidataP18 $qid" }
             emptyList()
         }
     }
@@ -229,7 +229,7 @@ class MusicBrainzClient(
                 else -> exactId ?: bestId?.takeIf { bestScore >= 50 }
             }
         } catch (e: Exception) {
-            Log.w(TAG, "pickBestArtistMbid failed", e)
+            log.w(e) { "pickBestArtistMbid failed" }
             null
         }
     }
@@ -258,7 +258,7 @@ class MusicBrainzClient(
             root.optJSONObject("originalimage")?.optString("source")?.takeIf { it.isNotBlank() }
                 ?: root.optJSONObject("thumbnail")?.optString("source")?.takeIf { it.isNotBlank() }
         } catch (e: Exception) {
-            Log.w(TAG, "Wikipedia image failed", e)
+            log.w(e) { "Wikipedia image failed" }
             null
         }
     }
@@ -379,7 +379,7 @@ class MusicBrainzClient(
                 genres = parseTags(json)
             )
         } catch (e: Exception) {
-            Log.w(TAG, "parse artist detail failed", e)
+            log.w(e) { "parse artist detail failed" }
             ArtistHit(mbid, "")
         }
     }
@@ -405,7 +405,7 @@ class MusicBrainzClient(
             }
             best
         } catch (e: Exception) {
-            Log.w(TAG, "parse release search failed", e)
+            log.w(e) { "parse release search failed" }
             null
         }
     }
@@ -415,12 +415,12 @@ class MusicBrainzClient(
         try {
             val response = http.get(url)
             if (!response.status.isSuccess()) {
-                Log.w(TAG, "GET $url → ${response.status}")
+                log.w { "GET $url → ${response.status}" }
                 return@withLock null
             }
             response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "GET failed $url", e)
+            log.w(e) { "GET failed $url" }
             null
         }
     }
@@ -442,7 +442,7 @@ class MusicBrainzClient(
                 dest.isFile && dest.length() > 0L
             }
         } catch (e: Exception) {
-            Log.w(TAG, "download failed $url", e)
+            log.w(e) { "download failed $url" }
             false
         }
     }
@@ -461,7 +461,7 @@ class MusicBrainzClient(
             .replace(")", "\\)")
 
     companion object {
-        private const val TAG = "MusicBrainz"
+        private val log = yuriLog("MusicBrainz")
         /** Anonymous MB guideline ≈ 1 req/s. */
         private const val MIN_INTERVAL_MS = 1_100L
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicSource.kt
index aa6a1d64..6da0b24f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/MusicSource.kt
@@ -6,41 +6,7 @@ import capital.yuri.yuriplayer.data.db.ArtistProfileEntity
 import capital.yuri.yuriplayer.data.db.SourceOverrideDao
 import capital.yuri.yuriplayer.data.db.SourceOverrideEntity
 
-enum class SourceType(val rank: Int) {
-    LOCAL(0),
-    JELLYFIN(10),
-    /** OpenSubsonic / Subsonic protocol (Navidrome, Gonic, Official, …). */
-    SUBSONIC(20),
-    /** @deprecated Prefer [SUBSONIC]; kept for existing source_instances rows. */
-    NAVIDROME(20),
-    WEBDAV(30),
-    OTHER(100);
-
-    fun displayName(): String = when (this) {
-        LOCAL -> "Local"
-        JELLYFIN -> "Jellyfin"
-        SUBSONIC -> "Subsonic"
-        NAVIDROME -> "Navidrome"
-        WEBDAV -> "WebDAV"
-        OTHER -> "Other"
-    }
-
-    companion object {
-        fun from(raw: String?): SourceType =
-            entries.firstOrNull { it.name.equals(raw, ignoreCase = true) } ?: OTHER
-
-        /** True for Subsonic-protocol backends including legacy NAVIDROME rows. */
-        fun isSubsonicFamily(type: SourceType): Boolean =
-            type == SUBSONIC || type == NAVIDROME
-    }
-}
-
-data class SourceOffering(
-    val sourceType: SourceType,
-    val sourceId: Long? = null,
-    val sourceName: String,
-    val song: Song
-)
+// SourceType + SourceOffering moved to :core (commonMain), same package.
 
 data class CatalogTrack(
     val identityKey: String,
@@ -214,8 +180,6 @@ fun categorizeLink(url: String, fallbackLabel: String? = null): ArtistLink {
             "YouTube" to LinkCategory.STREAMING
         u.contains("musicbrainz.org") -> "MusicBrainz" to LinkCategory.DATABASE
         u.contains("discogs.com") -> "Discogs" to LinkCategory.DATABASE
-        u.contains("wikidata.org") -> "Wikidata" to LinkCategory.DATABASE
-        u.contains("wikipedia.org") -> "Wikipedia" to LinkCategory.DATABASE
         u.contains("last.fm") || u.contains("lastfm") -> "Last.fm" to LinkCategory.DATABASE
         u.contains("allmusic.com") -> "AllMusic" to LinkCategory.DATABASE
         u.contains("rateyourmusic.com") || u.contains("rymc.") ->
@@ -226,6 +190,8 @@ fun categorizeLink(url: String, fallbackLabel: String? = null): ArtistLink {
         u.contains("tiktok.com") -> "TikTok" to LinkCategory.SOCIAL
         u.contains("bandsintown.com") -> "Bandsintown" to LinkCategory.OTHER
         u.contains("songkick.com") -> "Songkick" to LinkCategory.OTHER
+        u.contains("wikidata.org") -> "Wikidata" to LinkCategory.DATABASE
+        u.contains("wikipedia.org") -> "Wikipedia" to LinkCategory.DATABASE
         else -> (fallbackLabel ?: "Link") to LinkCategory.OTHER
     }
     val finalLabel = when {
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/RemotePlaylistService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/RemotePlaylistService.kt
index 6d4e5b29..51f3c8ac 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/RemotePlaylistService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/RemotePlaylistService.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.Playlist
 import capital.yuri.yuriplayer.data.PlaylistRepository
 import capital.yuri.yuriplayer.data.Song
@@ -65,7 +65,7 @@ class RemotePlaylistService(
             if (playlists.get(remote.stableId) != null) continue
             if (importToLocal(remote) != null) imported++
         }
-        if (imported > 0) Log.i(TAG, "imported $imported owned remote playlists")
+        if (imported > 0) log.i { "imported $imported owned remote playlists" }
         return imported
     }
 
@@ -125,7 +125,7 @@ class RemotePlaylistService(
         val user = row.username ?: return null
         val secret = row.secret ?: return null
         return jellyfin.authenticate(url, user, secret).getOrElse {
-            Log.w(TAG, "jellyfin auth for playlists failed: ${it.message}")
+            log.w { "jellyfin auth for playlists failed: ${it.message}" }
             null
         }
     }
@@ -142,6 +142,6 @@ class RemotePlaylistService(
     }
 
     companion object {
-        private const val TAG = "RemotePlaylists"
+        private val log = yuriLog("RemotePlaylists")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt
index aaa08b14..df0cbec7 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt
@@ -1,73 +1,3 @@
 package capital.yuri.yuriplayer.data.source
 
-import capital.yuri.yuriplayer.data.db.SourceInstanceDao
-import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
-import kotlinx.coroutines.flow.Flow
-
-/**
- * Persisted remote library servers (Jellyfin, Subsonic/OpenSubsonic, …).
- * Local scan is not a [SourceInstanceEntity] — it is always present.
- */
-class SourceInstanceRepository(
-    private val dao: SourceInstanceDao
-) {
-    fun observeAll(): Flow<List<SourceInstanceEntity>> = dao.observeAll()
-
-    suspend fun getAll(): List<SourceInstanceEntity> = dao.getAll()
-
-    suspend fun get(id: Long): SourceInstanceEntity? =
-        dao.getAll().firstOrNull { it.id == id }
-
-    suspend fun upsert(entity: SourceInstanceEntity): Long = dao.upsert(entity)
-
-    suspend fun delete(id: Long) = dao.delete(id)
-
-    suspend fun setEnabled(id: Long, enabled: Boolean) {
-        val row = get(id) ?: return
-        dao.update(row.copy(enabled = enabled))
-    }
-
-    suspend fun addJellyfin(
-        name: String,
-        baseUrl: String,
-        username: String,
-        passwordOrToken: String
-    ): Long = upsert(
-        SourceInstanceEntity(
-            type = SourceType.JELLYFIN.name,
-            name = name.ifBlank { "Jellyfin" },
-            baseUrl = normalizeBaseUrl(baseUrl),
-            username = username,
-            secret = passwordOrToken,
-            enabled = true
-        )
-    )
-
-    suspend fun addSubsonic(
-        name: String,
-        baseUrl: String,
-        username: String,
-        password: String
-    ): Long = upsert(
-        SourceInstanceEntity(
-            type = SourceType.SUBSONIC.name,
-            name = name.ifBlank { "Subsonic" },
-            baseUrl = normalizeBaseUrl(baseUrl),
-            username = username,
-            secret = password,
-            enabled = true
-        )
-    )
-
-    companion object {
-        fun normalizeBaseUrl(raw: String): String {
-            var u = raw.trim().trimEnd('/')
-            if (!u.startsWith("http://", ignoreCase = true) &&
-                !u.startsWith("https://", ignoreCase = true)
-            ) {
-                u = "https://$u"
-            }
-            return u
-        }
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicArtistImageSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicArtistImageSource.kt
index 59b98b11..85291302 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicArtistImageSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicArtistImageSource.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -67,12 +67,12 @@ class SubsonicArtistImageSource(
             password = secret
         )
         return client.ping(base).getOrElse {
-            Log.w(TAG, "ping failed for ${server.name}: ${it.message}")
+            log.w { "ping failed for ${server.name}: ${it.message}" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "SubsonicArtistImg"
+        private val log = yuriLog("SubsonicArtistImg")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicClient.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicClient.kt
index a52b5c3d..50305eb9 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicClient.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/SubsonicClient.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.data.source
 
 import android.net.Uri
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.Song
 import capital.yuri.yuriplayer.http.UrlScope
 import capital.yuri.yuriplayer.http.url
@@ -65,7 +65,7 @@ class SubsonicClient(
             openSubsonic = open,
             serverVersion = resp.version ?: resp.serverVersion
         )
-    }.onFailure { Log.w(TAG, "ping failed: ${it.message}") }
+    }.onFailure { log.w { "ping failed: ${it.message}" } }
 
     /**
      * Paged album index via getAlbumList2 (alphabeticalByName).
@@ -100,7 +100,7 @@ class SubsonicClient(
             offset = offset,
             exhausted = refs.size < pageSize
         )
-    }.onFailure { Log.w(TAG, "listAlbumsPage failed: ${it.message}") }
+    }.onFailure { log.w { "listAlbumsPage failed: ${it.message}" } }
 
     suspend fun listSongsForAlbum(session: Session, albumId: String): Result<List<Song>> =
         runCatching {
@@ -117,7 +117,7 @@ class SubsonicClient(
                     albumArtistFallback = album.resolvedAlbumArtist()
                 )
             }
-        }.onFailure { Log.w(TAG, "listSongsForAlbum($albumId) failed: ${it.message}") }
+        }.onFailure { log.w { "listSongsForAlbum($albumId) failed: ${it.message}" } }
 
     /**
      * Streams all songs via album list paging. Prefer this for large Navidrome libraries.
@@ -148,7 +148,7 @@ class SubsonicClient(
             var albumFetchFailed = false
             for (album in page.albums) {
                 val songs = listSongsForAlbum(session, album.id).getOrElse {
-                    Log.w(TAG, "getAlbum failed ${album.id}: ${it.message}")
+                    log.w { "getAlbum failed ${album.id}: ${it.message}" }
                     albumFetchFailed = true
                     emptyList()
                 }
@@ -164,7 +164,7 @@ class SubsonicClient(
             if (page.exhausted) break
         }
         delivered
-    }.onFailure { Log.w(TAG, "listSongsPaged failed: ${it.message}") }
+    }.onFailure { log.w { "listSongsPaged failed: ${it.message}" } }
 
     /**
      * Legacy full walk via indexes (small libraries / servers without albumList2).
@@ -208,7 +208,7 @@ class SubsonicClient(
             ?: resp.similarSongs?.song
             ?: emptyList()
         children.mapNotNull { it.toSong(session) }
-    }.onFailure { Log.w(TAG, "similarSongs failed: ${it.message}") }
+    }.onFailure { log.w { "similarSongs failed: ${it.message}" } }
 
     data class LibraryHits(
         val songs: List<Song>,
@@ -250,7 +250,7 @@ class SubsonicClient(
             ArtistHit(id = id, name = name, coverArt = a.coverArt)
         }
         LibraryHits(songs = songs, albums = albums, artists = artists)
-    }.onFailure { Log.w(TAG, "searchLibrary failed: ${it.message}") }
+    }.onFailure { log.w { "searchLibrary failed: ${it.message}" } }
 
     suspend fun searchArtists(
         session: Session,
@@ -260,7 +260,7 @@ class SubsonicClient(
         searchLibrary(session, query, songCount = 0, albumCount = 0, artistCount = count)
             .getOrThrow()
             .artists
-    }.onFailure { Log.w(TAG, "searchArtists failed: ${it.message}") }
+    }.onFailure { log.w { "searchArtists failed: ${it.message}" } }
 
     data class ArtistHit(
         val id: String,
@@ -291,7 +291,7 @@ class SubsonicClient(
                 owner = p.owner
             )
         }
-    }.onFailure { Log.w(TAG, "listPlaylists failed: ${it.message}") }
+    }.onFailure { log.w { "listPlaylists failed: ${it.message}" } }
 
     suspend fun playlistSongs(session: Session, playlistId: String): Result<List<Song>> =
         runCatching {
@@ -300,7 +300,7 @@ class SubsonicClient(
             }
             val detail = json.decodeFromString<SubsonicResponse>(body).subsonicResponse.playlist
             detail?.entry.orEmpty().mapNotNull { it.toSong(session, albumCoverArt = detail?.coverArt) }
-        }.onFailure { Log.w(TAG, "playlistSongs failed: ${it.message}") }
+        }.onFailure { log.w { "playlistSongs failed: ${it.message}" } }
 
     fun streamUrl(session: Session, id: String): String =
         restUrl(session, "stream") {
@@ -391,8 +391,8 @@ class SubsonicClient(
             albumArtist = albumArtistName ?: trackArtistName,
             album = album?.takeIf { it.isNotBlank() } ?: albumNameFallback?.takeIf { it.isNotBlank() },
             durationMs = duration?.times(1000L)?.takeIf { it > 0 },
-            contentUri = Uri.parse(stream),
-            albumArtUri = art,
+            contentUri = stream,
+            albumArtUri = art?.toString(),
             trackNumber = track,
             discNumber = discNumber,
             year = year,
@@ -570,7 +570,7 @@ class SubsonicClient(
     )
 
     companion object {
-        private const val TAG = "SubsonicClient"
+        private val log = yuriLog("SubsonicClient")
         /** 1.16.1 is widely implemented; OpenSubsonic servers accept it. */
         private const val API_VERSION = "1.16.1"
     }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/WikidataArtistImageSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/WikidataArtistImageSource.kt
index 0428f108..678e2e9f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/WikidataArtistImageSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/WikidataArtistImageSource.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.artistKey
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
@@ -100,7 +100,7 @@ class WikidataArtistImageSource(
                 hits
             }
         } catch (e: Exception) {
-            Log.w(TAG, "search failed", e)
+            log.w(e) { "search failed" }
             emptyList()
         }
 
@@ -291,7 +291,7 @@ class WikidataArtistImageSource(
                     ?.takeIf { it.isNotBlank() }
             }
         } catch (e: Exception) {
-            Log.w(TAG, "labels failed", e)
+            log.w(e) { "labels failed" }
             emptyList()
         }
     }
@@ -301,13 +301,13 @@ class WikidataArtistImageSource(
             val response = http.get(url)
             if (!response.status.isSuccess()) null else response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "GET $url", e)
+            log.w(e) { "GET $url" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "WikidataArtistImg"
+        private val log = yuriLog("WikidataArtistImg")
 
         private val MUSIC_INSTANCE_QIDS = setOf(
             "Q215380", "Q5741069", "Q1058743", "Q2088357", "Q588750",
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/source/WikipediaArtistImageSource.kt b/app/src/main/java/capital/yuri/yuriplayer/data/source/WikipediaArtistImageSource.kt
index 6118865b..d0ebef9c 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/source/WikipediaArtistImageSource.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/source/WikipediaArtistImageSource.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.data.source
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.artistKey
 import capital.yuri.yuriplayer.http.url
 import io.ktor.client.HttpClient
@@ -172,7 +172,7 @@ class WikipediaArtistImageSource(
                     }
                 }
             } catch (e: Exception) {
-                Log.w(TAG, "search failed for $qRaw", e)
+                log.w(e) { "search failed for $qRaw" }
             }
             if (seen.size >= 6) break
         }
@@ -235,7 +235,7 @@ class WikipediaArtistImageSource(
             }
             out.distinct()
         } catch (e: Exception) {
-            Log.w(TAG, "pageImages failed", e)
+            log.w(e) { "pageImages failed" }
             emptyList()
         }
     }
@@ -245,13 +245,13 @@ class WikipediaArtistImageSource(
             val response = http.get(url)
             if (!response.status.isSuccess()) null else response.bodyAsText()
         } catch (e: Exception) {
-            Log.w(TAG, "GET $url", e)
+            log.w(e) { "GET $url" }
             null
         }
     }
 
     companion object {
-        private const val TAG = "WikiArtistImg"
+        private val log = yuriLog("WikiArtistImg")
 
         /** Person / group signals. */
         private val ARTIST_HINTS = listOf(
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/text/StringSimilarity.kt b/app/src/main/java/capital/yuri/yuriplayer/data/text/StringSimilarity.kt
index feced81a..eb489411 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/text/StringSimilarity.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/text/StringSimilarity.kt
@@ -1,252 +1,5 @@
 package capital.yuri.yuriplayer.data.text
 
-import android.icu.text.Transliterator
-import java.text.Normalizer
-
-/**
- * Script-aware fuzzy matching for music tags.
- *
- * **Jaro–Winkler** — Latin names/titles. Jaro is the mean of matching-char
- * rates in both strings plus the non-transposed match rate. Matches only count
- * inside a sliding window of `max(len)/2 - 1`. Winkler then boosts strings that
- * share a prefix (up to 4 chars, scale 0.1). Great for "Seether"/"Seeter" and
- * "Fray"/"Frat" at the end of a long title. Bad for CJK: one kanji is a whole
- * morpheme, prefix boost is Latin-centric, and a 4-character title with one
- * typo is already 25% different.
- *
- * **Levenshtein** — edit count. We keep it as a *cap* ("at most 2 edits") so
- * Trench/Breach (2 edits, 6 letters) stay distinct.
- *
- * **N-gram Jaccard** — best default for CJK. Each string → set of character
- * n-grams; score is `|A∩B| / |A∪B|`. Unigrams treat each Han/Kana/Hangul
- * character as a token (the usual CJK indexer). Bigrams catch local typos
- * without needing spaces. Same metric works for Latin ("oh ms believer").
- *
- * **Folds before compare** (not stored in catalog keys):
- * - NFKC, Latin-ASCII (Ø→O, é→e)
- * - Katakana→Hiragana so ナイトコード ≡ ないとこーど
- * - Traditional→Simplified Han so 周杰倫 ≡ 周杰伦
- * - Hangul NFD (jamo) so syllable-level typos compare
- *
- * Libraries considered, not taken:
- * - `com.aallam.similarity:string-similarity-kotlin` — KMP port of tdebatty,
- *   last release 0.1.0 / years stale.
- * - `info.debatty:java-string-similarity` — same algorithms, JVM-only.
- * - Apache Commons Text — maintained, JVM-only, KMP later would fork anyway.
- * In-tree + ICU transliterators stay KMP-movable (swap ICU for a expect/actual).
- */
-object StringSimilarity {
-
-    enum class Kind { ALBUM, TITLE, ARTIST }
-
-    fun likelySame(a: String, b: String, kind: Kind): Boolean {
-        if (a == b) return true
-        val fa = foldCompare(a)
-        val fb = foldCompare(b)
-        if (fa.isEmpty() || fb.isEmpty()) return false
-        if (fa == fb) return true
-
-        val pa = codePoints(fa)
-        val pb = codePoints(fb)
-        val minCp = minOf(pa.size, pb.size)
-        val maxCp = maxOf(pa.size, pb.size)
-        if (minCp == 0) return false
-        if (maxCp - minCp > 4 && maxCp > 8) return false
-
-        val cjk = isCjkHeavy(pa) || isCjkHeavy(pb)
-        val levCap = if (cjk) 2 else 2
-        val lev = editDistanceCodePoints(pa, pb, levCap + 1)
-        val jw = jaroWinkler(pa, pb)
-        val jac1 = ngramJaccard(pa, pb, 1)
-        val jac2 = if (minCp >= 2) ngramJaccard(pa, pb, 2) else jac1
-
-        if (cjk) {
-            return when (kind) {
-                Kind.ARTIST -> (jac1 >= 0.85 && lev <= 1) || jw >= 0.95
-                Kind.ALBUM, Kind.TITLE ->
-                    jac1 >= 0.80 && lev <= 1 ||
-                        jac2 >= 0.75 ||
-                        (jw >= 0.90 && lev <= 1)
-            }
-        }
-
-        return when (kind) {
-            Kind.ALBUM ->
-                minCp >= 12 && jw >= 0.93 && lev <= 2
-            Kind.TITLE ->
-                (minCp >= 6 && jw >= 0.90 && lev <= 2) ||
-                    (minCp >= 14 && jw >= 0.92)
-            Kind.ARTIST ->
-                minCp >= 4 && jw >= 0.96 && lev <= 2
-        }
-    }
-
-    fun foldCompare(value: String): String {
-        var t = value.trim().lowercase()
-        t = Normalizer.normalize(t, Normalizer.Form.NFKC)
-        t = transliterate(t, "Traditional-Simplified")
-        t = katakanaToHiragana(t)
-        t = Normalizer.normalize(t, Normalizer.Form.NFD)
-        t = t.replace(Regex("\\p{M}+"), "")
-        t = transliterate(t, "Latin-ASCII")
-        t = t.replace(Regex("[\\s\\p{Punct}]+"), " ").trim()
-        return t
-    }
-
-    private fun transliterate(value: String, id: String): String = try {
-        Transliterator.getInstance(id).transliterate(value)
-    } catch (_: Exception) {
-        value
-    }
-
-    private fun katakanaToHiragana(value: String): String {
-        val sb = StringBuilder(value.length)
-        var i = 0
-        while (i < value.length) {
-            val cp = value.codePointAt(i)
-            val folded = if (cp in 0x30A1..0x30F6) cp - 0x60 else cp
-            sb.appendCodePoint(folded)
-            i += Character.charCount(cp)
-        }
-        return sb.toString()
-    }
-
-    private fun isCjkHeavy(cps: IntArray): Boolean {
-        if (cps.isEmpty()) return false
-        var n = 0
-        for (cp in cps) {
-            val script = Character.UnicodeScript.of(cp)
-            if (script == Character.UnicodeScript.HAN ||
-                script == Character.UnicodeScript.HIRAGANA ||
-                script == Character.UnicodeScript.KATAKANA ||
-                script == Character.UnicodeScript.HANGUL ||
-                script == Character.UnicodeScript.BOPOMOFO
-            ) {
-                n++
-            }
-        }
-        return n * 2 >= cps.size
-    }
-
-    private fun codePoints(s: String): IntArray {
-        val n = s.codePointCount(0, s.length)
-        val out = IntArray(n)
-        var i = 0
-        var p = 0
-        while (p < s.length) {
-            val cp = s.codePointAt(p)
-            out[i++] = cp
-            p += Character.charCount(cp)
-        }
-        return out
-    }
-
-    /** Jaro–Winkler similarity in `0f..1f`. */
-    fun jaroWinkler(a: IntArray, b: IntArray): Float {
-        if (a.isEmpty() && b.isEmpty()) return 1f
-        if (a.isEmpty() || b.isEmpty()) return 0f
-        if (a.contentEquals(b)) return 1f
-        val jaro = jaro(a, b)
-        if (jaro < 0.7f) return jaro
-        var prefix = 0
-        val limit = minOf(4, a.size, b.size)
-        while (prefix < limit && a[prefix] == b[prefix]) prefix++
-        return jaro + prefix * 0.1f * (1f - jaro)
-    }
-
-    private fun jaro(a: IntArray, b: IntArray): Float {
-        val s1: IntArray
-        val s2: IntArray
-        if (a.size >= b.size) {
-            s1 = a
-            s2 = b
-        } else {
-            s1 = b
-            s2 = a
-        }
-        val matchWindow = maxOf(s1.size / 2 - 1, 0)
-        val s1Match = BooleanArray(s1.size)
-        val s2Match = BooleanArray(s2.size)
-        var matches = 0
-        for (i in s1.indices) {
-            val lo = maxOf(0, i - matchWindow)
-            val hi = minOf(i + matchWindow + 1, s2.size)
-            for (j in lo until hi) {
-                if (s2Match[j] || s1[i] != s2[j]) continue
-                s1Match[i] = true
-                s2Match[j] = true
-                matches++
-                break
-            }
-        }
-        if (matches == 0) return 0f
-        var k = 0
-        var trans = 0
-        for (i in s1.indices) {
-            if (!s1Match[i]) continue
-            while (!s2Match[k]) k++
-            if (s1[i] != s2[k]) trans++
-            k++
-        }
-        val m = matches.toFloat()
-        return (m / s1.size + m / s2.size + (m - trans / 2f) / m) / 3f
-    }
-
-    fun ngramJaccard(a: IntArray, b: IntArray, n: Int): Float {
-        if (n <= 0) return 0f
-        if (a.contentEquals(b)) return 1f
-        val ga = ngrams(a, n)
-        val gb = ngrams(b, n)
-        if (ga.isEmpty() && gb.isEmpty()) return 1f
-        if (ga.isEmpty() || gb.isEmpty()) return 0f
-        var inter = 0
-        val keys = ga.keys + gb.keys
-        var union = 0
-        for (g in keys) {
-            val ca = ga[g] ?: 0
-            val cb = gb[g] ?: 0
-            inter += minOf(ca, cb)
-            union += maxOf(ca, cb)
-        }
-        return if (union == 0) 0f else inter.toFloat() / union
-    }
-
-    private fun ngrams(cps: IntArray, n: Int): Map<Long, Int> {
-        if (cps.size < n) {
-            if (cps.isEmpty()) return emptyMap()
-            var h = 0L
-            for (cp in cps) h = h * 1_000_003L + cp
-            return mapOf(h to 1)
-        }
-        val out = HashMap<Long, Int>(cps.size)
-        for (i in 0..cps.size - n) {
-            var h = 0L
-            for (j in 0 until n) h = h * 1_000_003L + cps[i + j]
-            out[h] = (out[h] ?: 0) + 1
-        }
-        return out
-    }
-
-    private fun editDistanceCodePoints(a: IntArray, b: IntArray, max: Int): Int {
-        if (a.contentEquals(b)) return 0
-        if (kotlin.math.abs(a.size - b.size) > max) return max + 1
-        val m = b.size
-        var prev = IntArray(m + 1) { it }
-        var cur = IntArray(m + 1)
-        for (i in 1..a.size) {
-            cur[0] = i
-            var rowMin = i
-            val ca = a[i - 1]
-            for (j in 1..m) {
-                val cost = if (ca == b[j - 1]) 0 else 1
-                cur[j] = minOf(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
-                if (cur[j] < rowMin) rowMin = cur[j]
-            }
-            if (rowMin > max) return max + 1
-            val tmp = prev
-            prev = cur
-            cur = tmp
-        }
-        return prev[m]
-    }
-}
+// Moved to :core as `capital.yuri.yuriplayer.core.text.StringSimilarity`.
+// This typealias keeps any remaining in-app callers compiling.
+typealias StringSimilarity = capital.yuri.yuriplayer.core.text.StringSimilarity
diff --git a/app/src/main/java/capital/yuri/yuriplayer/data/theme/ThemeService.kt b/app/src/main/java/capital/yuri/yuriplayer/data/theme/ThemeService.kt
index eb33f7c9..aa0c00b7 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/data/theme/ThemeService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/data/theme/ThemeService.kt
@@ -4,7 +4,7 @@ import android.content.Context
 import android.graphics.Bitmap
 import android.graphics.BitmapFactory
 import android.net.Uri
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.compose.material3.ColorScheme
 import androidx.compose.ui.graphics.Color
 import androidx.compose.ui.graphics.luminance
@@ -191,7 +191,7 @@ class ThemeService(
             } ?: return null
             scaleTo(decoded, maxSize)
         } catch (e: Exception) {
-            Log.w(TAG, "uri decode failed $uri", e)
+            log.w(e) { "uri decode failed $uri" }
             null
         }
     }
@@ -218,7 +218,7 @@ class ThemeService(
     }
 
     companion object {
-        private const val TAG = "YuriPlayer.Theme"
+        private val log = yuriLog("Theme")
         private const val DISK_PREFS = "theme_color_cache"
         private const val DISK_ORDER = "__order"
         private const val MAX_DISK = 256
diff --git a/app/src/main/java/capital/yuri/yuriplayer/di/AppModule.kt b/app/src/main/java/capital/yuri/yuriplayer/di/AppModule.kt
index 6c3e11b4..1415f4c4 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/di/AppModule.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/di/AppModule.kt
@@ -19,7 +19,9 @@ import capital.yuri.yuriplayer.data.PlaylistRepository
 import capital.yuri.yuriplayer.data.ScanCheckpointStore
 import capital.yuri.yuriplayer.data.SecretCoverPrivacy
 import capital.yuri.yuriplayer.data.UserImageStore
+import capital.yuri.yuriplayer.data.androidCatalogRepository
 import capital.yuri.yuriplayer.data.db.YuriDatabase
+import capital.yuri.yuriplayer.data.db.createYuriDatabase
 import capital.yuri.yuriplayer.data.organize.LibraryOrganizeService
 import capital.yuri.yuriplayer.data.organize.OrganizeLayoutPrefs
 import capital.yuri.yuriplayer.data.source.ArtistInfoService
@@ -50,7 +52,9 @@ import capital.yuri.yuriplayer.data.source.WikidataArtistImageSource
 import capital.yuri.yuriplayer.data.storage.StorageRootRegistry
 import capital.yuri.yuriplayer.data.storage.StorageRoots
 import capital.yuri.yuriplayer.data.theme.ThemeService
+import capital.yuri.yuriplayer.core.network.NetworkMonitor
 import capital.yuri.yuriplayer.media.FfmpegService
+import capital.yuri.yuriplayer.network.AndroidNetworkMonitor
 import capital.yuri.yuriplayer.player.MusicServiceAutoPlay
 import capital.yuri.yuriplayer.player.PlaybackHistoryStore
 import capital.yuri.yuriplayer.player.PlaybackStateStore
@@ -60,6 +64,7 @@ import capital.yuri.yuriplayer.player.QueueManager
 import capital.yuri.yuriplayer.player.SourceColdSync
 import capital.yuri.yuriplayer.player.radio.RadioEngine
 import capital.yuri.yuriplayer.player.radio.RadioPlaybackAlgorithm
+import capital.yuri.yuriplayer.player.radio.ReleaseCatalog
 import capital.yuri.yuriplayer.player.radio.ReleasePoolAlgorithm
 import io.ktor.client.HttpClient
 import kotlinx.coroutines.CoroutineScope
@@ -85,7 +90,10 @@ val appModule = module {
     single { LibraryScanNotifier(androidContext()) }
     single { ScanCheckpointStore(androidContext()) }
 
-    single { YuriDatabase.create(androidContext()) }
+    // Cross-platform reachability signal (drives the "No internet" banner).
+    single<NetworkMonitor> { AndroidNetworkMonitor(androidContext()) }
+
+    single { createYuriDatabase(androidContext()) }
     single { get<YuriDatabase>().albumPrefs() }
     single { get<YuriDatabase>().albumMetadata() }
     single { get<YuriDatabase>().catalog() }
@@ -97,7 +105,7 @@ val appModule = module {
     single { get<YuriDatabase>().sources() }
     single { get<YuriDatabase>().scrobblers() }
 
-    single { CatalogRepository(get(), get(), get()) }
+    single { androidCatalogRepository(get(), get(), get()) }
     single {
         LibraryIndex(
             context = androidContext(),
@@ -147,6 +155,7 @@ val appModule = module {
     single { LibrarySourceRegistry(get()) }
 
     single { SourceResolver(get()) }
+
     single {
         ExploreSearchService(
             context = androidContext(),
@@ -241,8 +250,8 @@ val appModule = module {
     single { ReleasePoolAlgorithm() }
     single {
         RadioEngine(
-            library = get(),
-            settings = get(),
+            catalog = ReleaseCatalog { get<LibraryIndex>().albums(taggedOnly = true) },
+            autoPlayEnabled = { get<LibrarySettings>().isAutoPlayRecommendedEnabled() },
             playbackAlgo = get(),
             poolAlgo = get()
         )
diff --git a/app/src/main/java/capital/yuri/yuriplayer/media/FfmpegService.kt b/app/src/main/java/capital/yuri/yuriplayer/media/FfmpegService.kt
index ecfbf368..ee4d44f3 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/media/FfmpegService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/media/FfmpegService.kt
@@ -2,7 +2,7 @@ package capital.yuri.yuriplayer.media
 
 import android.content.Context
 import android.os.Build
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
@@ -73,7 +73,7 @@ class FfmpegService(private val context: Context) {
                 true
             }.getOrDefault(false)
             if (!copied) {
-                Log.w(TAG, "No FFmpeg asset for abi=$abi ($assetPath). Build native/ffmpeg first.")
+                log.w { "No FFmpeg asset for abi=$abi ($assetPath). Build native/ffmpeg first." }
                 return null
             }
         }
@@ -81,7 +81,7 @@ class FfmpegService(private val context: Context) {
         dest.setReadable(true, true)
         dest.setExecutable(true, true)
         if (!dest.canExecute()) {
-            Log.w(TAG, "FFmpeg binary not executable: $dest")
+            log.w { "FFmpeg binary not executable: $dest" }
             return null
         }
         binary = dest
@@ -103,19 +103,19 @@ class FfmpegService(private val context: Context) {
                 .redirectErrorStream(true)
                 .directory(context.cacheDir)
             val proc = pb.start()
-            val log = proc.inputStream.bufferedReader().use { it.readText() }
+            val output = proc.inputStream.bufferedReader().use { it.readText() }
             val code = proc.waitFor()
             if (code != 0) {
-                Log.w(TAG, "ffmpeg exit=$code\n$log")
+                log.w { "ffmpeg exit=$code\n$output" }
             }
             code == 0
         } catch (e: Exception) {
-            Log.w(TAG, "ffmpeg exec failed", e)
+            log.w(e) { "ffmpeg exec failed" }
             false
         }
     }
 
     companion object {
-        private const val TAG = "FfmpegService"
+        private val log = yuriLog("FfmpegService")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/network/AndroidNetworkMonitor.kt b/app/src/main/java/capital/yuri/yuriplayer/network/AndroidNetworkMonitor.kt
new file mode 100644
index 00000000..1dc16cb8
--- /dev/null
+++ b/app/src/main/java/capital/yuri/yuriplayer/network/AndroidNetworkMonitor.kt
@@ -0,0 +1,41 @@
+package capital.yuri.yuriplayer.network
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.Network
+import android.net.NetworkCapabilities
+import capital.yuri.yuriplayer.core.network.NetworkMonitor
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * Reflects the device's active network. "Online" = the active network has
+ * internet capability and is validated (Android reports this once it has
+ * connectivity, not merely when an interface is up).
+ */
+class AndroidNetworkMonitor(context: Context) : NetworkMonitor {
+    private val _isOnline = MutableStateFlow(true)
+    override val isOnline: StateFlow<Boolean> = _isOnline.asStateFlow()
+
+    private val cm =
+        context.applicationContext.getSystemService(Context.CONNECTIVITY_SERVICE) as ConnectivityManager
+
+    private val callback = object : ConnectivityManager.NetworkCallback() {
+        override fun onAvailable(network: Network) = refresh()
+        override fun onLost(network: Network) = refresh()
+        override fun onCapabilitiesChanged(network: Network, caps: NetworkCapabilities) = refresh()
+    }
+
+    init {
+        runCatching { cm.registerDefaultNetworkCallback(callback) }
+        refresh()
+    }
+
+    private fun refresh() {
+        val caps = runCatching { cm.getNetworkCapabilities(cm.activeNetwork) }.getOrNull()
+        _isOnline.value = caps != null &&
+            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_INTERNET) &&
+            caps.hasCapability(NetworkCapabilities.NET_CAPABILITY_VALIDATED)
+    }
+}
diff --git a/app/src/main/java/capital/yuri/yuriplayer/network/HttpModule.kt b/app/src/main/java/capital/yuri/yuriplayer/network/HttpModule.kt
index 021b6bc1..043674d4 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/network/HttpModule.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/network/HttpModule.kt
@@ -1,5 +1,6 @@
 package capital.yuri.yuriplayer.network
 
+import capital.yuri.yuriplayer.core.log.yuriLog
 import io.ktor.client.HttpClient
 import io.ktor.client.engine.cio.CIO
 import io.ktor.client.plugins.HttpTimeout
@@ -48,7 +49,7 @@ val httpModule = module {
             install(Logging) {
                 logger = object : Logger {
                     override fun log(message: String) {
-                        android.util.Log.d("Ktor", redactSecrets(omitBinaryDump(message)))
+                        yuriLog("Ktor").d { redactSecrets(omitBinaryDump(message)) }
                     }
                 }
                 // BODY so auth failures are diagnosable; secrets stripped in [redactSecrets].
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/ArtistRadio.kt b/app/src/main/java/capital/yuri/yuriplayer/player/ArtistRadio.kt
index 52afdd57..36bf5ef9 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/ArtistRadio.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/ArtistRadio.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.player
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.AlbumItem
 import capital.yuri.yuriplayer.data.LibraryIndex
 import capital.yuri.yuriplayer.data.Song
@@ -14,8 +14,7 @@ import kotlin.random.Random
  */
 object ArtistRadio {
 
-    private const val TAG = "YuriPlayer.Radio"
-
+    private val log = yuriLog("Radio")
     data class Pick(
         val album: AlbumItem,
         val source: ColdSource
@@ -29,7 +28,7 @@ object ArtistRadio {
     ): Pick? {
         val artistName = resolveArtistName(seedSong, finishedSource)
         if (artistName == null) {
-            Log.i(TAG, "no artist from seed=${seedSong?.displayTitle} source=$finishedSource")
+            log.i { "no artist from seed=${seedSong?.displayTitle} source=$finishedSource" }
             return null
         }
         val artistNorm = artistKey(artistName) ?: return null
@@ -42,21 +41,15 @@ object ArtistRadio {
         }
 
         if (candidates.isEmpty()) {
-            Log.i(
-                TAG,
-                "no candidates for artist='$artistName' (norm=$artistNorm) " +
-                    "exclude=$excludeAlbumKeys libraryAlbums=${library.albums(taggedOnly = true).size}"
-            )
+            log.i { "no candidates for artist='$artistName' (norm=$artistNorm) " +
+                    "exclude=$excludeAlbumKeys libraryAlbums=${library.albums(taggedOnly = true).size}" }
             return null
         }
 
         val pick = candidates[Random.nextInt(candidates.size)]
         val key = albumKey(pick.name, pick.artist)
-        Log.i(
-            TAG,
-            "picked '${pick.displayName}' by ${pick.displayArtist} " +
-                "(${pick.trackCount} tracks) from ${candidates.size} candidates"
-        )
+        log.i { "picked '${pick.displayName}' by ${pick.displayArtist} " +
+                "(${pick.trackCount} tracks) from ${candidates.size} candidates" }
         return Pick(
             album = pick,
             source = ColdSource(
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/MusicService.kt b/app/src/main/java/capital/yuri/yuriplayer/player/MusicService.kt
index 53940069..545d0ed8 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/MusicService.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/MusicService.kt
@@ -14,7 +14,7 @@ import android.os.Build
 import android.os.IBinder
 import android.os.PowerManager
 import android.os.SystemClock
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.core.app.NotificationCompat
 import capital.yuri.yuriplayer.activities.MainActivity
 import capital.yuri.yuriplayer.data.LibrarySettings
@@ -123,7 +123,7 @@ class MusicService : Service() {
             sessionActivity = openPlayerPendingIntent(),
             onPlay = {
                 if (SystemClock.elapsedRealtime() < ignoreSessionPlayUntilElapsed) {
-                    Log.i(TAG, "session onPlay ignored — startup")
+                    log.i { "session onPlay ignored — startup" }
                     return@MusicServiceEngineHooks
                 }
                 play()
@@ -141,20 +141,20 @@ class MusicService : Service() {
                 else if (!userWantsPlay) releaseSleepLocks()
             },
             onError = { message, recoverable ->
-                Log.e(TAG, "engine error: $message recoverable=$recoverable")
+                log.e { "engine error: $message recoverable=$recoverable" }
                 if (recoverable && userWantsPlay && !recoveringAudio && !advancing) {
                     recoverFromAudioGlitch()
                 }
             }
         )
 
-        Log.i(TAG, "engine=${engineHooks?.engineId}")
+        log.i { "engine=${engineHooks?.engineId}" }
         restorePlaybackState()
         startPeriodicPersist()
         startStallWatchdog()
         serviceScope.launch {
             librarySettings.streamQuality.drop(1).collect { q ->
-                Log.i(TAG, "stream quality → ${q.id} — rebuffer next")
+                log.i { "stream quality → ${q.id} — rebuffer next" }
                 syncPreparedNext()
             }
         }
@@ -197,7 +197,7 @@ class MusicService : Service() {
     private fun flushPendingRemoteRestore(autoPlay: Boolean): Boolean {
         val pending = pendingRemoteRestore ?: return false
         pendingRemoteRestore = null
-        Log.i(TAG, "flushPendingRemoteRestore pos=${pending.positionMs} autoPlay=$autoPlay")
+        log.i { "flushPendingRemoteRestore pos=${pending.positionMs} autoPlay=$autoPlay" }
         rebufferWindow(pending.positionMs, autoPlay = autoPlay, forceReload = true)
         return true
     }
@@ -206,7 +206,7 @@ class MusicService : Service() {
         val current = queueManager.currentSong() ?: return
         clearStickySeek()
         pendingRemoteRestore = null
-        Log.i(TAG, "hardRestartCurrent '${current.displayTitle}' pos=$startPositionMs")
+        log.i { "hardRestartCurrent '${current.displayTitle}' pos=$startPositionMs" }
         rebufferWindow(startPositionMs.coerceAtLeast(0L), autoPlay = autoPlay, forceReload = true)
     }
 
@@ -247,13 +247,10 @@ class MusicService : Service() {
             return
         }
 
-        Log.i(
-            TAG,
-            "rebufferWindow engine=${hooks.engineId} current='${current.displayTitle}' " +
+        log.i { "rebufferWindow engine=${hooks.engineId} current='${current.displayTitle}' " +
                 "peekNext='${if (repeatOne) "(repeat-one)" else nextSong?.displayTitle}' " +
                 "startMs=$startPositionMs autoPlay=$autoPlay force=$forceReload " +
-                "remote=${isRemoteSong(current)}"
-        )
+                "remote=${isRemoteSong(current)}" }
 
         try {
             windowGeneration += 1
@@ -274,7 +271,7 @@ class MusicService : Service() {
                 autoPlay = autoPlay
             )
         } catch (e: Exception) {
-            Log.e(TAG, "rebufferWindow failed", e)
+            log.e(e) { "rebufferWindow failed" }
         }
 
         _nowPlaying.value = current
@@ -284,11 +281,12 @@ class MusicService : Service() {
         syncPreparedNext()
     }
 
-    private fun maybeRecordHistory(song: Song) {
-        val key = song.path ?: song.contentUri.toString()
+    private fun maybeRecordHistory(song: Song?) {
+        val s = song ?: return
+        val key = s.path ?: s.contentUri
         if (key == lastHistoryKey) return
         lastHistoryKey = key
-        historyStore.record(song)
+        historyStore.record(s)
     }
 
     private fun applyAdvance(result: QueueManager.AdvanceResult, autoPlay: Boolean = true) {
@@ -319,7 +317,7 @@ class MusicService : Service() {
             }
             result.reload -> hardRestartCurrent(autoPlay = autoPlay)
             result.song != null -> {
-                val target = result.song
+                val target = result.song ?: return
                 _nowPlaying.value = target
                 maybeRecordHistory(target)
                 updateForegroundNotification()
@@ -342,8 +340,9 @@ class MusicService : Service() {
             result.seekToStart -> engineHooks?.seekTo(0L)
             result.reload -> hardRestartCurrent(autoPlay = true)
             result.song != null -> {
-                _nowPlaying.value = result.song
-                maybeRecordHistory(result.song)
+                val song = result.song ?: return
+                _nowPlaying.value = song
+                maybeRecordHistory(song)
                 syncPreparedNext()
             }
         }
@@ -361,7 +360,7 @@ class MusicService : Service() {
         }
         val upcoming = queueManager.upcoming(WARM_AHEAD)
         val next = upcoming.firstOrNull()
-        Log.i(TAG, "syncPreparedNext '${next?.displayTitle}' warm=${upcoming.size}")
+        log.i { "syncPreparedNext '${next?.displayTitle}' warm=${upcoming.size}" }
         hooks.setNext(next)
         warmUpcoming(upcoming)
     }
@@ -406,7 +405,7 @@ class MusicService : Service() {
         val now = SystemClock.elapsedRealtime()
         if (now < ignoreAutoAdvancedUntilElapsed) {
             ignoreAutoAdvancedUntilElapsed = 0L
-            Log.i(TAG, "autoAdvanced ignored — queue already moved")
+            log.i { "autoAdvanced ignored — queue already moved" }
             return
         }
         if (advancing) return
@@ -414,7 +413,7 @@ class MusicService : Service() {
         advancing = true
         try {
             val result = queueManager.advance(userInitiated = false)
-            Log.i(TAG, "autoAdvanced → '${result.song?.displayTitle}'")
+            log.i { "autoAdvanced → '${result.song?.displayTitle}'" }
             applyAdvanceKeepEngine(result)
         } finally {
             advancing = false
@@ -432,10 +431,7 @@ class MusicService : Service() {
         val preparedId = hooks.preparedNextId()
         val expectedId = expected.toPlaybackMedia(quality = librarySettings.getStreamQuality()).mediaId
         if (preparedId == null || preparedId != expectedId) {
-            Log.i(
-                TAG,
-                "skip prepared mismatch want='${expected.displayTitle}' have=$preparedId"
-            )
+            log.i { "skip prepared mismatch want='${expected.displayTitle}' have=$preparedId" }
             syncPreparedNext()
             return false
         }
@@ -460,7 +456,7 @@ class MusicService : Service() {
         if (inUserSeekGuard()) {
             val target = stickySeekTargetMs.takeIf { it >= 0L }
                 ?: engineHooks?.getPositionMs() ?: 0L
-            Log.i(TAG, "ENDED suppressed after user seek → reseek $target")
+            log.i { "ENDED suppressed after user seek → reseek $target" }
             rebufferWindow(target, autoPlay = true, forceReload = true)
             return
         }
@@ -474,7 +470,7 @@ class MusicService : Service() {
         advancing = true
         try {
             if (advanceUsingPreparedNext(userInitiated = false)) {
-                Log.i(TAG, "onEnded → playPreparedNext")
+                log.i { "onEnded → playPreparedNext" }
                 return
             }
             if (!claimEndOfWindow(fromUser = false)) return
@@ -688,9 +684,9 @@ class MusicService : Service() {
         try {
             hooks.seekTo(target)
             if (hooks.getPlayWhenReady() && !hooks.isPlaying()) hooks.play()
-            Log.i(TAG, "seekTo target=$target (raw=$positionMs) duration=$duration")
+            log.i { "seekTo target=$target (raw=$positionMs) duration=$duration" }
         } catch (e: Exception) {
-            Log.w(TAG, "seekTo failed", e)
+            log.w(e) { "seekTo failed" }
             clearStickySeek()
         }
         persistState()
@@ -735,10 +731,7 @@ class MusicService : Service() {
                         positionMs = saved.positionMs,
                         wasPlayWhenReady = false
                     )
-                    Log.i(
-                        TAG,
-                        "restore deferred remote '${current?.displayTitle}' pos=${saved.positionMs}"
-                    )
+                    log.i { "restore deferred remote '${current?.displayTitle}' pos=${saved.positionMs}" }
                 } else {
                     delay(RESTORE_PREPARE_DELAY_MS)
                     rebufferWindow(
@@ -756,7 +749,7 @@ class MusicService : Service() {
                 ignoreSessionPlayUntilElapsed =
                     SystemClock.elapsedRealtime() + STARTUP_IGNORE_SESSION_PLAY_MS
                 engineHooks?.setSessionActive(true)
-                Log.i(TAG, "restore complete — paused until user plays")
+                log.i { "restore complete — paused until user plays" }
             }
         }
     }
@@ -830,11 +823,8 @@ class MusicService : Service() {
                 if (nearEnd && userWantsPlay && frozenFor >= NEAR_END_ADVANCE_MS &&
                     (wantPlay || buffering)
                 ) {
-                    Log.i(
-                        TAG,
-                        "near-end freeze ${frozenFor}ms pos=$pos/$duration " +
-                            "playing=$playing buffering=$buffering wantPlay=$wantPlay → onEnded"
-                    )
+                    log.i { "near-end freeze ${frozenFor}ms pos=$pos/$duration " +
+                            "playing=$playing buffering=$buffering wantPlay=$wantPlay → onEnded" }
                     onEngineEnded()
                     stallSamplePos = -1L
                     continue
@@ -845,7 +835,7 @@ class MusicService : Service() {
                 if (wantPlay && !playing && !buffering && pos > 1_000L &&
                     frozenFor >= ENDED_SILENCE_MS && remaining <= 5_000L
                 ) {
-                    Log.i(TAG, "silent near end ${frozenFor}ms pos=$pos/$duration → onEnded")
+                    log.i { "silent near end ${frozenFor}ms pos=$pos/$duration → onEnded" }
                     onEngineEnded()
                     stallSamplePos = -1L
                     continue
@@ -858,7 +848,7 @@ class MusicService : Service() {
                     if (userWantsPlay && !playing && !buffering && !inCall &&
                         frozenFor >= UNEXPECTED_PAUSE_MS && !nearEnd
                     ) {
-                        Log.i(TAG, "unexpected pause ${frozenFor}ms pos=$pos — resume")
+                        log.i { "unexpected pause ${frozenFor}ms pos=$pos — resume" }
                         acquireSleepLocks()
                         hooks.play()
                     }
@@ -870,17 +860,14 @@ class MusicService : Service() {
                 val threshold = if (remote) NETWORK_STALL_MS else STALL_MS
 
                 if (userWantsPlay && !playing && !isInCall() && frozenFor >= UNEXPECTED_PAUSE_MS) {
-                    Log.i(TAG, "unexpected pause ${frozenFor}ms pos=$pos — resume")
+                    log.i { "unexpected pause ${frozenFor}ms pos=$pos — resume" }
                     acquireSleepLocks()
                     hooks.play()
                     continue
                 }
 
                 if (frozenFor >= threshold) {
-                    Log.w(
-                        TAG,
-                        "stall watchdog: pos frozen at $pos for ${frozenFor}ms remote=$remote — recovering"
-                    )
+                    log.w { "stall watchdog: pos frozen at $pos for ${frozenFor}ms remote=$remote — recovering" }
                     recoverFromAudioGlitch(atPositionMs = pos)
                 }
             }
@@ -925,7 +912,7 @@ class MusicService : Service() {
                 }
             if (!lock.isHeld) lock.acquire()
         } catch (e: Exception) {
-            Log.w(TAG, "wakeLock", e)
+            log.w(e) { "wakeLock" }
         }
         if (!isRemoteSong(_nowPlaying.value)) return
         try {
@@ -938,7 +925,7 @@ class MusicService : Service() {
                 }
             if (!lock.isHeld) lock.acquire()
         } catch (e: Exception) {
-            Log.w(TAG, "wifiLock", e)
+            log.w(e) { "wifiLock" }
         }
     }
 
@@ -946,12 +933,12 @@ class MusicService : Service() {
         try {
             if (wakeLock?.isHeld == true) wakeLock?.release()
         } catch (e: Exception) {
-            Log.w(TAG, "wakeLock release", e)
+            log.w(e) { "wakeLock release" }
         }
         try {
             if (wifiLock?.isHeld == true) wifiLock?.release()
         } catch (e: Exception) {
-            Log.w(TAG, "wifiLock release", e)
+            log.w(e) { "wifiLock release" }
         }
     }
 
@@ -965,7 +952,7 @@ class MusicService : Service() {
                 val wasPlaying = userWantsPlay ||
                     hooks?.getPlayWhenReady() == true ||
                     hooks?.isPlaying() == true
-                Log.w(TAG, "audio glitch → rebuffer at $pos autoPlay=$wasPlaying")
+                log.w { "audio glitch → rebuffer at $pos autoPlay=$wasPlaying" }
                 rebufferWindow(pos, autoPlay = wasPlaying, forceReload = true)
             } finally {
                 delay(600)
@@ -1071,7 +1058,7 @@ class MusicService : Service() {
                         .setShowActionsInCompactView(0, 1, 2)
                 )
             } catch (e: Throwable) {
-                Log.d(TAG, "MediaStyle skipped: ${e.message}")
+                log.d { "MediaStyle skipped: ${e.message}" }
             }
         }
         return builder.build()
@@ -1118,7 +1105,7 @@ class MusicService : Service() {
     }
 
     override fun onTaskRemoved(rootIntent: Intent?) {
-        Log.i(TAG, "onTaskRemoved — stopping playback")
+        log.i { "onTaskRemoved — stopping playback" }
         stopForAppClosed()
         super.onTaskRemoved(rootIntent)
     }
@@ -1134,7 +1121,7 @@ class MusicService : Service() {
         try {
             stateStore.save(snap, pos, playWhenReady = false)
         } catch (e: Exception) {
-            Log.w(TAG, "persist on close", e)
+            log.w(e) { "persist on close" }
         }
         if (historyStore.clearOnClose) {
             historyStore.clear()
@@ -1156,7 +1143,7 @@ class MusicService : Service() {
     }
 
     companion object {
-        private const val TAG = "YuriPlayer"
+        private val log = yuriLog("MusicService")
         const val CHANNEL_ID = "yuri_playback"
         const val NOTIFICATION_ID = 42
         const val ACTION_PLAY = "capital.yuri.yuriplayer.action.PLAY"
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt b/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt
index ed526c45..42cf923f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt
@@ -1,64 +1,3 @@
 package capital.yuri.yuriplayer.player
 
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.player.radio.RadioBatch
-import capital.yuri.yuriplayer.player.radio.RadioEngine
-import capital.yuri.yuriplayer.player.radio.RadioSession
-
-/**
- * Thin adapter: [QueueManager] ↔ [RadioEngine].
- * Exhaust path loads a full [RadioBatch] into cold queue.
- * Restock keeps cold topped up while radio is active.
- */
-class MusicServiceAutoPlay(
-    private val engine: RadioEngine
-) {
-    val radioEngine: RadioEngine get() = engine
-
-    fun noteSource(source: ColdSource?) {
-        engine.noteSource(source)
-    }
-
-    fun maybePick(
-        seedSong: Song?,
-        finishedSource: ColdSource?,
-        repeatMode: RepeatMode
-    ): LegacyPick? {
-        val batch: RadioBatch = engine.maybePlan(seedSong, finishedSource, repeatMode)
-            ?: return null
-        return LegacyPick(
-            songs = batch.songs,
-            source = batch.source,
-            session = batch.session,
-            upcoming = emptyList()
-        )
-    }
-
-    /**
-     * Top-up songs for the active radio session.
-     * If the engine lost its in-memory session (process restore) but the queue
-     * still has an active [queueSession], rehydrate first so restock can run.
-     */
-    fun restock(
-        currentColdSize: Int,
-        alreadyQueuedKeys: Set<String>,
-        queueSession: RadioSession? = null
-    ): List<Song> {
-        val live = queueSession?.takeIf { it.active }
-        if (live != null && engine.session?.active != true) {
-            engine.adoptSession(live)
-        }
-        return engine.restockSongs(currentColdSize, alreadyQueuedKeys)
-    }
-
-    fun currentSession(): RadioSession? = engine.session
-
-    fun stopRadio() = engine.stopRadio()
-
-    data class LegacyPick(
-        val songs: List<Song>,
-        val source: ColdSource,
-        val session: RadioSession? = null,
-        val upcoming: List<Song> = emptyList()
-    )
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceEngineHooks.kt b/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceEngineHooks.kt
index 308a993c..d88a7d78 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceEngineHooks.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceEngineHooks.kt
@@ -2,7 +2,7 @@ package capital.yuri.yuriplayer.player
 
 import android.app.PendingIntent
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.LibrarySettings
 import capital.yuri.yuriplayer.data.Song
 
@@ -51,7 +51,7 @@ internal class MusicServiceEngineHooks(
     fun playWindow(song: Song, next: Song?, startPositionMs: Long, autoPlay: Boolean) {
         active = true
         host.playWindow(song, next, startPositionMs, autoPlay)
-        Log.i(TAG, "window via ${host.engineId} '${song.displayTitle}' next=${next?.displayTitle}")
+        log.i { "window via ${host.engineId} '${song.displayTitle}' next=${next?.displayTitle}" }
     }
 
     fun setNext(song: Song?) {
@@ -115,6 +115,6 @@ internal class MusicServiceEngineHooks(
     }
 
     companion object {
-        private const val TAG = "EngineHooks"
+        private val log = yuriLog("EngineHooks")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceLocalEngine.kt b/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceLocalEngine.kt
index c47c4c3c..be087cdb 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceLocalEngine.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/MusicServiceLocalEngine.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.player
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.LibrarySettings
 import capital.yuri.yuriplayer.data.Song
 import capital.yuri.yuriplayer.player.engine.AudioPipeline
@@ -54,14 +54,14 @@ class MusicServiceLocalEngine(
         override fun onIsPlayingChanged(playing: Boolean) = playingChanged(playing)
 
         override fun onError(message: String, recoverable: Boolean) {
-            Log.e(TAG, "engine($engineId) error: $message recoverable=$recoverable")
+            log.e { "engine($engineId) error: $message recoverable=$recoverable" }
             onEngineError(message, recoverable)
         }
     }
 
     init {
         engine.addListener(listener)
-        Log.i(TAG, "active engine=$engineId")
+        log.i { "active engine=$engineId" }
     }
 
     /**
@@ -78,13 +78,10 @@ class MusicServiceLocalEngine(
             quality = quality.id,
             uri = current.uri.toString()
         )
-        Log.i(
-            TAG,
-            "load engine=$engineId '${song.displayTitle}' " +
+        log.i { "load engine=$engineId '${song.displayTitle}' " +
                 "uri=${current.uri} scheme=${current.uri.scheme} quality=${quality.id} " +
                 "mime=${song.mimeType} live=${current.live} autoPlay=$autoPlay pos=$startPositionMs " +
-                "successor=${successor?.title}"
-        )
+                "successor=${successor?.title}" }
         engine.setPlayWhenReady(autoPlay)
         engine.load(current, successor, startPositionMs)
         if (autoPlay) engine.play()
@@ -125,6 +122,6 @@ class MusicServiceLocalEngine(
     }
 
     companion object {
-        private const val TAG = "SelectedEngine"
+        private val log = yuriLog("SelectedEngine")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackHistoryStore.kt b/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackHistoryStore.kt
index 86da6d42..4f2f7a2e 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackHistoryStore.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackHistoryStore.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.player
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.Song
 import capital.yuri.yuriplayer.data.json.AppJson
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -63,7 +63,7 @@ class PlaybackHistoryStore(context: Context) {
         while (current.size > maxEntries) current.removeAt(current.lastIndex)
         _entries.value = current
         persist()
-        Log.d(TAG, "record '${song.displayTitle}' size=${current.size}")
+        log.d { "record '${song.displayTitle}' size=${current.size}" }
     }
 
     fun clear() {
@@ -72,7 +72,7 @@ class PlaybackHistoryStore(context: Context) {
             if (file.exists()) file.delete()
         } catch (_: Exception) {
         }
-        Log.i(TAG, "history cleared")
+        log.i { "history cleared" }
     }
 
     private fun trimToMax() {
@@ -96,7 +96,7 @@ class PlaybackHistoryStore(context: Context) {
                 tmp.delete()
             }
         } catch (e: Exception) {
-            Log.w(TAG, "persist failed", e)
+            log.w(e) { "persist failed" }
         }
     }
 
@@ -106,7 +106,7 @@ class PlaybackHistoryStore(context: Context) {
             val dto = json.decodeFromString(HistoryFileDto.serializer(), file.readText())
             dto.entries.take(maxEntries)
         } catch (e: Exception) {
-            Log.w(TAG, "load failed", e)
+            log.w(e) { "load failed" }
             emptyList()
         }
     }
@@ -117,7 +117,7 @@ class PlaybackHistoryStore(context: Context) {
     }
 
     companion object {
-        private const val TAG = "YuriPlayer.History"
+        private val log = yuriLog("History")
         private const val FILE_NAME = "playback_history.json"
         private const val PREFS = "yuri_history_prefs"
         private const val KEY_MAX = "max_entries"
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackStateStore.kt b/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackStateStore.kt
index 94743f55..431ab46d 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackStateStore.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/PlaybackStateStore.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.player
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.Song
 import capital.yuri.yuriplayer.data.json.AppJson
 import kotlinx.serialization.Serializable
@@ -44,7 +44,7 @@ class PlaybackStateStore(context: Context) {
                 tmp.delete()
             }
         } catch (e: Exception) {
-            Log.w(TAG, "Failed to save playback state", e)
+            log.w(e) { "Failed to save playback state" }
         }
     }
 
@@ -81,7 +81,7 @@ class PlaybackStateStore(context: Context) {
                 playWhenReady = dto.playWhenReady
             )
         } catch (e: Exception) {
-            Log.w(TAG, "Failed to load playback state", e)
+            log.w(e) { "Failed to load playback state" }
             null
         }
     }
@@ -121,7 +121,7 @@ class PlaybackStateStore(context: Context) {
     )
 
     companion object {
-        private const val TAG = "PlaybackStateStore"
+        private val log = yuriLog("PlaybackStateStore")
         private const val FILE_NAME = "playback_state.json"
         /** v4: playedStack for Previous across restarts. */
         private const val VERSION = 4
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/PlayerController.kt b/app/src/main/java/capital/yuri/yuriplayer/player/PlayerController.kt
index 38ba410d..19ef10b3 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/PlayerController.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/PlayerController.kt
@@ -5,7 +5,7 @@ import android.content.Context
 import android.content.Intent
 import android.content.ServiceConnection
 import android.os.IBinder
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.core.content.ContextCompat
 import capital.yuri.yuriplayer.data.AlbumItem
 import capital.yuri.yuriplayer.data.Song
@@ -79,7 +79,7 @@ class PlayerController(
             try {
                 pending?.invoke()
             } catch (e: Exception) {
-                Log.e(TAG, "pending action failed", e)
+                log.e(e) { "pending action failed" }
             }
         }
 
@@ -139,7 +139,7 @@ class PlayerController(
         if (s != null) {
             action(s)
         } else {
-            Log.i(TAG, "service not bound yet — queueing action")
+            log.i { "service not bound yet — queueing action" }
             pendingAction = { service?.let(action) }
         }
     }
@@ -327,6 +327,6 @@ class PlayerController(
     }
 
     companion object {
-        private const val TAG = "YuriPlayer.Ctrl"
+        private val log = yuriLog("Ctrl")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/QueueEventBridge.kt b/app/src/main/java/capital/yuri/yuriplayer/player/QueueEventBridge.kt
index 98acf0bd..e4c6d513 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/QueueEventBridge.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/QueueEventBridge.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.player
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.SupervisorJob
@@ -23,15 +23,12 @@ class QueueEventBridge(
                 when (event) {
                     is QueueEvent.SourceChanged -> {
                         autoPlay.noteSource(event.source)
-                        Log.d(TAG, "SourceChanged ${event.source}")
+                        log.d { "SourceChanged ${event.source}" }
                     }
                     is QueueEvent.Exhausted -> {
-                        Log.i(
-                            TAG,
-                            "Exhausted seed=${event.seed?.displayTitle} " +
+                        log.i { "Exhausted seed=${event.seed?.displayTitle} " +
                                 "source=${event.source} repeat=${event.repeatMode} " +
-                                "(MusicService starts auto-play if enabled)"
-                        )
+                                "(MusicService starts auto-play if enabled)" }
                     }
                     is QueueEvent.RepeatModeChanged,
                     is QueueEvent.ShuffleChanged -> Unit
@@ -41,6 +38,6 @@ class QueueEventBridge(
     }
 
     companion object {
-        private const val TAG = "YuriPlayer.QueueEvents"
+        private val log = yuriLog("QueueEvents")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/QueueEvents.kt b/app/src/main/java/capital/yuri/yuriplayer/player/QueueEvents.kt
index b2b76430..42cf923f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/QueueEvents.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/QueueEvents.kt
@@ -1,28 +1,3 @@
 package capital.yuri.yuriplayer.player
 
-import capital.yuri.yuriplayer.data.Song
-
-/**
- * Discrete queue moments — not continuous UI state (that stays on [QueueManager.snapshot]).
- *
- * Collectors: auto-play, (later) scrobblers, analytics, multi-device sync.
- */
-sealed interface QueueEvent {
-    /** Cold+hot empty, repeat off / no repopulate. Opportunity for radio / auto-play. */
-    data class Exhausted(
-        val seed: Song?,
-        val source: ColdSource?,
-        val repeatMode: RepeatMode
-    ) : QueueEvent
-
-    /** A new cold source was loaded via [QueueManager.playSource]. */
-    data class SourceChanged(
-        val source: ColdSource?,
-        val songCount: Int,
-        val startSong: Song?
-    ) : QueueEvent
-
-    data class RepeatModeChanged(val mode: RepeatMode) : QueueEvent
-
-    data class ShuffleChanged(val enabled: Boolean) : QueueEvent
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/QueueManager.kt b/app/src/main/java/capital/yuri/yuriplayer/player/QueueManager.kt
index 48183b4d..42cf923f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/QueueManager.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/QueueManager.kt
@@ -1,938 +1,3 @@
 package capital.yuri.yuriplayer.player
 
-import android.util.Log
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.player.radio.RadioSession
-import capital.yuri.yuriplayer.player.radio.RadioSourcePrefs
-import kotlinx.coroutines.channels.BufferOverflow
-import kotlinx.coroutines.flow.MutableSharedFlow
-import kotlinx.coroutines.flow.MutableStateFlow
-import kotlinx.coroutines.flow.SharedFlow
-import kotlinx.coroutines.flow.StateFlow
-import kotlinx.coroutines.flow.asSharedFlow
-import kotlinx.coroutines.flow.asStateFlow
-import kotlin.random.Random
-
-/**
- * Dual-queue + optional radio session.
- *
- * While radio is active, [ensureRadioStock] continuously tops the cold queue:
- *   shuffle songs → random tracks until maxRadioQueue
- *   shuffle releases / ordered → next whole release while under max
- * Called after advance, radio start, cold remove, and prefs apply.
- */
-class QueueManager {
-
-    private val hotQueue = mutableListOf<Song>()
-    private var coldOriginal: List<Song> = emptyList()
-    private val coldQueue = mutableListOf<Song>()
-    private var coldSource: ColdSource? = null
-    private var lane = QueueLane.COLD
-    private var indexInLane = -1
-    private var shuffleEnabled = false
-    private var repeatMode = RepeatMode.OFF
-    private var floatingCurrent: Song? = null
-    private val playedStack = mutableListOf<Song>()
-
-    private var radioSession: RadioSession? = null
-    private var radioUpcoming: List<Song> = emptyList()
-
-    private val _snapshot = MutableStateFlow(QueueSnapshot())
-    val snapshot: StateFlow<QueueSnapshot> = _snapshot.asStateFlow()
-
-    private val _events = MutableSharedFlow<QueueEvent>(
-        extraBufferCapacity = 32,
-        onBufferOverflow = BufferOverflow.DROP_OLDEST
-    )
-    val events: SharedFlow<QueueEvent> = _events.asSharedFlow()
-
-    @Volatile
-    var autoPlayHelper: MusicServiceAutoPlay? = null
-
-    private fun emit(event: QueueEvent) {
-        _events.tryEmit(event)
-    }
-
-    fun currentSong(): Song? {
-        floatingCurrent?.let { return it }
-        return when (lane) {
-            QueueLane.HOT -> hotQueue.getOrNull(indexInLane)
-            QueueLane.COLD -> coldQueue.getOrNull(indexInLane)
-        }
-    }
-
-    fun getSnapshot(): QueueSnapshot = _snapshot.value
-    fun coldSource(): ColdSource? = coldSource
-    fun isRadioActive(): Boolean = radioSession?.active == true
-
-    fun setRadioSession(session: RadioSession?) {
-        radioSession = session
-        if (session != null) {
-            shuffleEnabled = session.prefs.shuffle
-            if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
-            // Keep engine session in sync for restock
-            autoPlayHelper?.radioEngine?.adoptSession(session)
-        }
-        publish()
-        if (session?.active == true) ensureRadioStock()
-    }
-
-    fun setRadioUpcoming(songs: List<Song>) {
-        radioUpcoming = songs
-        publish()
-    }
-
-    fun clearRadio() {
-        radioSession = null
-        radioUpcoming = emptyList()
-        autoPlayHelper?.stopRadio()
-        publish()
-    }
-
-    fun peekNext(): Song? {
-        if (repeatMode == RepeatMode.ONE) return null
-        if (floatingCurrent != null) {
-            if (hotQueue.isNotEmpty()) return hotQueue.first()
-            if (coldQueue.isNotEmpty()) return coldQueue.first()
-            if (radioUpcoming.isNotEmpty()) return radioUpcoming.first()
-            if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty()) {
-                return if (shuffleEnabled) coldOriginal.random() else coldOriginal.first()
-            }
-            return null
-        }
-        when (lane) {
-            QueueLane.HOT -> {
-                if (indexInLane in hotQueue.indices && indexInLane < hotQueue.lastIndex) {
-                    return hotQueue[indexInLane + 1]
-                }
-                if (coldQueue.isNotEmpty()) return coldQueue.first()
-                if (radioUpcoming.isNotEmpty()) return radioUpcoming.first()
-                if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty()) {
-                    return if (shuffleEnabled) coldOriginal.random() else coldOriginal.first()
-                }
-                return null
-            }
-            QueueLane.COLD -> {
-                if (hotQueue.isNotEmpty()) return hotQueue.first()
-                if (indexInLane in coldQueue.indices && indexInLane < coldQueue.lastIndex) {
-                    return coldQueue[indexInLane + 1]
-                }
-                if (radioUpcoming.isNotEmpty()) return radioUpcoming.first()
-                if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty()) {
-                    return if (shuffleEnabled) coldOriginal.random() else coldOriginal.first()
-                }
-                return null
-            }
-        }
-    }
-
-    fun peekPrevious(): Song? {
-        linearPrevious()?.let { return it }
-        return playedStack.lastOrNull()
-    }
-
-    /** Previous item still sitting in the queue (unshuffled album/playlist). */
-    private fun linearPrevious(): Song? {
-        if (shuffleEnabled || floatingCurrent != null) return null
-        return when (lane) {
-            QueueLane.HOT -> hotQueue.getOrNull(indexInLane - 1)
-            QueueLane.COLD -> coldQueue.getOrNull(indexInLane - 1)
-        }
-    }
-
-    /** Next [limit] songs after current, hot then cold then radio. */
-    fun upcoming(limit: Int = 2): List<Song> {
-        if (limit <= 0 || repeatMode == RepeatMode.ONE) return emptyList()
-        val out = ArrayList<Song>(limit)
-        fun take(song: Song?) {
-            if (song == null || out.size >= limit) return
-            if (out.any { it.songKey == song.songKey }) return
-            out += song
-        }
-        if (floatingCurrent != null) {
-            hotQueue.forEach { take(it) }
-            if (out.size >= limit) return out
-            coldQueue.forEach { take(it) }
-            if (out.size >= limit) return out
-            radioUpcoming.forEach { take(it) }
-            return out
-        }
-        when (lane) {
-            QueueLane.HOT -> {
-                if (indexInLane in hotQueue.indices) {
-                    for (i in (indexInLane + 1) until hotQueue.size) {
-                        take(hotQueue[i])
-                        if (out.size >= limit) return out
-                    }
-                }
-                coldQueue.forEach { take(it) }
-                if (out.size >= limit) return out
-                radioUpcoming.forEach { take(it) }
-            }
-            QueueLane.COLD -> {
-                hotQueue.forEach { take(it) }
-                if (out.size >= limit) return out
-                if (indexInLane in coldQueue.indices) {
-                    for (i in (indexInLane + 1) until coldQueue.size) {
-                        take(coldQueue[i])
-                        if (out.size >= limit) return out
-                    }
-                }
-                radioUpcoming.forEach { take(it) }
-            }
-        }
-        return out
-    }
-
-    private fun publish() {
-        _snapshot.value = QueueSnapshot(
-            hotQueue = hotQueue.toList(),
-            coldQueue = coldQueue.toList(),
-            coldOriginal = coldOriginal,
-            coldSource = coldSource,
-            lane = lane,
-            indexInLane = indexInLane,
-            shuffleEnabled = shuffleEnabled,
-            repeatMode = repeatMode,
-            playedStack = playedStack.toList(),
-            radioSession = radioSession,
-            radioUpcoming = radioUpcoming,
-            floatingCurrent = floatingCurrent
-        )
-    }
-
-    /** Hot-lane mutations: don't copy the (often huge) cold lists. */
-    private fun publishHot() {
-        _snapshot.value = _snapshot.value.copy(
-            hotQueue = hotQueue.toList(),
-            lane = lane,
-            indexInLane = indexInLane,
-            floatingCurrent = floatingCurrent
-        )
-    }
-
-    /** Repeat flag only — leave song lists shared. */
-    private fun publishRepeat() {
-        _snapshot.value = _snapshot.value.copy(repeatMode = repeatMode)
-    }
-
-    private fun pushPlayed(song: Song) {
-        if (playedStack.lastOrNull()?.let { sameSong(it, song) } == true) return
-        playedStack.add(song)
-        while (playedStack.size > MAX_PLAYED_STACK) {
-            playedStack.removeAt(0)
-        }
-    }
-
-    private fun detachCurrentWithoutHistory() {
-        if (floatingCurrent != null) {
-            floatingCurrent = null
-            return
-        }
-        when (lane) {
-            QueueLane.HOT -> {
-                if (indexInLane in hotQueue.indices) hotQueue.removeAt(indexInLane)
-            }
-            QueueLane.COLD -> {
-                if (indexInLane in coldQueue.indices) coldQueue.removeAt(indexInLane)
-            }
-        }
-        indexInLane = -1
-    }
-
-    private fun tryAutoPlayRescue(seed: Song?, source: ColdSource?): AdvanceResult? {
-        val helper = autoPlayHelper ?: return null
-        val pick = helper.maybePick(seed, source, repeatMode) ?: return null
-        val songs = pick.songs
-        if (songs.isEmpty()) return null
-        Log.i(TAG, "radio/auto-play rescue → ${songs.size} tracks (${pick.source.title})")
-        if (pick.session != null) {
-            radioSession = pick.session
-            shuffleEnabled = pick.session.prefs.shuffle
-            if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
-        }
-        radioUpcoming = pick.upcoming
-        playSource(songs, startIndex = 0, source = pick.source, keepRadio = true)
-        ensureRadioStock()
-        val next = currentSong() ?: return null
-        return AdvanceResult(song = next)
-    }
-
-    /**
-     * Continuously top up cold while radio is active.
-     * Safe to call often — no-ops when already at/above target or pool empty.
-     */
-    fun ensureRadioStock() {
-        val sess = radioSession?.takeIf { it.active } ?: return
-        val helper = autoPlayHelper ?: return
-        val keys = buildSet {
-            coldQueue.forEach { add(songKey(it)) }
-            currentSong()?.let { add(songKey(it)) }
-            floatingCurrent?.let { add(songKey(it)) }
-            playedStack.takeLast(80).forEach { add(songKey(it)) }
-        }
-        // coldQueue includes the currently playing track when lane is COLD
-        val add = helper.restock(
-            currentColdSize = coldQueue.size,
-            alreadyQueuedKeys = keys,
-            queueSession = sess
-        )
-        if (add.isEmpty()) return
-        coldQueue.addAll(add)
-        coldOriginal = coldOriginal + add
-        Log.i(
-            TAG,
-            "radio stock +${add.size} cold=${coldQueue.size} " +
-                "shuffle=${sess.prefs.shuffle} unit=${sess.prefs.shuffleUnit}"
-        )
-        publish()
-    }
-
-    fun restore(snap: QueueSnapshot) {
-        hotQueue.clear()
-        hotQueue.addAll(snap.hotQueue)
-        coldOriginal = snap.coldOriginal.ifEmpty { snap.coldQueue }
-        coldQueue.clear()
-        coldQueue.addAll(snap.coldQueue)
-        coldSource = snap.coldSource
-        lane = snap.lane
-        indexInLane = snap.indexInLane
-        shuffleEnabled = snap.shuffleEnabled
-        repeatMode = snap.repeatMode
-        floatingCurrent = snap.floatingCurrent
-        playedStack.clear()
-        playedStack.addAll(snap.playedStack)
-        radioSession = snap.radioSession
-        radioUpcoming = snap.radioUpcoming
-        if (radioSession?.active == true && repeatMode == RepeatMode.COLD) {
-            repeatMode = RepeatMode.OFF
-        }
-        val max = when (lane) {
-            QueueLane.HOT -> hotQueue.lastIndex
-            QueueLane.COLD -> coldQueue.lastIndex
-        }
-        if (max >= 0) indexInLane = indexInLane.coerceIn(0, max)
-        // Rehydrate engine so restock works after process restore
-        radioSession?.takeIf { it.active }?.let { autoPlayHelper?.radioEngine?.adoptSession(it) }
-        publish()
-        if (radioSession?.active == true) ensureRadioStock()
-    }
-
-    fun playSource(
-        songs: List<Song>,
-        startIndex: Int = 0,
-        source: ColdSource? = null,
-        keepRadio: Boolean = false
-    ) {
-        if (songs.isEmpty()) return
-        Log.i(TAG, "playSource size=${songs.size} start=$startIndex source=$source keepRadio=$keepRadio")
-        floatingCurrent = null
-        playedStack.clear()
-        coldSource = source
-
-        if (!keepRadio && source?.type != ColdSourceType.RADIO) {
-            radioSession = null
-            radioUpcoming = emptyList()
-            autoPlayHelper?.stopRadio()
-        }
-
-        coldOriginal = songs.toList()
-        coldQueue.clear()
-
-        val isRadio = source?.type == ColdSourceType.RADIO || keepRadio || radioSession?.active == true
-        if (!isRadio && shuffleEnabled) {
-            coldQueue.addAll(songs.shuffled(Random(System.nanoTime())))
-            val tapped = songs.getOrNull(startIndex)
-            if (tapped != null) {
-                coldQueue.removeAll { sameSong(it, tapped) }
-                coldQueue.add(0, tapped)
-            }
-            indexInLane = 0
-        } else {
-            coldQueue.addAll(songs)
-            indexInLane = startIndex.coerceIn(0, coldQueue.lastIndex)
-            if (indexInLane > 0) {
-                for (i in 0 until indexInLane) {
-                    pushPlayed(coldQueue[i])
-                }
-                repeat(indexInLane) { coldQueue.removeAt(0) }
-                indexInLane = 0
-            }
-        }
-        lane = QueueLane.COLD
-        publish()
-        emit(
-            QueueEvent.SourceChanged(
-                source = source,
-                songCount = songs.size,
-                startSong = currentSong()
-            )
-        )
-        // Immediately top up toward maxRadioQueue so the queue page fills live
-        if (isRadio) ensureRadioStock()
-    }
-
-    fun updateColdFromSource(songs: List<Song>, sourceId: String): Boolean {
-        val src = coldSource ?: return false
-        if (!src.id.equals(sourceId, ignoreCase = true)) return false
-        if (songs.isEmpty()) return false
-        if (src.type == ColdSourceType.RADIO) return false
-
-        val newKeys = songs.map { songKey(it) }
-        val oldKeys = coldOriginal.map { songKey(it) }
-        if (newKeys == oldKeys) return false
-
-        val current = currentSong()
-        coldOriginal = songs.toList()
-
-        val ordered = if (shuffleEnabled) {
-            songs.shuffled(Random(System.nanoTime())).toMutableList()
-        } else {
-            songs.toMutableList()
-        }
-
-        if (current != null && ordered.any { sameSong(it, current) }) {
-            ordered.removeAll { sameSong(it, current) }
-            when {
-                floatingCurrent != null -> {
-                    coldQueue.clear()
-                    coldQueue.addAll(ordered)
-                }
-                lane == QueueLane.COLD -> {
-                    coldQueue.clear()
-                    coldQueue.add(current)
-                    coldQueue.addAll(ordered)
-                    indexInLane = 0
-                }
-                else -> {
-                    coldQueue.clear()
-                    coldQueue.addAll(ordered)
-                }
-            }
-        } else {
-            coldQueue.clear()
-            coldQueue.addAll(ordered)
-            if (lane == QueueLane.COLD && floatingCurrent == null) {
-                indexInLane = if (coldQueue.isEmpty()) -1 else 0
-            }
-        }
-
-        Log.i(
-            TAG,
-            "updateColdFromSource id=$sourceId size=${songs.size} " +
-                "cold=${coldQueue.size} shuffle=$shuffleEnabled (overrides reset)"
-        )
-        publish()
-        return true
-    }
-
-    fun replaceColdKeepingCurrent(
-        songs: List<Song>,
-        source: ColdSource? = null,
-        session: RadioSession? = null
-    ) {
-        if (songs.isEmpty()) return
-        if (session != null) {
-            radioSession = session
-            shuffleEnabled = session.prefs.shuffle
-            if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
-            autoPlayHelper?.radioEngine?.adoptSession(session)
-        }
-        if (source != null) coldSource = source
-
-        val current = currentSong()
-        coldOriginal = songs.toList()
-        val ordered = songs.toMutableList()
-
-        if (current != null) {
-            ordered.removeAll { sameSong(it, current) }
-            if (floatingCurrent != null) {
-                coldQueue.clear()
-                coldQueue.addAll(ordered)
-            } else if (lane == QueueLane.COLD) {
-                coldQueue.clear()
-                coldQueue.add(current)
-                coldQueue.addAll(ordered)
-                indexInLane = 0
-            } else {
-                coldQueue.clear()
-                coldQueue.addAll(ordered)
-            }
-        } else {
-            coldQueue.clear()
-            coldQueue.addAll(ordered)
-            if (lane == QueueLane.COLD) {
-                indexInLane = if (coldQueue.isEmpty()) -1 else 0
-            }
-        }
-        radioUpcoming = emptyList()
-        Log.i(TAG, "replaceColdKeepingCurrent cold=${coldQueue.size}")
-        publish()
-        if (radioSession?.active == true) ensureRadioStock()
-    }
-
-    fun addToQueue(song: Song) {
-        hotQueue.add(song)
-        publishHot()
-    }
-
-    fun addToQueue(songs: List<Song>) {
-        if (songs.isEmpty()) return
-        hotQueue.addAll(songs)
-        publishHot()
-    }
-
-    fun clearHotQueue(): Boolean {
-        if (lane == QueueLane.HOT && indexInLane in hotQueue.indices) {
-            floatingCurrent = hotQueue[indexInLane]
-            hotQueue.clear()
-            indexInLane = -1
-            publishHot()
-            return false
-        }
-        hotQueue.clear()
-        publishHot()
-        return false
-    }
-
-    fun removeFromQueue(index: Int): Boolean {
-        if (index !in hotQueue.indices) return false
-        val removingCurrent = floatingCurrent == null && lane == QueueLane.HOT && index == indexInLane
-        hotQueue.removeAt(index)
-        if (lane == QueueLane.HOT && floatingCurrent == null) {
-            when {
-                hotQueue.isEmpty() -> {
-                    indexInLane = -1
-                    publishHot()
-                    return removingCurrent
-                }
-                index < indexInLane -> indexInLane--
-                removingCurrent -> {
-                    if (indexInLane > hotQueue.lastIndex) indexInLane = hotQueue.lastIndex
-                }
-            }
-        }
-        publishHot()
-        return removingCurrent
-    }
-
-    fun removeFromContext(index: Int): Boolean {
-        if (index !in coldQueue.indices) return false
-        val removingCurrent = floatingCurrent == null && lane == QueueLane.COLD && index == indexInLane
-        coldQueue.removeAt(index)
-        if (lane == QueueLane.COLD && floatingCurrent == null) {
-            when {
-                coldQueue.isEmpty() -> {
-                    indexInLane = -1
-                    publish()
-                    if (radioSession?.active == true) ensureRadioStock()
-                    return removingCurrent
-                }
-                index < indexInLane -> indexInLane--
-                removingCurrent -> {
-                    if (indexInLane > coldQueue.lastIndex) indexInLane = coldQueue.lastIndex
-                }
-            }
-        }
-        publish()
-        if (radioSession?.active == true) ensureRadioStock()
-        return removingCurrent
-    }
-
-    fun moveColdToHot(coldIndex: Int): Boolean {
-        if (coldIndex !in coldQueue.indices) return false
-        val removingCurrent = floatingCurrent == null && lane == QueueLane.COLD && coldIndex == indexInLane
-        val song = coldQueue.removeAt(coldIndex)
-        if (lane == QueueLane.COLD && floatingCurrent == null) {
-            when {
-                coldQueue.isEmpty() -> indexInLane = -1
-                coldIndex < indexInLane -> indexInLane--
-                removingCurrent -> indexInLane = indexInLane.coerceAtMost(coldQueue.lastIndex)
-            }
-        }
-        hotQueue.add(song)
-        publish()
-        if (radioSession?.active == true) ensureRadioStock()
-        return removingCurrent
-    }
-
-    fun moveInQueue(from: Int, to: Int) {
-        if (from !in hotQueue.indices || to !in hotQueue.indices || from == to) return
-        val item = hotQueue.removeAt(from)
-        hotQueue.add(to, item)
-        if (lane == QueueLane.HOT && floatingCurrent == null) {
-            indexInLane = remapIndex(indexInLane, from, to)
-        }
-        publishHot()
-    }
-
-    fun moveInContext(from: Int, to: Int) {
-        if (from !in coldQueue.indices || to !in coldQueue.indices || from == to) return
-        val item = coldQueue.removeAt(from)
-        coldQueue.add(to, item)
-        if (lane == QueueLane.COLD && floatingCurrent == null) {
-            indexInLane = remapIndex(indexInLane, from, to)
-        }
-        _snapshot.value = _snapshot.value.copy(
-            coldQueue = coldQueue.toList(),
-            indexInLane = indexInLane
-        )
-    }
-
-    fun playItem(laneTarget: QueueLane, index: Int) {
-        when (laneTarget) {
-            QueueLane.HOT -> {
-                if (index !in hotQueue.indices) return
-                val target = hotQueue[index]
-                val current = currentSong()
-                if (current != null && !sameSong(current, target)) pushPlayed(current)
-                if (current == null || !sameSong(current, target)) detachCurrentWithoutHistory()
-
-                var targetIdx = hotQueue.indexOfFirst { sameSong(it, target) }
-                if (targetIdx < 0) {
-                    hotQueue.add(0, target)
-                    targetIdx = 0
-                }
-                if (targetIdx > 0) repeat(targetIdx) { hotQueue.removeAt(0) }
-
-                floatingCurrent = null
-                lane = QueueLane.HOT
-                indexInLane = 0
-                publish()
-            }
-            QueueLane.COLD -> {
-                if (index !in coldQueue.indices) return
-                val target = coldQueue[index]
-                val current = currentSong()
-                if (current != null && !sameSong(current, target)) pushPlayed(current)
-                if (current == null || !sameSong(current, target)) detachCurrentWithoutHistory()
-
-                var targetIdx = coldQueue.indexOfFirst { sameSong(it, target) }
-                if (targetIdx < 0) {
-                    coldQueue.add(0, target)
-                    targetIdx = 0
-                }
-                if (targetIdx > 0) {
-                    for (i in 0 until targetIdx) pushPlayed(coldQueue[i])
-                    repeat(targetIdx) { coldQueue.removeAt(0) }
-                }
-
-                floatingCurrent = null
-                lane = QueueLane.COLD
-                indexInLane = 0
-                publish()
-            }
-        }
-    }
-
-    fun setShuffle(enabled: Boolean) {
-        if (radioSession?.active == true) {
-            val helper = autoPlayHelper
-            val next = helper?.radioEngine?.setShufflePrefs(enabled)
-            if (next != null) {
-                radioSession = radioSession?.copy(prefs = next)
-                shuffleEnabled = next.shuffle
-                val batch = helper.radioEngine.planBatch()
-                if (batch != null && batch.songs.isNotEmpty()) {
-                    replaceColdKeepingCurrent(batch.songs, batch.source, batch.session)
-                    return
-                }
-                publish()
-                emit(QueueEvent.ShuffleChanged(next.shuffle))
-            }
-            return
-        }
-
-        val current = currentSong()
-        if (!enabled) {
-            if (!shuffleEnabled) return
-            shuffleEnabled = false
-            coldQueue.clear()
-            coldQueue.addAll(coldOriginal)
-            if (current != null && lane == QueueLane.COLD && floatingCurrent == null) {
-                val idx = coldQueue.indexOfFirst { sameSong(it, current) }
-                indexInLane = if (idx >= 0) idx else 0
-            }
-            publish()
-            emit(QueueEvent.ShuffleChanged(false))
-            return
-        }
-        shuffleEnabled = true
-        val shuffled = coldOriginal.shuffled(Random(System.nanoTime())).toMutableList()
-        if (current != null && (lane == QueueLane.COLD || floatingCurrent != null)) {
-            shuffled.removeAll { sameSong(it, current) }
-            if (floatingCurrent == null && lane == QueueLane.COLD) {
-                shuffled.add(0, current)
-                coldQueue.clear()
-                coldQueue.addAll(shuffled)
-                indexInLane = 0
-            } else {
-                coldQueue.clear()
-                coldQueue.addAll(shuffled)
-            }
-        } else {
-            coldQueue.clear()
-            coldQueue.addAll(shuffled)
-        }
-        publish()
-        emit(QueueEvent.ShuffleChanged(true))
-    }
-
-    fun applyRadioPrefs(prefs: RadioSourcePrefs) {
-        val helper = autoPlayHelper ?: return
-        helper.radioEngine.updatePrefs(prefs)
-        val sess = helper.radioEngine.session ?: return
-        radioSession = sess
-        shuffleEnabled = sess.prefs.shuffle
-        if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
-        val batch = helper.radioEngine.planBatch()
-        if (batch != null && batch.songs.isNotEmpty()) {
-            replaceColdKeepingCurrent(batch.songs, batch.source, batch.session)
-        } else {
-            publish()
-            ensureRadioStock()
-        }
-        emit(QueueEvent.ShuffleChanged(sess.prefs.shuffle))
-    }
-
-    fun cycleRepeatMode() {
-        repeatMode = if (radioSession?.active == true) {
-            when (repeatMode) {
-                RepeatMode.OFF -> RepeatMode.ONE
-                else -> RepeatMode.OFF
-            }
-        } else {
-            when (repeatMode) {
-                RepeatMode.OFF -> RepeatMode.ONE
-                RepeatMode.ONE -> RepeatMode.COLD
-                RepeatMode.COLD -> RepeatMode.OFF
-            }
-        }
-        publishRepeat()
-        emit(QueueEvent.RepeatModeChanged(repeatMode))
-    }
-
-    fun setRepeatMode(mode: RepeatMode) {
-        val resolved = if (radioSession?.active == true && mode == RepeatMode.COLD) {
-            RepeatMode.OFF
-        } else mode
-        if (repeatMode == resolved) return
-        repeatMode = resolved
-        publishRepeat()
-        emit(QueueEvent.RepeatModeChanged(resolved))
-    }
-
-    fun advance(userInitiated: Boolean): AdvanceResult {
-        if (repeatMode == RepeatMode.ONE && !userInitiated) {
-            return AdvanceResult(song = currentSong(), reload = true)
-        }
-
-        val wasFloating = floatingCurrent != null
-        val fromLane = lane
-        val fromIndex = indexInLane
-        val seedBefore = currentSong()
-        val sourceBefore = coldSource
-
-        if (floatingCurrent != null) {
-            pushPlayed(floatingCurrent!!)
-            floatingCurrent = null
-        } else {
-            when (fromLane) {
-                QueueLane.HOT -> {
-                    if (fromIndex in hotQueue.indices) pushPlayed(hotQueue.removeAt(fromIndex))
-                }
-                QueueLane.COLD -> {
-                    if (fromIndex in coldQueue.indices) pushPlayed(coldQueue.removeAt(fromIndex))
-                }
-            }
-        }
-
-        // Top up radio cold as each track leaves
-        ensureRadioStock()
-
-        if (wasFloating) return resolveNextFromHeads(seedBefore, sourceBefore)
-
-        if (fromLane == QueueLane.HOT && fromIndex in hotQueue.indices) {
-            lane = QueueLane.HOT
-            indexInLane = fromIndex
-            publish()
-            return AdvanceResult(song = hotQueue[indexInLane])
-        }
-
-        if (hotQueue.isNotEmpty() && fromLane != QueueLane.HOT) {
-            lane = QueueLane.HOT
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = hotQueue[0])
-        }
-
-        if (fromLane == QueueLane.COLD && fromIndex in coldQueue.indices) {
-            lane = QueueLane.COLD
-            indexInLane = fromIndex
-            publish()
-            return AdvanceResult(song = coldQueue[indexInLane])
-        }
-
-        if (coldQueue.isNotEmpty()) {
-            lane = QueueLane.COLD
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = coldQueue[0])
-        }
-
-        // Cold emptied — try one more restock before rescue/finish
-        ensureRadioStock()
-        if (coldQueue.isNotEmpty()) {
-            lane = QueueLane.COLD
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = coldQueue[0])
-        }
-
-        if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty() && radioSession?.active != true) {
-            repopulateCold()
-            lane = QueueLane.COLD
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = coldQueue[0])
-        }
-
-        val seed = seedBefore ?: playedStack.lastOrNull()
-        emit(QueueEvent.Exhausted(seed = seed, source = sourceBefore, repeatMode = repeatMode))
-        tryAutoPlayRescue(seed, sourceBefore)?.let { return it }
-
-        indexInLane = -1
-        publish()
-        return AdvanceResult(finished = true)
-    }
-
-    private fun resolveNextFromHeads(
-        seedBefore: Song?,
-        sourceBefore: ColdSource?
-    ): AdvanceResult {
-        if (hotQueue.isNotEmpty()) {
-            lane = QueueLane.HOT
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = hotQueue[0])
-        }
-        if (coldQueue.isNotEmpty()) {
-            lane = QueueLane.COLD
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = coldQueue[0])
-        }
-        ensureRadioStock()
-        if (coldQueue.isNotEmpty()) {
-            lane = QueueLane.COLD
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = coldQueue[0])
-        }
-        if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty() && radioSession?.active != true) {
-            repopulateCold()
-            lane = QueueLane.COLD
-            indexInLane = 0
-            publish()
-            return AdvanceResult(song = coldQueue[0])
-        }
-        val seed = seedBefore ?: playedStack.lastOrNull()
-        emit(QueueEvent.Exhausted(seed = seed, source = sourceBefore, repeatMode = repeatMode))
-        tryAutoPlayRescue(seed, sourceBefore)?.let { return it }
-        indexInLane = -1
-        publish()
-        return AdvanceResult(finished = true)
-    }
-
-    fun skipPrevious(
-        currentPositionMs: Long,
-        forceTrackChange: Boolean = false
-    ): AdvanceResult {
-        val current = currentSong()
-        if (!forceTrackChange && currentPositionMs >= PREV_RESTART_MS) {
-            return AdvanceResult(song = current, seekToStart = true)
-        }
-
-        linearPrevious()?.let { prev ->
-            indexInLane -= 1
-            publish()
-            Log.i(TAG, "skipPrevious linear → '${prev.displayTitle}' idx=$indexInLane")
-            return AdvanceResult(song = prev)
-        }
-
-        if (playedStack.isEmpty()) {
-            return AdvanceResult(song = current, seekToStart = true)
-        }
-
-        val prev = playedStack.removeAt(playedStack.lastIndex)
-
-        if (floatingCurrent != null) {
-            floatingCurrent = null
-        } else {
-            when (lane) {
-                QueueLane.HOT -> {
-                    if (indexInLane in hotQueue.indices) hotQueue.removeAt(indexInLane)
-                }
-                QueueLane.COLD -> {
-                    if (indexInLane in coldQueue.indices) coldQueue.removeAt(indexInLane)
-                }
-            }
-        }
-
-        val useCold = coldSource != null || coldQueue.isNotEmpty() || coldOriginal.isNotEmpty()
-        if (useCold) {
-            if (current != null) coldQueue.add(0, current)
-            coldQueue.add(0, prev)
-            lane = QueueLane.COLD
-            indexInLane = 0
-        } else {
-            if (current != null) hotQueue.add(0, current)
-            hotQueue.add(0, prev)
-            lane = QueueLane.HOT
-            indexInLane = 0
-        }
-        floatingCurrent = null
-
-        publish()
-        Log.i(TAG, "skipPrevious history → '${prev.displayTitle}'")
-        return AdvanceResult(song = prev)
-    }
-
-    private fun repopulateCold() {
-        coldQueue.clear()
-        if (shuffleEnabled) {
-            coldQueue.addAll(coldOriginal.shuffled(Random(System.nanoTime())))
-        } else {
-            coldQueue.addAll(coldOriginal)
-        }
-        playedStack.clear()
-    }
-
-    private fun remapIndex(current: Int, from: Int, to: Int): Int = when {
-        current == from -> to
-        from < current && to >= current -> current - 1
-        from > current && to <= current -> current + 1
-        else -> current
-    }
-
-    private fun sameSong(a: Song, b: Song): Boolean {
-        if (a.path != null && b.path != null) return a.path == b.path
-        return a.contentUri == b.contentUri || a.id == b.id
-    }
-
-    private fun songKey(s: Song): String =
-        s.path?.lowercase() ?: s.contentUri.toString()
-
-    data class AdvanceResult(
-        val song: Song? = null,
-        val finished: Boolean = false,
-        val reload: Boolean = false,
-        val seekToStart: Boolean = false
-    )
-
-    companion object {
-        private const val TAG = "YuriPlayer.Queue"
-        const val PREV_RESTART_MS = 3_000L
-        private const val MAX_PLAYED_STACK = 200
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/QueueModels.kt b/app/src/main/java/capital/yuri/yuriplayer/player/QueueModels.kt
index 45ba1f25..42cf923f 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/QueueModels.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/QueueModels.kt
@@ -1,91 +1,3 @@
 package capital.yuri.yuriplayer.player
 
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.player.radio.RadioSession
-import kotlinx.serialization.Serializable
-
-@Serializable
-enum class RepeatMode {
-    OFF,
-    ONE,
-    /** Loop the cold queue (album / playlist source) after it ends. */
-    COLD
-}
-
-@Serializable
-enum class QueueLane {
-    HOT,
-    COLD
-}
-
-@Serializable
-enum class ColdSourceType {
-    ALBUM,
-    PLAYLIST,
-    ARTIST,
-    SONGS,
-    /** Named radio session segment (still backs onto an album/release). */
-    RADIO,
-    UNKNOWN
-}
-
-@Serializable
-data class ColdSource(
-    val type: ColdSourceType,
-    val id: String,
-    val title: String? = null
-) {
-    fun matches(type: ColdSourceType, id: String): Boolean =
-        this.type == type && this.id.equals(id, ignoreCase = true)
-}
-
-/**
- * Snapshot of the dual-queue system for UI + persistence.
- *
- * [radioSession] names the station when radio is active.
- * [radioUpcoming] is the prefetched next radio release (not yet in cold).
- *
- * Shuffle in radio mode only reorders the **current** cold segment; the next
- * radio release is still algorithm-picked (see [RadioSession] KDoc).
- */
-@Serializable
-data class QueueSnapshot(
-    val hotQueue: List<Song> = emptyList(),
-    val coldQueue: List<Song> = emptyList(),
-    val coldOriginal: List<Song> = emptyList(),
-    val coldSource: ColdSource? = null,
-    val lane: QueueLane = QueueLane.COLD,
-    val indexInLane: Int = -1,
-    val shuffleEnabled: Boolean = false,
-    val repeatMode: RepeatMode = RepeatMode.OFF,
-    val playedStack: List<Song> = emptyList(),
-    val radioSession: RadioSession? = null,
-    val radioUpcoming: List<Song> = emptyList(),
-    /** Playing item when it is not at [indexInLane] (search / one-off). */
-    val floatingCurrent: Song? = null
-) {
-    val currentSong: Song?
-        get() = floatingCurrent ?: when (lane) {
-            QueueLane.HOT -> hotQueue.getOrNull(indexInLane)
-            QueueLane.COLD -> coldQueue.getOrNull(indexInLane)
-        }
-
-    val flatQueue: List<Song>
-        get() = hotQueue + coldQueue
-
-    /**
-     * True when a radio session is active **or** the cold source is typed RADIO.
-     * Label text alone is not enough — some stations set coldSource without
-     * keeping [radioSession].active, which hid the tune button.
-     */
-    val isRadio: Boolean
-        get() = radioSession?.active == true || coldSource?.type == ColdSourceType.RADIO
-
-    fun isPlayingFromAlbum(albumKey: String): Boolean =
-        coldSource?.matches(ColdSourceType.ALBUM, albumKey) == true ||
-            (coldSource?.type == ColdSourceType.RADIO &&
-                coldSource.id.equals(albumKey, ignoreCase = true))
-
-    fun isPlayingFromPlaylist(playlistId: String): Boolean =
-        coldSource?.matches(ColdSourceType.PLAYLIST, playlistId) == true
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/SourceColdSync.kt b/app/src/main/java/capital/yuri/yuriplayer/player/SourceColdSync.kt
index 2263ec11..d540094c 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/SourceColdSync.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/SourceColdSync.kt
@@ -1,6 +1,6 @@
 package capital.yuri.yuriplayer.player
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import capital.yuri.yuriplayer.data.PlaylistRepository
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Job
@@ -37,7 +37,7 @@ class SourceColdSync(
                 .distinctUntilChanged()
                 .collectLatest { playlistId ->
                     if (playlistId == null) return@collectLatest
-                    Log.i(TAG, "watching playlist $playlistId for cold sync")
+                    log.i { "watching playlist $playlistId for cold sync" }
                     playlists.observePlaylist(playlistId).collect { pl ->
                         val songs = pl?.songs.orEmpty()
                         if (songs.isEmpty()) return@collect
@@ -55,6 +55,6 @@ class SourceColdSync(
     }
 
     companion object {
-        private const val TAG = "YuriPlayer.ColdSync"
+        private val log = yuriLog("ColdSync")
     }
 }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/engine/AudioPipeline.kt b/app/src/main/java/capital/yuri/yuriplayer/player/engine/AudioPipeline.kt
index 3f122ae2..6c4910d4 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/engine/AudioPipeline.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/engine/AudioPipeline.kt
@@ -1,16 +1,17 @@
 package capital.yuri.yuriplayer.player.engine
 
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 
 /**
  * What we asked the server for vs what actually arrived.
- * Filter logcat: `adb logcat YuriAudio:I *:S`
+ * Filter logcat: `adb logcat YuriPlayer.YuriAudio:I *:S`
  */
 object AudioPipeline {
     const val TAG = "YuriAudio"
+    private val log = yuriLog(TAG)
 
     data class Snapshot(
         val title: String,
@@ -42,7 +43,7 @@ object AudioPipeline {
     private val _last = MutableStateFlow<Snapshot?>(null)
     val last: StateFlow<Snapshot?> = _last.asStateFlow()
 
-    fun i(msg: String) = Log.i(TAG, msg)
+    fun i(msg: String) = log.i { msg }
 
     fun notePlay(
         title: String,
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/engine/Media3PlaybackEngine.kt b/app/src/main/java/capital/yuri/yuriplayer/player/engine/Media3PlaybackEngine.kt
index 47cd190e..7d8a2072 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/engine/Media3PlaybackEngine.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/engine/Media3PlaybackEngine.kt
@@ -4,7 +4,7 @@ import android.content.Context
 import android.net.Uri
 import android.os.Handler
 import android.os.Looper
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import androidx.annotation.OptIn
 import androidx.media3.common.AudioAttributes
 import androidx.media3.common.C
@@ -133,7 +133,7 @@ class Media3PlaybackEngine(
         }
 
         override fun onPlayerError(error: PlaybackException) {
-            Log.e(TAG, "player error code=${error.errorCode} ${error.message}", error)
+            log.e(error) { "player error code=${error.errorCode} ${error.message}" }
             val recoverable =
                 error.errorCode == PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_FAILED ||
                         error.errorCode == PlaybackException.ERROR_CODE_IO_NETWORK_CONNECTION_TIMEOUT ||
@@ -190,10 +190,7 @@ class Media3PlaybackEngine(
         player.setMediaItems(mediaItems, idx, startPositionMs.coerceAtLeast(0L))
         player.prepare()
         _currentUri.value = playable.getOrNull(idx)?.uri
-        Log.i(
-            TAG,
-            "setWindow size=${playable.size} start=$idx network=${playable[idx].isNetwork} live=${playable[idx].live}"
-        )
+        log.i { "setWindow size=${playable.size} start=$idx network=${playable[idx].isNetwork} live=${playable[idx].live}" }
     }
 
     private fun applyHeaders(items: List<PlaybackMedia>) {
@@ -299,7 +296,7 @@ class Media3PlaybackEngine(
         applyHeaders(listOf(playable))
         player.addMediaItem(playable.toMediaItem())
         if (player.playbackState == Player.STATE_IDLE) player.prepare()
-        Log.i(TAG, "setNext '${playable.title}' network=${playable.isNetwork}")
+        log.i { "setNext '${playable.title}' network=${playable.isNetwork}" }
     }
 
     override fun hasPreparedNext(): Boolean = player.hasNextMediaItem()
@@ -361,7 +358,7 @@ class Media3PlaybackEngine(
     }
 
     companion object {
-        private const val TAG = "Media3Engine"
+        private val log = yuriLog("Media3Engine")
         private const val NEXT_PRELOAD_US = 30_000_000L
 
         val DESCRIPTOR = PlaybackEngineDescriptor(
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngine.kt b/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngine.kt
index 28250da2..6c98fad4 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngine.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngine.kt
@@ -160,7 +160,7 @@ fun Song.toPlaybackMedia(
         artist = displayArtist,
         album = displayAlbum,
         albumArtist = displayAlbumArtist,
-        artworkUri = albumArtUri,
+        artworkUri = albumArtUri?.let { Uri.parse(it) },
         headers = headers,
         isNetwork = network,
         live = live
@@ -176,7 +176,7 @@ fun Song.isLiveAudio(): Boolean {
     ) {
         return true
     }
-    return contentUri.getBooleanQueryParameter("live", false)
+    return Uri.parse(contentUri).getBooleanQueryParameter("live", false)
 }
 
 fun resolvePlayableUri(
@@ -190,14 +190,14 @@ fun resolvePlayableUri(
         if (file.exists() && file.canRead()) return Uri.fromFile(file)
     }
     if (!path.isNullOrBlank() && path.startsWith("jellyfin:")) {
-        return jellyfinPlayableUri(song.contentUri, path.removePrefix("jellyfin:"), quality)
+        return jellyfinPlayableUri(Uri.parse(song.contentUri), path.removePrefix("jellyfin:"), quality)
     }
     if (!path.isNullOrBlank() &&
         (path.startsWith("subsonic:") || path.startsWith("navidrome:"))
     ) {
-        return subsonicPlayableUri(song.contentUri, quality)
+        return subsonicPlayableUri(Uri.parse(song.contentUri), quality)
     }
-    return song.contentUri
+    return Uri.parse(song.contentUri)
 }
 
 /**
@@ -294,7 +294,7 @@ fun isNetworkUri(uri: Uri): Boolean {
 
 /** Pull token headers from a stream URI when present (Jellyfin api_key query). */
 fun extractStreamHeaders(song: Song): Map<String, String> {
-    val uri = song.contentUri
+    val uri = Uri.parse(song.contentUri)
     val apiKey = uri.getQueryParameter("api_key")
         ?: uri.getQueryParameter("ApiKey")
         ?: return emptyMap()
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngineFactory.kt b/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngineFactory.kt
index 460cd5c6..52cc7fd6 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngineFactory.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/engine/PlaybackEngineFactory.kt
@@ -1,7 +1,7 @@
 package capital.yuri.yuriplayer.player.engine
 
 import android.content.Context
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 
 /**
  * Which [PlaybackEngine] implementation plays **all** audio (local + remote).
@@ -43,22 +43,21 @@ object PlaybackEngineCatalog {
  * One selection plays everything — no per-URI hybrid routing.
  */
 object PlaybackEngineFactory {
-    private const val TAG = "EngineFactory"
-
+    private val log = yuriLog("EngineFactory")
     fun create(context: Context, id: PlaybackEngineId): PlaybackEngine {
         val app = context.applicationContext
         return when (id) {
             PlaybackEngineId.MEDIA3 -> {
-                Log.i(TAG, "create Media3PlaybackEngine")
+                log.i { "create Media3PlaybackEngine" }
                 Media3PlaybackEngine(app)
             }
             PlaybackEngineId.VLC -> {
-                Log.i(TAG, "create VlcPlaybackEngine")
+                log.i { "create VlcPlaybackEngine" }
                 VlcPlaybackEngine(app)
             }
             PlaybackEngineId.FFMPEG -> {
                 // Not implemented — fall back so playback still works.
-                Log.w(TAG, "FFmpeg engine not ready; falling back to VLC")
+                log.w { "FFmpeg engine not ready; falling back to VLC" }
                 VlcPlaybackEngine(app)
             }
         }
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/engine/StreamPrefetcher.kt b/app/src/main/java/capital/yuri/yuriplayer/player/engine/StreamPrefetcher.kt
index 6fda36c9..5a8b25f5 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/engine/StreamPrefetcher.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/engine/StreamPrefetcher.kt
@@ -4,7 +4,7 @@ import android.content.Context
 import android.net.Uri
 import android.os.Handler
 import android.os.HandlerThread
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import java.io.File
 import java.io.FileOutputStream
 import java.net.HttpURLConnection
@@ -91,7 +91,7 @@ class StreamPrefetcher private constructor(cacheDir: File) {
                 return
             }
             tmp.delete()
-            Log.i(TAG, "prefetch start '${item.title}'")
+            log.i { "prefetch start '${item.title}'" }
             conn = (URL(item.uri.toString()).openConnection() as HttpURLConnection).apply {
                 instanceFollowRedirects = true
                 connectTimeout = 15_000
@@ -101,13 +101,13 @@ class StreamPrefetcher private constructor(cacheDir: File) {
             }
             val code = conn.responseCode
             if (code !in 200..299) {
-                Log.w(TAG, "prefetch HTTP $code '${item.title}'")
+                log.w { "prefetch HTTP $code '${item.title}'" }
                 return
             }
             val total = conn.contentLengthLong.takeIf { it > 0 } ?: -1L
             AudioPipeline.noteHttp(conn.contentType, total.takeIf { it > 0 }, item.title)
             if (total > MAX_BYTES) {
-                Log.w(TAG, "prefetch skip '${item.title}' too large $total")
+                log.w { "prefetch skip '${item.title}' too large $total" }
                 return
             }
             FileOutputStream(tmp).use { out ->
@@ -120,7 +120,7 @@ class StreamPrefetcher private constructor(cacheDir: File) {
                         out.write(buf, 0, n)
                         written += n
                         if (written > MAX_BYTES) {
-                            Log.w(TAG, "prefetch abort '${item.title}' over cap")
+                            log.w { "prefetch abort '${item.title}' over cap" }
                             tmp.delete()
                             return
                         }
@@ -141,9 +141,9 @@ class StreamPrefetcher private constructor(cacheDir: File) {
                 tmp.delete()
             }
             synchronized(ready) { ready[item.mediaId] = dest }
-            Log.i(TAG, "prefetch ready '${item.title}' ${dest.length()}B of $total")
+            log.i { "prefetch ready '${item.title}' ${dest.length()}B of $total" }
         } catch (e: Exception) {
-            Log.w(TAG, "prefetch failed '${item.title}': ${e.message}")
+            log.w { "prefetch failed '${item.title}': ${e.message}" }
             tmp.delete()
         } finally {
             runCatching { conn?.disconnect() }
@@ -162,7 +162,7 @@ class StreamPrefetcher private constructor(cacheDir: File) {
     }
 
     companion object {
-        private const val TAG = "StreamPrefetch"
+        private val log = yuriLog("StreamPrefetch")
         private const val MIN_BYTES = 256 * 1024L
         private const val MAX_BYTES = 256L * 1024L * 1024L
         private const val MAX_FILES = 8
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/engine/VlcPlaybackEngine.kt b/app/src/main/java/capital/yuri/yuriplayer/player/engine/VlcPlaybackEngine.kt
index ad0b34d5..45b931b0 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/engine/VlcPlaybackEngine.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/engine/VlcPlaybackEngine.kt
@@ -7,7 +7,7 @@ import android.os.Handler
 import android.os.HandlerThread
 import android.os.Looper
 import android.os.ParcelFileDescriptor
-import android.util.Log
+import capital.yuri.yuriplayer.core.log.yuriLog
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
@@ -114,7 +114,7 @@ class VlcPlaybackEngine(
                         if (loadGeneration != eventGeneration) return@post
                         if (mp !== active()) return@post
                         if (!mp.isPlaying) {
-                            Log.i(TAG, "unexpected pause → resume")
+                            log.i { "unexpected pause → resume" }
                             runCatching { mp.play() }
                         }
                     }
@@ -127,11 +127,11 @@ class VlcPlaybackEngine(
                 dispatch { onPlaybackStateChanged(PlaybackEngine.PlaybackState.IDLE) }
                 if (!playWhenReady) return
                 if (!windowHasPlayed) {
-                    Log.i(TAG, "stopped before play — load, not EOF")
+                    log.i { "stopped before play — load, not EOF" }
                     return
                 }
                 if (currentIsLive()) {
-                    Log.i(TAG, "live stopped → reconnect")
+                    log.i { "live stopped → reconnect" }
                     runCatching { mp.play() }
                     return
                 }
@@ -148,7 +148,7 @@ class VlcPlaybackEngine(
                 if (loadGeneration != eventGeneration) return
                 if (currentIsLive()) {
                     if (playWhenReady) {
-                        Log.i(TAG, "live EOF → reconnect")
+                        log.i { "live EOF → reconnect" }
                         runCatching { mp.play() }
                     }
                     return
@@ -165,7 +165,7 @@ class VlcPlaybackEngine(
                 dispatch { onEnded() }
             }
             MediaPlayer.Event.EncounteredError -> {
-                Log.e(TAG, "VLC EncounteredError uri=${_currentUri.value}")
+                log.e { "VLC EncounteredError uri=${_currentUri.value}" }
                 _isPlaying.value = false
                 dispatch { onIsPlayingChanged(false) }
                 if (playWhenReady && swapToPreparedNext()) {
@@ -195,12 +195,12 @@ class VlcPlaybackEngine(
                     event.buffering >= 100f
                 if (!buffered) return
                 nextReady = true
-                Log.i(TAG, "standby ready '${nextItem?.title}' warming=$nextWarming")
+                log.i { "standby ready '${nextItem?.title}' warming=$nextWarming" }
                 // Stay playing at volume 0. Pause kills HTTP (`reading while
                 // paused`) and the swapped stream then dies at EOF.
             }
             MediaPlayer.Event.EncounteredError -> {
-                Log.w(TAG, "standby prepare failed '${nextItem?.title}'")
+                log.w { "standby prepare failed '${nextItem?.title}'" }
                 nextReady = false
                 nextPreparing = false
                 nextWarming = false
@@ -400,7 +400,7 @@ class VlcPlaybackEngine(
                 opened.fold(
                     onSuccess = { input -> attachAndMaybePlay(playable, input, gen) },
                     onFailure = { e ->
-                        Log.e(TAG, "open failed ${playable.uri}", e)
+                        log.e(e) { "open failed ${playable.uri}" }
                         dispatch { onError(e.message ?: "VLC open failed", recoverable = true) }
                     }
                 )
@@ -423,7 +423,7 @@ class VlcPlaybackEngine(
             mediaFromOpened(item, input)
         } catch (e: Exception) {
             input.close()
-            Log.e(TAG, "mediaFromOpened ${item.uri}", e)
+            log.e(e) { "mediaFromOpened ${item.uri}" }
             dispatch { onError(e.message ?: "VLC media failed", recoverable = true) }
             return
         }
@@ -435,10 +435,7 @@ class VlcPlaybackEngine(
         }
         bindMedia(active(), media, isNext = false)
         dispatch { onMediaTransition(PlaybackEngine.TransitionReason.PLAYLIST) }
-        Log.i(
-            TAG,
-            "attached uri=${item.uri} network=${item.isNetwork} autoPlay=$playWhenReady"
-        )
+        log.i { "attached uri=${item.uri} network=${item.isNetwork} autoPlay=$playWhenReady" }
         if (playWhenReady) active().play()
     }
 
@@ -450,7 +447,7 @@ class VlcPlaybackEngine(
         pendingSeekMs = -1L
         val max = (len - 1_000L).coerceAtLeast(0L)
         val target = seek.coerceIn(0L, max)
-        Log.i(TAG, "seek ${seek}ms → ${target}ms of ${len}ms")
+        log.i { "seek ${seek}ms → ${target}ms of ${len}ms" }
         runCatching { mp.time = target }
     }
 
@@ -471,7 +468,7 @@ class VlcPlaybackEngine(
                 opened.fold(
                     onSuccess = { input -> attachStandby(item, input, gen) },
                     onFailure = { e ->
-                        Log.w(TAG, "standby open failed ${item.uri}: ${e.message}")
+                        log.w { "standby open failed ${item.uri}: ${e.message}" }
                         if (gen == nextGeneration) {
                             nextReady = false
                             nextPreparing = false
@@ -497,7 +494,7 @@ class VlcPlaybackEngine(
             mediaFromOpened(item, input)
         } catch (e: Exception) {
             input.close()
-            Log.w(TAG, "standby media failed ${item.uri}", e)
+            log.w(e) { "standby media failed ${item.uri}" }
             nextReady = false
             nextPreparing = false
             return
@@ -511,7 +508,7 @@ class VlcPlaybackEngine(
         val sp = standby()
         runCatching { sp.stop() }
         bindMedia(sp, media, isNext = true)
-        Log.i(TAG, "standby attached '${item.title}' network=${item.isNetwork}")
+        log.i { "standby attached '${item.title}' network=${item.isNetwork}" }
         nextPreparing = false
         nextReady = true
     }
@@ -548,7 +545,7 @@ class VlcPlaybackEngine(
         np.play()
         _isPlaying.value = true
         buffering = false
-        Log.i(TAG, "swap → '${nxt.title}'")
+        log.i { "swap → '${nxt.title}'" }
 
         runCatching { old.stop() }
         runCatching { old.media = null }
@@ -573,7 +570,7 @@ class VlcPlaybackEngine(
 
     private fun openInput(item: PlaybackMedia): OpenedInput {
         prefetcher.fileIfReady(item.mediaId)?.let { f ->
-            Log.i(TAG, "open disk '${item.title}' ${f.length()}B")
+            log.i { "open disk '${item.title}' ${f.length()}B" }
             return OpenedInput.Path(f.absolutePath)
         }
         val uri = item.uri
@@ -598,12 +595,12 @@ class VlcPlaybackEngine(
         val resolver = appContext.contentResolver
         val afd = runCatching { resolver.openAssetFileDescriptor(uri, "r") }.getOrNull()
         if (afd != null) {
-            Log.i(TAG, "opened AFD uri=$uri offset=${afd.startOffset} len=${afd.length}")
+            log.i { "opened AFD uri=$uri offset=${afd.startOffset} len=${afd.length}" }
             return OpenedInput.ContentAfd(afd)
         }
         val pfd = resolver.openFileDescriptor(uri, "r")
             ?: throw IllegalStateException("Cannot open content uri: $uri")
-        Log.i(TAG, "opened PFD uri=$uri")
+        log.i { "opened PFD uri=$uri" }
         return OpenedInput.ContentPfd(pfd)
     }
 
@@ -690,7 +687,7 @@ class VlcPlaybackEngine(
     }
 
     companion object {
-        private const val TAG = "VlcEngine"
+        private val log = yuriLog("VlcEngine")
         private const val FILE_CACHE_MS = 800
         private const val NETWORK_CACHE_MS = 6_000
         private const val PREFETCH_BYTES = 16 * 1024 * 1024
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt
index 20387cd6..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt
@@ -1,97 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import capital.yuri.yuriplayer.data.AlbumItem
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.data.artistKey
-
-/**
- * Album radio pool: every credited artist on the release, plus genre keys
- * when those tags exist (Song has no genre field yet — empty list is fine).
- */
-object AlbumRadioSeed {
-
-    fun fromAlbum(album: AlbumItem): Pair<ReleasePoolConfig, RadioSession> {
-        val artists = LinkedHashSet<String>()
-        val displayArtists = LinkedHashSet<String>()
-
-        album.artist?.trim()?.takeIf { it.isNotEmpty() }?.let {
-            displayArtists += it
-            artistKey(it)?.let(artists::add)
-        }
-
-        for (s in album.songs) {
-            collectArtist(s, artists, displayArtists)
-        }
-
-        val genres = collectGenres(album.songs)
-        val cfg = ReleasePoolConfig(
-            artistKeys = artists.toList(),
-            genreKeys = genres,
-            includeLps = true,
-            includeEps = true,
-            includeSingles = true,
-            allowExternalFetch = false,
-            avoidRecentPerKind = 1
-        )
-
-        val seedKey = ReleaseClassifier.releaseKey(album)
-        val label = album.name?.takeIf { it.isNotBlank() } ?: "Album"
-        val session = RadioSession(
-            kind = RadioSessionKind.ALBUM,
-            displayName = "Radio · $label",
-            algorithmId = RadioAlgorithmId.RELEASE_POOL,
-            seedId = seedKey,
-            seedTitle = label
-        )
-        return cfg to session
-    }
-
-    fun fromTracksForPlaylist(
-        songs: List<Song>,
-        playlistName: String?
-    ): Pair<ReleasePoolConfig, RadioSession> {
-        val cfg = PlaylistRadioSeed.fromTracks(songs)
-        val label = playlistName?.takeIf { it.isNotBlank() } ?: "Playlist"
-        val session = RadioSession(
-            kind = RadioSessionKind.PLAYLIST,
-            displayName = "Radio · $label",
-            algorithmId = RadioAlgorithmId.RELEASE_POOL,
-            seedId = label.lowercase(),
-            seedTitle = label
-        )
-        return cfg to session
-    }
-
-    fun artistSession(artistName: String): RadioSession {
-        val label = artistName.trim().ifBlank { "Artist" }
-        return RadioSession(
-            kind = RadioSessionKind.ARTIST,
-            displayName = "Radio · $label",
-            algorithmId = RadioAlgorithmId.PLAYBACK,
-            seedId = artistKey(label),
-            seedTitle = label
-        )
-    }
-
-    private fun collectArtist(
-        s: Song,
-        keys: MutableSet<String>,
-        display: MutableSet<String>
-    ) {
-        s.effectiveAlbumArtist?.trim()?.takeIf { it.isNotEmpty() }?.let {
-            display += it
-            artistKey(it)?.let(keys::add)
-        }
-        s.artist?.trim()?.takeIf { it.isNotEmpty() }?.let {
-            display += it
-            artistKey(it)?.let(keys::add)
-        }
-        s.creditArtists.forEach { name ->
-            display += name
-            artistKey(name)?.let(keys::add)
-        }
-    }
-
-    /** Placeholder until Song.genre / tag genres land. */
-    private fun collectGenres(songs: List<Song>): List<String> = emptyList()
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt
index 93adf089..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt
@@ -1,37 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.data.artistKey
-
-/**
- * Build a [ReleasePoolConfig] from playlist (or any track list) contents.
- * Artists are derived on-device from tags; genres land here when the catalog
- * has them. No network.
- */
-object PlaylistRadioSeed {
-
-    fun fromTracks(
-        songs: List<Song>,
-        includeLps: Boolean = true,
-        includeEps: Boolean = true,
-        includeSingles: Boolean = true
-    ): ReleasePoolConfig {
-        val artists = LinkedHashSet<String>()
-        for (s in songs) {
-            artistKey(s.effectiveAlbumArtist)?.let { artists += it }
-            artistKey(s.artist)?.let { artists += it }
-            s.creditArtists.forEach { name ->
-                artistKey(name)?.let { artists += it }
-            }
-        }
-        return ReleasePoolConfig(
-            artistKeys = artists.toList(),
-            genreKeys = emptyList(), // filled when Song.genre exists
-            includeLps = includeLps,
-            includeEps = includeEps,
-            includeSingles = includeSingles,
-            allowExternalFetch = false,
-            avoidRecentPerKind = 1
-        )
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt
index e9beffc1..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt
@@ -1,44 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import capital.yuri.yuriplayer.data.AlbumItem
-
-/**
- * On-device catalog view for algorithms. Keep this free of Android / Room so the
- * radio package can move to a shared KMP module or a self-hosted worker.
- */
-fun interface ReleaseCatalog {
-    fun albums(): List<AlbumItem>
-}
-
-/**
- * Pluggable radio strategy. Implementations must be pure w.r.t. I/O except via
- * [ReleaseCatalog] (and future optional NetworkReleaseSource behind a privacy gate).
- */
-interface RadioAlgorithm {
-    val id: RadioAlgorithmId
-
-    /**
-     * @return next release to queue, or null if this strategy has nothing.
-     * Algorithms must not mutate global player state — only their own memory
-     * (via [RecentReleaseMemory] passed in context side-channels if needed).
-     */
-    fun pick(
-        catalog: ReleaseCatalog,
-        context: RadioContext,
-        memory: RecentReleaseMemory
-    ): RadioPick?
-}
-
-/**
- * Optional network extension point. Always no-op until the user opts in and a
- * concrete source (Jellyfin / Navidrome / …) is configured.
- */
-interface ExternalReleaseSource {
-    val isEnabled: Boolean
-    /** Suspend-friendly later; sync stub for now. */
-    fun fetchCandidates(context: RadioContext): List<AlbumItem> = emptyList()
-}
-
-object NoExternalReleaseSource : ExternalReleaseSource {
-    override val isEnabled: Boolean = false
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioEngine.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioEngine.kt
index fa37f367..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioEngine.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioEngine.kt
@@ -1,416 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import android.util.Log
-import capital.yuri.yuriplayer.data.AlbumItem
-import capital.yuri.yuriplayer.data.LibraryIndex
-import capital.yuri.yuriplayer.data.LibrarySettings
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.data.artistKey
-import capital.yuri.yuriplayer.player.ColdSource
-import capital.yuri.yuriplayer.player.ColdSourceType
-import capital.yuri.yuriplayer.player.RepeatMode
-import kotlin.random.Random
-
-/**
- * Plans the radio cold queue (visible on the queue page) and restocks it.
- *
- * Shuffle OFF: whole LP/EP/Single blocks until ≥ maxRadioQueue (may exceed);
- *   restock appends the next release only when cold size < max.
- * Shuffle ON + SONGS: random tracks up to maxRadioQueue; restock tops cold every time.
- * Shuffle ON + RELEASES: shuffled whole releases (tracks ordered within);
- *   restock appends the next shuffled release when under target.
- */
-class RadioEngine(
-    private val library: LibraryIndex,
-    private val settings: LibrarySettings,
-    private val playbackAlgo: RadioPlaybackAlgorithm = RadioPlaybackAlgorithm(),
-    private val poolAlgo: ReleasePoolAlgorithm = ReleasePoolAlgorithm()
-) {
-    /** Prefer the full local library; tagged-only was starving restock. */
-    private val catalog = ReleaseCatalog { library.albums(taggedOnly = false) }
-    private val memory = RecentReleaseMemory()
-
-    @Volatile
-    var activeAlgorithm: RadioAlgorithmId = RadioAlgorithmId.PLAYBACK
-        private set
-
-    @Volatile
-    var session: RadioSession? = null
-        private set
-
-    /** Pool of candidate releases for the active session (artist/album/playlist). */
-    private var poolReleases: List<AlbumItem> = emptyList()
-
-    fun configurePlayback(config: RadioPlaybackConfig) {
-        playbackAlgo.config = config
-    }
-
-    fun configurePool(config: ReleasePoolConfig) {
-        poolAlgo.config = config
-        rebuildPoolFromConfig(config)
-    }
-
-    fun startAlbumRadio(album: AlbumItem, prefs: RadioSourcePrefs = RadioSourcePrefs()): RadioSession {
-        val (cfg, sess) = AlbumRadioSeed.fromAlbum(album)
-        val withPrefs = sess.copy(prefs = prefs)
-        configurePool(cfg)
-        activeAlgorithm = RadioAlgorithmId.RELEASE_POOL
-        session = withPrefs
-        memory.note(ReleaseClassifier.releaseKey(album), ReleaseClassifier.kindOf(album))
-        Log.i(TAG, "album radio '${withPrefs.displayName}' artists=${cfg.artistKeys.size}")
-        return withPrefs
-    }
-
-    fun startArtistRadio(artistName: String, prefs: RadioSourcePrefs = RadioSourcePrefs()): RadioSession {
-        val sess = AlbumRadioSeed.artistSession(artistName).copy(prefs = prefs)
-        activeAlgorithm = RadioAlgorithmId.PLAYBACK
-        session = sess
-        poolReleases = releasesForArtist(artistName)
-        Log.i(TAG, "artist radio '${sess.displayName}' releases=${poolReleases.size}")
-        return sess
-    }
-
-    fun startPlaylistRadio(
-        songs: List<Song>,
-        playlistName: String?,
-        prefs: RadioSourcePrefs = RadioSourcePrefs()
-    ): RadioSession {
-        val (cfg, sess) = AlbumRadioSeed.fromTracksForPlaylist(songs, playlistName)
-        val withPrefs = sess.copy(prefs = prefs)
-        configurePool(cfg)
-        activeAlgorithm = RadioAlgorithmId.RELEASE_POOL
-        session = withPrefs
-        Log.i(TAG, "playlist radio '${withPrefs.displayName}'")
-        return withPrefs
-    }
-
-    /**
-     * Re-attach a session that was persisted on the queue but lost from this
-     * in-memory engine (e.g. after process death). Rebuilds the release pool.
-     */
-    fun adoptSession(sess: RadioSession) {
-        if (!sess.active) return
-        session = sess
-        activeAlgorithm = sess.algorithmId
-        when (sess.kind) {
-            RadioSessionKind.ARTIST -> {
-                val name = sess.seedTitle
-                    ?: sess.displayName.removePrefix("Radio · ").trim()
-                poolReleases = releasesForArtist(name)
-            }
-            RadioSessionKind.ALBUM,
-            RadioSessionKind.PLAYLIST,
-            RadioSessionKind.CUSTOM -> {
-                // Fall back to full catalog; seed-specific pool is best-effort.
-                if (poolReleases.isEmpty()) {
-                    poolReleases = catalog.albums().filter { it.songs.isNotEmpty() }
-                }
-            }
-        }
-        Log.i(
-            TAG,
-            "adoptSession '${sess.displayName}' kind=${sess.kind} " +
-                "pool=${poolReleases.size} shuffle=${sess.prefs.shuffle}"
-        )
-    }
-
-    fun ensureAutoPlaySession(seedSong: Song?, finishedSource: ColdSource?): RadioSession {
-        session?.takeIf { it.active }?.let { return it }
-        val artist = seedSong?.effectiveAlbumArtist
-            ?: seedSong?.artist
-            ?: finishedSource?.title
-            ?: finishedSource?.id?.substringBefore('|')
-            ?: "Radio"
-        return startArtistRadio(artist.trim().ifBlank { "Radio" })
-    }
-
-    fun updatePrefs(prefs: RadioSourcePrefs) {
-        val s = session ?: return
-        session = s.copy(prefs = prefs)
-        Log.i(
-            TAG,
-            "prefs shuffle=${prefs.shuffle} unit=${prefs.shuffleUnit} max=${prefs.maxRadioQueue} " +
-                "lib=${prefs.useLibraryDiscovery} jf=${prefs.useJellyfinInstantMix} " +
-                "sub=${prefs.useSubsonicSimilar} mono=${prefs.useMonochromeDiscovery}"
-        )
-    }
-
-    fun setShufflePrefs(enabled: Boolean): RadioSourcePrefs? {
-        val s = session ?: return null
-        if (s.prefs.shuffle == enabled) return null
-        val next = s.prefs.copy(shuffle = enabled)
-        session = s.copy(prefs = next)
-        Log.i(TAG, "prefs shuffle=${next.shuffle} unit=${next.shuffleUnit} max=${next.maxRadioQueue}")
-        return next
-    }
-
-    fun toggleShufflePrefs(): RadioSourcePrefs? {
-        val s = session ?: return null
-        return setShufflePrefs(!s.prefs.shuffle)
-    }
-
-    fun stopRadio() {
-        session = null
-        poolReleases = emptyList()
-        Log.i(TAG, "radio stopped")
-    }
-
-    fun noteSource(source: ColdSource?) {
-        if (source?.type != ColdSourceType.ALBUM && source?.type != ColdSourceType.RADIO) return
-        val id = source.id.takeIf { it.isNotBlank() } ?: return
-        memory.note(id, ReleaseKind.UNKNOWN)
-    }
-
-    fun planBatch(
-        seedSong: Song? = null,
-        finishedSource: ColdSource? = null,
-        excludeKeys: Set<String> = emptySet()
-    ): RadioBatch? {
-        val sess = session?.takeIf { it.active } ?: return null
-        val prefs = sess.prefs
-        val max = prefs.maxRadioQueue.coerceIn(1, 500)
-        val releases = availableReleases(excludeKeys)
-        if (releases.isEmpty()) {
-            Log.i(TAG, "planBatch: no releases")
-            return null
-        }
-
-        val songs = when {
-            !prefs.shuffle -> planReleaseBlocks(releases, max, excludeKeys)
-            prefs.shuffleUnit == RadioShuffleUnit.RELEASES ->
-                planShuffledReleases(releases, max, excludeKeys)
-            else -> planShuffledSongs(releases, max, excludeKeys)
-        }
-        if (songs.isEmpty()) return null
-
-        songs.forEach { s ->
-            val k = albumKeyOf(s)
-            if (k.isNotBlank()) memory.note(k, ReleaseKind.UNKNOWN)
-        }
-
-        val source = ColdSource(
-            type = ColdSourceType.RADIO,
-            id = sess.seedId ?: sess.displayName,
-            title = sess.displayName
-        )
-        val reason = when {
-            !prefs.shuffle -> "release-blocks"
-            prefs.shuffleUnit == RadioShuffleUnit.RELEASES -> "shuffle-releases"
-            else -> "shuffle-songs"
-        }
-        Log.i(
-            TAG,
-            "planBatch '${sess.displayName}' songs=${songs.size} " +
-                "shuffle=${prefs.shuffle} unit=${prefs.shuffleUnit} max=$max pool=${releases.size}"
-        )
-        return RadioBatch(
-            songs = songs,
-            source = source,
-            session = sess,
-            reason = reason
-        )
-    }
-
-    fun restockSongs(
-        currentColdSize: Int,
-        alreadyQueuedKeys: Set<String>
-    ): List<Song> {
-        val sess = session?.takeIf { it.active } ?: return emptyList()
-        val max = sess.prefs.maxRadioQueue.coerceIn(1, 500)
-        val prefs = sess.prefs
-
-        if (prefs.shuffle && prefs.shuffleUnit == RadioShuffleUnit.SONGS) {
-            val need = max - currentColdSize
-            if (need <= 0) return emptyList()
-            val pool = songPool(availableReleases(emptySet()))
-                .filter { songKey(it) !in alreadyQueuedKeys }
-            if (pool.isEmpty()) {
-                Log.i(TAG, "restock songs: empty pool (cold=$currentColdSize max=$max)")
-                return emptyList()
-            }
-            val pick = pool.shuffled(Random(System.nanoTime())).take(need)
-            Log.i(TAG, "restock songs +${pick.size} (cold was $currentColdSize / $max)")
-            return pick
-        }
-
-        // Ordered or RELEASES: pull next whole release whenever under max
-        if (currentColdSize >= max) return emptyList()
-
-        val next = if (prefs.shuffle && prefs.shuffleUnit == RadioShuffleUnit.RELEASES) {
-            nextShuffledRelease(alreadyQueuedKeys)
-        } else {
-            nextOrderedRelease(alreadyQueuedKeys)
-        } ?: run {
-            Log.i(TAG, "restock release: no candidate (cold=$currentColdSize max=$max)")
-            return emptyList()
-        }
-
-        val tracks = sortedTracks(next).filter { songKey(it) !in alreadyQueuedKeys }
-        if (tracks.isEmpty()) return emptyList()
-        memory.note(ReleaseClassifier.releaseKey(next), ReleaseClassifier.kindOf(next))
-        Log.i(
-            TAG,
-            "restock release +${tracks.size} from '${next.displayName}' " +
-                "(cold was $currentColdSize / $max)"
-        )
-        return tracks
-    }
-
-    fun maybePlan(
-        seedSong: Song?,
-        finishedSource: ColdSource?,
-        repeatMode: RepeatMode
-    ): RadioBatch? {
-        val radioActive = session?.active == true
-        if (!radioActive && !settings.isAutoPlayRecommendedEnabled()) {
-            Log.d(TAG, "skip — no session & auto-play off")
-            return null
-        }
-        if (repeatMode != RepeatMode.OFF) return null
-
-        if (session?.active != true) {
-            ensureAutoPlaySession(seedSong, finishedSource)
-        }
-        return planBatch(seedSong, finishedSource)
-    }
-
-    // ── planning helpers ──────────────────────────────────────────────────
-
-    private fun planShuffledSongs(
-        releases: List<AlbumItem>,
-        max: Int,
-        excludeAlbumKeys: Set<String>
-    ): List<Song> {
-        val pool = songPool(
-            releases.filter { ReleaseClassifier.releaseKey(it) !in excludeAlbumKeys }
-        )
-        if (pool.isEmpty()) return emptyList()
-        return pool.shuffled(Random(System.nanoTime())).take(max)
-    }
-
-    private fun planShuffledReleases(
-        releases: List<AlbumItem>,
-        max: Int,
-        excludeAlbumKeys: Set<String>
-    ): List<Song> {
-        val pool = releases
-            .filter { ReleaseClassifier.releaseKey(it) !in excludeAlbumKeys && it.songs.isNotEmpty() }
-            .shuffled(Random(System.nanoTime()))
-        val out = ArrayList<Song>(max + 32)
-        for (rel in pool) {
-            val tracks = sortedTracks(rel)
-            if (tracks.isEmpty()) continue
-            out.addAll(tracks)
-            memory.note(ReleaseClassifier.releaseKey(rel), ReleaseClassifier.kindOf(rel))
-            if (out.size >= max) break
-        }
-        return out
-    }
-
-    private fun planReleaseBlocks(
-        releases: List<AlbumItem>,
-        max: Int,
-        excludeAlbumKeys: Set<String>
-    ): List<Song> {
-        val ordered = orderedReleases(releases, excludeAlbumKeys)
-        val out = ArrayList<Song>(max + 32)
-        for (rel in ordered) {
-            val tracks = sortedTracks(rel)
-            if (tracks.isEmpty()) continue
-            out.addAll(tracks)
-            memory.note(ReleaseClassifier.releaseKey(rel), ReleaseClassifier.kindOf(rel))
-            if (out.size >= max) break
-        }
-        return out
-    }
-
-    private fun nextOrderedRelease(alreadyQueuedKeys: Set<String>): AlbumItem? {
-        val ordered = orderedReleases(availableReleases(emptySet()), emptySet())
-        for (rel in ordered) {
-            val tracks = sortedTracks(rel)
-            if (tracks.isEmpty()) continue
-            val allQueued = tracks.all { songKey(it) in alreadyQueuedKeys }
-            if (!allQueued) return rel
-        }
-        return null
-    }
-
-    private fun nextShuffledRelease(alreadyQueuedKeys: Set<String>): AlbumItem? {
-        val candidates = availableReleases(emptySet()).filter { rel ->
-            val tracks = sortedTracks(rel)
-            tracks.isNotEmpty() && tracks.any { songKey(it) !in alreadyQueuedKeys }
-        }
-        if (candidates.isEmpty()) return null
-        return candidates.random(Random(System.nanoTime()))
-    }
-
-    private fun orderedReleases(
-        releases: List<AlbumItem>,
-        excludeAlbumKeys: Set<String>
-    ): List<AlbumItem> =
-        releases
-            .filter { ReleaseClassifier.releaseKey(it) !in excludeAlbumKeys }
-            .sortedWith(
-                compareByDescending<AlbumItem> {
-                    it.songs.mapNotNull { s -> s.year }.maxOrNull() ?: Int.MIN_VALUE
-                }.thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayName }
-            )
-
-    private fun sortedTracks(rel: AlbumItem): List<Song> =
-        rel.songs.sortedWith(
-            compareBy<Song> { it.discNumber ?: 1 }
-                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
-                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
-        )
-
-    private fun availableReleases(excludeKeys: Set<String>): List<AlbumItem> {
-        val base = if (poolReleases.isNotEmpty()) poolReleases else catalog.albums()
-        return base.filter { it.songs.isNotEmpty() && ReleaseClassifier.releaseKey(it) !in excludeKeys }
-    }
-
-    private fun songPool(releases: List<AlbumItem>): List<Song> =
-        releases.flatMap { it.songs }.distinctBy { songKey(it) }
-
-    private fun releasesForArtist(artistName: String): List<AlbumItem> {
-        val norm = artistKey(artistName) ?: return emptyList()
-        return catalog.albums().filter { album ->
-            artistKey(album.artist) == norm ||
-                album.songs.any { s ->
-                    artistKey(s.effectiveAlbumArtist) == norm ||
-                        artistKey(s.artist) == norm ||
-                        s.creditArtists.any { artistKey(it) == norm }
-                }
-        }
-    }
-
-    private fun rebuildPoolFromConfig(config: ReleasePoolConfig) {
-        val keys = config.artistKeys.mapNotNull { artistKey(it) }.toSet()
-        poolReleases = if (keys.isEmpty()) {
-            catalog.albums().filter { it.songs.isNotEmpty() }
-        } else {
-            catalog.albums().filter { album ->
-                album.songs.isNotEmpty() && (
-                    artistKey(album.artist)?.let { it in keys } == true ||
-                        album.songs.any { s ->
-                            artistKey(s.effectiveAlbumArtist)?.let { it in keys } == true ||
-                                artistKey(s.artist)?.let { it in keys } == true ||
-                                s.creditArtists.any { artistKey(it)?.let { k -> k in keys } == true }
-                        }
-                    )
-            }
-        }
-    }
-
-    private fun albumKeyOf(s: Song): String {
-        val a = (s.effectiveAlbumArtist ?: "").trim().lowercase()
-        val n = (s.album ?: "").trim().lowercase()
-        return "$a|$n"
-    }
-
-    private fun songKey(s: Song): String =
-        s.path?.lowercase() ?: s.contentUri.toString()
-
-    companion object {
-        private const val TAG = "YuriPlayer.Radio"
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioModels.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioModels.kt
index 2712299b..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioModels.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioModels.kt
@@ -1,134 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import capital.yuri.yuriplayer.data.AlbumItem
-import capital.yuri.yuriplayer.data.Song
-import capital.yuri.yuriplayer.player.ColdSource
-import capital.yuri.yuriplayer.player.RepeatMode
-import kotlinx.serialization.Serializable
-
-enum class ReleaseKind {
-    LP,
-    EP,
-    SINGLE,
-    UNKNOWN
-}
-
-data class RadioPick(
-    val album: AlbumItem,
-    val source: ColdSource,
-    val kind: ReleaseKind,
-    val algorithmId: String,
-    val reason: String = ""
-)
-
-/**
- * A planned radio segment: the songs RadioEngine wants in the cold queue.
- * Queue UI shows this list as the radio cold queue.
- */
-data class RadioBatch(
-    val songs: List<Song>,
-    val source: ColdSource,
-    val session: RadioSession,
-    val reason: String = ""
-)
-
-data class RadioContext(
-    val seedSong: Song?,
-    val finishedSource: ColdSource?,
-    val repeatMode: RepeatMode,
-    val focusArtistKeys: Set<String> = emptySet(),
-    val focusGenreKeys: Set<String> = emptySet()
-)
-
-@Serializable
-data class RadioPlaybackConfig(
-    val avoidRecentLps: Int = 1,
-    val avoidRecentEps: Int = 1,
-    val avoidRecentSingles: Int = 1,
-    val globalRecentExclude: Int = 1,
-    val weightLp: Float = 1.0f,
-    val weightEp: Float = 1.0f,
-    val weightSingle: Float = 0.85f,
-    val softPenaltyFactor: Float = 0.55f,
-    val softHistorySize: Int = 12,
-    val sameArtistBias: Float = 1.0f
-)
-
-@Serializable
-data class ReleasePoolConfig(
-    val artistKeys: List<String> = emptyList(),
-    val genreKeys: List<String> = emptyList(),
-    val includeLps: Boolean = true,
-    val includeEps: Boolean = true,
-    val includeSingles: Boolean = true,
-    val allowExternalFetch: Boolean = false,
-    val avoidRecentPerKind: Int = 1
-)
-
-/** How shuffle fills the radio cold queue. */
-@Serializable
-enum class RadioShuffleUnit {
-    /** Random tracks from the whole pool (default). */
-    SONGS,
-    /** Random order of whole LP/EP/Single blocks; tracks stay in release order. */
-    RELEASES
-}
-
-/**
- * Per radio-source preferences (artist / album / playlist station).
- *
- * Defaults: shuffle ON with [RadioShuffleUnit.SONGS]. Ordered whole-release
- * mode remains available by turning shuffle off.
- *
- * Discovery flags: combine any set of sources for similar artists/songs.
- */
-@Serializable
-data class RadioSourcePrefs(
-    /**
-     * true  → use [shuffleUnit] to fill cold up to [maxRadioQueue].
-     * false → whole LP/EP/Single blocks in year-desc order (legacy ordered mode).
-     */
-    val shuffle: Boolean = true,
-    val shuffleUnit: RadioShuffleUnit = RadioShuffleUnit.SONGS,
-    val maxRadioQueue: Int = DEFAULT_MAX_RADIO_QUEUE,
-    /** On-device catalog / already-scanned sources. */
-    val useLibraryDiscovery: Boolean = true,
-    /** Jellyfin Instant Mix when a matching item exists on an enabled server. */
-    val useJellyfinInstantMix: Boolean = false,
-    /** Subsonic / OpenSubsonic similar-songs / similar-artists. */
-    val useSubsonicSimilar: Boolean = false,
-    /**
-     * monochrome.tf community hifi-api recommendations
-     * (`/recommendations`, `/artist/similar`, `/mix`) — discovery only.
-     */
-    val useMonochromeDiscovery: Boolean = false
-) {
-    companion object {
-        const val DEFAULT_MAX_RADIO_QUEUE = 50
-    }
-}
-
-@Serializable
-enum class RadioAlgorithmId {
-    PLAYBACK,
-    RELEASE_POOL
-}
-
-@Serializable
-enum class RadioSessionKind {
-    ARTIST,
-    ALBUM,
-    PLAYLIST,
-    CUSTOM
-}
-
-@Serializable
-data class RadioSession(
-    val kind: RadioSessionKind,
-    val displayName: String,
-    val algorithmId: RadioAlgorithmId,
-    val seedId: String? = null,
-    val seedTitle: String? = null,
-    val active: Boolean = true,
-    val prefs: RadioSourcePrefs = RadioSourcePrefs()
-)
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt
index 9f354843..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt
@@ -1,144 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import android.util.Log
-import capital.yuri.yuriplayer.data.AlbumItem
-import capital.yuri.yuriplayer.data.artistKey
-import capital.yuri.yuriplayer.player.ColdSource
-import capital.yuri.yuriplayer.player.ColdSourceType
-import kotlin.math.pow
-import kotlin.random.Random
-
-/**
- * Continuous radio after a queue ends: prefer the seed artist, avoid repeating
- * the same LP / EP / Single too soon, weighted random among the rest.
- *
- * Entropy levers ([RadioPlaybackConfig]):
- * 1. **Hard per-kind cooldown** — last N LPs / EPs / Singles never candidates
- * 2. **Global cooldown** — last M releases of any kind excluded
- * 3. **Soft history penalty** — older plays still eligible but down-weighted
- * 4. **Type weights** — bias toward LPs vs singles
- * 5. **Weighted sample** — not uniform; uses (typeWeight × softPenalty)
- *
- * Future settings UI can expose these without changing the algorithm class.
- */
-class RadioPlaybackAlgorithm(
-    var config: RadioPlaybackConfig = RadioPlaybackConfig()
-) : RadioAlgorithm {
-
-    override val id: RadioAlgorithmId = RadioAlgorithmId.PLAYBACK
-
-    override fun pick(
-        catalog: ReleaseCatalog,
-        context: RadioContext,
-        memory: RecentReleaseMemory
-    ): RadioPick? {
-        val focus = context.focusArtistKeys
-        if (focus.isEmpty()) {
-            Log.i(TAG, "no focus artists")
-            return null
-        }
-
-        val all = catalog.albums().filter { it.songs.isNotEmpty() }
-        val sameArtist = all.filter { albumMatchesFocus(it, focus) }
-        if (sameArtist.isEmpty()) {
-            Log.i(TAG, "no albums for focus=$focus")
-            return null
-        }
-
-        val softOrder = memory.softOrderNewestFirst()
-        val softIndex = softOrder.mapIndexed { i, k -> k.lowercase() to i }.toMap()
-
-        data class Cand(val album: AlbumItem, val key: String, val kind: ReleaseKind, val weight: Double)
-
-        val candidates = sameArtist.mapNotNull { album ->
-            val key = ReleaseClassifier.releaseKey(album)
-            val kind = ReleaseClassifier.kindOf(album)
-            val hard = memory.hardExclude(
-                kind = kind,
-                perKind = perKindLimit(kind),
-                globalCount = config.globalRecentExclude
-            )
-            if (key in hard || hard.any { it.equals(key, true) }) return@mapNotNull null
-
-            val typeW = typeWeight(kind).toDouble().coerceAtLeast(0.01)
-            val softIdx = softIndex[key.lowercase()]
-            val softW = if (softIdx == null) {
-                1.0
-            } else {
-                config.softPenaltyFactor.toDouble().pow(softIdx + 1)
-                    .coerceAtLeast(0.05)
-            }
-            Cand(album, key, kind, typeW * softW)
-        }
-
-        if (candidates.isEmpty()) {
-            // Exhausted hard filters — fall back to anything same-artist except
-            // the single most recent global key so radio never dead-ends.
-            val last = memory.softOrderNewestFirst().firstOrNull()
-            val fallback = sameArtist.filter {
-                ReleaseClassifier.releaseKey(it) != last
-            }.ifEmpty { sameArtist }
-            val album = fallback[Random.nextInt(fallback.size)]
-            return toPick(album, "fallback-after-cooldown")
-        }
-
-        val picked = weightedSample(candidates) { it.weight } ?: return null
-        return toPick(picked.album, "weighted kind=${picked.kind} w=${"%.2f".format(picked.weight)}")
-    }
-
-    private fun perKindLimit(kind: ReleaseKind): Int = when (kind) {
-        ReleaseKind.LP -> config.avoidRecentLps
-        ReleaseKind.EP -> config.avoidRecentEps
-        ReleaseKind.SINGLE -> config.avoidRecentSingles
-        ReleaseKind.UNKNOWN -> config.globalRecentExclude
-    }
-
-    private fun typeWeight(kind: ReleaseKind): Float = when (kind) {
-        ReleaseKind.LP -> config.weightLp
-        ReleaseKind.EP -> config.weightEp
-        ReleaseKind.SINGLE -> config.weightSingle
-        ReleaseKind.UNKNOWN -> 0.5f
-    }
-
-    private fun albumMatchesFocus(album: AlbumItem, focus: Set<String>): Boolean {
-        val a = artistKey(album.artist)
-        if (a != null && a in focus) return true
-        return album.songs.any { song ->
-            artistKey(song.effectiveAlbumArtist)?.let { it in focus } == true ||
-                artistKey(song.artist)?.let { it in focus } == true ||
-                song.creditArtists.any { artistKey(it)?.let { k -> k in focus } == true }
-        }
-    }
-
-    private fun toPick(album: AlbumItem, reason: String): RadioPick {
-        val key = ReleaseClassifier.releaseKey(album)
-        val kind = ReleaseClassifier.kindOf(album)
-        return RadioPick(
-            album = album,
-            source = ColdSource(
-                type = ColdSourceType.ALBUM,
-                id = key,
-                title = album.name
-            ),
-            kind = kind,
-            algorithmId = id.name,
-            reason = reason
-        )
-    }
-
-    private fun <T> weightedSample(items: List<T>, weight: (T) -> Double): T? {
-        if (items.isEmpty()) return null
-        val total = items.sumOf { weight(it).coerceAtLeast(0.0) }
-        if (total <= 0.0) return items[Random.nextInt(items.size)]
-        var r = Random.nextDouble() * total
-        for (item in items) {
-            r -= weight(item).coerceAtLeast(0.0)
-            if (r <= 0.0) return item
-        }
-        return items.last()
-    }
-
-    companion object {
-        private const val TAG = "YuriPlayer.RadioPlay"
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt
index 9736712d..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt
@@ -1,47 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-/**
- * Per-kind + global recent release keys for hard cooldowns and soft weighting.
- * In-memory for now; RadioEngine can persist later with playback state.
- */
-class RecentReleaseMemory(
-    private val softCapacity: Int = 12
-) {
-    private val byKind = mutableMapOf<
-        ReleaseKind,
-        ArrayDeque<String>
-    >(
-        ReleaseKind.LP to ArrayDeque(),
-        ReleaseKind.EP to ArrayDeque(),
-        ReleaseKind.SINGLE to ArrayDeque(),
-        ReleaseKind.UNKNOWN to ArrayDeque()
-    )
-
-    private val global = ArrayDeque<String>()
-
-    fun note(key: String, kind: ReleaseKind) {
-        if (key.isBlank() || key == "|") return
-        push(byKind.getOrPut(kind) { ArrayDeque() }, key, max = 8)
-        push(global, key, max = softCapacity.coerceAtLeast(8))
-    }
-
-    fun hardExclude(
-        kind: ReleaseKind,
-        perKind: Int,
-        globalCount: Int
-    ): Set<String> = buildSet {
-        byKind[kind]?.takeLast(perKind.coerceAtLeast(0))?.let { addAll(it) }
-        global.takeLast(globalCount.coerceAtLeast(0)).let { addAll(it) }
-    }
-
-    /** Index 0 = most recent. Used for soft weight decay. */
-    fun softOrderNewestFirst(): List<String> = global.toList().asReversed()
-
-    fun lastOf(kind: ReleaseKind): String? = byKind[kind]?.lastOrNull()
-
-    private fun push(q: ArrayDeque<String>, key: String, max: Int) {
-        q.removeAll { it.equals(key, ignoreCase = true) }
-        q.addLast(key)
-        while (q.size > max) q.removeFirst()
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt
index 859be4e2..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt
@@ -1,26 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import capital.yuri.yuriplayer.data.AlbumItem
-
-/**
- * Heuristic release typing until tags/MB release-group types are reliable.
- * Matches the Spotify-ish bands we already use on artist pages.
- */
-object ReleaseClassifier {
-
-    fun kindOf(album: AlbumItem): ReleaseKind {
-        val n = album.trackCount
-        return when {
-            n <= 0 -> ReleaseKind.UNKNOWN
-            n == 1 -> ReleaseKind.SINGLE
-            n <= 6 -> ReleaseKind.EP
-            else -> ReleaseKind.LP
-        }
-    }
-
-    fun releaseKey(album: AlbumItem): String {
-        val a = (album.artist ?: "").trim().lowercase()
-        val n = (album.name ?: "").trim().lowercase()
-        return "$a|$n"
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt b/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt
index b7af3fc6..35c56c61 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt
@@ -1,104 +1,3 @@
 package capital.yuri.yuriplayer.player.radio
 
-import android.util.Log
-import capital.yuri.yuriplayer.data.AlbumItem
-import capital.yuri.yuriplayer.data.artistKey
-import capital.yuri.yuriplayer.player.ColdSource
-import capital.yuri.yuriplayer.player.ColdSourceType
-import kotlin.random.Random
-
-/**
- * Draws random releases from a user-defined artist (and later genre) pool.
- * Used for playlist-derived radios and explicit “station” configs.
- *
- * Network: [ExternalReleaseSource] is consulted only when
- * [ReleasePoolConfig.allowExternalFetch] is true **and** the source is enabled.
- * Default is local-only — privacy gate stays closed until the user opts in.
- */
-class ReleasePoolAlgorithm(
-    var config: ReleasePoolConfig = ReleasePoolConfig(),
-    private val external: ExternalReleaseSource = NoExternalReleaseSource
-) : RadioAlgorithm {
-
-    override val id: RadioAlgorithmId = RadioAlgorithmId.RELEASE_POOL
-
-    override fun pick(
-        catalog: ReleaseCatalog,
-        context: RadioContext,
-        memory: RecentReleaseMemory
-    ): RadioPick? {
-        val artistFocus = (config.artistKeys.mapNotNull { artistKey(it) } +
-            context.focusArtistKeys).toSet()
-
-        if (artistFocus.isEmpty() && config.genreKeys.isEmpty()) {
-            Log.i(TAG, "empty pool")
-            return null
-        }
-
-        var pool = catalog.albums().filter { it.songs.isNotEmpty() }
-
-        if (artistFocus.isNotEmpty()) {
-            pool = pool.filter { albumMatchesArtists(it, artistFocus) }
-        }
-        // genreKeys: no genre tags in catalog yet — reserved filter
-
-        pool = pool.filter { album ->
-            when (ReleaseClassifier.kindOf(album)) {
-                ReleaseKind.LP -> config.includeLps
-                ReleaseKind.EP -> config.includeEps
-                ReleaseKind.SINGLE -> config.includeSingles
-                ReleaseKind.UNKNOWN -> true
-            }
-        }
-
-        if (config.allowExternalFetch && external.isEnabled) {
-            // Stub: merge external candidates when privacy gate opens.
-            val remote = external.fetchCandidates(context)
-            if (remote.isNotEmpty()) {
-                Log.i(TAG, "external returned ${remote.size} (not persisted)")
-                pool = pool + remote.filter { it.songs.isNotEmpty() }
-            }
-        }
-
-        if (pool.isEmpty()) {
-            Log.i(TAG, "no local releases in pool artists=$artistFocus")
-            return null
-        }
-
-        val filtered = pool.filter { album ->
-            val key = ReleaseClassifier.releaseKey(album)
-            val kind = ReleaseClassifier.kindOf(album)
-            val hard = memory.hardExclude(
-                kind = kind,
-                perKind = config.avoidRecentPerKind,
-                globalCount = config.avoidRecentPerKind
-            )
-            key !in hard && hard.none { it.equals(key, true) }
-        }.ifEmpty { pool }
-
-        val album = filtered[Random.nextInt(filtered.size)]
-        val key = ReleaseClassifier.releaseKey(album)
-        val kind = ReleaseClassifier.kindOf(album)
-        Log.i(TAG, "pool pick '${album.displayName}' kind=$kind from ${filtered.size}")
-        return RadioPick(
-            album = album,
-            source = ColdSource(ColdSourceType.ALBUM, key, album.name),
-            kind = kind,
-            algorithmId = id.name,
-            reason = "pool artists=${artistFocus.size}"
-        )
-    }
-
-    private fun albumMatchesArtists(album: AlbumItem, focus: Set<String>): Boolean {
-        artistKey(album.artist)?.let { if (it in focus) return true }
-        return album.songs.any { song ->
-            artistKey(song.effectiveAlbumArtist)?.let { it in focus } == true ||
-                artistKey(song.artist)?.let { it in focus } == true ||
-                song.creditArtists.any { artistKey(it)?.let { k -> k in focus } == true }
-        }
-    }
-
-    companion object {
-        private const val TAG = "YuriPlayer.RadioPool"
-    }
-}
+// Moved to :core (commonMain), same package.
diff --git a/app/src/main/java/capital/yuri/yuriplayer/ui/TestTags.kt b/app/src/main/java/capital/yuri/yuriplayer/ui/TestTags.kt
index 3363005e..c165a546 100644
--- a/app/src/main/java/capital/yuri/yuriplayer/ui/TestTags.kt
+++ b/app/src/main/java/capital/yuri/yuriplayer/ui/TestTags.kt
@@ -5,8 +5,11 @@ package capital.yuri.yuriplayer.ui
  * Keep these stable — instrumented tests and Maestro flows both use them.
  */
 object TestTags {
+    const val TAB_HOME = "tab_home"
     const val TAB_MY_STUFF = "tab_my_stuff"
     const val TAB_EXPLORE = "tab_explore"
+    /** Alias — Explore used to be labeled Search. */
+    const val TAB_SEARCH = TAB_EXPLORE
     const val SETTINGS = "settings"
 
     const val MYSTUFF_PINS = "mystuff_pins"
diff --git a/app/src/test/java/capital/yuri/yuriplayer/data/CatalogIdentityTest.kt b/app/src/test/java/capital/yuri/yuriplayer/data/CatalogIdentityTest.kt
index 1fd64336..6b0ea5aa 100644
--- a/app/src/test/java/capital/yuri/yuriplayer/data/CatalogIdentityTest.kt
+++ b/app/src/test/java/capital/yuri/yuriplayer/data/CatalogIdentityTest.kt
@@ -1,6 +1,5 @@
 package capital.yuri.yuriplayer.data
 
-import android.net.Uri
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertFalse
 import org.junit.Assert.assertTrue
@@ -221,7 +220,7 @@ private fun song(
     artist = artist,
     albumArtist = artist,
     album = album,
-    contentUri = Uri.parse("file:///$key"),
+    contentUri = "file:///$key",
     trackNumber = tn,
     discNumber = disc,
     path = path ?: "/music/$key/$album/${tn ?: 0}. $title.flac"
diff --git a/build.gradle.kts b/build.gradle.kts
index ab540e18..b136521d 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -1,7 +1,12 @@
 // Top-level build file where you can add configuration options common to all sub-projects/modules.
 plugins {
     alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.android.kmp.library) apply false
+    alias(libs.plugins.kotlin.multiplatform) apply false
+    alias(libs.plugins.kotlin.jvm) apply false
     alias(libs.plugins.kotlin.compose) apply false
     alias(libs.plugins.kotlin.serialization) apply false
+    alias(libs.plugins.compose.multiplatform) apply false
     alias(libs.plugins.ksp) apply false
+    alias(libs.plugins.androidx.room) apply false
 }
diff --git a/components/build.gradle.kts b/components/build.gradle.kts
new file mode 100644
index 00000000..9d541458
--- /dev/null
+++ b/components/build.gradle.kts
@@ -0,0 +1,44 @@
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+    alias(libs.plugins.android.kmp.library)
+    alias(libs.plugins.kotlin.compose)
+}
+
+kotlin {
+    android {
+        namespace = "capital.yuri.yuriplayer.components"
+        compileSdk = 36
+        minSdk = 27
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+        }
+    }
+    jvm {
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
+        }
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            implementation(project(":core"))
+            implementation(libs.jetbrains.compose.runtime)
+            implementation(libs.jetbrains.compose.foundation)
+            implementation(libs.jetbrains.compose.ui)
+            implementation(libs.jetbrains.compose.material3)
+            implementation(libs.jetbrains.compose.material.icons.extended)
+            implementation(libs.kotlinx.coroutines.core)
+            implementation(libs.coil.compose)
+            implementation(libs.coil.network.ktor3)
+        }
+        androidMain.dependencies {
+            implementation(libs.kotlinx.coroutines.android)
+        }
+        jvmMain.dependencies {
+            implementation(libs.ktor.client.cio)
+        }
+        jvmTest.dependencies {
+            implementation(kotlin("test"))
+        }
+    }
+}
diff --git a/components/src/androidMain/AndroidManifest.xml b/components/src/androidMain/AndroidManifest.xml
new file mode 100644
index 00000000..cc947c56
--- /dev/null
+++ b/components/src/androidMain/AndroidManifest.xml
@@ -0,0 +1 @@
+<manifest />
diff --git a/components/src/androidMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.android.kt b/components/src/androidMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.android.kt
new file mode 100644
index 00000000..4e730847
--- /dev/null
+++ b/components/src/androidMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.android.kt
@@ -0,0 +1,12 @@
+package capital.yuri.yuriplayer.components.platform
+
+import android.content.res.Resources
+import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.IntSize
+
+actual fun screenSizePx(): IntSize {
+    val metrics = Resources.getSystem().displayMetrics
+    return IntSize(metrics.widthPixels, metrics.heightPixels)
+}
+
+actual fun windowPositionOnScreenPx(): IntOffset = IntOffset.Zero
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/OfflineBanner.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/OfflineBanner.kt
new file mode 100644
index 00000000..b8cec0c4
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/OfflineBanner.kt
@@ -0,0 +1,47 @@
+package capital.yuri.yuriplayer.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.LinkOff
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.i18n.LocalStrings
+
+/**
+ * Thin, full-width "No internet" strip shown while [NetworkMonitor] reports
+ * offline. Mobile renders it under the navbar; desktop renders it under the
+ * search bar at the top of the main view.
+ */
+@Composable
+fun OfflineBanner(modifier: Modifier = Modifier) {
+    Row(
+        modifier = modifier
+            .fillMaxWidth()
+            .background(MaterialTheme.colorScheme.errorContainer)
+            .padding(horizontal = 12.dp, vertical = 6.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Icon(
+            Icons.Default.LinkOff,
+            contentDescription = null,
+            tint = MaterialTheme.colorScheme.onErrorContainer
+        )
+        Spacer(Modifier.width(8.dp))
+        val strings = LocalStrings.current
+        Text(
+            strings.noInternet,
+            color = MaterialTheme.colorScheme.onErrorContainer,
+            style = MaterialTheme.typography.bodySmall
+        )
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/album/AlbumPage.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/album/AlbumPage.kt
new file mode 100644
index 00000000..7314211c
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/album/AlbumPage.kt
@@ -0,0 +1,276 @@
+package capital.yuri.yuriplayer.components.album
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.BoxWithConstraints
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.filled.Edit
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.layout.WindowWidthClass
+import capital.yuri.yuriplayer.components.layout.windowWidthClass
+import capital.yuri.yuriplayer.components.list.LikeHeart
+import capital.yuri.yuriplayer.components.list.TrackRow
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.AlbumPageModel
+import capital.yuri.yuriplayer.components.model.TrackRowModel
+import capital.yuri.yuriplayer.components.theme.AlbumArtBackdrop
+import capital.yuri.yuriplayer.components.theme.rememberCoverColors
+
+@Composable
+fun AlbumPage(
+    album: AlbumPageModel,
+    playing: Boolean,
+    onBack: () -> Unit,
+    onPlay: () -> Unit,
+    onTrack: (Int) -> Unit,
+    onEdit: () -> Unit = {},
+    onEditTrack: (Int) -> Unit = {},
+    onArtist: (String) -> Unit = {},
+    liked: Boolean = false,
+    onToggleLike: () -> Unit = {},
+    likedTrackIds: Set<String> = emptySet(),
+    onToggleTrackLike: (String) -> Unit = {},
+    songMenu: (TrackRowModel) -> List<out MenuEntry> = { emptyList() },
+    onSources: (TrackRowModel) -> Unit = {},
+    modifier: Modifier = Modifier
+) {
+    val coverColors by rememberCoverColors(
+        artworkUri = album.artworkUri,
+        audioPath = album.tracks.firstOrNull()?.id
+    )
+    AlbumArtBackdrop(
+        wash = coverColors?.container ?: Color.Transparent,
+        accent = coverColors?.accent ?: Color.Transparent,
+        modifier = modifier
+            .fillMaxSize()
+            .background(MaterialTheme.colorScheme.background)
+    ) {
+        BoxWithConstraints(Modifier.fillMaxSize()) {
+            val widthClass = windowWidthClass(maxWidth)
+            when (widthClass) {
+                WindowWidthClass.Compact -> AlbumPageCompact(
+                    album, playing, onBack, onPlay, onTrack, onEdit, onEditTrack, onArtist,
+                    liked, onToggleLike, likedTrackIds, onToggleTrackLike, songMenu, onSources
+                )
+                WindowWidthClass.Medium,
+                WindowWidthClass.Expanded -> AlbumPageWide(
+                    album, playing, onBack, onPlay, onTrack, onEdit, onEditTrack, onArtist,
+                    liked, onToggleLike, likedTrackIds, onToggleTrackLike, songMenu, onSources
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun AlbumPageCompact(
+    album: AlbumPageModel,
+    playing: Boolean,
+    onBack: () -> Unit,
+    onPlay: () -> Unit,
+    onTrack: (Int) -> Unit,
+    onEdit: () -> Unit,
+    onEditTrack: (Int) -> Unit,
+    onArtist: (String) -> Unit,
+    liked: Boolean,
+    onToggleLike: () -> Unit,
+    likedTrackIds: Set<String>,
+    onToggleTrackLike: (String) -> Unit,
+    songMenu: (TrackRowModel) -> List<out MenuEntry>,
+    onSources: (TrackRowModel) -> Unit
+) {
+    Column(Modifier.fillMaxSize()) {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            IconButton(onClick = onBack) {
+                Icon(
+                    Icons.AutoMirrored.Filled.ArrowBack,
+                    contentDescription = "Back",
+                    tint = MaterialTheme.colorScheme.onBackground
+                )
+            }
+            Text("Album", style = MaterialTheme.typography.titleMedium, color = MaterialTheme.colorScheme.onBackground)
+            Spacer(Modifier.weight(1f))
+            LikeHeart(liked = liked, onToggle = onToggleLike)
+            IconButton(onClick = onEdit) {
+                Icon(Icons.Default.Edit, contentDescription = "Edit album")
+            }
+        }
+        CoverArt(
+            model = album.artworkUri,
+            modifier = Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 48.dp)
+                .aspectRatio(1f),
+            corner = 12.dp
+        )
+        AlbumMeta(album, playing, onPlay, onArtist, liked, onToggleLike, Modifier.padding(20.dp))
+        TrackList(album, onTrack, onEditTrack, likedTrackIds, onToggleTrackLike, songMenu, onSources)
+    }
+}
+
+@Composable
+private fun AlbumPageWide(
+    album: AlbumPageModel,
+    playing: Boolean,
+    onBack: () -> Unit,
+    onPlay: () -> Unit,
+    onTrack: (Int) -> Unit,
+    onEdit: () -> Unit,
+    onEditTrack: (Int) -> Unit,
+    onArtist: (String) -> Unit,
+    liked: Boolean,
+    onToggleLike: () -> Unit,
+    likedTrackIds: Set<String>,
+    onToggleTrackLike: (String) -> Unit,
+    songMenu: (TrackRowModel) -> List<out MenuEntry>,
+    onSources: (TrackRowModel) -> Unit
+) {
+    Row(Modifier.fillMaxSize().padding(24.dp)) {
+        Column(
+            Modifier
+                .widthIn(min = 240.dp, max = 360.dp)
+                .padding(end = 28.dp)
+        ) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                IconButton(onClick = onBack) {
+                    Icon(
+                        Icons.AutoMirrored.Filled.ArrowBack,
+                        contentDescription = "Back",
+                        tint = MaterialTheme.colorScheme.onBackground
+                    )
+                }
+                Spacer(Modifier.weight(1f))
+                LikeHeart(liked = liked, onToggle = onToggleLike)
+                IconButton(onClick = onEdit) {
+                    Icon(Icons.Default.Edit, contentDescription = "Edit album")
+                }
+            }
+            CoverArt(
+                model = album.artworkUri,
+                modifier = Modifier.fillMaxWidth().aspectRatio(1f),
+                corner = 12.dp
+            )
+            Spacer(Modifier.height(16.dp))
+            AlbumMeta(album, playing, onPlay, onArtist, liked, onToggleLike)
+        }
+        TrackList(
+            album, onTrack, onEditTrack, likedTrackIds, onToggleTrackLike, songMenu, onSources,
+            modifier = Modifier.weight(1f)
+        )
+    }
+}
+
+@Composable
+private fun AlbumMeta(
+    album: AlbumPageModel,
+    playing: Boolean,
+    onPlay: () -> Unit,
+    onArtist: (String) -> Unit,
+    liked: Boolean,
+    onToggleLike: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(modifier) {
+        Text(
+            album.title,
+            style = MaterialTheme.typography.headlineSmall,
+            fontWeight = FontWeight.Bold,
+            color = MaterialTheme.colorScheme.onBackground
+        )
+        Text(
+            album.artist,
+            style = MaterialTheme.typography.bodyLarge,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f),
+            modifier = Modifier.clickable { onArtist(album.artist) }
+        )
+        val bits = buildList {
+            album.year?.let { add(it.toString()) }
+            add("${album.tracks.size} tracks")
+        }
+        Text(
+            bits.joinToString(" · "),
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f),
+            modifier = Modifier.padding(top = 4.dp)
+        )
+        Row(verticalAlignment = Alignment.CenterVertically, modifier = Modifier.padding(top = 8.dp)) {
+            IconButton(onClick = onPlay) {
+                Icon(
+                    if (playing) Icons.Default.Pause else Icons.Default.PlayArrow,
+                    contentDescription = if (playing) "Pause" else "Play",
+                    tint = MaterialTheme.colorScheme.primary
+                )
+            }
+            LikeHeart(liked = liked, onToggle = onToggleLike)
+        }
+    }
+}
+
+@Composable
+private fun TrackList(
+    album: AlbumPageModel,
+    onTrack: (Int) -> Unit,
+    onEditTrack: (Int) -> Unit = {},
+    likedTrackIds: Set<String> = emptySet(),
+    onToggleTrackLike: (String) -> Unit = {},
+    songMenu: (TrackRowModel) -> List<out MenuEntry> = { emptyList() },
+    onSources: (TrackRowModel) -> Unit = {},
+    modifier: Modifier = Modifier
+) {
+    val discs = album.tracks.groupBy { it.discNumber ?: 1 }
+    val multi = discs.size > 1
+    LazyColumn(modifier.fillMaxSize()) {
+        discs.toSortedMap().forEach { (disc, tracks) ->
+            if (multi) {
+                item(key = "disc-$disc") {
+                    Text(
+                        "Disc $disc",
+                        modifier = Modifier.padding(horizontal = 16.dp, vertical = 8.dp),
+                        style = MaterialTheme.typography.titleSmall,
+                        fontWeight = FontWeight.SemiBold
+                    )
+                }
+            }
+            itemsIndexed(tracks, key = { _, t -> t.id }) { _, track ->
+                val global = album.tracks.indexOfFirst { it.id == track.id }
+                TrackRow(
+                    track = track,
+                    onClick = { onTrack(global.coerceAtLeast(0)) },
+                    onLongClick = { onEditTrack(global.coerceAtLeast(0)) },
+                    showCover = false,
+                    showAlbum = false,
+                    liked = track.id in likedTrackIds,
+                    onToggleLike = { onToggleTrackLike(track.id) },
+                    contextItems = songMenu(track),
+                    onSources = { onSources(track) }
+                )
+            }
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/art/CoverArt.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/art/CoverArt.kt
new file mode 100644
index 00000000..9fdfb11e
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/art/CoverArt.kt
@@ -0,0 +1,64 @@
+package capital.yuri.yuriplayer.components.art
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Album
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+import coil3.compose.AsyncImage
+
+/**
+ * Shared cover. The frame is always 1:1. Non-square art keeps its ratio and
+ * is centered in that square (contain), sitting on [surfaceVariant].
+ */
+@Composable
+fun CoverArt(
+    model: Any?,
+    modifier: Modifier = Modifier,
+    size: Dp? = null,
+    corner: Dp = 8.dp,
+    contentDescription: String? = null,
+    contentScale: ContentScale = ContentScale.Fit,
+    square: Boolean = true
+) {
+    val shape = RoundedCornerShape(corner)
+    val frame = when {
+        size != null -> modifier.size(size)
+        square -> modifier.aspectRatio(1f)
+        else -> modifier
+    }
+    Box(
+        modifier = frame
+            .clip(shape)
+            .background(MaterialTheme.colorScheme.surfaceVariant),
+        contentAlignment = Alignment.Center
+    ) {
+        if (model == null || (model is String && model.isBlank())) {
+            Icon(
+                Icons.Default.Album,
+                contentDescription = contentDescription,
+                tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.35f)
+            )
+        } else {
+            AsyncImage(
+                model = model,
+                contentDescription = contentDescription,
+                modifier = Modifier.fillMaxSize(),
+                contentScale = contentScale,
+                alignment = Alignment.Center
+            )
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/artist/ArtistPage.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/artist/ArtistPage.kt
new file mode 100644
index 00000000..cef6eadd
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/artist/ArtistPage.kt
@@ -0,0 +1,501 @@
+package capital.yuri.yuriplayer.components.artist
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.lazy.rememberLazyListState
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.MoreHoriz
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material.icons.filled.Shuffle
+import androidx.compose.material3.AssistChip
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.FilledIconButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.IconButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.derivedStateOf
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.draw.clipToBounds
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.RectangleShape
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import coil3.compose.AsyncImage
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.list.ContextMenuAnchor
+import capital.yuri.yuriplayer.components.list.LikeHeart
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.list.AlbumCard
+import capital.yuri.yuriplayer.components.list.TrackRow
+import capital.yuri.yuriplayer.components.list.formatTime
+import capital.yuri.yuriplayer.components.model.AlbumPageModel
+import capital.yuri.yuriplayer.components.model.ArtistPageModel
+import capital.yuri.yuriplayer.components.model.TrackRowModel
+
+private enum class DiscoFilter { Popular, Albums, Singles }
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+fun ArtistPage(
+    artist: ArtistPageModel,
+    playing: Boolean,
+    onPlay: () -> Unit,
+    onShuffle: () -> Unit,
+    onTrack: (Int) -> Unit,
+    onOpenAlbum: (AlbumPageModel) -> Unit,
+    modifier: Modifier = Modifier,
+    onChangeHeader: () -> Unit = {},
+    onFetchHeader: () -> Unit = {},
+    onClearHeader: () -> Unit = {},
+    liked: Boolean = false,
+    onToggleLike: () -> Unit = {},
+    likedTrackIds: Set<String> = emptySet(),
+    onToggleTrackLike: (String) -> Unit = {},
+    songMenu: (TrackRowModel) -> List<out MenuEntry> = { emptyList() }
+) {
+    val listState = rememberLazyListState()
+    val mini by remember { derivedStateOf { listState.firstVisibleItemIndex > 0 } }
+    var disco by remember { mutableStateOf(DiscoFilter.Popular) }
+    var more by remember { mutableStateOf(false) }
+    val releases = remember(artist.discography, disco) {
+        when (disco) {
+            DiscoFilter.Popular -> artist.discography
+            DiscoFilter.Albums -> artist.discography.filter { it.releaseKind() == "Album" }
+            DiscoFilter.Singles -> artist.discography.filter { it.releaseKind() != "Album" }
+        }
+    }
+
+    Box(modifier.fillMaxSize().background(MaterialTheme.colorScheme.background)) {
+        LazyColumn(state = listState, modifier = Modifier.fillMaxSize()) {
+            item {
+                ArtistBanner(artist)
+            }
+            item {
+                Row(
+                    Modifier
+                        .fillMaxWidth()
+                        .background(MaterialTheme.colorScheme.background)
+                        .padding(horizontal = 24.dp, vertical = 16.dp),
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(12.dp)
+                ) {
+                    FilledIconButton(
+                        onClick = onPlay,
+                        modifier = Modifier.size(56.dp),
+                        shape = CircleShape,
+                        colors = IconButtonDefaults.filledIconButtonColors(
+                            containerColor = MaterialTheme.colorScheme.primary,
+                            contentColor = MaterialTheme.colorScheme.onPrimary
+                        )
+                    ) {
+                        Icon(
+                            if (playing) Icons.Default.Pause else Icons.Default.PlayArrow,
+                            contentDescription = if (playing) "Pause" else "Play",
+                            modifier = Modifier.size(32.dp)
+                        )
+                    }
+                    IconButton(onClick = onShuffle) {
+                        Icon(
+                            Icons.Default.Shuffle,
+                            contentDescription = "Shuffle",
+                            tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.8f)
+                        )
+                    }
+                    LikeHeart(liked = liked, onToggle = onToggleLike)
+                    IconButton(onClick = { more = true }) {
+                        Icon(
+                            Icons.Default.MoreHoriz,
+                            contentDescription = "More",
+                            tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.8f)
+                        )
+                    }
+                    DropdownMenu(expanded = more, onDismissRequest = { more = false }) {
+                        DropdownMenuItem(
+                            text = { Text("Change header") },
+                            onClick = { more = false; onChangeHeader() }
+                        )
+                        DropdownMenuItem(
+                            text = { Text("Choose from sources") },
+                            onClick = { more = false; onFetchHeader() }
+                        )
+                        DropdownMenuItem(
+                            text = { Text("Clear header") },
+                            onClick = { more = false; onClearHeader() }
+                        )
+                    }
+                }
+            }
+            item {
+                Row(
+                    Modifier
+                        .fillMaxWidth()
+                        .background(MaterialTheme.colorScheme.background)
+                        .padding(horizontal = 24.dp),
+                    horizontalArrangement = Arrangement.spacedBy(32.dp)
+                ) {
+                    Column(Modifier.weight(1.2f)) {
+                        Text(
+                            "Popular",
+                            style = MaterialTheme.typography.titleLarge,
+                            fontWeight = FontWeight.Bold,
+                            modifier = Modifier.padding(bottom = 8.dp)
+                        )
+                        artist.popular.forEachIndexed { i, track ->
+                            PopularRow(
+                                index = i + 1,
+                                track = track,
+                                liked = track.id in likedTrackIds,
+                                onToggleLike = { onToggleTrackLike(track.id) },
+                                onClick = { onTrack(i) },
+                                menu = songMenu(track)
+                            )
+                        }
+                    }
+                    if (artist.likedCount > 0) {
+                        Column(Modifier.weight(0.8f)) {
+                            Text(
+                                "You Liked",
+                                style = MaterialTheme.typography.titleLarge,
+                                fontWeight = FontWeight.Bold,
+                                modifier = Modifier.padding(bottom = 8.dp)
+                            )
+                            Surface(
+                                shape = RoundedCornerShape(8.dp),
+                                color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.4f),
+                                modifier = Modifier.fillMaxWidth().clickable(onClick = onPlay)
+                            ) {
+                                Row(
+                                    Modifier.padding(12.dp),
+                                    verticalAlignment = Alignment.CenterVertically
+                                ) {
+                                    CoverArt(
+                                        model = artist.liked.firstOrNull()?.artworkUri ?: artist.artworkUri,
+                                        size = 72.dp,
+                                        corner = 36.dp,
+                                        contentScale = ContentScale.Crop
+                                    )
+                                    Spacer(Modifier.width(14.dp))
+                                    Column {
+                                        Text(
+                                            "${artist.likedCount} songs · ${artist.likedReleaseCount} releases",
+                                            fontWeight = FontWeight.SemiBold
+                                        )
+                                        Text(
+                                            "By ${artist.name}",
+                                            style = MaterialTheme.typography.bodySmall,
+                                            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                                        )
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            item {
+                Column(Modifier.fillMaxWidth().background(MaterialTheme.colorScheme.background)) {
+                    Row(
+                        Modifier.fillMaxWidth().padding(start = 24.dp, end = 24.dp, top = 28.dp, bottom = 8.dp),
+                        verticalAlignment = Alignment.CenterVertically
+                    ) {
+                        Text(
+                            "Discography",
+                            style = MaterialTheme.typography.titleLarge,
+                            fontWeight = FontWeight.Bold,
+                            modifier = Modifier.weight(1f)
+                        )
+                        TextButton(onClick = {}) { Text("Show all") }
+                    }
+                    Row(
+                        Modifier.padding(horizontal = 24.dp),
+                        horizontalArrangement = Arrangement.spacedBy(8.dp)
+                    ) {
+                        FilterChip(
+                            selected = disco == DiscoFilter.Popular,
+                            onClick = { disco = DiscoFilter.Popular },
+                            label = { Text("Popular releases") }
+                        )
+                        FilterChip(
+                            selected = disco == DiscoFilter.Albums,
+                            onClick = { disco = DiscoFilter.Albums },
+                            label = { Text("Albums") }
+                        )
+                        FilterChip(
+                            selected = disco == DiscoFilter.Singles,
+                            onClick = { disco = DiscoFilter.Singles },
+                            label = { Text("Singles and EPs") }
+                        )
+                    }
+                    Spacer(Modifier.height(12.dp))
+                    LazyRow(
+                        contentPadding = PaddingValues(horizontal = 16.dp),
+                        horizontalArrangement = Arrangement.spacedBy(4.dp)
+                    ) {
+                        items(releases, key = { it.id }) { album ->
+                            AlbumCard(
+                                album = album.copy(artist = "${album.year ?: ""} · ${album.releaseKind()}".trim(' ', '·')),
+                                onClick = { onOpenAlbum(album) }
+                            )
+                        }
+                    }
+                }
+            }
+            if (artist.appearsOn.isNotEmpty()) {
+                item {
+                    Column(Modifier.fillMaxWidth().background(MaterialTheme.colorScheme.background)) {
+                        Text(
+                            "Appears on",
+                            style = MaterialTheme.typography.titleLarge,
+                            fontWeight = FontWeight.Bold,
+                            modifier = Modifier.padding(start = 24.dp, end = 24.dp, top = 28.dp, bottom = 8.dp)
+                        )
+                        LazyRow(
+                            contentPadding = PaddingValues(horizontal = 16.dp),
+                            horizontalArrangement = Arrangement.spacedBy(4.dp)
+                        ) {
+                            items(artist.appearsOn, key = { "ao-${it.id}" }) { album ->
+                                AlbumCard(album = album, onClick = { onOpenAlbum(album) })
+                            }
+                        }
+                    }
+                }
+            }
+            item {
+                Column(Modifier.fillMaxWidth().background(MaterialTheme.colorScheme.background)) {
+                Text(
+                    "About",
+                    style = MaterialTheme.typography.titleLarge,
+                    fontWeight = FontWeight.Bold,
+                    modifier = Modifier.padding(start = 24.dp, end = 24.dp, top = 28.dp, bottom = 8.dp)
+                )
+                Surface(
+                    modifier = Modifier
+                        .padding(horizontal = 24.dp)
+                        .fillMaxWidth()
+                        .height(280.dp)
+                        .clip(RoundedCornerShape(12.dp)),
+                    color = MaterialTheme.colorScheme.surfaceVariant
+                ) {
+                    Box(Modifier.fillMaxSize().clipToBounds()) {
+                        CoverArt(
+                            model = artist.artworkUri,
+                            modifier = Modifier.matchParentSize(),
+                            corner = 0.dp,
+                            contentScale = ContentScale.Crop,
+                            square = false
+                        )
+                        Box(
+                            Modifier
+                                .fillMaxSize()
+                                .background(
+                                    Brush.verticalGradient(
+                                        listOf(Color.Transparent, Color.Black.copy(alpha = 0.82f))
+                                    )
+                                )
+                        )
+                        Column(
+                            Modifier.align(Alignment.BottomStart).padding(16.dp)
+                        ) {
+                            if (artist.genres.isNotEmpty()) {
+                                FlowRow(
+                                    horizontalArrangement = Arrangement.spacedBy(8.dp),
+                                    verticalArrangement = Arrangement.spacedBy(4.dp),
+                                    modifier = Modifier.padding(bottom = 10.dp)
+                                ) {
+                                    artist.genres.take(8).forEach { g ->
+                                        AssistChip(onClick = {}, label = { Text(g) })
+                                    }
+                                }
+                            }
+                            Text(
+                                artist.stats,
+                                color = Color.White.copy(alpha = 0.8f),
+                                style = MaterialTheme.typography.labelMedium,
+                                modifier = Modifier.padding(bottom = 8.dp)
+                            )
+                            Text(
+                                artist.about?.takeIf { it.isNotBlank() }
+                                    ?: "No bio yet — we’ll fill this in from Wikipedia and TheAudioDB.",
+                                color = Color.White,
+                                style = MaterialTheme.typography.bodyMedium,
+                                maxLines = 8,
+                                overflow = TextOverflow.Ellipsis
+                            )
+                        }
+                    }
+                }
+                Spacer(Modifier.height(48.dp))
+                }
+            }
+        }
+        if (mini) {
+            Row(
+                Modifier
+                    .fillMaxWidth()
+                    .background(MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.95f))
+                    .padding(horizontal = 16.dp, vertical = 8.dp),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                FilledIconButton(
+                    onClick = onPlay,
+                    modifier = Modifier.size(40.dp),
+                    shape = CircleShape,
+                    colors = IconButtonDefaults.filledIconButtonColors(
+                        containerColor = MaterialTheme.colorScheme.primary,
+                        contentColor = MaterialTheme.colorScheme.onPrimary
+                    )
+                ) {
+                    Icon(
+                        if (playing) Icons.Default.Pause else Icons.Default.PlayArrow,
+                        contentDescription = null
+                    )
+                }
+                Spacer(Modifier.width(12.dp))
+                Text(artist.name, fontWeight = FontWeight.Bold, style = MaterialTheme.typography.titleMedium)
+            }
+        }
+    }
+}
+
+@Composable
+private fun ArtistBanner(artist: ArtistPageModel) {
+    val banner = artist.bannerUri?.takeIf { it.isNotBlank() }
+    Box(
+        Modifier
+            .fillMaxWidth()
+            .aspectRatio(3f)
+            .clipToBounds()
+            .clip(RectangleShape)
+            .background(MaterialTheme.colorScheme.surfaceVariant)
+    ) {
+        if (banner != null) {
+            AsyncImage(
+                model = banner,
+                contentDescription = artist.name,
+                modifier = Modifier.matchParentSize(),
+                contentScale = ContentScale.Crop,
+                alignment = Alignment.Center
+            )
+        }
+        Box(
+            Modifier
+                .matchParentSize()
+                .background(
+                    Brush.verticalGradient(
+                        0f to Color.Black.copy(alpha = 0.25f),
+                        0.45f to Color.Transparent,
+                        1f to MaterialTheme.colorScheme.background
+                    )
+                )
+        )
+        Column(
+            Modifier
+                .align(Alignment.BottomStart)
+                .padding(horizontal = 28.dp, vertical = 16.dp)
+        ) {
+            Text(
+                artist.name,
+                color = Color.White,
+                fontWeight = FontWeight.Black,
+                fontSize = 56.sp,
+                lineHeight = 60.sp,
+                maxLines = 2,
+                overflow = TextOverflow.Ellipsis
+            )
+            Text(
+                artist.stats,
+                color = Color.White.copy(alpha = 0.85f),
+                style = MaterialTheme.typography.bodyMedium,
+                modifier = Modifier.padding(top = 6.dp)
+            )
+        }
+    }
+}
+
+@Composable
+private fun PopularRow(
+    index: Int,
+    track: TrackRowModel,
+    liked: Boolean,
+    onToggleLike: () -> Unit,
+    onClick: () -> Unit,
+    menu: List<out MenuEntry> = emptyList()
+) {
+    ContextMenuAnchor(items = menu) { openMenu ->
+        Row(
+            Modifier
+                .fillMaxWidth()
+                .clip(RoundedCornerShape(4.dp))
+                .clickable(onClick = onClick)
+                .padding(vertical = 6.dp, horizontal = 4.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            Text(
+                index.toString(),
+                modifier = Modifier.width(28.dp),
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+            CoverArt(model = track.artworkUri, size = 40.dp, corner = 4.dp)
+            Spacer(Modifier.width(12.dp))
+            Text(
+                track.title,
+                modifier = Modifier.weight(1f),
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                fontWeight = FontWeight.Medium
+            )
+            LikeHeart(liked = liked, onToggle = onToggleLike)
+            Text(
+                formatTime(track.durationMs ?: 0L),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+        }
+    }
+}
+
+internal fun AlbumPageModel.releaseKind(): String = when {
+    tracks.size <= 3 -> "Single"
+    tracks.size <= 7 -> "EP"
+    else -> "Album"
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/dialog/InWindowDialog.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/dialog/InWindowDialog.kt
new file mode 100644
index 00000000..547967d0
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/dialog/InWindowDialog.kt
@@ -0,0 +1,70 @@
+package capital.yuri.yuriplayer.components.dialog
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.zIndex
+
+/**
+ * Modal that paints inside the current window — never a separate OS dialog.
+ */
+@Composable
+fun InWindowDialog(
+    onDismiss: () -> Unit,
+    modifier: Modifier = Modifier,
+    content: @Composable () -> Unit
+) {
+    Box(
+        Modifier
+            .fillMaxSize()
+            .zIndex(40f)
+            .background(Color.Black.copy(alpha = 0.52f))
+            .clickable(
+                indication = null,
+                interactionSource = remember { MutableInteractionSource() },
+                onClick = onDismiss
+            ),
+        contentAlignment = Alignment.Center
+    ) {
+        Box(
+            modifier.clickable(
+                indication = null,
+                interactionSource = remember { MutableInteractionSource() },
+                onClick = {}
+            )
+        ) {
+            content()
+        }
+    }
+}
+
+@Composable
+fun InWindowPanel(
+    onDismiss: () -> Unit,
+    modifier: Modifier = Modifier,
+    content: @Composable () -> Unit
+) {
+    InWindowDialog(onDismiss = onDismiss, modifier = modifier) {
+        Surface(
+            shape = RoundedCornerShape(16.dp),
+            tonalElevation = 6.dp,
+            color = MaterialTheme.colorScheme.surface,
+            contentColor = MaterialTheme.colorScheme.onSurface,
+            modifier = Modifier.clip(RoundedCornerShape(16.dp))
+        ) {
+            content()
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/i18n/Strings.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/i18n/Strings.kt
new file mode 100644
index 00000000..09ebbec8
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/i18n/Strings.kt
@@ -0,0 +1,22 @@
+package capital.yuri.yuriplayer.components.i18n
+
+import androidx.compose.runtime.staticCompositionLocalOf
+
+/**
+ * Localizable UI strings. One [Strings] implementation per locale; add more
+ * and register them in [resolveStrings]. Lyricist KSP codegen can replace this
+ * manual `LocalStrings` later, but the contract stays identical.
+ */
+interface Strings {
+    val noInternet: String
+}
+
+class EnStrings : Strings {
+    override val noInternet: String = "No internet"
+}
+
+private fun resolveStrings(languageTag: String): Strings = when (languageTag.lowercase().substringBefore('-')) {
+    else -> EnStrings()
+}
+
+val LocalStrings = staticCompositionLocalOf<Strings> { EnStrings() }
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/AdaptiveShell.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/AdaptiveShell.kt
new file mode 100644
index 00000000..81bf3415
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/AdaptiveShell.kt
@@ -0,0 +1,48 @@
+package capital.yuri.yuriplayer.components.layout
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxHeight
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.VerticalDivider
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun AdaptiveShell(
+    widthClass: WindowWidthClass,
+    bottomBar: @Composable () -> Unit,
+    sidebar: @Composable () -> Unit,
+    modifier: Modifier = Modifier,
+    content: @Composable () -> Unit
+) {
+    val bg = MaterialTheme.colorScheme.background
+    val outline = MaterialTheme.colorScheme.outline.copy(alpha = 0.25f)
+    Column(
+        modifier
+            .fillMaxSize()
+            .background(bg)
+    ) {
+        Row(Modifier.weight(1f).fillMaxWidth()) {
+            Box(
+                Modifier
+                    .weight(1f)
+                    .fillMaxHeight()
+                    .background(bg)
+            ) { content() }
+            if (widthClass == WindowWidthClass.Expanded) {
+                VerticalDivider(color = outline)
+                Box(Modifier.width(340.dp).fillMaxHeight()) { sidebar() }
+            }
+        }
+        HorizontalDivider(color = outline)
+        bottomBar()
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/DesktopBentoLayout.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/DesktopBentoLayout.kt
new file mode 100644
index 00000000..ab5a3e78
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/DesktopBentoLayout.kt
@@ -0,0 +1,596 @@
+package capital.yuri.yuriplayer.components.layout
+
+import capital.yuri.yuriplayer.components.OfflineBanner
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.gestures.Orientation
+import androidx.compose.foundation.gestures.draggable
+import androidx.compose.foundation.gestures.rememberDraggableState
+import androidx.compose.foundation.hoverable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.interaction.collectIsHoveredAsState
+import androidx.compose.foundation.layout.BoxWithConstraints
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxHeight
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.text.BasicTextField
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.automirrored.filled.ArrowForward
+import androidx.compose.material.icons.filled.Favorite
+import androidx.compose.material.icons.filled.Home
+import androidx.compose.material.icons.filled.PushPin
+import androidx.compose.material.icons.filled.Search
+import androidx.compose.material.icons.filled.Settings
+import androidx.compose.material.icons.outlined.LibraryMusic
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.FilledIconButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.IconButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberUpdatedState
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.SolidColor
+import androidx.compose.ui.input.pointer.PointerIcon
+import androidx.compose.ui.input.pointer.pointerHoverIcon
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.list.ContextMenuAnchor
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+
+enum class DesktopNav { Home, Search }
+
+enum class LibraryFilter { Recents, Playlists, Albums, Artists }
+
+data class LibraryRailItem(
+    val id: String,
+    val title: String,
+    val subtitle: String,
+    val artworkUri: String?,
+    val circular: Boolean = false,
+    val pinned: Boolean = false,
+    val heart: Boolean = false
+)
+
+@Composable
+fun DesktopBentoLayout(
+    nav: DesktopNav,
+    searchQuery: String,
+    onSearchQuery: (String) -> Unit,
+    onHome: () -> Unit,
+    onBack: () -> Unit,
+    onForward: () -> Unit,
+    canBack: Boolean,
+    canForward: Boolean,
+    onSettings: () -> Unit,
+    scanMenu: @Composable () -> Unit = {},
+    libraryFilter: LibraryFilter,
+    onLibraryFilter: (LibraryFilter) -> Unit,
+    libraryItems: List<LibraryRailItem>,
+    selectedLibraryId: String?,
+    onLibraryItem: (LibraryRailItem) -> Unit,
+    libraryMenu: (LibraryRailItem) -> List<out MenuEntry> = { emptyList() },
+    bottomBar: @Composable () -> Unit,
+    sidebar: @Composable () -> Unit,
+    modifier: Modifier = Modifier,
+    showSidebar: Boolean = true,
+    leftFraction: Float = 0.22f,
+    rightFraction: Float = 0.26f,
+    onLeftFraction: (Float, persist: Boolean) -> Unit = { _, _ -> },
+    onRightFraction: (Float, persist: Boolean) -> Unit = { _, _ -> },
+    offline: Boolean = false,
+    content: @Composable () -> Unit
+) {
+    val bg = MaterialTheme.colorScheme.background
+    Column(modifier.fillMaxSize().background(bg)) {
+        TopChrome(
+            nav = nav,
+            searchQuery = searchQuery,
+            onSearchQuery = onSearchQuery,
+            onHome = onHome,
+            onBack = onBack,
+            onForward = onForward,
+            canBack = canBack,
+            canForward = canForward,
+            onSettings = onSettings,
+            scanMenu = scanMenu
+        )
+        if (offline) {
+            OfflineBanner()
+        }
+        BoxWithConstraints(
+            Modifier
+                .weight(1f)
+                .fillMaxWidth()
+                .padding(horizontal = 8.dp)
+        ) {
+            val density = LocalDensity.current
+            val totalPx = constraints.maxWidth.toFloat().coerceAtLeast(1f)
+            val handleW = 10.dp
+            val handlePx = with(density) { handleW.toPx() }
+            val minLeftPx = with(density) { 180.dp.toPx() }
+            val minRightPx = with(density) { 200.dp.toPx() }
+            val minCenterPx = with(density) { 280.dp.toPx() }
+            val handlesTotalPx = handlePx * if (showSidebar) 2 else 1
+
+            var leftDragPx by remember { mutableFloatStateOf(0f) }
+            var rightDragPx by remember { mutableFloatStateOf(0f) }
+            var draggingLeft by remember { mutableStateOf(false) }
+            var draggingRight by remember { mutableStateOf(false) }
+
+            val rightBasePx = if (showSidebar) {
+                (rightFraction * totalPx).coerceAtLeast(minRightPx)
+            } else {
+                0f
+            }
+            val leftBasePx = (leftFraction * totalPx).coerceAtLeast(minLeftPx)
+
+            fun maxLeftPx(rightPx: Float) =
+                (totalPx - rightPx - minCenterPx - handlesTotalPx).coerceAtLeast(minLeftPx)
+
+            fun maxRightPx(leftPx: Float) =
+                (totalPx - leftPx - minCenterPx - handlesTotalPx).coerceAtLeast(minRightPx)
+
+            val leftPx = if (draggingLeft) {
+                (leftBasePx + leftDragPx).coerceIn(minLeftPx, maxLeftPx(rightBasePx))
+            } else {
+                leftBasePx.coerceIn(minLeftPx, maxLeftPx(rightBasePx))
+            }
+            val rightPx = if (!showSidebar) {
+                0f
+            } else if (draggingRight) {
+                (rightBasePx - rightDragPx).coerceIn(minRightPx, maxRightPx(leftPx))
+            } else {
+                rightBasePx.coerceIn(minRightPx, maxRightPx(leftPx))
+            }
+
+            Row(Modifier.fillMaxSize(), verticalAlignment = Alignment.CenterVertically) {
+                LibraryRail(
+                    filter = libraryFilter,
+                    onFilter = onLibraryFilter,
+                    items = libraryItems,
+                    selectedId = selectedLibraryId,
+                    onItem = onLibraryItem,
+                    itemMenu = libraryMenu,
+                    modifier = Modifier.width(with(density) { leftPx.toDp() }).fillMaxHeight()
+                )
+                ResizeHandle(
+                    onDelta = { leftDragPx += it },
+                    onStart = {
+                        leftDragPx = 0f
+                        draggingLeft = true
+                    },
+                    onStop = {
+                        val px = (leftBasePx + leftDragPx).coerceIn(
+                            minLeftPx,
+                            maxLeftPx(rightBasePx)
+                        )
+                        onLeftFraction(px / totalPx, true)
+                        draggingLeft = false
+                        leftDragPx = 0f
+                    }
+                )
+                Surface(
+                    modifier = Modifier.weight(1f).fillMaxHeight(),
+                    shape = MaterialTheme.shapes.large,
+                    color = MaterialTheme.colorScheme.surface
+                ) {
+                    Box(Modifier.fillMaxSize()) { content() }
+                }
+                if (showSidebar) {
+                    ResizeHandle(
+                        onDelta = { rightDragPx += it },
+                        onStart = {
+                            rightDragPx = 0f
+                            draggingRight = true
+                        },
+                        onStop = {
+                            val px = (rightBasePx - rightDragPx).coerceIn(
+                                minRightPx,
+                                maxRightPx(leftPx)
+                            )
+                            onRightFraction(px / totalPx, true)
+                            draggingRight = false
+                            rightDragPx = 0f
+                        }
+                    )
+                    Surface(
+                        modifier = Modifier.width(with(density) { rightPx.toDp() }).fillMaxHeight(),
+                        shape = MaterialTheme.shapes.large,
+                        color = MaterialTheme.colorScheme.surface
+                    ) {
+                        sidebar()
+                    }
+                }
+            }
+        }
+        Box(Modifier.fillMaxWidth().padding(horizontal = 8.dp, vertical = 8.dp)) { bottomBar() }
+    }
+}
+
+@Composable
+private fun ResizeHandle(
+    onDelta: (Float) -> Unit,
+    onStart: () -> Unit,
+    onStop: () -> Unit
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val hovered by interaction.collectIsHoveredAsState()
+    val onDeltaState = rememberUpdatedState(onDelta)
+    val onStartState = rememberUpdatedState(onStart)
+    val onStopState = rememberUpdatedState(onStop)
+    val dragState = rememberDraggableState { delta -> onDeltaState.value(delta) }
+    Box(
+        Modifier
+            .width(10.dp)
+            .fillMaxHeight()
+            .hoverable(interaction)
+            .pointerHoverIcon(PointerIcon.Hand)
+            .draggable(
+                state = dragState,
+                orientation = Orientation.Horizontal,
+                startDragImmediately = true,
+                onDragStarted = { onStartState.value() },
+                onDragStopped = { onStopState.value() }
+            ),
+        contentAlignment = Alignment.Center
+    ) {
+        Box(
+            Modifier
+                .width(if (hovered) 4.dp else 2.dp)
+                .height(48.dp)
+                .clip(RoundedCornerShape(2.dp))
+                .background(
+                    if (hovered) MaterialTheme.colorScheme.primary
+                    else MaterialTheme.colorScheme.outline.copy(alpha = 0.45f)
+                )
+        )
+    }
+}
+
+@Composable
+private fun TopChrome(
+    nav: DesktopNav,
+    searchQuery: String,
+    onSearchQuery: (String) -> Unit,
+    onHome: () -> Unit,
+    onBack: () -> Unit,
+    onForward: () -> Unit,
+    canBack: Boolean,
+    canForward: Boolean,
+    onSettings: () -> Unit,
+    scanMenu: @Composable () -> Unit = {}
+) {
+    Row(
+        Modifier
+            .fillMaxWidth()
+            .padding(horizontal = 12.dp, vertical = 8.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        IconButton(onClick = onBack, enabled = canBack) {
+            Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
+        }
+        IconButton(onClick = onForward, enabled = canForward) {
+            Icon(Icons.AutoMirrored.Filled.ArrowForward, contentDescription = "Forward")
+        }
+        FilledIconButton(
+            onClick = onHome,
+            shape = CircleShape,
+            colors = IconButtonDefaults.filledIconButtonColors(
+                containerColor = MaterialTheme.colorScheme.surface,
+                contentColor = MaterialTheme.colorScheme.onSurface
+            )
+        ) {
+            Icon(Icons.Default.Home, contentDescription = "Home")
+        }
+        Spacer(Modifier.weight(1f))
+        SearchPill(
+            query = searchQuery,
+            onQuery = onSearchQuery,
+            modifier = Modifier.widthIn(min = 280.dp, max = 520.dp).weight(1.2f)
+        )
+        Spacer(Modifier.weight(1f))
+        scanMenu()
+        IconButton(onClick = onSettings) {
+            Icon(
+                Icons.Default.Settings,
+                contentDescription = "Settings",
+                tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+        }
+    }
+}
+
+@Composable
+private fun SearchPill(
+    query: String,
+    onQuery: (String) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    val onSurface = MaterialTheme.colorScheme.onSurface
+    val muted = onSurface.copy(alpha = 0.5f)
+    Row(
+        modifier = modifier
+            .height(40.dp)
+            .clip(CircleShape)
+            .background(MaterialTheme.colorScheme.surface)
+            .padding(horizontal = 14.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Icon(
+            Icons.Default.Search,
+            contentDescription = null,
+            modifier = Modifier.size(18.dp),
+            tint = muted
+        )
+        Spacer(Modifier.width(10.dp))
+        Box(Modifier.weight(1f), contentAlignment = Alignment.CenterStart) {
+            if (query.isEmpty()) {
+                Text(
+                    "What do you want to play?",
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = muted,
+                    maxLines = 1
+                )
+            }
+            BasicTextField(
+                value = query,
+                onValueChange = onQuery,
+                singleLine = true,
+                textStyle = MaterialTheme.typography.bodyMedium.copy(color = onSurface),
+                cursorBrush = SolidColor(onSurface),
+                modifier = Modifier.fillMaxWidth()
+            )
+        }
+    }
+}
+
+@Composable
+private fun LibraryRail(
+    filter: LibraryFilter,
+    onFilter: (LibraryFilter) -> Unit,
+    items: List<LibraryRailItem>,
+    selectedId: String?,
+    onItem: (LibraryRailItem) -> Unit,
+    itemMenu: (LibraryRailItem) -> List<out MenuEntry> = { emptyList() },
+    modifier: Modifier = Modifier
+) {
+    val heartItems = items.filter { it.heart }
+    val pinned = items.filter { it.pinned }
+    val regular = items.filter { !it.pinned && !it.heart }
+
+    Surface(
+        modifier = modifier,
+        shape = MaterialTheme.shapes.large,
+        color = MaterialTheme.colorScheme.surface
+    ) {
+        Column(Modifier.fillMaxSize().padding(12.dp)) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                Icon(
+                    Icons.Outlined.LibraryMusic,
+                    contentDescription = null,
+                    tint = MaterialTheme.colorScheme.onSurface
+                )
+                Spacer(Modifier.width(8.dp))
+                Text(
+                    "Your library",
+                    style = MaterialTheme.typography.titleMedium,
+                    fontWeight = FontWeight.Bold
+                )
+            }
+
+            // "My Stuff" (heart) sits above the pins.
+            heartItems.forEach { item ->
+                RailRow(item, item.id == selectedId, onItem, itemMenu)
+            }
+
+            // Pins sit above the filter chips so they read as pinned items.
+            if (pinned.isNotEmpty()) {
+                LazyRow(
+                    modifier = Modifier.fillMaxWidth().padding(top = 12.dp, bottom = 4.dp),
+                    horizontalArrangement = Arrangement.spacedBy(10.dp)
+                ) {
+                    items(pinned, key = { it.id }) { item ->
+                        PinCard(item, item.id == selectedId, onItem, itemMenu)
+                    }
+                }
+            }
+
+            LazyRow(
+                modifier = Modifier.fillMaxWidth().padding(top = 12.dp, bottom = 8.dp),
+                horizontalArrangement = Arrangement.spacedBy(6.dp)
+            ) {
+                item {
+                    FilterChip(
+                        selected = filter == LibraryFilter.Recents,
+                        onClick = { onFilter(LibraryFilter.Recents) },
+                        label = { Text("Recents", maxLines = 1) }
+                    )
+                }
+                item {
+                    FilterChip(
+                        selected = filter == LibraryFilter.Playlists,
+                        onClick = { onFilter(LibraryFilter.Playlists) },
+                        label = { Text("Playlists", maxLines = 1) }
+                    )
+                }
+                item {
+                    FilterChip(
+                        selected = filter == LibraryFilter.Albums,
+                        onClick = { onFilter(LibraryFilter.Albums) },
+                        label = { Text("Albums", maxLines = 1) }
+                    )
+                }
+                item {
+                    FilterChip(
+                        selected = filter == LibraryFilter.Artists,
+                        onClick = { onFilter(LibraryFilter.Artists) },
+                        label = { Text("Artists", maxLines = 1) }
+                    )
+                }
+            }
+
+            LazyColumn(Modifier.weight(1f)) {
+                items(regular, key = { it.id }) { item ->
+                    RailRow(item, item.id == selectedId, onItem, itemMenu)
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun RailRow(
+    item: LibraryRailItem,
+    selected: Boolean,
+    onItem: (LibraryRailItem) -> Unit,
+    itemMenu: (LibraryRailItem) -> List<out MenuEntry>
+) {
+    ContextMenuAnchor(items = itemMenu(item)) {
+        Row(
+            Modifier
+                .fillMaxWidth()
+                .clip(RoundedCornerShape(12.dp))
+                .background(
+                    if (selected) MaterialTheme.colorScheme.primary.copy(alpha = 0.14f)
+                    else MaterialTheme.colorScheme.surface
+                )
+                .clickable { onItem(item) }
+                .padding(8.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            if (item.heart) {
+                Box(
+                    Modifier
+                        .size(48.dp)
+                        .clip(RoundedCornerShape(8.dp))
+                        .background(Color(0xFFE91E63)),
+                    contentAlignment = Alignment.Center
+                ) {
+                    Icon(
+                        Icons.Filled.Favorite,
+                        contentDescription = null,
+                        tint = Color.White
+                    )
+                }
+            } else {
+                CoverArt(
+                    model = item.artworkUri,
+                    size = 48.dp,
+                    corner = if (item.circular) 24.dp else 8.dp,
+                    contentScale = if (item.circular) ContentScale.Crop else ContentScale.Fit
+                )
+            }
+            Spacer(Modifier.width(12.dp))
+            Column(Modifier.weight(1f)) {
+                Text(
+                    item.title,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    fontWeight = FontWeight.Medium,
+                    color = MaterialTheme.colorScheme.onSurface
+                )
+                Text(
+                    item.subtitle,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+            }
+            if (item.pinned) {
+                Icon(
+                    Icons.Default.PushPin,
+                    contentDescription = "Pinned",
+                    modifier = Modifier.size(14.dp),
+                    tint = MaterialTheme.colorScheme.primary
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun PinCard(
+    item: LibraryRailItem,
+    selected: Boolean,
+    onItem: (LibraryRailItem) -> Unit,
+    itemMenu: (LibraryRailItem) -> List<out MenuEntry>
+) {
+    ContextMenuAnchor(items = itemMenu(item)) {
+        Column(
+            horizontalAlignment = Alignment.CenterHorizontally,
+            modifier = Modifier
+                .width(68.dp)
+                .clip(RoundedCornerShape(10.dp))
+                .background(
+                    if (selected) MaterialTheme.colorScheme.primary.copy(alpha = 0.14f)
+                    else Color.Transparent
+                )
+                .clickable { onItem(item) }
+                .padding(6.dp)
+        ) {
+            Box {
+                CoverArt(
+                    model = item.artworkUri,
+                    size = 44.dp,
+                    corner = if (item.circular) 22.dp else 8.dp,
+                    contentScale = if (item.circular) ContentScale.Crop else ContentScale.Fit
+                )
+                Box(
+                    Modifier
+                        .align(Alignment.BottomEnd)
+                        .size(16.dp)
+                        .background(MaterialTheme.colorScheme.primary, CircleShape),
+                    contentAlignment = Alignment.Center
+                ) {
+                    Icon(
+                        Icons.Default.PushPin,
+                        contentDescription = "Pinned",
+                        modifier = Modifier.size(10.dp),
+                        tint = MaterialTheme.colorScheme.onPrimary
+                    )
+                }
+            }
+            Text(
+                item.title,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurface,
+                modifier = Modifier.padding(top = 4.dp)
+            )
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/WindowSize.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/WindowSize.kt
new file mode 100644
index 00000000..c07a734f
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/layout/WindowSize.kt
@@ -0,0 +1,25 @@
+package capital.yuri.yuriplayer.components.layout
+
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.remember
+import androidx.compose.ui.unit.Dp
+import androidx.compose.ui.unit.dp
+
+enum class WindowWidthClass {
+    /** Phone, or a narrow window. Collapsing headers, mini-player. */
+    Compact,
+    /** Tablet / split. Side-by-side album pages, optional sidebar. */
+    Medium,
+    /** Desktop. Right now-playing sidebar + bottom transport. */
+    Expanded
+}
+
+fun windowWidthClass(width: Dp): WindowWidthClass = when {
+    width < 600.dp -> WindowWidthClass.Compact
+    width < 1100.dp -> WindowWidthClass.Medium
+    else -> WindowWidthClass.Expanded
+}
+
+@Composable
+fun rememberWindowWidthClass(width: Dp): WindowWidthClass =
+    remember(width) { windowWidthClass(width) }
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/AlbumCard.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/AlbumCard.kt
new file mode 100644
index 00000000..b32aba45
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/AlbumCard.kt
@@ -0,0 +1,54 @@
+package capital.yuri.yuriplayer.components.list
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.model.AlbumPageModel
+
+@Composable
+fun AlbumCard(
+    album: AlbumPageModel,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(
+        modifier = modifier
+            .width(160.dp)
+            .clickable(onClick = onClick)
+            .padding(8.dp)
+    ) {
+        CoverArt(
+            model = album.artworkUri,
+            modifier = Modifier.fillMaxWidth().aspectRatio(1f),
+            corner = 10.dp,
+            contentDescription = album.title
+        )
+        Text(
+            album.title,
+            modifier = Modifier.padding(top = 8.dp),
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            fontWeight = FontWeight.SemiBold,
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurface
+        )
+        Text(
+            album.artist,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+        )
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/ContextMenu.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/ContextMenu.kt
new file mode 100644
index 00000000..3db735d1
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/ContextMenu.kt
@@ -0,0 +1,80 @@
+package capital.yuri.yuriplayer.components.list
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxScope
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.input.pointer.PointerEventPass
+import androidx.compose.ui.input.pointer.PointerEventType
+import androidx.compose.ui.input.pointer.isSecondaryPressed
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.unit.DpOffset
+import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.Popup
+import androidx.compose.ui.window.PopupProperties
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.menu.YuriContextMenu
+import kotlin.math.roundToInt
+
+typealias ContextAction = MenuEntry.Item
+
+@Composable
+fun ContextMenuAnchor(
+    items: List<out MenuEntry>,
+    modifier: Modifier = Modifier,
+    onLongPressOpen: Boolean = true,
+    showPredictionCone: Boolean = false,
+    content: @Composable BoxScope.(openMenu: () -> Unit) -> Unit
+) {
+    var open by remember { mutableStateOf(false) }
+    var offset by remember { mutableStateOf(DpOffset.Zero) }
+    val density = LocalDensity.current
+    val openMenu: () -> Unit = {
+        offset = DpOffset(12.dp, 8.dp)
+        open = true
+    }
+    Box(
+        modifier.pointerInput(items) {
+            if (items.isEmpty()) return@pointerInput
+            awaitPointerEventScope {
+                while (true) {
+                    val event = awaitPointerEvent(PointerEventPass.Initial)
+                    if (event.type != PointerEventType.Press) continue
+                    if (!event.buttons.isSecondaryPressed) continue
+                    val change = event.changes.firstOrNull() ?: continue
+                    change.consume()
+                    offset = with(density) {
+                        DpOffset(change.position.x.toDp(), change.position.y.toDp())
+                    }
+                    open = true
+                }
+            }
+        }
+    ) {
+        content(if (onLongPressOpen && items.isNotEmpty()) openMenu else ({ }))
+        if (open && items.isNotEmpty()) {
+            val px = with(density) {
+                IntOffset(offset.x.toPx().roundToInt(), offset.y.toPx().roundToInt())
+            }
+            Popup(
+                alignment = Alignment.TopStart,
+                offset = px,
+                onDismissRequest = { open = false },
+                properties = PopupProperties(focusable = true, dismissOnClickOutside = true)
+            ) {
+                YuriContextMenu(
+                    entries = items,
+                    onDismiss = { open = false },
+                    showPredictionCone = showPredictionCone
+                )
+            }
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/LikeHeart.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/LikeHeart.kt
new file mode 100644
index 00000000..d7c0fe9e
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/LikeHeart.kt
@@ -0,0 +1,27 @@
+package capital.yuri.yuriplayer.components.list
+
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Favorite
+import androidx.compose.material.icons.outlined.FavoriteBorder
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+
+@Composable
+fun LikeHeart(
+    liked: Boolean,
+    onToggle: () -> Unit,
+    modifier: Modifier = Modifier,
+    contentDescription: String? = if (liked) "Unlike" else "Like"
+) {
+    IconButton(onClick = onToggle, modifier = modifier) {
+        Icon(
+            imageVector = if (liked) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder,
+            contentDescription = contentDescription,
+            tint = if (liked) MaterialTheme.colorScheme.primary
+            else MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+        )
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/SongBadgeRow.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/SongBadgeRow.kt
new file mode 100644
index 00000000..77587725
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/SongBadgeRow.kt
@@ -0,0 +1,68 @@
+package capital.yuri.yuriplayer.components.list
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Cloud
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+
+@Composable
+fun SongBadgeRow(
+    explicit: Boolean,
+    multiSource: Boolean,
+    modifier: Modifier = Modifier,
+    onSources: (() -> Unit)? = null
+) {
+    if (!explicit && !multiSource) return
+    Row(
+        modifier = modifier,
+        horizontalArrangement = Arrangement.spacedBy(4.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        if (explicit) {
+            Box(
+                modifier = Modifier
+                    .clip(RoundedCornerShape(2.dp))
+                    .background(MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f))
+                    .padding(horizontal = 3.dp, vertical = 1.dp),
+                contentAlignment = Alignment.Center
+            ) {
+                Text(
+                    "E",
+                    fontSize = 9.sp,
+                    fontWeight = FontWeight.Bold,
+                    color = MaterialTheme.colorScheme.surface,
+                    lineHeight = 10.sp
+                )
+            }
+        }
+        if (multiSource) {
+            Icon(
+                Icons.Default.Cloud,
+                contentDescription = "Sources",
+                modifier = Modifier
+                    .size(14.dp)
+                    .then(
+                        if (onSources != null) Modifier.clickable(onClick = onSources)
+                        else Modifier
+                    ),
+                tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/TrackRow.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/TrackRow.kt
new file mode 100644
index 00000000..26847597
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/list/TrackRow.kt
@@ -0,0 +1,115 @@
+package capital.yuri.yuriplayer.components.list
+
+import androidx.compose.foundation.ExperimentalFoundationApi
+import androidx.compose.foundation.background
+import androidx.compose.foundation.combinedClickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.TrackRowModel
+
+@OptIn(ExperimentalFoundationApi::class)
+@Composable
+fun TrackRow(
+    track: TrackRowModel,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    showCover: Boolean = true,
+    showAlbum: Boolean = true,
+    onLongClick: (() -> Unit)? = null,
+    liked: Boolean = false,
+    onToggleLike: (() -> Unit)? = null,
+    contextItems: List<out MenuEntry> = emptyList(),
+    onSources: (() -> Unit)? = null
+) {
+    val highlight = MaterialTheme.colorScheme.primary.copy(alpha = 0.12f)
+    ContextMenuAnchor(items = contextItems) { openMenu ->
+        Row(
+            modifier = modifier
+                .fillMaxWidth()
+                .background(if (track.highlighted) highlight else MaterialTheme.colorScheme.surface.copy(alpha = 0f))
+                .combinedClickable(
+                    onClick = onClick,
+                    onLongClick = {
+                        when {
+                            contextItems.isNotEmpty() -> openMenu()
+                            onLongClick != null -> onLongClick()
+                        }
+                    }
+                )
+                .padding(horizontal = 16.dp, vertical = 8.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+        if (track.trackNumber != null && !showCover) {
+            Text(
+                track.trackNumber.toString(),
+                modifier = Modifier.width(28.dp),
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+            )
+        } else if (showCover) {
+            CoverArt(model = track.artworkUri, size = 44.dp, corner = 6.dp)
+            Spacer(Modifier.width(12.dp))
+        }
+        Column(Modifier.weight(1f)) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                Text(
+                    track.title,
+                    maxLines = 1,
+                    overflow = TextOverflow.Ellipsis,
+                    fontWeight = if (track.highlighted) FontWeight.SemiBold else FontWeight.Normal,
+                    color = MaterialTheme.colorScheme.onSurface,
+                    modifier = Modifier.weight(1f, fill = false)
+                )
+                if (track.explicit || track.multiSource) {
+                    Spacer(Modifier.width(6.dp))
+                    SongBadgeRow(
+                        explicit = track.explicit,
+                        multiSource = track.multiSource,
+                        onSources = onSources
+                    )
+                }
+            }
+            val sub = if (showAlbum) "${track.artist} · ${track.album}" else track.artist
+            Text(
+                sub,
+                maxLines = 1,
+                overflow = TextOverflow.Ellipsis,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+        }
+        if (onToggleLike != null) {
+            LikeHeart(liked = liked, onToggle = onToggleLike)
+        }
+        track.durationMs?.let {
+            Text(
+                formatTime(it),
+                style = MaterialTheme.typography.labelSmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+            )
+        }
+        }
+    }
+}
+
+fun formatTime(ms: Long): String {
+    if (ms <= 0) return "0:00"
+    val total = (ms / 1000).toInt()
+    val m = total / 60
+    val s = total % 60
+    return "$m:${s.toString().padStart(2, '0')}"
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/MenuDsl.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/MenuDsl.kt
new file mode 100644
index 00000000..ce9a3855
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/MenuDsl.kt
@@ -0,0 +1,72 @@
+package capital.yuri.yuriplayer.components.menu
+
+/**
+ * Hierarchical context menu. Implementors declare options; the host renders
+ * them with prediction-cone hover for submenus.
+ *
+ * ```
+ * buildContextMenu {
+ *   item("Add to playlist", alternate = {
+ *     item("Chill") { addTo("chill") }
+ *   }) { openPicker() }
+ *   submenu("Go to") {
+ *     item("Album") { openAlbum() }
+ *     item("Artist") { openArtist() }
+ *   }
+ *   divider()
+ *   item("Delete", destructive = true) { remove() }
+ * }
+ * ```
+ */
+sealed class MenuEntry {
+    data class Item(
+        val label: String,
+        val shortcut: String? = null,
+        val destructive: Boolean = false,
+        val enabled: Boolean = true,
+        val alternate: List<MenuEntry> = emptyList(),
+        val onClick: () -> Unit
+    ) : MenuEntry()
+
+    data class Submenu(
+        val label: String,
+        val children: List<MenuEntry>
+    ) : MenuEntry()
+
+    data object Divider : MenuEntry()
+}
+
+@DslMarker
+annotation class ContextMenuDsl
+
+@ContextMenuDsl
+class ContextMenuScope {
+    private val entries = mutableListOf<MenuEntry>()
+
+    fun item(
+        label: String,
+        shortcut: String? = null,
+        destructive: Boolean = false,
+        enabled: Boolean = true,
+        alternate: (ContextMenuScope.() -> Unit)? = null,
+        onClick: () -> Unit
+    ) {
+        val alt = alternate?.let { ContextMenuScope().apply(it).build() }.orEmpty()
+        entries += MenuEntry.Item(label, shortcut, destructive, enabled, alt, onClick)
+    }
+
+    fun submenu(label: String, block: ContextMenuScope.() -> Unit) {
+        entries += MenuEntry.Submenu(label, ContextMenuScope().apply(block).build())
+    }
+
+    fun divider() {
+        entries += MenuEntry.Divider
+    }
+
+    internal fun build(): List<MenuEntry> = entries.toList()
+}
+
+fun buildContextMenu(block: ContextMenuScope.() -> Unit): List<MenuEntry> =
+    ContextMenuScope().apply(block).build()
+
+typealias ContextAction = MenuEntry.Item
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/PredictionCone.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/PredictionCone.kt
new file mode 100644
index 00000000..a208ff95
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/PredictionCone.kt
@@ -0,0 +1,48 @@
+package capital.yuri.yuriplayer.components.menu
+
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Rect
+import kotlin.math.abs
+
+/**
+ * Amazon / macOS prediction cone: while a submenu is open, travel inside the
+ * triangle (previous pointer → submenu near-edge corners) must not switch the
+ * highlighted parent item.
+ */
+fun pointInTriangle(p: Offset, a: Offset, b: Offset, c: Offset): Boolean {
+    if (!finite(p) || !finite(a) || !finite(b) || !finite(c)) return false
+    val v0x = c.x - a.x
+    val v0y = c.y - a.y
+    val v1x = b.x - a.x
+    val v1y = b.y - a.y
+    val v2x = p.x - a.x
+    val v2y = p.y - a.y
+    val dot00 = v0x * v0x + v0y * v0y
+    val dot01 = v0x * v1x + v0y * v1y
+    val dot02 = v0x * v2x + v0y * v2y
+    val dot11 = v1x * v1x + v1y * v1y
+    val dot12 = v1x * v2x + v1y * v2y
+    val denom = dot00 * dot11 - dot01 * dot01
+    if (abs(denom) < 1e-6f) return false
+    val inv = 1f / denom
+    val u = (dot11 * dot02 - dot01 * dot12) * inv
+    val v = (dot00 * dot12 - dot01 * dot02) * inv
+    return u >= -0.02f && v >= -0.02f && u + v <= 1.02f
+}
+
+fun predictionCone(origin: Offset, submenu: Rect, openLeft: Boolean = false): Triple<Offset, Offset, Offset>? {
+    if (!finite(origin) || submenu.isEmpty) return null
+    val edge = if (openLeft) submenu.right else submenu.left
+    return Triple(
+        origin,
+        Offset(edge, submenu.top),
+        Offset(edge, submenu.bottom)
+    )
+}
+
+fun pointerInPredictionCone(current: Offset, origin: Offset, submenu: Rect, openLeft: Boolean = false): Boolean {
+    val cone = predictionCone(origin, submenu, openLeft) ?: return false
+    return pointInTriangle(current, cone.first, cone.second, cone.third)
+}
+
+private fun finite(o: Offset): Boolean = o.x.isFinite() && o.y.isFinite()
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/YuriContextMenu.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/YuriContextMenu.kt
new file mode 100644
index 00000000..e250f85c
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/menu/YuriContextMenu.kt
@@ -0,0 +1,356 @@
+package capital.yuri.yuriplayer.components.menu
+
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.hoverable
+import androidx.compose.foundation.interaction.MutableInteractionSource
+import androidx.compose.foundation.interaction.collectIsHoveredAsState
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.IntrinsicSize
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.KeyboardArrowLeft
+import androidx.compose.material.icons.automirrored.filled.KeyboardArrowRight
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateMapOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Rect
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.Path
+import androidx.compose.ui.graphics.PathEffect
+import androidx.compose.ui.graphics.drawscope.Stroke
+import androidx.compose.ui.input.pointer.PointerEventPass
+import androidx.compose.ui.input.pointer.PointerEventType
+import androidx.compose.ui.input.pointer.isSecondaryPressed
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.layout.Layout
+import androidx.compose.ui.layout.boundsInParent
+import androidx.compose.ui.layout.onGloballyPositioned
+import androidx.compose.ui.layout.positionInRoot
+import androidx.compose.ui.layout.positionInWindow
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.IntSize
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.platform.screenSizePx
+import capital.yuri.yuriplayer.components.platform.windowPositionOnScreenPx
+import kotlin.math.roundToInt
+
+/**
+ * Material 3 menu with nested submenus and a prediction cone so the pointer
+ * can travel diagonally into a submenu without highlighting siblings.
+ */
+@Composable
+fun YuriContextMenu(
+    entries: List<out MenuEntry>,
+    onDismiss: () -> Unit,
+    modifier: Modifier = Modifier,
+    showPredictionCone: Boolean = false
+) {
+    var openSubmenu by remember { mutableIntStateOf(-1) }
+    var pointer by remember { mutableStateOf(Offset.Unspecified) }
+    var coneOrigin by remember { mutableStateOf(Offset.Unspecified) }
+    var submenuRect by remember { mutableStateOf(Rect.Zero) }
+
+    val density = LocalDensity.current
+    // Submenus share the same width bounds as the parent column; include the
+    // Surface's 4dp padding on each side to stay consistent with measured sizes.
+    val submenuMaxWidthPx = with(density) { 288.dp.toPx() }
+
+    // Viewport width and the popup window's on-screen origin (platform-specific).
+    val screenWidthPx = remember { screenSizePx().width }
+    val windowOrigin = remember(openSubmenu) {
+        if (openSubmenu >= 0) windowPositionOnScreenPx() else IntOffset.Zero
+    }
+
+    var parentSize by remember { mutableStateOf(IntSize.Zero) }
+    var popupPosInWindow by remember { mutableStateOf(IntOffset.Zero) }
+    var parentTopInRoot by remember { mutableStateOf(0f) }
+    val itemTopsInRoot = remember { mutableStateMapOf<Int, Float>() }
+
+    // Open the submenu to the left when the parent menu would otherwise push it
+    // past the right edge of the viewport.
+    val flipToLeft = parentSize.width > 0 && screenWidthPx > 0 &&
+        (windowOrigin.x + popupPosInWindow.x + parentSize.width + submenuMaxWidthPx.toInt()) > screenWidthPx
+
+    // Vertical offset of the highlighted item relative to the parent menu top.
+    val itemY = if (openSubmenu >= 0) {
+        itemTopsInRoot[openSubmenu]?.let { (it - parentTopInRoot).roundToInt().coerceAtLeast(0) } ?: 0
+    } else 0
+
+    Box(
+        modifier
+            .pointerInput(entries) {
+                awaitPointerEventScope {
+                    while (true) {
+                        val event = awaitPointerEvent(PointerEventPass.Initial)
+                        val change = event.changes.lastOrNull() ?: continue
+                        val next = change.position
+                        if (pointer != Offset.Unspecified) coneOrigin = pointer
+                        pointer = next
+                    }
+                }
+            }
+            .onGloballyPositioned { coords ->
+                val pos = coords.positionInWindow()
+                popupPosInWindow = IntOffset(pos.x.roundToInt(), pos.y.roundToInt())
+            }
+    ) {
+        Layout(
+            content = {
+                MenuColumn(
+                    entries = entries,
+                    openSubmenu = openSubmenu,
+                    onHover = { index ->
+                        val origin = if (coneOrigin != Offset.Unspecified) coneOrigin else pointer
+                        val blocked = openSubmenu >= 0 &&
+                            index != openSubmenu &&
+                            pointerInPredictionCone(pointer, origin, submenuRect, flipToLeft)
+                        if (!blocked) openSubmenu = index
+                    },
+                    onOpenSubmenu = { openSubmenu = it },
+                    onDismiss = onDismiss,
+                    submenuOpensLeft = flipToLeft,
+                    onItemPositioned = { index, topInRoot -> itemTopsInRoot[index] = topInRoot },
+                    modifier = Modifier.onGloballyPositioned { coords ->
+                        parentSize = coords.size
+                        parentTopInRoot = coords.positionInRoot().y
+                    }
+                )
+                val nested = entries.getOrNull(openSubmenu)?.nestedChildren()
+                if (!nested.isNullOrEmpty()) {
+                    MenuColumn(
+                        entries = nested,
+                        openSubmenu = -1,
+                        onHover = {},
+                        onOpenSubmenu = {},
+                        onDismiss = onDismiss,
+                        modifier = Modifier.onGloballyPositioned {
+                            submenuRect = it.boundsInParent()
+                        }
+                    )
+                }
+            }
+        ) { measurables, constraints ->
+            val parent = measurables[0].measure(constraints)
+            val submenu = measurables.getOrNull(1)?.measure(constraints)
+            val submenuWidth = submenu?.width ?: 0
+            val submenuHeight = submenu?.height ?: 0
+
+            val width = if (submenu != null) parent.width + submenuWidth else parent.width
+            val height = if (submenu != null) maxOf(parent.height, itemY + submenuHeight) else parent.height
+
+            layout(width, height) {
+                if (submenu != null && flipToLeft) {
+                    submenu.place(0, itemY)
+                    parent.place(submenuWidth, 0)
+                } else {
+                    parent.place(0, 0)
+                    submenu?.place(parent.width, itemY)
+                }
+            }
+        }
+
+        if (showPredictionCone && openSubmenu >= 0) {
+            val cone = predictionCone(pointer, submenuRect, flipToLeft)
+            if (cone != null) {
+                Canvas(Modifier.matchParentSize()) {
+                    val path = Path().apply {
+                        moveTo(cone.first.x, cone.first.y)
+                        lineTo(cone.second.x, cone.second.y)
+                        lineTo(cone.third.x, cone.third.y)
+                        close()
+                    }
+                    drawPath(path, Color(0x402196F3))
+                    drawPath(
+                        path,
+                        Color(0xFF1565C0),
+                        style = Stroke(
+                            width = 1.5.dp.toPx(),
+                            pathEffect = PathEffect.dashPathEffect(floatArrayOf(8f, 6f))
+                        )
+                    )
+                    drawCircle(Color(0xFF1565C0), radius = 3.dp.toPx(), center = cone.first)
+                    drawCircle(Color(0xFF1565C0), radius = 3.dp.toPx(), center = cone.second)
+                    drawCircle(Color(0xFF1565C0), radius = 3.dp.toPx(), center = cone.third)
+                }
+            }
+        }
+    }
+}
+
+private fun MenuEntry.nestedChildren(): List<MenuEntry>? = when (this) {
+    is MenuEntry.Submenu -> children
+    is MenuEntry.Item -> alternate.takeIf { it.isNotEmpty() }
+    is MenuEntry.Divider -> null
+}
+
+@Composable
+private fun MenuColumn(
+    entries: List<out MenuEntry>,
+    openSubmenu: Int,
+    onHover: (Int) -> Unit,
+    onOpenSubmenu: (Int) -> Unit,
+    onDismiss: () -> Unit,
+    modifier: Modifier = Modifier,
+    submenuOpensLeft: Boolean = false,
+    onItemPositioned: (Int, Float) -> Unit = { _, _ -> }
+) {
+    Surface(
+        modifier = modifier.padding(4.dp),
+        shape = RoundedCornerShape(12.dp),
+        tonalElevation = 6.dp,
+        shadowElevation = 8.dp,
+        color = MaterialTheme.colorScheme.surface
+    ) {
+        Column(
+            Modifier
+                .width(IntrinsicSize.Max)
+                .widthIn(min = 180.dp, max = 280.dp)
+                .padding(vertical = 6.dp)
+        ) {
+            entries.forEachIndexed { index, entry ->
+                when (entry) {
+                    is MenuEntry.Divider -> HorizontalDivider(
+                        Modifier.padding(vertical = 4.dp, horizontal = 8.dp)
+                    )
+                    is MenuEntry.Item -> MenuItemRow(
+                        label = entry.label,
+                        shortcut = entry.shortcut,
+                        destructive = entry.destructive,
+                        enabled = entry.enabled,
+                        selected = openSubmenu == index && entry.alternate.isNotEmpty(),
+                        hasSubmenu = entry.alternate.isNotEmpty(),
+                        submenuOpensLeft = submenuOpensLeft,
+                        modifier = Modifier.onGloballyPositioned { coords ->
+                            onItemPositioned(index, coords.positionInRoot().y)
+                        },
+                        onHover = { onHover(-1) },
+                        onClick = {
+                            if (entry.enabled) {
+                                onDismiss()
+                                entry.onClick()
+                            }
+                        },
+                        onAltClick = if (entry.alternate.isNotEmpty()) {
+                            { onOpenSubmenu(index) }
+                        } else null
+                    )
+                    is MenuEntry.Submenu -> MenuItemRow(
+                        label = entry.label,
+                        shortcut = null,
+                        destructive = false,
+                        enabled = true,
+                        selected = openSubmenu == index,
+                        hasSubmenu = true,
+                        submenuOpensLeft = submenuOpensLeft,
+                        modifier = Modifier.onGloballyPositioned { coords ->
+                            onItemPositioned(index, coords.positionInRoot().y)
+                        },
+                        onHover = { onHover(index) },
+                        onClick = { onHover(index) }
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun MenuItemRow(
+    label: String,
+    shortcut: String?,
+    destructive: Boolean,
+    enabled: Boolean,
+    selected: Boolean,
+    hasSubmenu: Boolean,
+    onHover: () -> Unit,
+    onClick: () -> Unit,
+    onAltClick: (() -> Unit)? = null,
+    modifier: Modifier = Modifier,
+    submenuOpensLeft: Boolean = false
+) {
+    val interaction = remember { MutableInteractionSource() }
+    val hovered by interaction.collectIsHoveredAsState()
+    val highlight = selected || hovered
+    val color = when {
+        !enabled -> MaterialTheme.colorScheme.onSurface.copy(alpha = 0.38f)
+        destructive -> MaterialTheme.colorScheme.error
+        else -> MaterialTheme.colorScheme.onSurface
+    }
+    Row(
+        modifier
+            .fillMaxWidth()
+            .padding(horizontal = 6.dp)
+            .clip(RoundedCornerShape(8.dp))
+            .background(
+                if (highlight && enabled) MaterialTheme.colorScheme.primary.copy(alpha = 0.12f)
+                else Color.Transparent
+            )
+            .hoverable(interaction)
+            .pointerInput(label, onAltClick) {
+                awaitPointerEventScope {
+                    while (true) {
+                        val e = awaitPointerEvent()
+                        if (e.type == PointerEventType.Enter || e.type == PointerEventType.Move) {
+                            if (!e.buttons.isSecondaryPressed) onHover()
+                        }
+                        if (e.type == PointerEventType.Press && e.buttons.isSecondaryPressed) {
+                            val alt = onAltClick
+                            if (alt != null) {
+                                e.changes.forEach { it.consume() }
+                                alt()
+                            }
+                        }
+                    }
+                }
+            }
+            .clickable(enabled = enabled, onClick = onClick)
+            .padding(horizontal = 12.dp, vertical = 8.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Text(
+            label,
+            style = MaterialTheme.typography.bodyMedium,
+            color = color,
+            modifier = Modifier.weight(1f)
+        )
+        if (shortcut != null) {
+            Text(
+                shortcut,
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.4f),
+                modifier = Modifier.padding(start = 16.dp)
+            )
+        }
+        if (hasSubmenu) {
+            Icon(
+                if (submenuOpensLeft) Icons.AutoMirrored.Filled.KeyboardArrowLeft
+                else Icons.AutoMirrored.Filled.KeyboardArrowRight,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.45f),
+                modifier = Modifier.padding(start = 8.dp)
+            )
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/model/UiModels.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/model/UiModels.kt
new file mode 100644
index 00000000..fc7c1e57
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/model/UiModels.kt
@@ -0,0 +1,156 @@
+package capital.yuri.yuriplayer.components.model
+
+import capital.yuri.yuriplayer.core.library.albumGroupKey
+import capital.yuri.yuriplayer.core.library.catalogKey
+import capital.yuri.yuriplayer.core.library.collapseAlbumTracks
+import capital.yuri.yuriplayer.core.library.matchesArtistName
+import capital.yuri.yuriplayer.core.library.matchesCreditedArtist
+import capital.yuri.yuriplayer.data.Song
+
+data class CoverRef(
+    val id: String,
+    val title: String,
+    val subtitle: String,
+    val artworkUri: String?
+)
+
+data class TrackRowModel(
+    val id: String,
+    val title: String,
+    val artist: String,
+    val album: String,
+    val durationMs: Long? = null,
+    val trackNumber: Int? = null,
+    val discNumber: Int? = null,
+    val artworkUri: String? = null,
+    val highlighted: Boolean = false,
+    val explicit: Boolean = false,
+    val multiSource: Boolean = false,
+    val sourceIds: List<String> = emptyList()
+)
+
+data class AlbumPageModel(
+    val id: String,
+    val title: String,
+    val artist: String,
+    val artworkUri: String?,
+    val year: Int? = null,
+    val tracks: List<TrackRowModel>
+)
+
+data class ArtistPageModel(
+    val name: String,
+    val artworkUri: String?,
+    val bannerUri: String? = null,
+    val stats: String,
+    val about: String? = null,
+    val popular: List<TrackRowModel>,
+    val liked: List<TrackRowModel>,
+    val likedCount: Int,
+    val likedReleaseCount: Int,
+    val discography: List<AlbumPageModel>,
+    val appearsOn: List<AlbumPageModel>,
+    val genres: List<String> = emptyList()
+)
+
+fun Song.toRow(highlighted: Boolean = false) = TrackRowModel(
+    id = songKey,
+    title = displayTitle,
+    artist = displayArtist,
+    album = displayAlbum,
+    durationMs = durationMs,
+    trackNumber = trackNumber,
+    discNumber = discNumber,
+    artworkUri = albumArtUri,
+    highlighted = highlighted,
+    explicit = isExplicit,
+    multiSource = false,
+    sourceIds = listOf(songKey)
+)
+
+fun Song.toCover() = CoverRef(
+    id = songKey,
+    title = displayTitle,
+    subtitle = displayArtist,
+    artworkUri = albumArtUri
+)
+
+fun List<Song>.albums(
+    preferredIds: Map<String, String> = emptyMap()
+): List<AlbumPageModel> =
+    groupBy { albumGroupKey(it) }
+        .mapNotNull { (_, songs) ->
+            val collapsed = collapseAlbumTracks(songs, preferredIds)
+            val first = collapsed.firstOrNull()?.preferred ?: return@mapNotNull null
+            AlbumPageModel(
+                id = albumGroupKey(first),
+                title = first.displayAlbum,
+                artist = first.albumArtist?.takeIf { it.isNotBlank() } ?: first.displayArtist,
+                artworkUri = collapsed.firstNotNullOfOrNull { it.preferred.albumArtUri },
+                year = collapsed.mapNotNull { it.preferred.year }.maxOrNull(),
+                tracks = collapsed.map { it.toRow() }
+            )
+        }
+        .sortedBy { it.title.lowercase() }
+
+private fun capital.yuri.yuriplayer.core.library.CollapsedSong.toRow() = TrackRowModel(
+    id = preferred.songKey,
+    title = preferred.displayTitle,
+    artist = preferred.displayArtist,
+    album = preferred.displayAlbum,
+    durationMs = preferred.durationMs,
+    trackNumber = preferred.trackNumber,
+    discNumber = preferred.discNumber,
+    artworkUri = preferred.albumArtUri,
+    explicit = explicit,
+    multiSource = multiSource,
+    sourceIds = sources.map { it.songKey }
+)
+
+fun List<Song>.artistPage(
+    name: String,
+    likedIds: Set<String> = emptySet(),
+    recents: List<Song> = emptyList()
+): ArtistPageModel {
+    val allAlbums = albums()
+    val discography = allAlbums.filter { it.artist.matchesArtistName(name) }
+        .sortedByDescending { it.year ?: Int.MIN_VALUE }
+    val appearsOn = allAlbums.filter { album ->
+        !album.artist.matchesArtistName(name) &&
+            album.tracks.any { row ->
+                row.artist.matchesCreditedArtist(name)
+            }
+    }.sortedByDescending { it.year ?: Int.MIN_VALUE }
+
+    // One logical track per recording: local + Jellyfin + Subsonic copies of the
+    // same song collapse onto a single entry, so track counts / popular / liked
+    // don't inflate for multi-source discographies (e.g. Lemon Demon).
+    val ofArtist = filter {
+        it.displayArtist.matchesArtistName(name) || (it.albumArtist?.matchesArtistName(name) == true)
+    }.distinctBy { it.catalogKey() }
+
+    val recentRank = recents.mapIndexed { i, t -> t.songKey to i }.toMap()
+    val popular = ofArtist
+        .sortedWith(
+            compareBy<Song> { recentRank[it.songKey] ?: Int.MAX_VALUE }
+                .thenBy { it.displayAlbum }
+                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
+        )
+        .distinctBy { it.displayTitle.lowercase() }
+        .take(5)
+        .map { it.toRow() }
+    val likedTracks = ofArtist.filter { it.songKey in likedIds }
+    return ArtistPageModel(
+        name = name,
+        artworkUri = ofArtist.firstNotNullOfOrNull { it.albumArtUri } ?: discography.firstOrNull()?.artworkUri,
+        bannerUri = null,
+        stats = "${discography.size} albums · ${ofArtist.size} tracks",
+        about = null,
+        popular = popular,
+        liked = likedTracks.take(8).map { it.toRow() },
+        likedCount = likedTracks.size,
+        likedReleaseCount = likedTracks.map { it.displayAlbum }.distinct().size,
+        discography = discography,
+        appearsOn = appearsOn
+    )
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.kt
new file mode 100644
index 00000000..78212606
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.kt
@@ -0,0 +1,17 @@
+package capital.yuri.yuriplayer.components.platform
+
+import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.IntSize
+
+/**
+ * Size of the primary display / viewport in pixels.
+ */
+expect fun screenSizePx(): IntSize
+
+/**
+ * Top-left of the current (focused or active) window on screen, in pixels.
+ *
+ * Android has a single full-screen window, so this is always [IntOffset.Zero].
+ * Desktop reads the AWT window position (the popup window while a menu is open).
+ */
+expect fun windowPositionOnScreenPx(): IntOffset
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/BottomPlayerBar.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/BottomPlayerBar.kt
new file mode 100644
index 00000000..8ebeb19a
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/BottomPlayerBar.kt
@@ -0,0 +1,237 @@
+package capital.yuri.yuriplayer.components.player
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Favorite
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material.icons.filled.QueueMusic
+import androidx.compose.material.icons.filled.Repeat
+import androidx.compose.material.icons.filled.RepeatOne
+import androidx.compose.material.icons.filled.Shuffle
+import androidx.compose.material.icons.filled.SkipNext
+import androidx.compose.material.icons.filled.SkipPrevious
+import androidx.compose.material.icons.filled.VolumeUp
+import androidx.compose.material.icons.outlined.FavoriteBorder
+import androidx.compose.material3.FilledIconButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.IconButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Slider
+import androidx.compose.material3.SliderDefaults
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.list.ContextMenuAnchor
+import capital.yuri.yuriplayer.components.list.formatTime
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.CoverRef
+import capital.yuri.yuriplayer.core.player.RepeatMode
+
+@Composable
+fun BottomPlayerBar(
+    track: CoverRef?,
+    playing: Boolean,
+    positionMs: Long,
+    durationMs: Long,
+    onPrev: () -> Unit,
+    onToggle: () -> Unit,
+    onNext: () -> Unit,
+    onSeek: (Long) -> Unit,
+    modifier: Modifier = Modifier,
+    accent: Color = MaterialTheme.colorScheme.primary,
+    shuffle: Boolean = false,
+    repeat: RepeatMode = RepeatMode.OFF,
+    onToggleShuffle: () -> Unit = {},
+    onCycleRepeat: () -> Unit = {},
+    volume: Float = 1f,
+    onVolume: (Float) -> Unit = {},
+    liked: Boolean = false,
+    onToggleLike: () -> Unit = {},
+    queueVisible: Boolean = true,
+    onToggleQueue: () -> Unit = {},
+    songMenu: List<out MenuEntry> = emptyList()
+) {
+    val muted = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+    Surface(
+        modifier = modifier.fillMaxWidth(),
+        color = MaterialTheme.colorScheme.surface,
+        contentColor = MaterialTheme.colorScheme.onSurface,
+        shape = MaterialTheme.shapes.large
+    ) {
+        Box(
+            Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 12.dp, vertical = 10.dp)
+                .height(84.dp)
+        ) {
+            ContextMenuAnchor(
+                items = if (track != null) songMenu else emptyList(),
+                modifier = Modifier.align(Alignment.CenterStart).widthIn(max = 360.dp)
+            ) {
+                Row(verticalAlignment = Alignment.CenterVertically) {
+                    CoverArt(model = track?.artworkUri, size = 56.dp, corner = 6.dp)
+                    Spacer(Modifier.width(12.dp))
+                    Column(Modifier.weight(1f, fill = false).widthIn(max = 220.dp)) {
+                        Text(
+                            track?.title ?: "Nothing playing",
+                            maxLines = 1,
+                            overflow = TextOverflow.Ellipsis,
+                            fontWeight = FontWeight.SemiBold,
+                            style = MaterialTheme.typography.bodyMedium,
+                            color = MaterialTheme.colorScheme.onSurface
+                        )
+                        Text(
+                            track?.subtitle ?: " ",
+                            maxLines = 1,
+                            overflow = TextOverflow.Ellipsis,
+                            style = MaterialTheme.typography.bodySmall,
+                            color = muted
+                        )
+                    }
+                    if (track != null) {
+                        IconButton(onClick = onToggleLike) {
+                            Icon(
+                                if (liked) Icons.Filled.Favorite else Icons.Outlined.FavoriteBorder,
+                                contentDescription = if (liked) "Unlike" else "Like",
+                                tint = if (liked) accent else muted
+                            )
+                        }
+                    }
+                }
+            }
+            Column(
+                Modifier
+                    .align(Alignment.Center)
+                    .fillMaxWidth(0.42f),
+                horizontalAlignment = Alignment.CenterHorizontally
+            ) {
+                Row(
+                    verticalAlignment = Alignment.CenterVertically,
+                    horizontalArrangement = Arrangement.spacedBy(2.dp)
+                ) {
+                    IconButton(onClick = onToggleShuffle, modifier = Modifier.size(36.dp)) {
+                        Icon(
+                            Icons.Default.Shuffle,
+                            contentDescription = "Shuffle",
+                            modifier = Modifier.size(18.dp),
+                            tint = if (shuffle) accent else muted
+                        )
+                    }
+                    IconButton(onClick = onPrev, modifier = Modifier.size(36.dp)) {
+                        Icon(
+                            Icons.Default.SkipPrevious,
+                            contentDescription = "Previous",
+                            modifier = Modifier.size(22.dp)
+                        )
+                    }
+                    FilledIconButton(
+                        onClick = onToggle,
+                        modifier = Modifier.size(36.dp),
+                        shape = CircleShape,
+                        colors = IconButtonDefaults.filledIconButtonColors(
+                            containerColor = MaterialTheme.colorScheme.onSurface,
+                            contentColor = MaterialTheme.colorScheme.surface
+                        )
+                    ) {
+                        Icon(
+                            if (playing) Icons.Default.Pause else Icons.Default.PlayArrow,
+                            contentDescription = if (playing) "Pause" else "Play",
+                            modifier = Modifier.size(20.dp)
+                        )
+                    }
+                    IconButton(onClick = onNext, modifier = Modifier.size(36.dp)) {
+                        Icon(
+                            Icons.Default.SkipNext,
+                            contentDescription = "Next",
+                            modifier = Modifier.size(22.dp)
+                        )
+                    }
+                    IconButton(onClick = onCycleRepeat, modifier = Modifier.size(36.dp)) {
+                        Icon(
+                            if (repeat == RepeatMode.ONE) Icons.Default.RepeatOne else Icons.Default.Repeat,
+                            contentDescription = when (repeat) {
+                                RepeatMode.OFF -> "Repeat off"
+                                RepeatMode.COLD -> "Repeat all"
+                                RepeatMode.ONE -> "Repeat one"
+                            },
+                            modifier = Modifier.size(18.dp),
+                            tint = if (repeat != RepeatMode.OFF) accent else muted
+                        )
+                    }
+                }
+                Spacer(Modifier.height(8.dp))
+                Row(
+                    Modifier.fillMaxWidth(),
+                    verticalAlignment = Alignment.CenterVertically
+                ) {
+                    Text(
+                        formatTime(positionMs),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = muted
+                    )
+                    Spacer(Modifier.width(10.dp))
+                    WavySeekBar(
+                        progress = if (durationMs > 0) {
+                            (positionMs.toFloat() / durationMs).coerceIn(0f, 1f)
+                        } else 0f,
+                        playing = playing,
+                        onProgressChange = { if (durationMs > 0) onSeek((it * durationMs).toLong()) },
+                        onProgressChangeFinished = { if (durationMs > 0) onSeek((it * durationMs).toLong()) },
+                        activeColor = MaterialTheme.colorScheme.onSurface,
+                        inactiveColor = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.22f),
+                        modifier = Modifier.weight(1f)
+                    )
+                    Spacer(Modifier.width(10.dp))
+                    Text(
+                        formatTime(durationMs),
+                        style = MaterialTheme.typography.labelSmall,
+                        color = muted
+                    )
+                }
+            }
+            Row(
+                Modifier.align(Alignment.CenterEnd),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                IconButton(onClick = onToggleQueue) {
+                    Icon(
+                        Icons.Default.QueueMusic,
+                        contentDescription = "Queue",
+                        tint = if (queueVisible) accent else muted
+                    )
+                }
+                Icon(Icons.Default.VolumeUp, contentDescription = "Volume", tint = muted)
+                Slider(
+                    value = volume,
+                    onValueChange = onVolume,
+                    modifier = Modifier.width(100.dp).height(20.dp),
+                    colors = SliderDefaults.colors(
+                        thumbColor = MaterialTheme.colorScheme.onSurface,
+                        activeTrackColor = MaterialTheme.colorScheme.onSurface,
+                        inactiveTrackColor = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.22f)
+                    )
+                )
+            }
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/NowPlayingSidebar.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/NowPlayingSidebar.kt
new file mode 100644
index 00000000..5a6e570a
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/NowPlayingSidebar.kt
@@ -0,0 +1,79 @@
+package capital.yuri.yuriplayer.components.player
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.CoverRef
+import capital.yuri.yuriplayer.components.model.TrackRowModel
+
+@Composable
+fun NowPlayingSidebar(
+    track: CoverRef?,
+    hot: List<TrackRowModel>,
+    cold: List<TrackRowModel>,
+    coldLabel: String = "Up next",
+    history: List<TrackRowModel>,
+    onPlayHot: (Int) -> Unit,
+    onPlayCold: (Int) -> Unit,
+    onHistoryTrack: (TrackRowModel) -> Unit,
+    onClearHot: () -> Unit = {},
+    onClearHistory: () -> Unit = {},
+    onMoveHot: ((from: Int, to: Int) -> Unit)? = null,
+    onMoveCold: ((from: Int, to: Int) -> Unit)? = null,
+    likedIds: Set<String> = emptySet(),
+    onToggleTrackLike: (String) -> Unit = {},
+    songMenu: (TrackRowModel) -> List<out MenuEntry> = { emptyList() },
+    nowPlayingMenu: List<out MenuEntry> = emptyList(),
+    modifier: Modifier = Modifier
+) {
+    var artExpanded by remember { mutableStateOf(false) }
+    Column(
+        modifier
+            .fillMaxSize()
+            .background(MaterialTheme.colorScheme.surface)
+            .padding(12.dp)
+    ) {
+        Text(
+            "Queue",
+            style = MaterialTheme.typography.titleMedium,
+            fontWeight = FontWeight.Bold,
+            color = MaterialTheme.colorScheme.onSurface
+        )
+        Spacer(Modifier.height(8.dp))
+        QueuePanel(
+            nowPlaying = track,
+            hot = hot,
+            cold = cold,
+            coldLabel = coldLabel,
+            history = history,
+            onPlayHot = onPlayHot,
+            onPlayCold = onPlayCold,
+            onPlayHistory = onHistoryTrack,
+            onClearHot = onClearHot,
+            onClearHistory = onClearHistory,
+            onMoveHot = onMoveHot,
+            onMoveCold = onMoveCold,
+            likedIds = likedIds,
+            onToggleLike = onToggleTrackLike,
+            songMenu = songMenu,
+            nowPlayingMenu = nowPlayingMenu,
+            artExpanded = artExpanded,
+            onToggleArt = { artExpanded = !artExpanded },
+            modifier = Modifier.weight(1f)
+        )
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/QueuePanel.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/QueuePanel.kt
new file mode 100644
index 00000000..21800f57
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/QueuePanel.kt
@@ -0,0 +1,354 @@
+package capital.yuri.yuriplayer.components.player
+
+import androidx.compose.animation.AnimatedVisibility
+import androidx.compose.animation.expandVertically
+import androidx.compose.animation.fadeIn
+import androidx.compose.animation.fadeOut
+import androidx.compose.animation.shrinkVertically
+import androidx.compose.foundation.background
+import androidx.compose.foundation.gestures.detectDragGesturesAfterLongPress
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyListScope
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.KeyboardArrowDown
+import androidx.compose.material.icons.filled.KeyboardArrowUp
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.IconButtonDefaults
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.list.ContextMenuAnchor
+import capital.yuri.yuriplayer.components.list.TrackRow
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.CoverRef
+import capital.yuri.yuriplayer.components.model.TrackRowModel
+import kotlin.math.roundToInt
+
+private enum class QueueTab { Queue, History }
+
+/**
+ * Shared queue chrome (mobile overlay + desktop rail).
+ * Hot = user-queued (plays next). Cold = album / playlist / radio rest.
+ */
+@Composable
+fun QueuePanel(
+    nowPlaying: CoverRef?,
+    hot: List<TrackRowModel>,
+    cold: List<TrackRowModel>,
+    coldLabel: String = "Up next",
+    history: List<TrackRowModel>,
+    onPlayHot: (Int) -> Unit,
+    onPlayCold: (Int) -> Unit,
+    onPlayHistory: (TrackRowModel) -> Unit = {},
+    onClearHot: () -> Unit = {},
+    onClearHistory: () -> Unit = {},
+    onMoveHot: ((from: Int, to: Int) -> Unit)? = null,
+    onMoveCold: ((from: Int, to: Int) -> Unit)? = null,
+    likedIds: Set<String> = emptySet(),
+    onToggleLike: (String) -> Unit = {},
+    songMenu: (TrackRowModel) -> List<out MenuEntry> = { emptyList() },
+    nowPlayingMenu: List<out MenuEntry> = emptyList(),
+    artExpanded: Boolean = false,
+    onToggleArt: (() -> Unit)? = null,
+    modifier: Modifier = Modifier
+) {
+    var tab by remember { mutableStateOf(QueueTab.Queue) }
+    Column(modifier.fillMaxSize()) {
+        Row(
+            Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 8.dp, vertical = 4.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            LazyRow(
+                modifier = Modifier.weight(1f),
+                horizontalArrangement = Arrangement.spacedBy(8.dp),
+                verticalAlignment = Alignment.CenterVertically
+            ) {
+                item {
+                    FilterChip(
+                        selected = tab == QueueTab.Queue,
+                        onClick = { tab = QueueTab.Queue },
+                        label = { Text("Queue", maxLines = 1) }
+                    )
+                }
+                item {
+                    FilterChip(
+                        selected = tab == QueueTab.History,
+                        onClick = { tab = QueueTab.History },
+                        label = { Text("Recently played", maxLines = 1) }
+                    )
+                }
+            }
+            if (tab == QueueTab.Queue && hot.isNotEmpty()) {
+                TextButton(onClick = onClearHot) { Text("Clear") }
+            }
+            if (tab == QueueTab.History && history.isNotEmpty()) {
+                TextButton(onClick = onClearHistory) { Text("Clear") }
+            }
+        }
+        when (tab) {
+            QueueTab.Queue -> {
+                nowPlaying?.let { np ->
+                    AnimatedVisibility(
+                        visible = artExpanded,
+                        enter = fadeIn() + expandVertically(),
+                        exit = fadeOut() + shrinkVertically()
+                    ) {
+                        ExpandableCover(
+                            artworkUri = np.artworkUri,
+                            expanded = true,
+                            onToggle = onToggleArt,
+                            modifier = Modifier
+                                .fillMaxWidth()
+                                .padding(horizontal = 8.dp, vertical = 8.dp)
+                                .aspectRatio(1f)
+                        )
+                    }
+                    NowPlayingQueueCard(
+                        track = np,
+                        showCover = !artExpanded,
+                        onToggleArt = onToggleArt,
+                        menu = nowPlayingMenu
+                    )
+                }
+                Box(Modifier.weight(1f)) {
+                    LazyColumn(Modifier.fillMaxSize()) {
+                        if (hot.isNotEmpty()) {
+                            item(key = "hdr-hot") {
+                                SectionHeader("Queue · ${hot.size}")
+                            }
+                            queueRows(
+                                rows = hot,
+                                prefix = "hot",
+                                onPlay = onPlayHot,
+                                onMove = onMoveHot,
+                                likedIds = likedIds,
+                                onToggleLike = onToggleLike,
+                                songMenu = songMenu
+                            )
+                        }
+                        item(key = "hdr-cold") {
+                            SectionHeader("$coldLabel · ${cold.size}")
+                            Text(
+                                if (hot.isNotEmpty()) {
+                                    "Queued tracks play first. Drag to reorder."
+                                } else {
+                                    "Play an album or list to fill what comes next."
+                                },
+                                style = MaterialTheme.typography.labelSmall,
+                                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.4f),
+                                modifier = Modifier.padding(horizontal = 8.dp, vertical = 2.dp)
+                            )
+                        }
+                        if (cold.isEmpty()) {
+                            item(key = "cold-empty") {
+                                Text(
+                                    "Nothing else queued.",
+                                    style = MaterialTheme.typography.bodySmall,
+                                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f),
+                                    modifier = Modifier.padding(horizontal = 8.dp, vertical = 8.dp)
+                                )
+                            }
+                        } else {
+                            queueRows(
+                                rows = cold,
+                                prefix = "cold",
+                                onPlay = onPlayCold,
+                                onMove = onMoveCold,
+                                likedIds = likedIds,
+                                onToggleLike = onToggleLike,
+                                songMenu = songMenu
+                            )
+                        }
+                    }
+                }
+            }
+            QueueTab.History -> {
+                if (history.isEmpty()) {
+                    Text(
+                        "Play something and it’ll land here.",
+                        modifier = Modifier.padding(16.dp),
+                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+                    )
+                } else {
+                    LazyColumn(Modifier.weight(1f)) {
+                        itemsIndexed(history, key = { i, row -> "hist-${row.id}-$i" }) { _, row ->
+                            TrackRow(
+                                track = row,
+                                onClick = { onPlayHistory(row) },
+                                showCover = true,
+                                showAlbum = true,
+                                liked = row.id in likedIds,
+                                onToggleLike = { onToggleLike(row.id) },
+                                contextItems = songMenu(row)
+                            )
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun SectionHeader(label: String) {
+    Text(
+        label,
+        style = MaterialTheme.typography.titleSmall,
+        fontWeight = FontWeight.SemiBold,
+        modifier = Modifier.padding(horizontal = 12.dp, vertical = 8.dp)
+    )
+}
+
+private fun LazyListScope.queueRows(
+    rows: List<TrackRowModel>,
+    prefix: String,
+    onPlay: (Int) -> Unit,
+    onMove: ((Int, Int) -> Unit)?,
+    likedIds: Set<String>,
+    onToggleLike: (String) -> Unit,
+    songMenu: (TrackRowModel) -> List<out MenuEntry>
+) {
+    itemsIndexed(rows, key = { i, row -> "$prefix-${row.id}-$i" }) { index, row ->
+        val density = LocalDensity.current
+        val rowPx = with(density) { 64.dp.toPx() }
+        TrackRow(
+            track = row,
+            onClick = { onPlay(index) },
+            showCover = true,
+            showAlbum = false,
+            liked = row.id in likedIds,
+            onToggleLike = { onToggleLike(row.id) },
+            contextItems = songMenu(row),
+            modifier = if (onMove == null) Modifier
+            else Modifier.pointerInput(rows, onMove) {
+                var from: Int? = null
+                var dy = 0f
+                detectDragGesturesAfterLongPress(
+                    onDragStart = {
+                        from = index
+                        dy = 0f
+                    },
+                    onDrag = { change, drag ->
+                        change.consume()
+                        dy += drag.y
+                    },
+                    onDragEnd = {
+                        val start = from ?: return@detectDragGesturesAfterLongPress
+                        val to = (start + (dy / rowPx).roundToInt())
+                            .coerceIn(0, rows.lastIndex)
+                        if (start != to) onMove(start, to)
+                        from = null
+                    },
+                    onDragCancel = { from = null }
+                )
+            }
+        )
+    }
+}
+
+@Composable
+private fun NowPlayingQueueCard(
+    track: CoverRef,
+    showCover: Boolean,
+    onToggleArt: (() -> Unit)?,
+    menu: List<out MenuEntry> = emptyList()
+) {
+    ContextMenuAnchor(items = menu) {
+        Row(
+            Modifier
+                .fillMaxWidth()
+                .padding(horizontal = 12.dp, vertical = 8.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+        if (showCover) {
+            ExpandableCover(
+                artworkUri = track.artworkUri,
+                expanded = false,
+                onToggle = onToggleArt,
+                modifier = Modifier.size(48.dp)
+            )
+            Spacer(Modifier.width(12.dp))
+        }
+        Column(Modifier.weight(1f)) {
+            Text(
+                "Now playing",
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.primary
+            )
+            Text(track.title, fontWeight = FontWeight.SemiBold, maxLines = 1)
+            Text(
+                track.subtitle,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f),
+                maxLines = 1
+            )
+        }
+        }
+    }
+}
+
+@Composable
+private fun ExpandableCover(
+    artworkUri: String?,
+    expanded: Boolean,
+    onToggle: (() -> Unit)?,
+    modifier: Modifier = Modifier
+) {
+    Box(modifier.clip(MaterialTheme.shapes.medium)) {
+        CoverArt(
+            model = artworkUri,
+            modifier = Modifier.fillMaxSize(),
+            corner = if (expanded) 16.dp else 8.dp
+        )
+        if (onToggle != null) {
+            IconButton(
+                onClick = onToggle,
+                modifier = Modifier
+                    .align(if (expanded) Alignment.TopEnd else Alignment.BottomEnd)
+                    .padding(if (expanded) 8.dp else 2.dp)
+                    .size(if (expanded) 32.dp else 22.dp)
+                    .clip(CircleShape)
+                    .background(Color.Black.copy(alpha = 0.45f)),
+                colors = IconButtonDefaults.iconButtonColors(contentColor = Color.White)
+            ) {
+                Icon(
+                    if (expanded) Icons.Default.KeyboardArrowDown else Icons.Default.KeyboardArrowUp,
+                    contentDescription = if (expanded) "Shrink cover" else "Expand cover",
+                    modifier = Modifier.size(if (expanded) 20.dp else 16.dp)
+                )
+            }
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/WavySeekBar.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/WavySeekBar.kt
new file mode 100644
index 00000000..6f94fe8f
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/player/WavySeekBar.kt
@@ -0,0 +1,183 @@
+package capital.yuri.yuriplayer.components.player
+
+import androidx.compose.animation.core.Animatable
+import androidx.compose.animation.core.LinearEasing
+import androidx.compose.animation.core.RepeatMode
+import androidx.compose.animation.core.animateFloat
+import androidx.compose.animation.core.infiniteRepeatable
+import androidx.compose.animation.core.rememberInfiniteTransition
+import androidx.compose.animation.core.tween
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.gestures.detectHorizontalDragGestures
+import androidx.compose.foundation.gestures.detectTapGestures
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.Path
+import androidx.compose.ui.graphics.StrokeCap
+import androidx.compose.ui.graphics.drawscope.Stroke
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.unit.dp
+import kotlin.math.PI
+import kotlin.math.sin
+
+/**
+ * Expressive seek bar: traveling sine wave while [playing], flattens when
+ * paused or while the user is dragging the thumb.
+ *
+ * [onProgressChangeFinished] receives the **exact** drop fraction so callers
+ * do not race Compose state or lose the last drag sample.
+ */
+@Composable
+fun WavySeekBar(
+    progress: Float,
+    playing: Boolean,
+    onProgressChange: (Float) -> Unit,
+    onProgressChangeFinished: (fraction: Float) -> Unit,
+    activeColor: Color,
+    inactiveColor: Color,
+    modifier: Modifier = Modifier,
+    maxWaveAmplitude: Float = 7f,
+    waveLength: Float = 32f
+) {
+    var dragging by remember { mutableFloatStateOf(-1f) }
+    val isDragging = dragging >= 0f
+    val shown = if (isDragging) dragging else progress.coerceIn(0f, 1f)
+
+    val wantWave = playing && !isDragging
+    val amplitudeFactor = remember { Animatable(if (wantWave) 1f else 0f) }
+    LaunchedEffect(wantWave) {
+        amplitudeFactor.animateTo(
+            targetValue = if (wantWave) 1f else 0f,
+            animationSpec = tween(durationMillis = if (isDragging) 120 else 420)
+        )
+    }
+
+    val infinite = rememberInfiniteTransition(label = "wavePhase")
+    val phase by infinite.animateFloat(
+        initialValue = 0f,
+        targetValue = (2f * PI).toFloat(),
+        animationSpec = infiniteRepeatable(
+            animation = tween(durationMillis = 1400, easing = LinearEasing),
+            repeatMode = RepeatMode.Restart
+        ),
+        label = "phase"
+    )
+
+    // Only read `phase` (and therefore drive redraws) while the wave is visible,
+    // so an idle/paused seek bar does not animate the Canvas every frame.
+    val effectivePhase = if (amplitudeFactor.value > 0.01f) phase else 0f
+
+    fun finishAt(fraction: Float) {
+        val f = fraction.coerceIn(0f, 1f)
+        onProgressChange(f)
+        onProgressChangeFinished(f)
+    }
+
+    Canvas(
+        modifier = modifier
+            .fillMaxWidth()
+            .height(40.dp)
+            .pointerInput(Unit) {
+                detectTapGestures { offset ->
+                    val p = (offset.x / size.width).coerceIn(0f, 1f)
+                    finishAt(p)
+                }
+            }
+            .pointerInput(Unit) {
+                detectHorizontalDragGestures(
+                    onDragStart = { offset ->
+                        val p = (offset.x / size.width).coerceIn(0f, 1f)
+                        dragging = p
+                        onProgressChange(p)
+                    },
+                    onDragEnd = {
+                        val drop = if (dragging >= 0f) dragging else progress
+                        dragging = -1f
+                        finishAt(drop)
+                    },
+                    onDragCancel = {
+                        dragging = -1f
+                        // Cancel: do not seek — report current progress only
+                        onProgressChangeFinished(progress.coerceIn(0f, 1f))
+                    },
+                    onHorizontalDrag = { change, _ ->
+                        val p = (change.position.x / size.width).coerceIn(0f, 1f)
+                        dragging = p
+                        onProgressChange(p)
+                    }
+                )
+            }
+    ) {
+        val w = size.width
+        val midY = size.height / 2f
+        val amp = maxWaveAmplitude * density * amplitudeFactor.value
+        val len = waveLength * density
+        val strokeInactive = 3.5f * density
+        val strokeActive = 5.5f * density
+        // Coarser step keeps the per-frame path cheap (debug builds stay usable).
+        val step = 4f
+
+        fun waveY(x: Float): Float {
+            if (amp < 0.5f) return midY
+            return midY + amp * sin(2f * PI.toFloat() * x / len + effectivePhase)
+        }
+
+        val inactivePath = Path().apply {
+            moveTo(0f, waveY(0f))
+            var x = 0f
+            while (x <= w) {
+                lineTo(x, waveY(x))
+                x += step
+            }
+        }
+        drawPath(
+            path = inactivePath,
+            color = inactiveColor,
+            style = Stroke(width = strokeInactive, cap = StrokeCap.Round)
+        )
+
+        val endX = w * shown
+        if (endX > 1f) {
+            val activePath = Path().apply {
+                moveTo(0f, waveY(0f))
+                var x = 0f
+                while (x <= endX) {
+                    lineTo(x, waveY(x))
+                    x += step
+                }
+            }
+            drawPath(
+                path = activePath,
+                color = activeColor,
+                style = Stroke(width = strokeActive, cap = StrokeCap.Round)
+            )
+        }
+
+        val thumbX = endX.coerceIn(0f, w)
+        val thumbY = waveY(thumbX)
+        drawCircle(
+            color = activeColor.copy(alpha = 0.35f),
+            radius = 12f * density,
+            center = Offset(thumbX, thumbY)
+        )
+        drawCircle(
+            color = activeColor,
+            radius = 8f * density,
+            center = Offset(thumbX, thumbY)
+        )
+        drawCircle(
+            color = Color.White.copy(alpha = 0.95f),
+            radius = 3.5f * density,
+            center = Offset(thumbX, thumbY)
+        )
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/settings/SettingsRows.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/settings/SettingsRows.kt
new file mode 100644
index 00000000..71da4d89
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/settings/SettingsRows.kt
@@ -0,0 +1,223 @@
+package capital.yuri.yuriplayer.components.settings
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Switch
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+
+@Composable
+fun SettingsSectionTitle(title: String) {
+    Text(
+        text = title,
+        style = MaterialTheme.typography.titleSmall,
+        fontWeight = FontWeight.SemiBold,
+        color = MaterialTheme.colorScheme.primary,
+        modifier = Modifier.padding(vertical = 10.dp)
+    )
+}
+
+@Composable
+fun SettingsGroup(
+    modifier: Modifier = Modifier,
+    content: @Composable ColumnScope.() -> Unit
+) {
+    Surface(
+        modifier = modifier.fillMaxWidth(),
+        shape = RoundedCornerShape(16.dp),
+        color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.45f),
+        tonalElevation = 0.dp
+    ) {
+        Column(content = content)
+    }
+    Spacer(modifier = Modifier.height(8.dp))
+}
+
+@Composable
+fun SettingsNavRow(
+    title: String,
+    subtitle: String? = null,
+    icon: ImageVector? = null,
+    trailing: String? = null,
+    onClick: () -> Unit
+) {
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable(onClick = onClick)
+            .padding(horizontal = 16.dp, vertical = 14.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        if (icon != null) {
+            Icon(
+                imageVector = icon,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.size(22.dp)
+            )
+            Spacer(modifier = Modifier.width(16.dp))
+        }
+        Column(modifier = Modifier.weight(1f)) {
+            Text(title, style = MaterialTheme.typography.bodyLarge)
+            if (!subtitle.isNullOrBlank()) {
+                Text(
+                    subtitle,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+            }
+        }
+        if (!trailing.isNullOrBlank()) {
+            Text(
+                trailing,
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.45f)
+            )
+        }
+    }
+}
+
+@Composable
+fun SettingsSwitchRow(
+    title: String,
+    subtitle: String? = null,
+    icon: ImageVector? = null,
+    checked: Boolean,
+    onCheckedChange: (Boolean) -> Unit
+) {
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable { onCheckedChange(!checked) }
+            .padding(horizontal = 16.dp, vertical = 12.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        if (icon != null) {
+            Icon(
+                imageVector = icon,
+                contentDescription = null,
+                tint = MaterialTheme.colorScheme.onSurfaceVariant,
+                modifier = Modifier.size(22.dp)
+            )
+            Spacer(modifier = Modifier.width(16.dp))
+        }
+        Column(modifier = Modifier.weight(1f).padding(end = 12.dp)) {
+            Text(title, style = MaterialTheme.typography.bodyLarge)
+            if (!subtitle.isNullOrBlank()) {
+                Text(
+                    subtitle,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+            }
+        }
+        Switch(checked = checked, onCheckedChange = onCheckedChange)
+    }
+}
+
+@Composable
+fun SettingsNote(text: String) {
+    Text(
+        text = text,
+        style = MaterialTheme.typography.bodySmall,
+        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+        modifier = Modifier.padding(vertical = 4.dp)
+    )
+}
+
+@Composable
+fun SettingsChoiceRow(
+    title: String,
+    subtitle: String? = null,
+    trailing: String,
+    options: List<Pair<String, String>>,
+    onSelect: (String) -> Unit
+) {
+    var open by remember { mutableStateOf(false) }
+    Row(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable { open = true }
+            .padding(horizontal = 16.dp, vertical = 14.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Column(modifier = Modifier.weight(1f).padding(end = 12.dp)) {
+            Text(title, style = MaterialTheme.typography.bodyLarge)
+            if (!subtitle.isNullOrBlank()) {
+                Text(
+                    subtitle,
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+            }
+        }
+        Text(
+            trailing,
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.45f)
+        )
+        DropdownMenu(expanded = open, onDismissRequest = { open = false }) {
+            options.forEach { (id, label) ->
+                DropdownMenuItem(
+                    text = { Text(label) },
+                    onClick = {
+                        open = false
+                        onSelect(id)
+                    }
+                )
+            }
+        }
+    }
+}
+
+@Composable
+fun SettingsTopBar(
+    title: String,
+    onBack: () -> Unit,
+    actions: @Composable () -> Unit = {}
+) {
+    Row(
+        modifier = Modifier.fillMaxWidth().padding(vertical = 4.dp),
+        verticalAlignment = Alignment.CenterVertically,
+        horizontalArrangement = Arrangement.SpaceBetween
+    ) {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            IconButton(onClick = onBack) {
+                Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
+            }
+            Text(
+                text = title,
+                style = MaterialTheme.typography.titleLarge,
+                fontWeight = FontWeight.SemiBold
+            )
+        }
+        actions()
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/settings/SettingsShell.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/settings/SettingsShell.kt
new file mode 100644
index 00000000..8cd0f8e6
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/settings/SettingsShell.kt
@@ -0,0 +1,126 @@
+package capital.yuri.yuriplayer.components.settings
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxHeight
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Close
+import androidx.compose.material.icons.filled.Cloud
+import androidx.compose.material.icons.filled.ColorLens
+import androidx.compose.material.icons.filled.Info
+import androidx.compose.material.icons.filled.LibraryMusic
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.graphics.vector.ImageVector
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+
+enum class SettingsCategory(val label: String, val icon: ImageVector) {
+    Appearance("Appearance", Icons.Default.ColorLens),
+    Playback("Playback", Icons.Default.PlayArrow),
+    Library("Library", Icons.Default.LibraryMusic),
+    Providers("Providers", Icons.Default.Cloud),
+    About("About", Icons.Default.Info)
+}
+
+/**
+ * Discord-shaped settings: left category rail, large right pane.
+ * Material 3 surfaces and extra-round selected pills.
+ */
+@Composable
+fun SettingsShell(
+    selected: SettingsCategory,
+    onSelect: (SettingsCategory) -> Unit,
+    onClose: () -> Unit,
+    modifier: Modifier = Modifier,
+    categories: List<SettingsCategory> = SettingsCategory.entries,
+    content: @Composable () -> Unit
+) {
+    Surface(
+        modifier = modifier,
+        shape = MaterialTheme.shapes.extraLarge,
+        color = MaterialTheme.colorScheme.surface,
+        tonalElevation = 2.dp
+    ) {
+        Row(Modifier.fillMaxSize()) {
+            Column(
+                Modifier
+                    .width(240.dp)
+                    .fillMaxHeight()
+                    .background(MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.35f))
+                    .padding(16.dp)
+            ) {
+                Text(
+                    "Settings",
+                    style = MaterialTheme.typography.headlineSmall,
+                    fontWeight = FontWeight.Bold,
+                    modifier = Modifier.padding(horizontal = 8.dp, vertical = 12.dp)
+                )
+                categories.forEach { cat ->
+                    val on = cat == selected
+                    Row(
+                        Modifier
+                            .fillMaxWidth()
+                            .clip(RoundedCornerShape(50))
+                            .clickable { onSelect(cat) }
+                            .background(
+                                if (on) MaterialTheme.colorScheme.primary.copy(alpha = 0.16f)
+                                else MaterialTheme.colorScheme.surface.copy(alpha = 0f)
+                            )
+                            .padding(horizontal = 14.dp, vertical = 12.dp),
+                        verticalAlignment = Alignment.CenterVertically
+                    ) {
+                        Icon(
+                            cat.icon,
+                            contentDescription = cat.label,
+                            tint = if (on) MaterialTheme.colorScheme.primary
+                            else MaterialTheme.colorScheme.onSurface
+                        )
+                        Spacer(Modifier.width(12.dp))
+                        Text(
+                            cat.label,
+                            fontWeight = if (on) FontWeight.SemiBold else FontWeight.Medium,
+                            color = if (on) MaterialTheme.colorScheme.primary
+                            else MaterialTheme.colorScheme.onSurface
+                        )
+                    }
+                }
+            }
+            Column(Modifier.weight(1f).fillMaxHeight()) {
+                Row(
+                    Modifier.fillMaxWidth().padding(8.dp),
+                    verticalAlignment = Alignment.CenterVertically
+                ) {
+                    Text(
+                        selected.label,
+                        style = MaterialTheme.typography.titleLarge,
+                        fontWeight = FontWeight.Bold,
+                        modifier = Modifier.weight(1f).padding(start = 8.dp)
+                    )
+                    IconButton(onClick = onClose) {
+                        Icon(Icons.Default.Close, contentDescription = "Close")
+                    }
+                }
+                Column(Modifier.fillMaxSize().padding(horizontal = 24.dp, vertical = 8.dp)) {
+                    content()
+                }
+            }
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/AccentPicker.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/AccentPicker.kt
new file mode 100644
index 00000000..d3734bdf
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/AccentPicker.kt
@@ -0,0 +1,76 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.CircleShape
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.unit.dp
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+fun ThemeModePicker(
+    mode: ThemeMode,
+    onMode: (ThemeMode) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    FlowRow(
+        modifier = modifier,
+        horizontalArrangement = Arrangement.spacedBy(8.dp)
+    ) {
+        ThemeMode.entries.forEach { m ->
+            FilterChip(
+                selected = mode == m,
+                onClick = { onMode(m) },
+                label = { Text(m.label) }
+            )
+        }
+    }
+}
+
+@OptIn(ExperimentalLayoutApi::class)
+@Composable
+fun AccentPicker(
+    selectedId: String,
+    onSelect: (String) -> Unit,
+    modifier: Modifier = Modifier
+) {
+    Column(modifier) {
+        Text(
+            "Accent",
+            style = MaterialTheme.typography.titleSmall,
+            color = MaterialTheme.colorScheme.onSurface,
+            modifier = Modifier.padding(bottom = 8.dp)
+        )
+        FlowRow(horizontalArrangement = Arrangement.spacedBy(10.dp), verticalArrangement = Arrangement.spacedBy(10.dp)) {
+            AccentCatalog.all.forEach { swatch ->
+                val selected = swatch.id == selectedId
+                Box(
+                    Modifier
+                        .size(40.dp)
+                        .clip(CircleShape)
+                        .background(swatch.color)
+                        .border(
+                            width = if (selected) 3.dp else 1.dp,
+                            color = if (selected) MaterialTheme.colorScheme.onSurface
+                            else MaterialTheme.colorScheme.onSurface.copy(alpha = 0.25f),
+                            shape = CircleShape
+                        )
+                        .clickable { onSelect(swatch.id) }
+                )
+            }
+        }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/AlbumArtBackdrop.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/AlbumArtBackdrop.kt
new file mode 100644
index 00000000..1a0af79c
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/AlbumArtBackdrop.kt
@@ -0,0 +1,85 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.BoxScope
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.State
+import androidx.compose.runtime.produceState
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.drawBehind
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.graphics.Brush
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.drawscope.DrawScope
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.core.library.sampleCoverArgb
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+
+/**
+ * Shared album-page atmosphere: page chrome stays [pageBackground], art color
+ * blooms radially from the cover (top-center on phone, left column on wide).
+ * Mobile and desktop both call this so the wash is identical.
+ */
+@Composable
+fun AlbumArtBackdrop(
+    wash: Color,
+    accent: Color = wash,
+    modifier: Modifier = Modifier,
+    content: @Composable BoxScope.() -> Unit
+) {
+    Box(
+        modifier = modifier.drawBehind {
+            drawAlbumArtScrim(wash = wash, accent = accent)
+        },
+        content = content
+    )
+}
+
+fun DrawScope.drawAlbumArtScrim(wash: Color, accent: Color) {
+    if (wash.alpha <= 0.01f) return
+    val compact = size.width < 600.dp.toPx()
+    val center = if (compact) {
+        Offset(size.width * 0.5f, size.height * 0.18f)
+    } else {
+        Offset(size.width * 0.16f, size.height * 0.28f)
+    }
+    val radius = size.maxDimension * 1.35f
+    drawRect(wash.copy(alpha = 0.07f))
+    drawRect(
+        brush = Brush.radialGradient(
+            colorStops = arrayOf(
+                0.00f to wash.copy(alpha = 0.50f),
+                0.16f to wash.copy(alpha = 0.34f),
+                0.34f to wash.copy(alpha = 0.18f),
+                0.52f to wash.copy(alpha = 0.09f),
+                0.72f to wash.copy(alpha = 0.035f),
+                1.00f to Color.Transparent
+            ),
+            center = center,
+            radius = radius
+        )
+    )
+    drawRect(
+        brush = Brush.radialGradient(
+            colorStops = arrayOf(
+                0.00f to accent.copy(alpha = 0.14f),
+                0.28f to accent.copy(alpha = 0.06f),
+                0.62f to accent.copy(alpha = 0.02f),
+                1.00f to Color.Transparent
+            ),
+            center = center,
+            radius = radius * 0.55f
+        )
+    )
+}
+
+@Composable
+fun rememberCoverColors(
+    artworkUri: String?,
+    audioPath: String? = null
+): State<PlayerColors?> = produceState(initialValue = null, artworkUri, audioPath) {
+    value = withContext(Dispatchers.Default) {
+        sampleCoverArgb(artworkUri, audioPath)?.let { playerColorsFromPixels(it) }
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/PlayerColors.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/PlayerColors.kt
new file mode 100644
index 00000000..f6d85a7d
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/PlayerColors.kt
@@ -0,0 +1,152 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.material3.ColorScheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.runtime.staticCompositionLocalOf
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.luminance
+import kotlin.math.max
+import kotlin.math.min
+
+data class PlayerColors(
+    val container: Color,
+    val onContainer: Color,
+    val accent: Color,
+    val onAccent: Color,
+    val muted: Color,
+    val surface: Color,
+    val onSurface: Color
+)
+
+val LocalPlayerColors = staticCompositionLocalOf<PlayerColors?> { null }
+
+fun fallbackPlayerColors(scheme: ColorScheme = YuriDarkColorScheme): PlayerColors = PlayerColors(
+    container = scheme.surface,
+    onContainer = scheme.onSurface,
+    accent = scheme.primary,
+    onAccent = scheme.onPrimary,
+    muted = scheme.onSurface.copy(alpha = 0.55f),
+    surface = scheme.surfaceVariant,
+    onSurface = scheme.onSurface
+)
+
+fun playerColorScheme(
+    colors: PlayerColors,
+    base: ColorScheme = YuriDarkColorScheme,
+    useArtBackground: Boolean = true
+): ColorScheme {
+    val bg = if (useArtBackground) colors.container else base.background
+    val onBg = if (useArtBackground) colors.onContainer else base.onBackground
+    val surface = if (useArtBackground) colors.container else base.surface
+    val onSurface = if (useArtBackground) colors.onContainer else base.onSurface
+    return darkColorScheme(
+        primary = colors.accent,
+        onPrimary = colors.onAccent,
+        primaryContainer = colors.container,
+        onPrimaryContainer = colors.onContainer,
+        secondary = colors.accent,
+        onSecondary = colors.onAccent,
+        background = bg,
+        onBackground = onBg,
+        surface = surface,
+        onSurface = onSurface,
+        surfaceVariant = if (useArtBackground) colors.surface else base.surfaceVariant,
+        onSurfaceVariant = if (useArtBackground) colors.muted else base.onSurfaceVariant,
+        outline = colors.muted
+    )
+}
+
+/**
+ * Palette-from-pixels (no Android Palette). Skips near-black/white, buckets
+ * quantized RGB, picks a dark stage + a lifted accent — same rules as mobile.
+ */
+fun playerColorsFromPixels(argb: IntArray): PlayerColors? {
+    if (argb.isEmpty()) return null
+    val buckets = HashMap<Int, Bucket>(64)
+    for (px in argb) {
+        val a = px ushr 24 and 0xFF
+        if (a < 32) continue
+        val r = px shr 16 and 0xFF
+        val g = px shr 8 and 0xFF
+        val b = px and 0xFF
+        val maxC = max(r, max(g, b))
+        val minC = min(r, min(g, b))
+        if (maxC < 18) continue
+        if (minC > 245) continue
+        val sat = if (maxC == 0) 0f else (maxC - minC).toFloat() / maxC
+        if (sat < 0.08f && maxC < 40) continue
+        val key = (r ushr 3 shl 10) or (g ushr 3 shl 5) or (b ushr 3)
+        val bucket = buckets.getOrPut(key) { Bucket() }
+        bucket.count++
+        bucket.r += r
+        bucket.g += g
+        bucket.b += b
+        bucket.sat += sat
+    }
+    if (buckets.isEmpty()) return null
+    val ranked = buckets.values.sortedByDescending { it.count }
+    val dominant = ranked.first().color()
+    val vibrant = ranked.maxBy { it.sat / it.count * (1f + it.count / ranked.first().count.toFloat()) }.color()
+
+    val containerRaw = dominant
+    val stage = if (containerRaw.luminance() > 0.35f) {
+        containerRaw.copy(
+            red = containerRaw.red * 0.35f,
+            green = containerRaw.green * 0.35f,
+            blue = containerRaw.blue * 0.35f
+        )
+    } else containerRaw
+    val accent = ensureAccentOnDark(vibrant, dominant, stage)
+    val onStage = if (stage.luminance() > 0.5f) Color.Black else Color.White
+    val onAccent = if (accent.luminance() > 0.55f) Color.Black else Color.White
+    return PlayerColors(
+        container = stage,
+        onContainer = onStage,
+        accent = accent,
+        onAccent = onAccent,
+        muted = onStage.copy(alpha = 0.55f),
+        surface = Color(
+            red = stage.red * 0.85f + 0.08f,
+            green = stage.green * 0.85f + 0.08f,
+            blue = stage.blue * 0.85f + 0.08f
+        ),
+        onSurface = onStage
+    )
+}
+
+private class Bucket {
+    var count = 0
+    var r = 0
+    var g = 0
+    var b = 0
+    var sat = 0f
+    fun color(): Color {
+        val n = count.coerceAtLeast(1)
+        return Color(r / n / 255f, g / n / 255f, b / n / 255f)
+    }
+}
+
+private fun ensureAccentOnDark(primary: Color, fallback: Color, stage: Color): Color {
+    val usable = listOf(primary, fallback).firstOrNull { c ->
+        c.luminance() > 0.22f && contrastRatio(c, stage) >= 3f
+    }
+    if (usable != null) return usable
+    val base = if (primary.luminance() >= fallback.luminance()) primary else fallback
+    var t = 0.15f
+    var out = base
+    while (out.luminance() < 0.42f && t <= 0.85f) {
+        out = Color(
+            red = base.red + (1f - base.red) * t,
+            green = base.green + (1f - base.green) * t,
+            blue = base.blue + (1f - base.blue) * t
+        )
+        t += 0.1f
+    }
+    return out
+}
+
+private fun contrastRatio(a: Color, b: Color): Float {
+    val l1 = a.luminance() + 0.05f
+    val l2 = b.luminance() + 0.05f
+    return max(l1, l2) / min(l1, l2)
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/ThemeCatalog.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/ThemeCatalog.kt
new file mode 100644
index 00000000..24f32c08
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/ThemeCatalog.kt
@@ -0,0 +1,115 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.material3.ColorScheme
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.material3.lightColorScheme
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.luminance
+
+/**
+ * Appearance is **not** glued to Material 3 forever.
+ *
+ * [ThemeFamily.MATERIAL3] is the default (light/dark + accent). Other families
+ * (Jewel, macOS, Windows) plug in later — see github.com/LizAinslie/yuriplayer/issues/16.
+ */
+enum class ThemeFamily(val id: String, val label: String) {
+    MATERIAL3("material3", "Material 3")
+}
+
+enum class ThemeMode(val id: String, val label: String) {
+    DARK("dark", "Dark"),
+    LIGHT("light", "Light"),
+    SYSTEM("system", "Follow system");
+
+    companion object {
+        fun fromId(raw: String?): ThemeMode =
+            entries.firstOrNull { it.id.equals(raw, true) } ?: DARK
+    }
+}
+
+data class AccentSwatch(
+    val id: String,
+    val label: String,
+    val color: Color
+)
+
+object AccentCatalog {
+    val yuri = AccentSwatch("yuri", "Yuri purple", Color(0xFFB388FF))
+    val all: List<AccentSwatch> = listOf(
+        yuri,
+        AccentSwatch("violet", "Violet", Color(0xFF7C4DFF)),
+        AccentSwatch("rose", "Rose", Color(0xFFFF8A80)),
+        AccentSwatch("coral", "Coral", Color(0xFFFF6E40)),
+        AccentSwatch("amber", "Amber", Color(0xFFFFC107)),
+        AccentSwatch("lime", "Lime", Color(0xFFC6FF00)),
+        AccentSwatch("teal", "Teal", Color(0xFF1DE9B6)),
+        AccentSwatch("sky", "Sky", Color(0xFF40C4FF)),
+        AccentSwatch("indigo", "Indigo", Color(0xFF5C6BC0)),
+        AccentSwatch("graphite", "Graphite", Color(0xFF90A4AE))
+    )
+
+    fun byId(id: String?): AccentSwatch =
+        all.firstOrNull { it.id.equals(id, true) } ?: yuri
+}
+
+data class ThemeChoice(
+    val mode: ThemeMode = ThemeMode.DARK,
+    val accentId: String = AccentCatalog.yuri.id,
+    val family: ThemeFamily = ThemeFamily.MATERIAL3
+)
+
+fun ThemeChoice.isDark(systemDark: Boolean): Boolean = when (mode) {
+    ThemeMode.DARK -> true
+    ThemeMode.LIGHT -> false
+    ThemeMode.SYSTEM -> systemDark
+}
+
+fun ThemeChoice.colorScheme(
+    systemDark: Boolean,
+    dynamic: ColorScheme? = null
+): ColorScheme {
+    if (dynamic != null && family == ThemeFamily.MATERIAL3) return dynamic
+    val accent = AccentCatalog.byId(accentId).color
+    return material3Scheme(isDark(systemDark), accent)
+}
+
+fun material3Scheme(dark: Boolean, accent: Color): ColorScheme {
+    val onAccent = if (accent.luminance() > 0.55f) Color(0xFF1A1224) else Color.White
+    return if (dark) {
+        darkColorScheme(
+            primary = accent,
+            onPrimary = onAccent,
+            primaryContainer = accent.copy(alpha = 0.28f),
+            onPrimaryContainer = Color(0xFFE8E0F0),
+            secondary = accent.copy(alpha = 0.85f),
+            onSecondary = onAccent,
+            tertiary = Color(0xFFEFB8C8),
+            onTertiary = Color(0xFF1A1224),
+            background = Color(0xFF121018),
+            onBackground = Color(0xFFE8E0F0),
+            surface = Color(0xFF1C1826),
+            onSurface = Color(0xFFE8E0F0),
+            surfaceVariant = Color(0xFF2A2438),
+            onSurfaceVariant = Color(0xFFB0A4C0),
+            outline = Color(0xFFB0A4C0).copy(alpha = 0.5f)
+        )
+    } else {
+        lightColorScheme(
+            primary = accent,
+            onPrimary = onAccent,
+            primaryContainer = accent.copy(alpha = 0.18f),
+            onPrimaryContainer = Color(0xFF1A1224),
+            secondary = accent,
+            onSecondary = onAccent,
+            tertiary = Color(0xFFB0005A),
+            onTertiary = Color.White,
+            background = Color(0xFFF6F0FA),
+            onBackground = Color(0xFF1A1224),
+            surface = Color(0xFFFFFBFF),
+            onSurface = Color(0xFF1A1224),
+            surfaceVariant = Color(0xFFE8DFF0),
+            onSurfaceVariant = Color(0xFF4A4258),
+            outline = Color(0xFF7A7088)
+        )
+    }
+}
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriColors.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriColors.kt
new file mode 100644
index 00000000..c6dff119
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriColors.kt
@@ -0,0 +1,34 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.material3.darkColorScheme
+import androidx.compose.ui.graphics.Color
+
+/** Same tokens as Android [capital.yuri.yuriplayer.activities.ui.theme]. */
+val YuriPurple = Color(0xFFB388FF)
+val YuriPurpleDim = Color(0xFF7E57C2)
+val YuriBg = Color(0xFF121018)
+val YuriSurface = Color(0xFF1C1826)
+val YuriSurfaceVariant = Color(0xFF2A2438)
+val YuriOnBg = Color(0xFFE8E0F0)
+val YuriMuted = Color(0xFFB0A4C0)
+val YuriBlackish = Color(0xFF1A1224)
+val YuriPurpleGrey = Color(0xFFCCC2DC)
+val YuriPink = Color(0xFFEFB8C8)
+
+val YuriDarkColorScheme = darkColorScheme(
+    primary = YuriPurple,
+    onPrimary = YuriBlackish,
+    primaryContainer = YuriPurpleDim,
+    onPrimaryContainer = YuriOnBg,
+    secondary = YuriPurpleGrey,
+    onSecondary = YuriBlackish,
+    tertiary = YuriPink,
+    onTertiary = YuriBlackish,
+    background = YuriBg,
+    onBackground = YuriOnBg,
+    surface = YuriSurface,
+    onSurface = YuriOnBg,
+    surfaceVariant = YuriSurfaceVariant,
+    onSurfaceVariant = YuriMuted,
+    outline = YuriMuted.copy(alpha = 0.5f)
+)
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriShapes.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriShapes.kt
new file mode 100644
index 00000000..95f9ccc0
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriShapes.kt
@@ -0,0 +1,14 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Shapes
+import androidx.compose.ui.unit.dp
+
+/** M3 Expressive-leaning scale: bigger rounds, bento cards. */
+val YuriShapes = Shapes(
+    extraSmall = RoundedCornerShape(8.dp),
+    small = RoundedCornerShape(12.dp),
+    medium = RoundedCornerShape(20.dp),
+    large = RoundedCornerShape(28.dp),
+    extraLarge = RoundedCornerShape(36.dp)
+)
diff --git a/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriTheme.kt b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriTheme.kt
new file mode 100644
index 00000000..985762a3
--- /dev/null
+++ b/components/src/commonMain/kotlin/capital/yuri/yuriplayer/components/theme/YuriTheme.kt
@@ -0,0 +1,45 @@
+package capital.yuri.yuriplayer.components.theme
+
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.ColorScheme
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+
+@Composable
+fun YuriTheme(
+    choice: ThemeChoice = ThemeChoice(),
+    colorScheme: ColorScheme? = null,
+    content: @Composable () -> Unit
+) {
+    val scheme = colorScheme ?: choice.colorScheme(isSystemInDarkTheme())
+    MaterialTheme(
+        colorScheme = scheme,
+        shapes = YuriShapes
+    ) {
+        Surface(
+            modifier = Modifier.fillMaxSize(),
+            color = scheme.background,
+            contentColor = scheme.onBackground
+        ) {
+            content()
+        }
+    }
+}
+
+@Composable
+fun PlayerChromeTheme(
+    colors: PlayerColors?,
+    useArtBackground: Boolean,
+    content: @Composable () -> Unit
+) {
+    val base = MaterialTheme.colorScheme
+    val scheme = if (colors != null) {
+        playerColorScheme(colors, base, useArtBackground)
+    } else {
+        base
+    }
+    MaterialTheme(colorScheme = scheme, shapes = YuriShapes, content = content)
+}
diff --git a/components/src/jvmMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.jvm.kt b/components/src/jvmMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.jvm.kt
new file mode 100644
index 00000000..62325d68
--- /dev/null
+++ b/components/src/jvmMain/kotlin/capital/yuri/yuriplayer/components/platform/Screen.jvm.kt
@@ -0,0 +1,31 @@
+package capital.yuri.yuriplayer.components.platform
+
+import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.IntSize
+import java.awt.GraphicsEnvironment
+import java.awt.KeyboardFocusManager
+import java.awt.Toolkit
+
+actual fun screenSizePx(): IntSize {
+    if (GraphicsEnvironment.isHeadless()) return IntSize.Zero
+    return try {
+        val size = Toolkit.getDefaultToolkit().screenSize
+        IntSize(size.width, size.height)
+    } catch (_: Throwable) {
+        IntSize.Zero
+    }
+}
+
+actual fun windowPositionOnScreenPx(): IntOffset {
+    if (GraphicsEnvironment.isHeadless()) return IntOffset.Zero
+    return try {
+        val focus = KeyboardFocusManager.getCurrentKeyboardFocusManager()
+        val window = focus.focusedWindow ?: focus.activeWindow
+        window?.let {
+            val loc = it.locationOnScreen
+            IntOffset(loc.x, loc.y)
+        } ?: IntOffset.Zero
+    } catch (_: Throwable) {
+        IntOffset.Zero
+    }
+}
diff --git a/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/menu/MenuDslTest.kt b/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/menu/MenuDslTest.kt
new file mode 100644
index 00000000..6749219f
--- /dev/null
+++ b/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/menu/MenuDslTest.kt
@@ -0,0 +1,21 @@
+package capital.yuri.yuriplayer.components.menu
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class MenuDslTest {
+    @Test
+    fun itemAlternateIsNestedNotPrimary() {
+        val menu = buildContextMenu {
+            item("Add to playlist", alternate = {
+                item("Late night") {}
+                item("Gym") {}
+            }) {}
+        }
+        val item = menu.single() as MenuEntry.Item
+        assertEquals("Add to playlist", item.label)
+        assertEquals(listOf("Late night", "Gym"), item.alternate.map { (it as MenuEntry.Item).label })
+        assertTrue(item.alternate.none { it is MenuEntry.Submenu })
+    }
+}
diff --git a/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/menu/PredictionConeTest.kt b/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/menu/PredictionConeTest.kt
new file mode 100644
index 00000000..77fb1866
--- /dev/null
+++ b/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/menu/PredictionConeTest.kt
@@ -0,0 +1,30 @@
+package capital.yuri.yuriplayer.components.menu
+
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Rect
+import kotlin.test.Test
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class PredictionConeTest {
+    private val submenu = Rect(200f, 40f, 360f, 200f)
+    private val origin = Offset(80f, 80f)
+
+    @Test
+    fun pointInsideTriangleCounts() {
+        assertTrue(pointInTriangle(Offset(10f, 10f), Offset(0f, 0f), Offset(20f, 0f), Offset(0f, 20f)))
+        assertFalse(pointInTriangle(Offset(20f, 20f), Offset(0f, 0f), Offset(20f, 0f), Offset(0f, 20f)))
+    }
+
+    @Test
+    fun diagonalTowardSubmenuIsSafe() {
+        assertTrue(pointerInPredictionCone(Offset(180f, 100f), origin, submenu))
+        assertTrue(pointerInPredictionCone(Offset(150f, 90f), origin, submenu))
+    }
+
+    @Test
+    fun siblingItemBelowIsNotSafe() {
+        assertFalse(pointerInPredictionCone(Offset(80f, 280f), origin, submenu))
+        assertFalse(pointerInPredictionCone(Offset(40f, 300f), origin, submenu))
+    }
+}
diff --git a/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/model/ArtistPageTest.kt b/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/model/ArtistPageTest.kt
new file mode 100644
index 00000000..09db368d
--- /dev/null
+++ b/components/src/jvmTest/kotlin/capital/yuri/yuriplayer/components/model/ArtistPageTest.kt
@@ -0,0 +1,93 @@
+package capital.yuri.yuriplayer.components.model
+
+import capital.yuri.yuriplayer.core.library.matchesQuery
+import capital.yuri.yuriplayer.core.library.matchesSearch
+import capital.yuri.yuriplayer.data.Song
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class ArtistPageTest {
+
+    private fun song(
+        title: String,
+        album: String,
+        artist: String = "Lemon Demon",
+        albumArtist: String? = "Lemon Demon",
+        tn: Int? = null,
+        disc: Int? = null,
+        path: String? = null,
+        sourceId: String = "local"
+    ) = Song(
+        id = "$path-$tn".hashCode().toLong(),
+        title = title,
+        artist = artist,
+        albumArtist = albumArtist,
+        album = album,
+        contentUri = if (sourceId == "local") "file:///$path" else "https://navi/stream/$tn",
+        trackNumber = tn,
+        discNumber = disc,
+        path = path,
+        sourceId = sourceId
+    )
+
+    private val spiritPhone = listOf(
+        "Lifetime Achievement Award",
+        "Touch-Tone Telephone",
+        "Cabinet Man",
+        "No Eyed Girl",
+        "When He Died",
+        "Sweet Bod",
+        "Eighth Wonder",
+        "Ancient Aliens",
+        "Soft Fuzzy Man",
+        "As Your Father I Expressly Forbid It",
+        "I Earn My Life",
+        "Reaganomics",
+        "Man-Made Object",
+        "Spiral of Ants"
+    )
+
+    @Test
+    fun albumsAndArtistPageForSingleSource() {
+        val tracks = spiritPhone.mapIndexed { i, title ->
+            song(title, album = "Spirit Phone", tn = i + 1, path = "/music/Lemon Demon/Spirit Phone/${i + 1}. $title.flac")
+        }
+        val albums = tracks.albums()
+        assertEquals(1, albums.size)
+        assertEquals("Spirit Phone", albums.first().title)
+
+        val page = tracks.artistPage("Lemon Demon")
+        assertEquals(1, page.discography.size)
+        assertTrue(page.stats.contains("14 tracks"), page.stats)
+    }
+
+    @Test
+    fun artistPageAcrossSourcesStillFindsDiscography() {
+        val local = spiritPhone.mapIndexed { i, title ->
+            song(title, "Spirit Phone", tn = i + 1, path = "/music/Lemon Demon/Spirit Phone/${i + 1}. $title.flac", sourceId = "local")
+        }
+        val remote = spiritPhone.mapIndexed { i, title ->
+            song(title, "Spirit Phone", albumArtist = "Lemon Demon", tn = i + 1, path = "subsonic:${i + 1}", sourceId = "navidrome-1")
+        }
+        val all = local + remote
+
+        val albums = all.albums()
+        assertEquals(1, albums.size, "expected one collapsed album, got ${albums.map { it.title }}")
+
+        val page = all.artistPage("Lemon Demon")
+        assertEquals(1, page.discography.size)
+        assertTrue(page.stats.contains("14 tracks"), page.stats)
+    }
+
+    @Test
+    fun searchMatchesLocalArtistAndAlbum() {
+        val tracks = spiritPhone.mapIndexed { i, title ->
+            song(title, "Spirit Phone", tn = i + 1, path = "/music/Lemon Demon/Spirit Phone/${i + 1}. $title.flac")
+        }
+        val local = tracks.first { it.displayArtist.equals("Lemon Demon", true) }
+        assertTrue(local.matchesQuery("lemon demon"))
+        assertTrue(local.matchesQuery("spirit phone"))
+        assertTrue("Lemon Demon".matchesSearch("lemon demon"))
+    }
+}
diff --git a/core/build.gradle.kts b/core/build.gradle.kts
new file mode 100644
index 00000000..60ec7794
--- /dev/null
+++ b/core/build.gradle.kts
@@ -0,0 +1,61 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+    alias(libs.plugins.android.kmp.library)
+    alias(libs.plugins.kotlin.serialization)
+    alias(libs.plugins.ksp)
+    alias(libs.plugins.androidx.room)
+}
+
+kotlin {
+    android {
+        namespace = "capital.yuri.yuriplayer.core"
+        compileSdk = 36
+        minSdk = 27
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_11)
+        }
+    }
+    jvm {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_11)
+        }
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            implementation(libs.kotlinx.coroutines.core)
+            implementation(libs.kotlinx.serialization.json)
+            implementation(libs.ktor.client.core)
+            implementation(libs.androidx.room.runtime)
+            implementation(libs.androidx.sqlite.bundled)
+        }
+        androidMain.dependencies {
+            implementation(libs.kotlinx.coroutines.android)
+            implementation(libs.ktor.client.cio)
+        }
+        jvmMain.dependencies {
+            implementation(libs.jaudiotagger)
+            implementation(libs.ktor.client.cio)
+            implementation(libs.slf4j.api)
+            implementation(libs.androidx.sqlite.bundled)
+        }
+        jvmTest.dependencies {
+            implementation(kotlin("test"))
+        }
+    }
+}
+
+dependencies {
+    // Common metadata pass generates the KMP constructor (expect/actual) and
+    // validates the schema. Per-target passes below generate the real
+    // `YuriDatabase_Impl` that each platform loads at runtime.
+    add("kspCommonMainMetadata", libs.androidx.room.compiler)
+    add("kspAndroid", libs.androidx.room.compiler)
+    add("kspJvm", libs.androidx.room.compiler)
+}
+
+room {
+    schemaDirectory(layout.projectDirectory.dir("schemas").asFile.absolutePath)
+}
diff --git a/core/src/androidMain/AndroidManifest.xml b/core/src/androidMain/AndroidManifest.xml
new file mode 100644
index 00000000..cc947c56
--- /dev/null
+++ b/core/src/androidMain/AndroidManifest.xml
@@ -0,0 +1 @@
+<manifest />
diff --git a/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.android.kt b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.android.kt
new file mode 100644
index 00000000..225878b6
--- /dev/null
+++ b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.android.kt
@@ -0,0 +1,35 @@
+package capital.yuri.yuriplayer.core.library
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import java.io.File
+import java.net.URI
+
+actual fun sampleCoverArgb(artworkUri: String?, audioPath: String?, size: Int): IntArray? {
+    val path = when {
+        artworkUri.isNullOrBlank() -> audioPath
+        artworkUri.startsWith("file:") -> runCatching { File(URI(artworkUri)).path }.getOrNull()
+        else -> artworkUri
+    } ?: return null
+    val file = File(path)
+    if (!file.isFile) return null
+    val opts = BitmapFactory.Options().apply {
+        inJustDecodeBounds = true
+    }
+    BitmapFactory.decodeFile(file.absolutePath, opts)
+    val longest = maxOf(opts.outWidth, opts.outHeight).coerceAtLeast(1)
+    val sample = (longest / size).coerceAtLeast(1)
+    val decoded = BitmapFactory.decodeFile(
+        file.absolutePath,
+        BitmapFactory.Options().apply {
+            inSampleSize = sample
+            inPreferredConfig = Bitmap.Config.ARGB_8888
+        }
+    ) ?: return null
+    val scaled = Bitmap.createScaledBitmap(decoded, size, size, true)
+    if (scaled != decoded) decoded.recycle()
+    val pixels = IntArray(size * size)
+    scaled.getPixels(pixels, 0, size, 0, 0, size, size)
+    if (scaled != decoded) scaled.recycle()
+    return pixels
+}
diff --git a/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.android.kt b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.android.kt
new file mode 100644
index 00000000..a452ecad
--- /dev/null
+++ b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.android.kt
@@ -0,0 +1,16 @@
+package capital.yuri.yuriplayer.core.log
+
+import android.util.Log
+
+actual fun platformLog(level: LogLevel, tag: String, message: String, throwable: Throwable?) {
+    val name = "YuriPlayer.$tag"
+    when (level) {
+        LogLevel.TRACE -> if (throwable != null) Log.v(name, message, throwable) else Log.v(name, message)
+        LogLevel.DEBUG -> if (throwable != null) Log.d(name, message, throwable) else Log.d(name, message)
+        LogLevel.INFO -> if (throwable != null) Log.i(name, message, throwable) else Log.i(name, message)
+        LogLevel.WARN -> if (throwable != null) Log.w(name, message, throwable) else Log.w(name, message)
+        LogLevel.ERROR -> if (throwable != null) Log.e(name, message, throwable) else Log.e(name, message)
+    }
+}
+
+actual fun platformLogEnabled(level: LogLevel): Boolean = true
diff --git a/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.android.kt b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.android.kt
new file mode 100644
index 00000000..99252af0
--- /dev/null
+++ b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.android.kt
@@ -0,0 +1,31 @@
+package capital.yuri.yuriplayer.core.platform
+
+import android.annotation.SuppressLint
+import android.content.Context
+import java.io.File
+
+/**
+ * Call [install] from Application.onCreate before anything reads dirs.
+ */
+object AndroidAppDirectories : AppDirectories {
+    @SuppressLint("StaticFieldLeak")
+    private var appContext: Context? = null
+
+    fun install(context: Context) {
+        appContext = context.applicationContext
+    }
+
+    private fun ctx(): Context =
+        requireNotNull(appContext) { "AndroidAppDirectories.install(context) was not called" }
+
+    override val configDir: String
+        get() = File(ctx().filesDir, "config").apply { mkdirs() }.absolutePath
+    override val cacheDir: String
+        get() = ctx().cacheDir.absolutePath
+    override val dataDir: String
+        get() = File(ctx().filesDir, "data").apply { mkdirs() }.absolutePath
+    override val defaultMusicRoots: List<String>
+        get() = emptyList()
+}
+
+actual fun appDirectories(): AppDirectories = AndroidAppDirectories
diff --git a/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.android.kt b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.android.kt
new file mode 100644
index 00000000..07837301
--- /dev/null
+++ b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.android.kt
@@ -0,0 +1,3 @@
+package capital.yuri.yuriplayer.core.platform
+
+actual fun hostOs(): HostOs = HostOs.ANDROID
diff --git a/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.android.kt b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.android.kt
new file mode 100644
index 00000000..8d31b124
--- /dev/null
+++ b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.android.kt
@@ -0,0 +1,37 @@
+package capital.yuri.yuriplayer.core.text
+
+import android.icu.text.Transliterator
+import android.os.Build
+import java.text.Normalizer
+
+internal actual fun foldCompare(s: String): String {
+    var t = s.trim().lowercase()
+    t = Normalizer.normalize(t, Normalizer.Form.NFKC)
+    t = transliterate(t, "Traditional-Simplified")
+    t = katakanaToHiragana(t)
+    t = Normalizer.normalize(t, Normalizer.Form.NFD)
+    t = t.replace(Regex("\\p{M}+"), "")
+    t = transliterate(t, "Latin-ASCII")
+    t = latinAscii(t)
+    t = t.replace(Regex("[\\s\\p{Punct}]+"), " ").trim()
+    return t
+}
+
+private fun transliterate(value: String, id: String): String = try {
+    if (Build.VERSION.SDK_INT >= 29) {
+        Transliterator.getInstance(id).transliterate(value)
+    } else {
+        value
+    }
+} catch (_: Exception) {
+    value
+}
+
+internal actual fun isCjkCodePoint(cp: Int): Boolean {
+    val script = Character.UnicodeScript.of(cp)
+    return script == Character.UnicodeScript.HAN ||
+        script == Character.UnicodeScript.HIRAGANA ||
+        script == Character.UnicodeScript.KATAKANA ||
+        script == Character.UnicodeScript.HANGUL ||
+        script == Character.UnicodeScript.BOPOMOFO
+}
diff --git a/core/src/androidMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.android.kt b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.android.kt
new file mode 100644
index 00000000..2e138357
--- /dev/null
+++ b/core/src/androidMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.android.kt
@@ -0,0 +1,20 @@
+package capital.yuri.yuriplayer.data.db
+
+import android.content.Context
+import androidx.room.Room
+import androidx.sqlite.driver.bundled.BundledSQLiteDriver
+import kotlinx.coroutines.Dispatchers
+
+/**
+ * Android factory for the shared [YuriDatabase] schema.
+ */
+fun createYuriDatabase(context: Context): YuriDatabase =
+    Room.databaseBuilder(
+        context.applicationContext,
+        YuriDatabase::class.java,
+        "yuriplayer.db"
+    )
+        .setDriver(BundledSQLiteDriver())
+        .setQueryCoroutineContext(Dispatchers.IO)
+        .addMigrations(*YuriMigrations.ALL)
+        .build()
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistProfile.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistProfile.kt
new file mode 100644
index 00000000..aa680cd4
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistProfile.kt
@@ -0,0 +1,32 @@
+package capital.yuri.yuriplayer.core.artist
+
+import kotlinx.serialization.Serializable
+
+enum class ArtistImageKind { PROFILE, BANNER }
+
+@Serializable
+data class ArtistImageCandidate(
+    val url: String,
+    val sourceId: String,
+    val label: String = sourceId,
+    val width: Int? = null,
+    val height: Int? = null
+)
+
+@Serializable
+data class ArtistProfile(
+    val artistKey: String,
+    val displayName: String,
+    val bio: String? = null,
+    val imageUri: String? = null,
+    val bannerUri: String? = null,
+    val genres: List<String> = emptyList(),
+    val source: String = "local",
+    val updatedAtMs: Long = 0L,
+    val bannerCleared: Boolean = false
+)
+
+fun artistKey(name: String?): String? {
+    val t = name?.trim()?.lowercase()?.replace(Regex("\\s+"), " ") ?: return null
+    return t.takeIf { it.isNotEmpty() }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/http/UrlDsl.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/http/UrlDsl.kt
new file mode 100644
index 00000000..a8c35a38
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/http/UrlDsl.kt
@@ -0,0 +1,35 @@
+package capital.yuri.yuriplayer.core.http
+
+import io.ktor.http.URLBuilder
+import io.ktor.http.appendPathSegments
+
+fun url(base: String, block: UrlScope.() -> Unit = {}): String =
+    UrlScope(URLBuilder(base.trim())).apply(block).build()
+
+class UrlScope internal constructor(private val builder: URLBuilder) {
+    fun path(vararg segments: String, encodeSlash: Boolean = false) {
+        val parts = segments.filter { it.isNotBlank() }
+        if (parts.isNotEmpty()) {
+            builder.appendPathSegments(*parts.toTypedArray(), encodeSlash = encodeSlash)
+        }
+    }
+
+    fun param(name: String, value: Any?) {
+        if (value == null) return
+        val text = value.toString()
+        if (text.isEmpty()) return
+        builder.parameters.append(name, text)
+    }
+
+    internal fun build(): String = builder.buildString()
+}
+
+fun normalizeBaseUrl(raw: String): String {
+    var u = raw.trim().trimEnd('/')
+    if (!u.startsWith("http://", ignoreCase = true) &&
+        !u.startsWith("https://", ignoreCase = true)
+    ) {
+        u = "https://$u"
+    }
+    return u
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.kt
new file mode 100644
index 00000000..9ea2f32a
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.kt
@@ -0,0 +1,8 @@
+package capital.yuri.yuriplayer.core.library
+
+/** Downsampled ARGB for theme extraction (folder art, then embedded). */
+expect fun sampleCoverArgb(
+    artworkUri: String?,
+    audioPath: String? = null,
+    size: Int = 48
+): IntArray?
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongIdentity.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongIdentity.kt
new file mode 100644
index 00000000..3cd0325d
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongIdentity.kt
@@ -0,0 +1,134 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.Song
+
+/**
+ * Cross-source identity for a [Song] (local + Jellyfin + Subsonic of the same
+ * recording). Supersedes the legacy desktop `Track` identity model — the String
+ * id is carried in [Song.songKey]/[Song.path].
+ */
+private val FEAT_IN_PARENS = Regex(
+    """(?i)[\(\[\{]\s*(feat\.?|ft\.?|featuring)\s+[^\)\]\}]+[\)\]\}]"""
+)
+private val FEAT_SUFFIX = Regex(
+    """(?i)\s+(feat\.?|ft\.?|featuring)\s+.+$"""
+)
+
+fun normalizeTitle(title: String?): String {
+    if (title.isNullOrBlank()) return ""
+    var t = title.trim()
+    t = FEAT_IN_PARENS.replace(t, "")
+    t = FEAT_SUFFIX.replace(t, "")
+    return foldSearch(t)
+}
+
+/**
+ * Cross-source identity (local + Jellyfin + Subsonic of the same recording).
+ * Playlists store this so a Navidrome search hit resolves to the library row.
+ */
+fun Song.catalogKey(): String {
+    val t = foldSearch(title ?: displayTitle)
+    if (t.isEmpty()) return songKey
+    val a = foldSearch(albumArtist ?: artist ?: "")
+    val al = foldSearch(album ?: "")
+    val n = trackNumber ?: 0
+    return "k:$t|$a|$al|$n"
+}
+
+/**
+ * Artist-agnostic key so Navidrome search (`feat. X` on artist) matches
+ * a scanned row (album artist only).
+ */
+fun Song.looseKey(): String {
+    val t = normalizeTitle(title ?: displayTitle)
+    val al = foldSearch(album ?: "")
+    val n = trackNumber ?: 0
+    return "p:$t|$al|$n"
+}
+
+fun Song.rawSourceId(): String? = when {
+    path?.startsWith("subsonic:") == true -> path!!.removePrefix("subsonic:")
+    path?.startsWith("jellyfin:") == true -> path!!.removePrefix("jellyfin:")
+    path?.startsWith("navidrome:") == true -> path!!.removePrefix("navidrome:")
+    else -> null
+}
+
+fun Song.indexKeys(): Set<String> = buildSet {
+    add(songKey)
+    add(catalogKey())
+    add(looseKey())
+    rawSourceId()?.let { add(it) }
+}
+
+fun Song.playlistKeys(): Set<String> = indexKeys()
+
+fun albumGroupKey(song: Song): String {
+    val album = foldSearch(song.album ?: song.displayAlbum)
+    val artist = foldSearch(song.albumArtist ?: song.artist ?: "")
+    return "$album::$artist"
+}
+
+fun albumPageIdentity(song: Song): String {
+    val disc = song.discNumber ?: 1
+    val tn = song.trackNumber
+    val title = normalizeTitle(song.title ?: song.displayTitle)
+    return if (tn != null && tn > 0 && title.isNotEmpty()) {
+        "n:$disc|$tn|$title"
+    } else if (title.isNotEmpty()) {
+        "t:$title|${foldSearch(song.album ?: "")}"
+    } else {
+        "id:${song.songKey}"
+    }
+}
+
+fun Song.sourceRank(): Int {
+    val sid = sourceId.orEmpty()
+    val uri = contentUri
+    return when {
+        sid == "local" || uri.startsWith("file:") -> 0
+        songKey.startsWith("jellyfin:") || sid.contains("jelly", true) -> 10
+        songKey.startsWith("subsonic:") || songKey.startsWith("navidrome:") ||
+            sid.contains("navi", true) || sid.contains("subsonic", true) -> 20
+        else -> 50
+    }
+}
+
+data class CollapsedSong(
+    val preferred: Song,
+    val sources: List<Song>
+) {
+    val identity: String get() = albumPageIdentity(preferred)
+    val multiSource: Boolean get() = sources.size > 1
+    val explicit: Boolean get() = sources.any { it.isExplicit }
+}
+
+fun collapseAlbumTracks(
+    songs: List<Song>,
+    preferredIds: Map<String, String> = emptyMap()
+): List<CollapsedSong> {
+    if (songs.isEmpty()) return emptyList()
+    val groups = LinkedHashMap<String, MutableList<Song>>()
+    for (s in songs) {
+        groups.getOrPut(albumPageIdentity(s)) { mutableListOf() }.add(s)
+    }
+    return groups.values.map { group ->
+        val identity = albumPageIdentity(group.first())
+        val prefId = preferredIds[identity]
+        val preferred = prefId?.let { id ->
+            group.firstOrNull { it.songKey == id || it.sourceId == id }
+        } ?: group.minByOrNull { it.sourceRank() } ?: group.first()
+        CollapsedSong(preferred, group.distinctBy { it.songKey })
+    }.sortedWith(
+        compareBy<CollapsedSong> { it.preferred.discNumber ?: 1 }
+            .thenBy { it.preferred.trackNumber ?: Int.MAX_VALUE }
+            .thenBy { it.preferred.displayTitle.lowercase() }
+    )
+}
+
+fun pickPreferred(sources: List<Song>, preferredId: String?): Song {
+    if (sources.isEmpty()) error("empty sources")
+    preferredId?.let { id ->
+        sources.firstOrNull { it.songKey == id || it.sourceId == id }?.let { return it }
+    }
+    return sources.minByOrNull { it.sourceRank() } ?: sources.first()
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongLibrary.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongLibrary.kt
new file mode 100644
index 00000000..9484edab
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongLibrary.kt
@@ -0,0 +1,172 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.ArtistItem
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.SortMode
+import capital.yuri.yuriplayer.data.albumKey
+import capital.yuri.yuriplayer.data.artistKey
+import capital.yuri.yuriplayer.data.isCombinedArtistName
+import capital.yuri.yuriplayer.data.primaryArtistName
+
+/**
+ * Pure, platform-agnostic aggregation over a [List] of [Song]. This is the
+ * same in-memory library-view logic Android's `LibraryIndex` uses, extracted
+ * so desktop and future platforms share it without Context / Room / MediaStore.
+ *
+ * Everything here is deterministic: it reads a [Song] list and returns grouped
+ * albums / artists / sorted / filtered lists. Persistence and scanning stay on
+ * the platform side.
+ */
+object SongLibrary {
+
+    fun normalizeKey(value: String?): String? {
+        val t = value.orEmpty().trim().replace(Regex("\\s+"), " ").lowercase()
+        return t.takeIf { it.isNotEmpty() }
+    }
+
+    fun albums(songs: List<Song>, query: String = "", taggedOnly: Boolean = true): List<AlbumItem> {
+        val q = query.trim()
+        val source = if (taggedOnly) songs.filter { it.hasAlbum } else songs
+
+        return source
+            .groupBy { normalizeKey(it.album) }
+            .mapNotNull { (albumKeyNorm, tracks) ->
+                if (albumKeyNorm == null) return@mapNotNull null
+
+                val albumArtistVotes = tracks
+                    .mapNotNull {
+                        val raw = primaryArtistName(it.albumArtist) ?: it.albumArtist
+                        raw?.let { a -> normalizeKey(a) to a }
+                    }
+                    .groupingBy { it.first }
+                    .eachCount()
+                val trackArtistVotes = tracks
+                    .mapNotNull {
+                        val raw = primaryArtistName(it.artist) ?: it.artist
+                        raw?.let { a -> normalizeKey(a) to a }
+                    }
+                    .groupingBy { it.first }
+                    .eachCount()
+
+                val bestAlbumArtistKey = albumArtistVotes.maxByOrNull { it.value }?.key
+                val bestTrackArtistKey = trackArtistVotes.maxByOrNull { it.value }?.key
+                val displayArtist = when {
+                    bestAlbumArtistKey != null ->
+                        tracks.firstOrNull { normalizeKey(it.albumArtist) == bestAlbumArtistKey }?.albumArtist
+                    bestTrackArtistKey != null ->
+                        tracks.firstOrNull { normalizeKey(it.artist) == bestTrackArtistKey }?.artist
+                    else -> null
+                }
+
+                val displayName = tracks
+                    .mapNotNull { it.album }
+                    .groupingBy { it }
+                    .eachCount()
+                    .maxByOrNull { it.value }
+                    ?.key
+                    ?: tracks.firstOrNull()?.album
+
+                val deduped = tracks.distinctBy { it.path?.lowercase() ?: it.contentUri }
+
+                AlbumItem(
+                    name = displayName,
+                    artist = displayArtist,
+                    trackCount = deduped.size,
+                    songs = deduped.sortedWith(
+                        compareBy<Song> { it.trackNumber ?: Int.MAX_VALUE }
+                            .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+                    )
+                )
+            }
+            .filter {
+                q.isEmpty() ||
+                    (it.name?.contains(q, true) == true) ||
+                    (it.artist?.contains(q, true) == true)
+            }
+            .sortedWith(
+                compareBy<AlbumItem> { it.artist == null }
+                    .thenBy(String.CASE_INSENSITIVE_ORDER) { it.artist ?: "" }
+                    .thenBy(String.CASE_INSENSITIVE_ORDER) { it.name ?: "" }
+            )
+    }
+
+    fun artists(songs: List<Song>, query: String = "", taggedOnly: Boolean = true): List<ArtistItem> {
+        val q = query.trim()
+        val source = if (taggedOnly) songs.filter { it.hasArtist } else songs
+
+        return source
+            .groupBy { artistKey(it.effectiveAlbumArtist) }
+            .mapNotNull { (key, tracks) ->
+                if (key.isNullOrBlank()) return@mapNotNull null
+                val displayName = tracks
+                    .mapNotNull { primaryArtistName(it.effectiveAlbumArtist) ?: it.effectiveAlbumArtist }
+                    .groupingBy { it }.eachCount()
+                    .maxByOrNull { it.value }
+                    ?.key
+                if (isCombinedArtistName(displayName)) return@mapNotNull null
+                val deduped = tracks.distinctBy { it.path?.lowercase() ?: it.contentUri }
+                val albumKeys = deduped.mapNotNull { albumKey(it.album, it.effectiveAlbumArtist) }.toSet()
+                ArtistItem(
+                    name = displayName,
+                    trackCount = deduped.size,
+                    albumCount = albumKeys.size,
+                    songs = deduped
+                )
+            }
+            .filter { q.isEmpty() || (it.name?.contains(q, true) == true) }
+            .sortedWith(
+                compareBy<ArtistItem> { it.name == null }
+                    .thenBy(String.CASE_INSENSITIVE_ORDER) { it.name ?: "" }
+            )
+    }
+
+    fun sorted(songs: List<Song>, mode: SortMode, taggedOnly: Boolean? = null): List<Song> {
+        val base = when (taggedOnly) {
+            true -> songs.filter { it.isTagged }
+            false -> songs.filter { !it.isTagged }
+            null -> songs
+        }
+        return sortSongs(base, mode)
+    }
+
+    fun search(songs: List<Song>, query: String, mode: SortMode = SortMode.TITLE, taggedOnly: Boolean? = null): List<Song> {
+        val q = query.trim()
+        val base = sorted(songs, mode, taggedOnly)
+        if (q.isEmpty()) return base
+        return base.filter { songMatches(it, q) }
+    }
+
+    private fun songMatches(song: Song, q: String): Boolean =
+        song.displayTitle.contains(q, true) ||
+            (song.artist?.contains(q, true) == true) ||
+            (song.albumArtist?.contains(q, true) == true) ||
+            (song.album?.contains(q, true) == true)
+
+    fun sortSongs(songs: List<Song>, mode: SortMode): List<Song> = when (mode) {
+        SortMode.TITLE -> songs.sortedWith(
+            compareBy<Song> { !it.hasTitle }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+        )
+        SortMode.ARTIST -> songs.sortedWith(
+            compareBy<Song> { !it.hasArtist }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayAlbumArtist }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayAlbum }
+                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+        )
+        SortMode.ALBUM -> songs.sortedWith(
+            compareBy<Song> { !it.hasAlbum }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayAlbumArtist }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayAlbum }
+                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+        )
+        SortMode.TRACK -> songs.sortedWith(
+            compareBy<Song> { !it.hasAlbum }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayAlbum }
+                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+        )
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongSearch.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongSearch.kt
new file mode 100644
index 00000000..1f46e41b
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/SongSearch.kt
@@ -0,0 +1,83 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.TrackIdentity
+import capital.yuri.yuriplayer.data.foldTagToken
+import capital.yuri.yuriplayer.data.parseArtistCredits
+import capital.yuri.yuriplayer.data.primaryArtistName
+
+/**
+ * Library search matching used by desktop Explore (and shared later).
+ * Folds stylized letters (ø → o), ignores extra punctuation/spacing, and
+ * requires every query token to appear somewhere in title/artist/album/path.
+ */
+fun Song.matchesQuery(query: String): Boolean {
+    val tokens = searchTokens(query)
+    if (tokens.isEmpty()) return false
+    val hay = foldSearch(
+        listOfNotNull(
+            title, artist, albumArtist, album, genre, path, contentUri, displayTitle, displayArtist, displayAlbum
+        ).joinToString(" ")
+    )
+    return tokens.all { hay.contains(it) }
+}
+
+fun String.matchesSearch(query: String): Boolean {
+    val tokens = searchTokens(query)
+    if (tokens.isEmpty()) return false
+    val hay = foldSearch(this)
+    return tokens.all { hay.contains(it) }
+}
+
+/**
+ * Precise artist-identity comparison for artist pages: does the primary artist
+ * of [this] equal the primary artist of [name] (case/accent folded)? This is
+ * whole-name equality, NOT substring — "Rav" must not match "Ravenna Golden".
+ */
+fun String.matchesArtistName(name: String): Boolean =
+    TrackIdentity.albumArtistsMatch(this, name)
+
+/**
+ * Precise "appears on" check: is [name] credited (primary OR featured) on [this]
+ * tag blob? Whole-name only, so it never matches a shorter prefix like "Rav"
+ * against "Ravenna Golden".
+ */
+fun String.matchesCreditedArtist(name: String): Boolean {
+    if (isBlank()) return false
+    val target = foldTagToken(primaryArtistName(name) ?: name)
+    if (target.isEmpty()) return false
+    return parseArtistCredits(this).any { foldTagToken(it) == target }
+}
+
+fun searchTokens(query: String): List<String> =
+    foldSearch(query).split(' ').filter { it.isNotEmpty() }
+
+fun foldSearch(raw: String): String {
+    val sb = StringBuilder(raw.length)
+    var i = 0
+    while (i < raw.length) {
+        val ch = raw[i]
+        when (ch) {
+            'ø', 'Ø', 'ó', 'ò', 'ö', 'ô', 'õ', 'Ó', 'Ò', 'Ö', 'Ô', 'Õ' -> sb.append('o')
+            'á', 'à', 'ä', 'â', 'ã', 'å', 'Á', 'À', 'Ä', 'Â', 'Ã', 'Å' -> sb.append('a')
+            'é', 'è', 'ë', 'ê', 'É', 'È', 'Ë', 'Ê' -> sb.append('e')
+            'í', 'ì', 'ï', 'î', 'Í', 'Ì', 'Ï', 'Î' -> sb.append('i')
+            'ú', 'ù', 'ü', 'û', 'Ú', 'Ù', 'Ü', 'Û' -> sb.append('u')
+            'ñ', 'Ñ' -> sb.append('n')
+            'ç', 'Ç' -> sb.append('c')
+            'ß' -> sb.append("ss")
+            'æ', 'Æ' -> sb.append("ae")
+            'œ', 'Œ' -> sb.append("oe")
+            '&' -> sb.append(" and ")
+            else -> {
+                val lower = ch.lowercaseChar()
+                if (lower.isLetterOrDigit()) sb.append(lower)
+                else if (lower.isWhitespace() || lower == '/' || lower == '\\' || lower == '-' || lower == '_') {
+                    if (sb.isNotEmpty() && sb.last() != ' ') sb.append(' ')
+                }
+            }
+        }
+        i++
+    }
+    return sb.toString().trim()
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/Track.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/Track.kt
new file mode 100644
index 00000000..62291d00
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/Track.kt
@@ -0,0 +1,7 @@
+@file:Suppress("unused")
+
+package capital.yuri.yuriplayer.core.library
+
+// Removed. The legacy desktop `Track` model was superseded by the shared
+// `capital.yuri.yuriplayer.data.Song` model. See SongSearch.kt / SongIdentity.kt
+// for the Song-based equivalents of the old Track helpers.
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackIdentity.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackIdentity.kt
new file mode 100644
index 00000000..43304737
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackIdentity.kt
@@ -0,0 +1,5 @@
+@file:Suppress("unused")
+
+package capital.yuri.yuriplayer.core.library
+
+// Removed. See SongIdentity.kt for the Song-based identity helpers.
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackSearch.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackSearch.kt
new file mode 100644
index 00000000..61451e1f
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackSearch.kt
@@ -0,0 +1,5 @@
+@file:Suppress("unused")
+
+package capital.yuri.yuriplayer.core.library
+
+// Removed. See SongSearch.kt for the Song-based search helpers.
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackSong.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackSong.kt
new file mode 100644
index 00000000..6e95a781
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/library/TrackSong.kt
@@ -0,0 +1,5 @@
+@file:Suppress("unused")
+
+package capital.yuri.yuriplayer.core.library
+
+// Removed. Song <-> Track bridge is gone with the legacy Track model.
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.kt
new file mode 100644
index 00000000..573dd467
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.kt
@@ -0,0 +1,53 @@
+package capital.yuri.yuriplayer.core.log
+
+/**
+ * Kotlin DSL over platform logs.
+ *
+ * Desktop → SLF4J/Logback, Android → logcat, Darwin (later) → os_log.
+ *
+ * ```
+ * val log = yuriLog("Vlcj")
+ * log.i { "play ${redactSecrets(mrl)}" }
+ * log.e(t) { "stream failed" }
+ *
+ * yuriLog("Index") {
+ *     d { "merge +$n" }
+ * }
+ * ```
+ *
+ * Tags are short (`Vlcj`, `Queue`). Platforms prefix `YuriPlayer.`, so logcat is
+ * `YuriPlayer.Vlcj`. `YuriPlayer.` on the caller's tag is stripped so
+ * `yuriLog("YuriPlayer.Radio")` and `yuriLog("Radio")` log the same.
+ */
+enum class LogLevel { TRACE, DEBUG, INFO, WARN, ERROR }
+
+class YuriLogger(val tag: String) {
+    inline fun t(t: Throwable? = null, msg: () -> String) = emit(LogLevel.TRACE, t, msg)
+    inline fun d(t: Throwable? = null, msg: () -> String) = emit(LogLevel.DEBUG, t, msg)
+    inline fun i(t: Throwable? = null, msg: () -> String) = emit(LogLevel.INFO, t, msg)
+    inline fun w(t: Throwable? = null, msg: () -> String) = emit(LogLevel.WARN, t, msg)
+    inline fun e(t: Throwable? = null, msg: () -> String) = emit(LogLevel.ERROR, t, msg)
+
+    inline fun emit(level: LogLevel, t: Throwable? = null, msg: () -> String) {
+        if (!platformLogEnabled(level)) return
+        platformLog(level, tag, redactSecrets(msg()), t)
+    }
+}
+
+fun yuriLog(tag: String): YuriLogger = YuriLogger(normalizeLogTag(tag))
+
+inline fun yuriLog(tag: String, block: YuriLogger.() -> Unit) = yuriLog(tag).block()
+
+fun normalizeLogTag(tag: String): String {
+    val t = tag.removePrefix("YuriPlayer.")
+    return if (t.isBlank() || t == "YuriPlayer") "App" else t
+}
+
+expect fun platformLog(level: LogLevel, tag: String, message: String, throwable: Throwable?)
+
+expect fun platformLogEnabled(level: LogLevel): Boolean
+
+fun redactSecrets(text: String): String =
+    text
+        .replace(Regex("([?&](?:t|s|api_key|ApiKey|access_token|password|pw|secret)=)[^&\\s]+"), "$1***")
+        .replace(Regex("(Authorization:\\s*)\\S+", RegexOption.IGNORE_CASE), "$1***")
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/network/NetworkMonitor.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/network/NetworkMonitor.kt
new file mode 100644
index 00000000..1f91ee4c
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/network/NetworkMonitor.kt
@@ -0,0 +1,13 @@
+package capital.yuri.yuriplayer.core.network
+
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * Cross-platform internet reachability signal.
+ *
+ * Drives the "No internet" banner and, together with per-source availability,
+ * gates external sources out of the queue while offline.
+ */
+interface NetworkMonitor {
+    val isOnline: StateFlow<Boolean>
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/os/OsMediaControls.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/os/OsMediaControls.kt
new file mode 100644
index 00000000..2b58bda4
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/os/OsMediaControls.kt
@@ -0,0 +1,55 @@
+package capital.yuri.yuriplayer.core.os
+
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import capital.yuri.yuriplayer.data.Song
+
+/**
+ * System playback integration: MPRIS (`playerctl`) on Linux, Now Playing on
+ * macOS, System Media Transport Controls on Windows.
+ */
+interface OsMediaControls {
+    fun attach(callbacks: Callbacks)
+
+    fun update(
+        track: Song?,
+        playing: Boolean,
+        positionMs: Long,
+        durationMs: Long,
+        volume: Float = 1f
+    )
+
+    /** Push repeat mode to the system media session (app -> OS). */
+    fun setLoop(mode: RepeatMode) {}
+
+    /** Push shuffle state to the system media session (app -> OS). */
+    fun setShuffle(enabled: Boolean) {}
+
+    fun release()
+
+    interface Callbacks {
+        fun onPlay()
+        fun onPause()
+        fun onPlayPause()
+        fun onStop()
+        fun onNext()
+        fun onPrevious()
+        fun onSeek(positionMs: Long)
+        fun onVolume(value: Float) {}
+        fun onLoop(mode: RepeatMode) {}
+        fun onShuffle(enabled: Boolean) {}
+        fun onRaise() {}
+        fun onQuit() {}
+    }
+}
+
+object NoOpMediaControls : OsMediaControls {
+    override fun attach(callbacks: OsMediaControls.Callbacks) {}
+    override fun update(
+        track: Song?,
+        playing: Boolean,
+        positionMs: Long,
+        durationMs: Long,
+        volume: Float
+    ) {}
+    override fun release() {}
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.kt
new file mode 100644
index 00000000..66ea3fb0
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.kt
@@ -0,0 +1,19 @@
+package capital.yuri.yuriplayer.core.platform
+
+/**
+ * OS-conventional locations for Yuri Player.
+ *
+ * Linux: XDG (`~/.config/yuriplayer`, `~/.cache/yuriplayer`, `~/.local/share/yuriplayer`,
+ * `$XDG_MUSIC_DIR` or `~/Music`).
+ * macOS: `~/Library/Application Support/YuriPlayer`, `~/Library/Caches/YuriPlayer`, `~/Music`.
+ * Windows: `%APPDATA%\YuriPlayer`, `%LOCALAPPDATA%\YuriPlayer\Cache`, `%USERPROFILE%\Music`.
+ * Android: app files / cache dirs; default music roots come from the platform scanner.
+ */
+interface AppDirectories {
+    val configDir: String
+    val cacheDir: String
+    val dataDir: String
+    val defaultMusicRoots: List<String>
+}
+
+expect fun appDirectories(): AppDirectories
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/CoverCache.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/CoverCache.kt
new file mode 100644
index 00000000..e616df5b
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/CoverCache.kt
@@ -0,0 +1,4 @@
+package capital.yuri.yuriplayer.core.platform
+
+/** Coil / cover files live under cacheDir/covers. */
+fun coverCacheDir(): String = appDirectories().cacheDir.trimEnd('/', '\\') + "/covers"
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.kt
new file mode 100644
index 00000000..2eaffcdc
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.kt
@@ -0,0 +1,11 @@
+package capital.yuri.yuriplayer.core.platform
+
+enum class HostOs {
+    ANDROID,
+    LINUX,
+    MACOS,
+    WINDOWS,
+    UNKNOWN
+}
+
+expect fun hostOs(): HostOs
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/ColdSource.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/ColdSource.kt
new file mode 100644
index 00000000..91ec5455
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/ColdSource.kt
@@ -0,0 +1,22 @@
+package capital.yuri.yuriplayer.core.player
+
+import kotlinx.serialization.Serializable
+
+/**
+ * The context the cold queue is currently playing through (an album, playlist,
+ * artist, radio station, or a one-off "songs" list). Shared so album/artist/
+ * playlist pages can light up their play/pause button and the queue UI can name
+ * the source.
+ */
+@Serializable
+enum class ColdSourceType { ALBUM, PLAYLIST, ARTIST, SONGS, RADIO, UNKNOWN }
+
+@Serializable
+data class ColdSource(
+    val type: ColdSourceType,
+    val id: String,
+    val title: String? = null
+) {
+    fun matches(type: ColdSourceType, id: String): Boolean =
+        this.type == type && this.id.equals(id, ignoreCase = true)
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/PlaybackEngine.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/PlaybackEngine.kt
new file mode 100644
index 00000000..944a173e
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/PlaybackEngine.kt
@@ -0,0 +1,75 @@
+package capital.yuri.yuriplayer.core.player
+
+import capital.yuri.yuriplayer.data.Song
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * Audio backend only. Queue / radio / now-playing identity live in the host
+ * ([capital.yuri.yuriplayer.player.QueueManager]).
+ * Same contract on Android, desktop, and later iOS.
+ */
+interface PlaybackEngine {
+    val isPlaying: StateFlow<Boolean>
+    val currentUri: StateFlow<String?>
+
+    fun load(
+        current: PlaybackMedia,
+        successor: PlaybackMedia? = null,
+        startPositionMs: Long = 0L
+    )
+
+    fun play()
+    fun pause()
+    fun stop()
+    fun seekTo(positionMs: Long)
+
+    fun getPositionMs(): Long
+    fun getDurationMs(): Long
+
+    fun setVolume(percent: Int) {}
+    fun getVolume(): Int = 100
+
+    fun setNext(item: PlaybackMedia?) {}
+    fun hasPreparedNext(): Boolean = false
+    fun playPreparedNext(): Boolean = false
+    fun warmupNext() {}
+
+    fun release()
+
+    fun addListener(listener: Listener)
+    fun removeListener(listener: Listener)
+
+    interface Listener {
+        fun onIsPlayingChanged(playing: Boolean) {}
+        fun onEnded() {}
+        fun onAutoAdvanced() {}
+        fun onError(message: String, recoverable: Boolean) {}
+    }
+}
+
+data class PlaybackMedia(
+    val mediaId: String,
+    val uri: String,
+    val title: String,
+    val artist: String? = null,
+    val album: String? = null,
+    val artworkUri: String? = null,
+    val headers: Map<String, String> = emptyMap(),
+    val isNetwork: Boolean = false,
+    val live: Boolean = false
+)
+
+/**
+ * Core [Song] → [PlaybackMedia]. [Song.contentUri] carries the actual playable
+ * URI (file path or http(s) URL); [Song.path] is the stable identity key.
+ */
+fun Song.toPlaybackMedia(): PlaybackMedia = PlaybackMedia(
+    mediaId = songKey,
+    uri = contentUri,
+    title = displayTitle,
+    artist = displayArtist,
+    album = displayAlbum,
+    artworkUri = albumArtUri,
+    isNetwork = contentUri.startsWith("http://") || contentUri.startsWith("https://"),
+    live = false
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/PlayerSession.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/PlayerSession.kt
new file mode 100644
index 00000000..cc477d7e
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/PlayerSession.kt
@@ -0,0 +1,27 @@
+package capital.yuri.yuriplayer.core.player
+
+import capital.yuri.yuriplayer.data.Song
+
+/**
+ * Serializable snapshot of the playback session for UI + persistence.
+ *
+ * Supersedes the legacy `PlayerSession` queue host (removed with the desktop
+ * `Track` model). Desktop/Android hosts drive the shared [capital.yuri.yuriplayer.player.QueueManager]
+ * and materialize this snapshot for their own persistence layer.
+ */
+data class PlaybackSnapshot(
+    val queue: List<Song> = emptyList(),
+    val linear: List<Song> = emptyList(),
+    val index: Int = 0,
+    val history: List<Song> = emptyList(),
+    val shuffle: Boolean = false,
+    val repeat: RepeatMode = RepeatMode.OFF,
+    val volume: Float = 1f,
+    val positionMs: Long = 0L,
+    val hotQueue: List<Song> = emptyList(),
+    val coldQueue: List<Song> = emptyList(),
+    val coldOriginal: List<Song> = emptyList(),
+    val coldSource: ColdSource? = null,
+    val lane: QueueLane = QueueLane.COLD,
+    val indexInLane: Int = 0
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/QueueLane.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/QueueLane.kt
new file mode 100644
index 00000000..f78cfec6
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/QueueLane.kt
@@ -0,0 +1,3 @@
+package capital.yuri.yuriplayer.core.player
+
+enum class QueueLane { HOT, COLD }
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/RepeatMode.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/RepeatMode.kt
new file mode 100644
index 00000000..ac5f2a45
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/player/RepeatMode.kt
@@ -0,0 +1,17 @@
+package capital.yuri.yuriplayer.core.player
+
+import kotlinx.serialization.Serializable
+
+/**
+ * Repeat semantics. [COLD] loops the cold queue (album / playlist context)
+ * after it ends — the Android `QueueManager` name for what desktop used to
+ * call `ALL`.
+ */
+@Serializable
+enum class RepeatMode { OFF, ONE, COLD }
+
+fun RepeatMode.next(): RepeatMode = when (this) {
+    RepeatMode.OFF -> RepeatMode.COLD
+    RepeatMode.COLD -> RepeatMode.ONE
+    RepeatMode.ONE -> RepeatMode.OFF
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/source/RemoteAccount.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/source/RemoteAccount.kt
new file mode 100644
index 00000000..8ee4e899
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/source/RemoteAccount.kt
@@ -0,0 +1,29 @@
+package capital.yuri.yuriplayer.core.source
+
+import kotlinx.serialization.Serializable
+
+enum class SourceKind {
+    LOCAL,
+    JELLYFIN,
+    SUBSONIC
+}
+
+@Serializable
+data class RemoteAccount(
+    val id: String,
+    val kind: SourceKind,
+    val name: String,
+    val baseUrl: String,
+    val username: String,
+    val secret: String,
+    val enabled: Boolean = true,
+    val accessToken: String? = null,
+    val userId: String? = null
+)
+
+@Serializable
+data class LibrarySourcesFile(
+    val extraFolders: List<String> = emptyList(),
+    val remotes: List<RemoteAccount> = emptyList(),
+    val deviceId: String = ""
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/source/SourceAvailabilityStore.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/source/SourceAvailabilityStore.kt
new file mode 100644
index 00000000..edcdb5ce
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/source/SourceAvailabilityStore.kt
@@ -0,0 +1,30 @@
+package capital.yuri.yuriplayer.core.source
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+
+/**
+ * Tracks external sources that are temporarily unreachable so the UI and the
+ * queue can exclude them until a later retry succeeds.
+ *
+ * Callers mark a source [markUnavailable] when a scan/fetch fails (logging the
+ * error at the call site) and [markAvailable] once a periodic retry recovers.
+ * [unavailable] is observable for UI ("source temporarily unavailable").
+ */
+class SourceAvailabilityStore {
+    private val _unavailable = MutableStateFlow<Map<String, String>>(emptyMap())
+    val unavailable: StateFlow<Map<String, String>> = _unavailable.asStateFlow()
+
+    fun markUnavailable(sourceId: String, reason: String) {
+        _unavailable.value = _unavailable.value + (sourceId to reason)
+    }
+
+    fun markAvailable(sourceId: String) {
+        _unavailable.value = _unavailable.value - sourceId
+    }
+
+    fun isUnavailable(sourceId: String): Boolean = sourceId in _unavailable.value
+
+    fun reason(sourceId: String): String? = _unavailable.value[sourceId]
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.kt
new file mode 100644
index 00000000..2ba970c3
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.kt
@@ -0,0 +1,211 @@
+package capital.yuri.yuriplayer.core.text
+
+/**
+ * Script-aware fuzzy matching for music tags. All algorithms are pure
+ * `commonMain`; only language data (Unicode normalization, transliteration and
+ * script detection) is pulled from the OS via [foldCompare] / [isCjkCodePoint].
+ */
+object StringSimilarity {
+
+    enum class Kind { ALBUM, TITLE, ARTIST }
+
+    fun likelySame(a: String, b: String, kind: Kind): Boolean {
+        if (a == b) return true
+        val fa = foldCompare(a)
+        val fb = foldCompare(b)
+        if (fa.isEmpty() || fb.isEmpty()) return false
+        if (fa == fb) return true
+
+        val pa = codePoints(fa)
+        val pb = codePoints(fb)
+        val minCp = minOf(pa.size, pb.size)
+        val maxCp = maxOf(pa.size, pb.size)
+        if (minCp == 0) return false
+        if (maxCp - minCp > 4 && maxCp > 8) return false
+
+        val cjk = isCjkHeavy(pa) || isCjkHeavy(pb)
+        val levCap = if (cjk) 2 else 2
+        val lev = editDistanceCodePoints(pa, pb, levCap + 1)
+        val jw = jaroWinkler(pa, pb)
+        val jac1 = ngramJaccard(pa, pb, 1)
+        val jac2 = if (minCp >= 2) ngramJaccard(pa, pb, 2) else jac1
+
+        if (cjk) {
+            return when (kind) {
+                Kind.ARTIST -> (jac1 >= 0.85 && lev <= 1) || jw >= 0.95
+                Kind.ALBUM, Kind.TITLE ->
+                    jac1 >= 0.80 && lev <= 1 ||
+                        jac2 >= 0.75 ||
+                        (jw >= 0.90 && lev <= 1)
+            }
+        }
+
+        return when (kind) {
+            Kind.ALBUM ->
+                minCp >= 12 && jw >= 0.93 && lev <= 2
+            Kind.TITLE ->
+                (minCp >= 6 && jw >= 0.90 && lev <= 2) ||
+                    (minCp >= 14 && jw >= 0.92)
+            Kind.ARTIST ->
+                minCp >= 4 && jw >= 0.96 && lev <= 2
+        }
+    }
+
+    /** Jaro–Winkler similarity in `0f..1f`. */
+    fun jaroWinkler(a: IntArray, b: IntArray): Float {
+        if (a.isEmpty() && b.isEmpty()) return 1f
+        if (a.isEmpty() || b.isEmpty()) return 0f
+        if (a.contentEquals(b)) return 1f
+        val jaro = jaro(a, b)
+        if (jaro < 0.7f) return jaro
+        var prefix = 0
+        val limit = minOf(4, a.size, b.size)
+        while (prefix < limit && a[prefix] == b[prefix]) prefix++
+        return jaro + prefix * 0.1f * (1f - jaro)
+    }
+
+    fun ngramJaccard(a: IntArray, b: IntArray, n: Int): Float {
+        if (n <= 0) return 0f
+        if (a.contentEquals(b)) return 1f
+        val ga = ngrams(a, n)
+        val gb = ngrams(b, n)
+        if (ga.isEmpty() && gb.isEmpty()) return 1f
+        if (ga.isEmpty() || gb.isEmpty()) return 0f
+        var inter = 0
+        val keys = ga.keys + gb.keys
+        var union = 0
+        for (g in keys) {
+            val ca = ga[g] ?: 0
+            val cb = gb[g] ?: 0
+            inter += minOf(ca, cb)
+            union += maxOf(ca, cb)
+        }
+        return if (union == 0) 0f else inter.toFloat() / union
+    }
+
+    private fun jaro(a: IntArray, b: IntArray): Float {
+        val s1: IntArray
+        val s2: IntArray
+        if (a.size >= b.size) {
+            s1 = a
+            s2 = b
+        } else {
+            s1 = b
+            s2 = a
+        }
+        val matchWindow = maxOf(s1.size / 2 - 1, 0)
+        val s1Match = BooleanArray(s1.size)
+        val s2Match = BooleanArray(s2.size)
+        var matches = 0
+        for (i in s1.indices) {
+            val lo = maxOf(0, i - matchWindow)
+            val hi = minOf(i + matchWindow + 1, s2.size)
+            for (j in lo until hi) {
+                if (s2Match[j] || s1[i] != s2[j]) continue
+                s1Match[i] = true
+                s2Match[j] = true
+                matches++
+                break
+            }
+        }
+        if (matches == 0) return 0f
+        var k = 0
+        var trans = 0
+        for (i in s1.indices) {
+            if (!s1Match[i]) continue
+            while (!s2Match[k]) k++
+            if (s1[i] != s2[k]) trans++
+            k++
+        }
+        val m = matches.toFloat()
+        return (m / s1.size + m / s2.size + (m - trans / 2f) / m) / 3f
+    }
+
+    private fun ngrams(cps: IntArray, n: Int): Map<Long, Int> {
+        if (cps.size < n) {
+            if (cps.isEmpty()) return emptyMap()
+            var h = 0L
+            for (cp in cps) h = h * 1_000_003L + cp
+            return mapOf(h to 1)
+        }
+        val out = HashMap<Long, Int>(cps.size)
+        for (i in 0..cps.size - n) {
+            var h = 0L
+            for (j in 0 until n) h = h * 1_000_003L + cps[i + j]
+            out[h] = (out[h] ?: 0) + 1
+        }
+        return out
+    }
+
+    private fun editDistanceCodePoints(a: IntArray, b: IntArray, max: Int): Int {
+        if (a.contentEquals(b)) return 0
+        if (kotlin.math.abs(a.size - b.size) > max) return max + 1
+        val m = b.size
+        var prev = IntArray(m + 1) { it }
+        var cur = IntArray(m + 1)
+        for (i in 1..a.size) {
+            cur[0] = i
+            var rowMin = i
+            val ca = a[i - 1]
+            for (j in 1..m) {
+                val cost = if (ca == b[j - 1]) 0 else 1
+                cur[j] = minOf(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
+                if (cur[j] < rowMin) rowMin = cur[j]
+            }
+            if (rowMin > max) return max + 1
+            val tmp = prev
+            prev = cur
+            cur = tmp
+        }
+        return prev[m]
+    }
+
+    /** Code points without `java.lang.Character` (manual surrogate handling). */
+    private fun codePoints(s: String): IntArray {
+        val out = ArrayList<Int>(s.length)
+        var i = 0
+        while (i < s.length) {
+            val c = s[i].code
+            if (c in 0xD800..0xDBFF && i + 1 < s.length && s[i + 1].code in 0xDC00..0xDFFF) {
+                out += ((c - 0xD800) shl 10) + (s[i + 1].code - 0xDC00) + 0x10000
+                i += 2
+            } else {
+                out += c
+                i += 1
+            }
+        }
+        return out.toIntArray()
+    }
+
+    private fun isCjkHeavy(cps: IntArray): Boolean {
+        if (cps.isEmpty()) return false
+        var n = 0
+        for (cp in cps) if (isCjkCodePoint(cp)) n++
+        return n * 2 >= cps.size
+    }
+}
+
+/** Unicode fold + transliteration, provided by the platform (ICU vs JVM). */
+internal expect fun foldCompare(s: String): String
+
+/** Whether a code point belongs to a CJK script (Han/Kana/Hangul/Bopomofo). */
+internal expect fun isCjkCodePoint(cp: Int): Boolean
+
+/** Katakana → Hiragana so ナイトコード ≡ ないとこーど (pure string op). */
+internal fun katakanaToHiragana(value: String): String =
+    value.map { ch ->
+        val cp = ch.code
+        if (cp in 0x30A1..0x30F6) (cp - 0x60).toChar() else ch
+    }.joinToString("")
+
+/** Latin-ASCII for characters that don't decompose under NFD (Ø→O, æ→ae, …). */
+internal fun latinAscii(s: String): String {
+    var t = s
+    t = t.replace('ø', 'o').replace('Ø', 'O')
+    t = t.replace("æ", "ae").replace("Æ", "AE")
+    t = t.replace("œ", "oe").replace("Œ", "OE")
+    t = t.replace('ł', 'l').replace('Ł', 'L')
+    t = t.replace('đ', 'd').replace('Đ', 'D')
+    t = t.replace("ß", "ss")
+    return t
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumItem.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumItem.kt
new file mode 100644
index 00000000..c84f2052
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumItem.kt
@@ -0,0 +1,25 @@
+package capital.yuri.yuriplayer.data
+
+data class AlbumItem(
+    val name: String?,
+    val artist: String?,
+    val trackCount: Int,
+    val songs: List<Song>
+) {
+    val displayName: String get() = name ?: "Unknown Album"
+    val displayArtist: String
+        get() = primaryArtistName(artist) ?: artist ?: "Unknown Artist"
+}
+
+data class ArtistItem(
+    val name: String?,
+    val trackCount: Int,
+    val albumCount: Int,
+    val songs: List<Song>
+) {
+    val displayName: String get() = primaryArtistName(name) ?: name ?: "Unknown Artist"
+}
+
+fun AlbumItem.releaseYear(): Int? = songs.mapNotNull { it.year }.maxOrNull()
+
+fun AlbumItem.releaseType(): ReleaseType = guessReleaseType(trackCount)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumLog.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumLog.kt
new file mode 100644
index 00000000..b03d7c6c
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumLog.kt
@@ -0,0 +1,84 @@
+package capital.yuri.yuriplayer.data
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
+
+/**
+ * Album expand / merge diagnostics.
+ *
+ * Tag is always [TAG] = `YuriAlbum` → logcat `YuriPlayer.YuriAlbum`.
+ * Every line starts with `[album title]` so you can grep Clancy / self-titled
+ * without knowing the code path.
+ *
+ * Levels:
+ * - V / TRACE — every track, every identity group member
+ * - D         — query step counts, grouping
+ * - I         — path summaries (seed → expand → merge → page)
+ * - W         — collapse / identity collision / never-shrink
+ */
+object AlbumLog {
+    const val TAG = "YuriAlbum"
+    private val log = yuriLog(TAG)
+
+    fun i(album: String?, msg: String) = log.i { line(album, msg) }
+    fun d(album: String?, msg: String) = log.d { line(album, msg) }
+    fun v(album: String?, msg: String) = log.t { line(album, msg) }
+    fun w(album: String?, msg: String) = log.w { line(album, msg) }
+
+    fun step(album: String?, name: String, count: Int, extra: String = "") {
+        val suffix = if (extra.isNotEmpty()) " $extra" else ""
+        log.d { line(album, "step $name n=$count$suffix") }
+    }
+
+    fun songs(album: String?, label: String, tracks: List<Song>) {
+        log.d { line(album, "$label n=${tracks.size}") }
+        tracks.forEachIndexed { i, s ->
+            log.t { line(album, "  $label[$i] ${songLine(s)}") }
+        }
+    }
+
+    fun entities(album: String?, label: String, rows: Collection<CatalogTrackEntity>) {
+        log.d { line(album, "$label n=${rows.size}") }
+        rows.forEachIndexed { i, r ->
+            log.t { line(album, "  $label[$i] ${entityLine(r)}") }
+        }
+    }
+
+    fun identityGroups(album: String?, groups: Map<String, List<Song>>) {
+        log.d { line(album, "identity groups=${groups.size}") }
+        groups.forEach { (id, members) ->
+            if (members.size > 1) {
+                log.w {
+                    line(
+                        album,
+                        "COLLIDE identity=$id n=${members.size} titles=${members.joinToString(" | ") { it.displayTitle }}"
+                    )
+                }
+                members.forEachIndexed { i, s ->
+                    log.t { line(album, "    collide[$i] ${songLine(s)}") }
+                }
+            } else {
+                log.t { line(album, "  id=$id → ${members.firstOrNull()?.displayTitle}") }
+            }
+        }
+    }
+
+    fun songLine(s: Song): String {
+        val src = CatalogRepository.sourceTypeForSong(s)
+        return "title='${s.title}' tn=${s.trackNumber} disc=${s.discNumber} " +
+            "album='${s.album}' aa='${s.albumArtist}' ar='${s.artist}' " +
+            "src=$src key=${s.songKey} path=${s.path} " +
+            "aKey=${albumKey(s.album, s.effectiveAlbumArtist)} id=${albumPageIdentity(s)}"
+    }
+
+    fun entityLine(r: CatalogTrackEntity): String =
+        "title='${r.title}' tn=${r.trackNumber} disc=${r.discNumber} " +
+            "album='${r.album}' aa='${r.albumArtist}' ar='${r.artist}' " +
+            "src=${r.sourceType} songKey=${r.songKey} aKey=${r.albumKey} " +
+            "artistKey=${r.artistKey} ext=${r.externalId}"
+
+    private fun line(album: String?, msg: String): String {
+        val label = album?.trim().orEmpty().ifBlank { "?" }
+        return "[$label] $msg"
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumMerge.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumMerge.kt
new file mode 100644
index 00000000..3ff09745
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumMerge.kt
@@ -0,0 +1,128 @@
+package capital.yuri.yuriplayer.data
+
+/**
+ * Union every known copy of a release. Multi-source = one logical track with
+ * offerings, NOT duplicate album cards. Never replaces a rich list with a thinner one.
+ */
+fun mergeAlbumSources(
+    seed: AlbumItem,
+    fromCatalog: AlbumItem?,
+    fromLocal: AlbumItem?
+): AlbumItem {
+    val album = seed.name ?: fromCatalog?.name ?: fromLocal?.name
+    AlbumLog.i(album, "merge seed=${seed.songs.size} catalog=${fromCatalog?.songs?.size ?: 0} local=${fromLocal?.songs?.size ?: 0} " +
+            "seedName='${seed.name}' catName='${fromCatalog?.name}' localName='${fromLocal?.name}'")
+    AlbumLog.songs(album, "merge.seed", seed.songs)
+    AlbumLog.songs(album, "merge.catalog", fromCatalog?.songs.orEmpty())
+    AlbumLog.songs(album, "merge.local", fromLocal?.songs.orEmpty())
+
+    val merged = dedupeAlbumPageTracks(
+        buildList {
+            addAll(fromCatalog?.songs.orEmpty())
+            addAll(fromLocal?.songs.orEmpty())
+            addAll(seed.songs)
+        }
+    )
+    if (merged.isEmpty()) {
+        AlbumLog.w(album, "merge empty → keep seed")
+        return seed
+    }
+
+    // Absolute never-shrink against every input
+    val richest = listOfNotNull(
+        fromCatalog?.songs?.size,
+        fromLocal?.songs?.size,
+        seed.songs.size,
+        merged.size
+    ).maxOrNull() ?: merged.size
+
+    val songs = if (merged.size < richest && seed.songs.size >= richest) {
+        dedupeAlbumPageTracks(seed.songs + merged)
+    } else if (merged.size < richest && (fromCatalog?.songs?.size ?: 0) >= richest) {
+        dedupeAlbumPageTracks(fromCatalog!!.songs + merged)
+    } else if (merged.size < richest && (fromLocal?.songs?.size ?: 0) >= richest) {
+        dedupeAlbumPageTracks(fromLocal!!.songs + merged)
+    } else {
+        merged
+    }
+
+    if (songs.size < richest) {
+        AlbumLog.w(album, "merge SHRANK richest=$richest → ${songs.size}")
+        AlbumLog.songs(album, "merge.out", songs)
+    } else {
+        AlbumLog.i(album, "merge out n=${songs.size} richest=$richest")
+    }
+
+    return AlbumItem(
+        name = seed.name
+            ?: fromLocal?.name
+            ?: fromCatalog?.name
+            ?: songs.firstOrNull()?.album,
+        artist = fromCatalog?.artist
+            ?: fromLocal?.artist
+            ?: seed.artist
+            ?: songs.firstOrNull()?.effectiveAlbumArtist,
+        trackCount = songs.size.coerceAtLeast(
+            listOfNotNull(
+                fromCatalog?.trackCount,
+                fromLocal?.trackCount,
+                seed.trackCount,
+                songs.size
+            ).maxOrNull() ?: 0
+        ),
+        songs = songs
+    )
+}
+
+fun findLocalAlbum(
+    library: LocalLibrary,
+    name: String?,
+    artist: String?
+): AlbumItem? {
+    if (name.isNullOrBlank()) return null
+    val key = albumKey(name, artist)
+
+    library.albums(taggedOnly = false).firstOrNull {
+        albumKey(it.name, it.artist) == key
+    }?.let {
+        AlbumLog.i(name, "findLocalAlbum exact key='$key' n=${it.songs.size}")
+        return it
+    }
+
+    library.albums(taggedOnly = false).firstOrNull {
+        TrackIdentity.albumsMatch(it.name, name) &&
+            (artist.isNullOrBlank() || TrackIdentity.albumArtistsMatch(it.artist, artist))
+    }?.let {
+        AlbumLog.i(name, "findLocalAlbum fuzzy n=${it.songs.size} artist='${it.artist}'")
+        return it
+    }
+
+    library.albums(taggedOnly = false).firstOrNull {
+        TrackIdentity.albumsNearlyMatch(it.name, name) &&
+            (artist.isNullOrBlank() || TrackIdentity.albumArtistsMatch(it.artist, artist))
+    }?.let {
+        AlbumLog.i(name, "findLocalAlbum typo n=${it.songs.size} local='${it.name}'")
+        return it
+    }
+
+    val nameFolded = TrackIdentity.normalizeToken(name)
+    val matches = library.songs().filter { song ->
+        TrackIdentity.albumsMatch(song.album, name) ||
+            TrackIdentity.normalizeToken(song.album) == nameFolded
+    }.filter { song ->
+        if (artist.isNullOrBlank()) return@filter true
+        val aa = song.effectiveAlbumArtist
+        if (aa.isNullOrBlank()) return@filter true
+        TrackIdentity.albumArtistsMatch(aa, artist)
+    }
+    if (matches.isEmpty()) return null
+    AlbumLog.i(name, "findLocalAlbum matches=${matches.size} key='$key'")
+    AlbumLog.songs(name, "findLocal", matches)
+    val deduped = dedupeAlbumPageTracks(matches)
+    return AlbumItem(
+        name = name,
+        artist = artist ?: deduped.firstOrNull()?.effectiveAlbumArtist,
+        trackCount = deduped.size,
+        songs = deduped
+    )
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumResolve.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumResolve.kt
new file mode 100644
index 00000000..13a45684
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumResolve.kt
@@ -0,0 +1,50 @@
+package capital.yuri.yuriplayer.data
+
+import capital.yuri.yuriplayer.data.db.CatalogDao
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+
+/**
+ * Full [AlbumItem] for the album page from catalog + optional seed + local index.
+ * Never returns fewer songs than a multi-track seed.
+ */
+suspend fun resolveAlbumItem(
+    dao: CatalogDao,
+    name: String?,
+    artist: String?,
+    seedSongs: List<Song> = emptyList(),
+    library: LocalLibrary? = null
+): AlbumItem? = withContext(Dispatchers.IO) {
+    if (name.isNullOrBlank() && seedSongs.isEmpty()) return@withContext null
+    val albumName = name ?: seedSongs.firstOrNull()?.album
+    val artistName = artist ?: seedSongs.firstOrNull()?.effectiveAlbumArtist
+    if (albumName.isNullOrBlank()) return@withContext null
+
+    val key = albumKey(albumName, artistName)
+    AlbumLog.i(albumName, "resolve artist='$artistName' key='$key' seed=${seedSongs.size}")
+    AlbumLog.songs(albumName, "resolve.seed", seedSongs)
+
+    val expanded = expandAlbumTracksByName(
+        dao = dao,
+        albumName = albumName,
+        artistName = artistName,
+        seedKey = key,
+        extraSeedSongs = seedSongs
+    )
+    AlbumLog.songs(albumName, "resolve.expanded", expanded)
+    val localSongs = library?.let { findLocalAlbum(it, albumName, artistName)?.songs }.orEmpty()
+    AlbumLog.songs(albumName, "resolve.local", localSongs)
+    val songs = dedupeAlbumPageTracks(expanded + seedSongs + localSongs)
+    AlbumLog.i(albumName, "resolve done n=${songs.size} expanded=${expanded.size} seed=${seedSongs.size} local=${localSongs.size}")
+    if (songs.size < seedSongs.size && seedSongs.size > 1) {
+        AlbumLog.w(albumName, "RESOLVE SHRANK seed=${seedSongs.size} → ${songs.size}")
+    }
+    if (songs.isEmpty()) return@withContext null
+
+    AlbumItem(
+        name = albumName,
+        artist = artistName ?: songs.firstOrNull()?.effectiveAlbumArtist,
+        trackCount = songs.size,
+        songs = songs
+    )
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt
new file mode 100644
index 00000000..a0935755
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/AlbumTrackExpand.kt
@@ -0,0 +1,338 @@
+package capital.yuri.yuriplayer.data
+
+import capital.yuri.yuriplayer.data.db.CatalogDao
+import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
+
+/**
+ * Full release resolution for the album page.
+ *
+ * Strategy (in order):
+ *  1. Every catalog row whose album tag equals the name (any albumKey / source)
+ *  2. Every albumKey that shares that album name, then all rows under those keys
+ *  3. Seed / navigation tracks
+ *  4. Artist filter (strict when artist known — keeps "Let Them Talk" artists apart)
+ *  5. Dedupe **sources of the same song** via disc+track#+title — never collapse
+ *     different songs on the same album (Clancy = 14 rows, not 1).
+ */
+suspend fun expandAlbumTracks(
+    dao: CatalogDao,
+    albumKey: String
+): List<Song> {
+    if (albumKey.isBlank()) return emptyList()
+
+    val direct = dao.getTracksForAlbum(albumKey)
+    val row = dao.getAlbum(albumKey)
+    val albumName = row?.name
+        ?: direct.firstOrNull()?.album
+        ?: albumKey.substringAfter('|', missingDelimiterValue = "").takeIf { it.isNotBlank() }
+    val artistName = row?.artist
+        ?: direct.firstOrNull()?.let { it.albumArtist ?: it.artist }
+        ?: albumKey.substringBefore('|').takeIf { it.isNotBlank() }
+
+    AlbumLog.i(albumName, "expand key='$albumKey' artist='$artistName' direct=${direct.size} row=${row != null}")
+
+    AlbumLog.entities(albumName, "direct", direct)
+
+    return expandAlbumTracksByName(
+        dao = dao,
+        albumName = albumName,
+        artistName = artistName,
+        seedKey = albumKey,
+        seedRows = direct
+    )
+}
+
+/** Two SQL lookups, no search. Enough to paint the album page immediately. */
+suspend fun fastExpandAlbumTracks(
+    dao: CatalogDao,
+    albumName: String?,
+    artistName: String?,
+    seedKey: String? = null,
+    extraSeedSongs: List<Song> = emptyList()
+): List<Song> {
+    val name = albumName?.trim().orEmpty()
+    val artist = artistName?.trim().orEmpty()
+    if (name.isEmpty() && seedKey.isNullOrBlank() && extraSeedSongs.isEmpty()) return emptyList()
+
+    val bySongKey = LinkedHashMap<String, CatalogTrackEntity>()
+    fun put(row: CatalogTrackEntity) { bySongKey.putIfAbsent(row.songKey, row) }
+
+    if (!seedKey.isNullOrBlank()) {
+        dao.getTracksForAlbum(seedKey).forEach { put(it) }
+    }
+    if (name.isNotEmpty()) {
+        dao.getTracksForAlbumNameArtist(name, artist, limit = 400).forEach { put(it) }
+        if (bySongKey.size < 4) {
+            dao.getTracksByAlbumName(name, limit = 400).forEach { put(it) }
+        }
+    }
+
+    val artistFolded = foldTagToken(primaryArtistName(artistName) ?: artistName ?: "")
+    val songs = bySongKey.values.filter { row ->
+        val albumOk = name.isEmpty() ||
+            TrackIdentity.albumsMatch(row.album, name) ||
+            TrackIdentity.albumsNearlyMatch(row.album, name) ||
+            (!seedKey.isNullOrBlank() && row.albumKey == seedKey)
+        if (!albumOk) return@filter false
+        if (artistFolded.isEmpty()) return@filter true
+        val aa = foldTagToken(
+            primaryArtistName(row.albumArtist ?: row.artist) ?: row.albumArtist ?: row.artist ?: ""
+        )
+        val ta = foldTagToken(primaryArtistName(row.artist) ?: row.artist ?: "")
+        aa.isEmpty() || aa == artistFolded || ta == artistFolded
+    }.map { it.toSong() }
+
+    val deduped = dedupeAlbumPageTracks(songs + extraSeedSongs)
+    AlbumLog.i(name, "fast expand n=${deduped.size} raw=${bySongKey.size}")
+
+    return deduped.sortedWith(albumTrackOrder())
+}
+
+suspend fun expandAlbumTracksByName(
+    dao: CatalogDao,
+    albumName: String?,
+    artistName: String?,
+    seedKey: String? = null,
+    seedRows: List<CatalogTrackEntity> = emptyList(),
+    extraSeedSongs: List<Song> = emptyList()
+): List<Song> {
+    if (albumName.isNullOrBlank() && seedKey.isNullOrBlank() && seedRows.isEmpty() && extraSeedSongs.isEmpty()) {
+        return emptyList()
+    }
+
+    val bySongKey = LinkedHashMap<String, CatalogTrackEntity>()
+    val name = albumName?.trim().orEmpty()
+    val artist = artistName?.trim().orEmpty()
+
+    fun put(row: CatalogTrackEntity) {
+        bySongKey.putIfAbsent(row.songKey, row)
+    }
+
+    seedRows.forEach { put(it) }
+    AlbumLog.step(name.ifEmpty { albumName }, "seedRows", seedRows.size)
+
+    if (!seedKey.isNullOrBlank()) {
+        val keyed = dao.getTracksForAlbum(seedKey)
+        keyed.forEach { put(it) }
+        AlbumLog.step(name.ifEmpty { albumName }, "seedKey", keyed.size, "key=$seedKey")
+    }
+
+    if (name.isNotEmpty()) {
+        // Primary: album tag + artist SQL
+        dao.getTracksForAlbumNameArtist(name, artist, limit = 1500).forEach { put(it) }
+        AlbumLog.step(name, "name+artist SQL", bySongKey.size, "artist='$artist'")
+
+        dao.getTracksByAlbumName(name, limit = 1500).forEach { put(it) }
+        AlbumLog.step(name, "name-only SQL", bySongKey.size)
+
+        val keys = dao.albumKeysForAlbumName(name).toMutableSet()
+        if (!seedKey.isNullOrBlank()) keys += seedKey
+        keys += albumKey(name, artistName)
+        if (artist.isNotEmpty()) {
+            keys += albumKey(name, null)
+        }
+        AlbumLog.d(name, "albumKeys=${keys.size} ${keys.joinToString()}")
+
+        for (k in keys) {
+            if (k.isBlank()) continue
+            val rows = dao.getTracksForAlbum(k)
+            rows.forEach { put(it) }
+            AlbumLog.v(name, "  key '$k' → ${rows.size}")
+
+        }
+        AlbumLog.step(name, "after keys", bySongKey.size)
+
+        if (name.length >= 16) {
+            val needle = name.take(28)
+            val hits = dao.searchTracks(needle, limit = 400)
+            var added = 0
+            hits.forEach { t ->
+                if (TrackIdentity.albumsNearlyMatch(t.album, name)) {
+                    val before = bySongKey.size
+                    put(t)
+                    if (bySongKey.size > before) added++
+                }
+            }
+            AlbumLog.step(name, "near-name search", bySongKey.size, "hits=${hits.size} added=$added")
+        }
+
+        if (bySongKey.size < 3) {
+            val needle = name.take(48)
+            if (needle.length >= 2) {
+                val hits = dao.searchTracks(needle, limit = 600)
+                var added = 0
+                hits.forEach { t ->
+                    if (TrackIdentity.albumsMatch(t.album, name)) {
+                        val before = bySongKey.size
+                        put(t)
+                        if (bySongKey.size > before) added++
+                    }
+                }
+                AlbumLog.step(name, "short-name search", bySongKey.size, "hits=${hits.size} added=$added")
+            }
+        }
+    }
+
+    val artistFolded = foldTagToken(primaryArtistName(artistName) ?: artistName ?: "")
+
+    fun artistOk(t: CatalogTrackEntity): Boolean {
+        if (artistFolded.isEmpty()) return true
+        val aa = foldTagToken(
+            primaryArtistName(t.albumArtist ?: t.artist) ?: t.albumArtist ?: t.artist ?: ""
+        )
+        val ta = foldTagToken(primaryArtistName(t.artist) ?: t.artist ?: "")
+        if (aa.isEmpty() && ta.isEmpty()) return true
+        return aa == artistFolded || ta == artistFolded
+    }
+
+    fun albumOk(t: CatalogTrackEntity): Boolean {
+        if (name.isEmpty()) return true
+        if (TrackIdentity.albumsMatch(t.album, name)) return true
+        if (TrackIdentity.albumsNearlyMatch(t.album, name)) return true
+        if (!seedKey.isNullOrBlank() && t.albumKey == seedKey) return true
+        return false
+    }
+
+    extraSeedSongs.take(4).forEach { seed ->
+        val q = seed.title?.trim().orEmpty()
+        if (q.length < 3) return@forEach
+        dao.searchTracks(q.take(48), limit = 80).forEach { t ->
+            if (!artistOk(t)) return@forEach
+            val titleHit = TrackIdentity.titlesNearlyMatch(t.title, seed.title, minLen = 6)
+            val albumHit = TrackIdentity.albumsNearlyMatch(t.album, name)
+            if (!titleHit && !albumHit) return@forEach
+            put(t)
+            val ak = t.albumKey
+            if (!ak.isNullOrBlank()) {
+                dao.getTracksForAlbum(ak).forEach { put(it) }
+            }
+        }
+    }
+
+    val filtered = bySongKey.values.filter { albumOk(it) && artistOk(it) }
+    val dropped = bySongKey.size - filtered.size
+    if (dropped > 0) {
+        AlbumLog.w(name, "filter dropped $dropped/${bySongKey.size} artistFold='$artistFolded'")
+
+        bySongKey.values.filter { !albumOk(it) || !artistOk(it) }.forEach {
+            AlbumLog.v(name, "  DROP albumOk=${albumOk(it)} artistOk=${artistOk(it)} ${AlbumLog.entityLine(it)}")
+
+        }
+    }
+    AlbumLog.entities(name, "filtered", filtered)
+
+    val fromDb = filtered.map { it.toSong() }
+    val combined = fromDb + extraSeedSongs
+    AlbumLog.songs(name, "extraSeed", extraSeedSongs)
+
+    val groups = combined.groupBy { albumPageIdentity(it) }
+    AlbumLog.identityGroups(name, groups)
+
+    val deduped = dedupeAlbumPageTracks(combined)
+
+    AlbumLog.i(name, "expand done artist='$artist' raw=${combined.size} deduped=${deduped.size} keys=${bySongKey.size} filtered=${filtered.size}")
+
+    AlbumLog.songs(name, "deduped", deduped)
+
+    return deduped.sortedWith(albumTrackOrder())
+}
+
+/**
+ * Collapse multi-source copies of the *same* song on one release.
+ * Prefer disc|trackNumber|title when track # is present so Clancy's 14 tracks
+ * never merge into one. Fall back to [TrackIdentity] when numbers are missing.
+ */
+fun dedupeAlbumPageTracks(tracks: List<Song>): List<Song> {
+    if (tracks.isEmpty()) return emptyList()
+    val unique = tracks.distinctBy { it.songKey }
+    val groups = collapseNearTitleGroups(unique.groupBy { albumPageIdentity(it) })
+    val albumHint = tracks.firstOrNull()?.album
+    if (groups.any { it.value.size > 1 } || groups.size != tracks.size) {
+        AlbumLog.identityGroups(albumHint, groups)
+    }
+    return groups.values
+        .map { group ->
+            val preferred = group.minByOrNull {
+                CatalogRepository.sourceTypeForSong(it).rank
+            } ?: group.first()
+            TrackIdentity.withRichestDisplay(preferred, group)
+        }
+        .sortedWith(albumTrackOrder())
+}
+
+fun albumTrackOrder(): Comparator<Song> =
+    compareBy<Song> { it.discNumber ?: 1 }
+        .thenBy { it.trackNumber ?: filenameTrackHint(it) }
+        .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+
+private fun filenameTrackHint(song: Song): Int {
+    val parsed = FilenameMetadataParser.parse(song.path ?: song.contentUri)
+    return parsed.trackNumber ?: Int.MAX_VALUE
+}
+
+private fun collapseNearTitleGroups(
+    groups: Map<String, List<Song>>
+): Map<String, List<Song>> {
+    if (groups.size <= 1) return groups
+    val entries = groups.entries.toList()
+    val used = BooleanArray(entries.size)
+    val out = LinkedHashMap<String, List<Song>>()
+    for (i in entries.indices) {
+        if (used[i]) continue
+        used[i] = true
+        val bucket = entries[i].value.toMutableList()
+        val sample = bucket.first()
+        val disc = sample.discNumber ?: 1
+        val tn = sample.trackNumber
+        for (j in i + 1 until entries.size) {
+            if (used[j]) continue
+            val other = entries[j].value.first()
+            val sameSlot = tn != null && tn > 0 &&
+                other.trackNumber == tn &&
+                (other.discNumber ?: 1) == disc
+            val minLen = if (sameSlot) 6 else 16
+            if (!TrackIdentity.titlesNearlyMatch(sample.title, other.title, minLen = minLen)) {
+                continue
+            }
+            if (!sameSlot && tn != null && other.trackNumber != null && other.trackNumber != tn) {
+                continue
+            }
+            used[j] = true
+            bucket += entries[j].value
+        }
+        out[entries[i].key] = bucket
+    }
+    return out
+}
+
+internal fun albumPageIdentity(song: Song): String {
+    val disc = song.discNumber ?: 1
+    val tn = song.trackNumber
+    val title = TrackIdentity.normalizeTitle(song.title)
+    // Always include title so missing/duplicate track numbers cannot collapse
+    // a whole release onto one row (Clancy / The Craving).
+    return if (tn != null && tn > 0 && title.isNotEmpty()) {
+        "n:$disc|$tn|$title"
+    } else if (title.isNotEmpty()) {
+        TrackIdentity.of(song)
+    } else {
+        "path:${song.songKey}"
+    }
+}
+
+/** Canonical entity → Song mapping shared by all catalog code. */
+fun CatalogTrackEntity.toSong(): Song = Song(
+    id = id,
+    title = title,
+    artist = artist,
+    albumArtist = albumArtist,
+    album = album,
+    durationMs = durationMs,
+    contentUri = contentUri,
+    albumArtUri = albumArtUri,
+    trackNumber = trackNumber,
+    discNumber = discNumber,
+    year = year,
+    path = path,
+    mimeType = mimeType
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt
new file mode 100644
index 00000000..c13b6e21
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/ArtistAlbumsLight.kt
@@ -0,0 +1,215 @@
+package capital.yuri.yuriplayer.data
+
+import capital.yuri.yuriplayer.data.db.CatalogAlbumEntity
+import capital.yuri.yuriplayer.data.db.CatalogDao
+import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+
+/**
+ * Fast discography for the artist page.
+ *
+ * Releases are built from the union of two paths so a discography that spans
+ * multiple sources is never silently truncated:
+ *  1. `catalog_albums` rollup rows (fast, one seed track per release).
+ *  2. A full track scan — artistKey + PRIMARY credit roles + `LIKE`-mention —
+ *     mirroring the artist-card strategy so releases whose album artist tag
+ *     differs slightly across sources still resolve to the page.
+ *
+ * The two paths are merged with near-duplicate clustering.
+ */
+suspend fun lightAlbumItemsForArtist(
+    dao: CatalogDao,
+    artistKey: String,
+    displayName: String? = null
+): List<AlbumItem> = withContext(Dispatchers.IO) {
+    if (artistKey.isBlank()) return@withContext emptyList()
+    val keys = ArtistAliasResolver.identityKeys(artistKey)
+    val canonical = ArtistAliasResolver.resolve(artistKey)
+
+    val albumRows = dao.getAlbumsForArtists(keys)
+        .filter { !isCombinedArtistName(it.artist) }
+
+    // Robust path: collect every track this artist is credited on using the
+    // same strategy as the artist card. Do NOT gate this on the album rows
+    // being empty — a multi-source artist (e.g. Lemon Demon across local /
+    // Jellyfin / Navidrome) can have some sources missing from catalog_albums
+    // under the expected artistKey.
+    val songs = LinkedHashMap<String, Song>()
+    fun addRows(rows: List<CatalogTrackEntity>) {
+        rows.forEach { songs.putIfAbsent(it.songKey, it.toLightSong()) }
+    }
+    addRows(dao.getTracksForArtists(keys))
+    addRows(dao.getTracksByCreditRoles(keys, ArtistRole.PRIMARY.name))
+
+    val names = buildList {
+        albumRows.firstOrNull()?.artist?.let { add(it) }
+        dao.getArtist(keys.first())?.displayName?.let { add(it) }
+        displayName?.let { add(it) }
+        dao.aliasesForCanonical(canonical).forEach { add(it.aliasName) }
+    }.distinct()
+    names.filter { it.length >= 3 }.forEach { name ->
+        addRows(
+            dao.getTracksMentioning(name).filter { entity ->
+                val song = entity.toLightSong()
+                allCreditsForSong(song).any { c ->
+                    c.role == ArtistRole.PRIMARY &&
+                        ArtistAliasResolver.resolve(artistKey(c.name) ?: "") ==
+                        ArtistAliasResolver.resolve(canonical)
+                }
+            }
+        )
+    }
+
+    val fromRows = if (albumRows.isEmpty()) {
+        emptyList()
+    } else {
+        val seeds = albumRows.map { it.albumKey }.chunked(400).flatMap { chunk ->
+            if (chunk.isEmpty()) emptyList() else dao.oneTrackPerAlbum(chunk)
+        }.associateBy { it.albumKey }
+        albumRows.map { row -> row.toLightAlbum(seeds[row.albumKey]?.toLightSong()) }
+    }
+
+    val fromTracks = songs.values
+        .groupBy { albumKey(it.album, it.effectiveAlbumArtist) }
+        .map { (_, tracks) ->
+            val sorted = CatalogRepository.dedupeLogicalTracks(tracks)
+            AlbumItem(
+                name = sorted.firstOrNull()?.album,
+                artist = primaryArtistName(sorted.firstOrNull()?.effectiveAlbumArtist)
+                    ?: sorted.firstOrNull()?.effectiveAlbumArtist,
+                trackCount = sorted.size,
+                songs = sorted.take(1)
+            )
+        }
+
+    AlbumLog.i(
+        displayName,
+        "light discography rows=${fromRows.size} tracks=${fromTracks.size} keys=${keys.size}"
+    )
+
+    clusterNearDuplicateAlbums(fromRows + fromTracks).sortedWith(lightAlbumOrder())
+}
+
+suspend fun lightAppearsOnForArtist(
+    dao: CatalogDao,
+    artistKey: String,
+    displayName: String? = null
+): List<AlbumItem> = withContext(Dispatchers.IO) {
+    if (artistKey.isBlank()) return@withContext emptyList()
+    val keys = ArtistAliasResolver.identityKeys(artistKey)
+    val canonical = ArtistAliasResolver.resolve(artistKey)
+    val songs = LinkedHashMap<String, Song>()
+    dao.getTracksByCreditRoles(keys, ArtistRole.FEATURED.name).forEach {
+        songs[it.songKey] = it.toLightSong()
+    }
+    if (songs.isEmpty()) return@withContext emptyList()
+
+    songs.values
+        .groupBy { albumKey(it.album, it.effectiveAlbumArtist) }
+        .mapNotNull { (_, tracks) ->
+            val primary = primaryArtistName(tracks.first().effectiveAlbumArtist)
+                ?: tracks.first().effectiveAlbumArtist
+            if (artistKey(primary) == canonical) return@mapNotNull null
+            val sorted = CatalogRepository.dedupeLogicalTracks(tracks)
+            AlbumItem(
+                name = sorted.firstOrNull()?.album,
+                artist = primary,
+                trackCount = sorted.size,
+                songs = sorted.take(1)
+            )
+        }
+        .let { clusterNearDuplicateAlbums(it) }
+        .sortedWith(lightAlbumOrder())
+}
+
+internal fun CatalogAlbumEntity.toLightAlbum(seed: Song?): AlbumItem {
+    val art = seed?.albumArtUri
+        ?: coverUrl?.takeIf { it.isNotBlank() }
+        ?: coverPath?.takeIf { it.isNotBlank() }
+    val song = when {
+        seed != null && seed.albumArtUri == null && art != null -> seed.copy(albumArtUri = art)
+        seed != null -> seed
+        else -> Song(
+            id = albumKey.hashCode().toLong(),
+            title = name,
+            artist = artist,
+            albumArtist = artist,
+            album = name,
+            durationMs = null,
+            contentUri = "",
+            albumArtUri = art,
+            year = year,
+            path = "album:$albumKey"
+        )
+    }.let { if (year != null && it.year == null) it.copy(year = year) else it }
+    return AlbumItem(
+        name = name,
+        artist = artist,
+        trackCount = trackCount,
+        songs = listOf(song)
+    )
+}
+
+private fun lightAlbumOrder() =
+    compareByDescending<AlbumItem> { it.songs.firstOrNull()?.year ?: Int.MIN_VALUE }
+        .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayName }
+
+private fun clusterNearDuplicateAlbums(items: List<AlbumItem>): List<AlbumItem> {
+    val exact = items.groupBy { albumKey(it.name, it.artist) }.map { (key, group) ->
+        val pick = group.maxByOrNull { it.trackCount } ?: group.first()
+        if (group.size > 1) {
+            AlbumLog.d(pick.name, "light merge cards=${group.size} key='$key' counts=${group.map { it.trackCount }}")
+        }
+        pick
+    }
+    val used = BooleanArray(exact.size)
+    val out = ArrayList<AlbumItem>(exact.size)
+    for (i in exact.indices) {
+        if (used[i]) continue
+        val a = exact[i]
+        val members = mutableListOf(a)
+        used[i] = true
+        val artistA = artistKey(a.artist)
+        for (j in i + 1 until exact.size) {
+            if (used[j]) continue
+            val b = exact[j]
+            if (artistKey(b.artist) != artistA) continue
+            if (!sameRelease(a, b)) continue
+            used[j] = true
+            members += b
+        }
+        val pick = members.maxByOrNull { it.trackCount } ?: a
+        out += pick.copy(trackCount = members.maxOf { it.trackCount })
+    }
+    return out
+}
+
+private fun sameRelease(a: AlbumItem, b: AlbumItem): Boolean {
+    if (!TrackIdentity.albumsNearlyMatch(a.name, b.name)) return false
+    val sa = a.songs.firstOrNull()
+    val sb = b.songs.firstOrNull()
+    if (sa == null || sb == null) return true
+    if (albumPageIdentity(sa) == albumPageIdentity(sb)) return true
+    if (TrackIdentity.titlesNearlyMatch(sa.title, sb.title, minLen = 6)) return true
+    val sameSlot = (sa.trackNumber ?: 0) > 0 &&
+        sa.trackNumber == sb.trackNumber &&
+        (sa.discNumber ?: 1) == (sb.discNumber ?: 1)
+    return sameSlot && TrackIdentity.titlesNearlyMatch(sa.title, sb.title, minLen = 4)
+}
+
+internal fun CatalogTrackEntity.toLightSong(): Song = Song(
+    id = id,
+    title = title,
+    artist = artist,
+    albumArtist = albumArtist,
+    album = album,
+    durationMs = durationMs,
+    contentUri = contentUri,
+    albumArtUri = albumArtUri,
+    trackNumber = trackNumber,
+    discNumber = discNumber,
+    year = year,
+    path = path,
+    mimeType = mimeType
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/ArtistCredits.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/ArtistCredits.kt
new file mode 100644
index 00000000..ec3eb9cf
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/ArtistCredits.kt
@@ -0,0 +1,167 @@
+package capital.yuri.yuriplayer.data
+
+/**
+ * Split a raw artist tag into primary vs featured credits.
+ *
+ * Separators:
+ *  - `;` always splits peers
+ *  - `feat.` / `ft.` / `featuring` starts the featured list
+ *  - commas/`&` in the *primary* blob stay inside names ("Earth, Wind & Fire")
+ *  - commas/`&`/`x` in a *feat.* blob split guest lists ("Miku, Rin & Luka")
+ */
+enum class ArtistRole {
+    PRIMARY,
+    FEATURED
+}
+
+data class ArtistCredit(
+    val name: String,
+    val role: ArtistRole,
+    val position: Int
+)
+
+private val FEAT_SPLIT = Regex(
+    """(?i)(?:\p{Zs}+|[\(\[\{]\p{Zs}*)(?:feat\.?|ft\.?|featuring)\.?\p{Zs}*"""
+)
+private val FEAT_IN_PARENS = Regex(
+    """(?i)[\(\[\{]\p{Zs}*(?:feat\.?|ft\.?|featuring)\.?\p{Zs}*([^\)\]\}]+)[\)\]\}]"""
+)
+private val FEAT_SUFFIX = Regex(
+    """(?i)\p{Zs}+(?:feat\.?|ft\.?|featuring)\.?\p{Zs}*(.+)$"""
+)
+private val FEAT_BLOB_SPLIT = Regex("""\s*(?:;|,|&|×)\s+|\s+(?:and|x)\s+""", RegexOption.IGNORE_CASE)
+private val TRAILING_OPEN = Regex("""[\(\[\{]\p{Zs}*$""")
+
+fun parseArtistCreditList(raw: String?): List<ArtistCredit> {
+    if (raw.isNullOrBlank()) return emptyList()
+    val parenFeats = ArrayList<String>()
+    var cleaned = raw.trim()
+    FEAT_IN_PARENS.findAll(cleaned).forEach { parenFeats += splitFeatBlob(it.groupValues[1]) }
+    cleaned = cleaned.replace(FEAT_IN_PARENS, " ").replace(Regex("""\s+"""), " ").trim()
+    cleaned = cleaned.replace(TRAILING_OPEN, "").trim()
+
+    val parts = cleaned.split(FEAT_SPLIT, limit = 2)
+    val out = ArrayList<ArtistCredit>()
+    fun addPrimary(blob: String) {
+        blob.split(';').map { it.trim().trim('(', ')', '[', ']', '{', '}') }.filter { it.isNotEmpty() }.forEach { name ->
+            if (out.none { it.name.equals(name, ignoreCase = true) }) {
+                out += ArtistCredit(name = name, role = ArtistRole.PRIMARY, position = out.size)
+            }
+        }
+    }
+    fun addFeatured(blob: String) {
+        splitFeatBlob(blob).forEach { name ->
+            if (out.none { it.name.equals(name, ignoreCase = true) }) {
+                out += ArtistCredit(name = name, role = ArtistRole.FEATURED, position = out.size)
+            }
+        }
+    }
+    addPrimary(parts[0])
+    parts.getOrNull(1)?.let { addFeatured(it) }
+    parenFeats.forEach { addFeatured(it) }
+    return out
+}
+
+fun splitFeatBlob(blob: String): List<String> {
+    var t = blob.trim()
+    t = t.replace(Regex("""[\(\[\{].*$"""), "").trim()
+    return t.split(FEAT_BLOB_SPLIT)
+        .map { it.trim().trim('.', '-', '/') }
+        .filter { it.length >= 2 }
+        .distinctBy { it.lowercase() }
+}
+
+fun featuredFromText(text: String?): List<String> {
+    if (text.isNullOrBlank()) return emptyList()
+    val found = LinkedHashSet<String>()
+    FEAT_IN_PARENS.findAll(text).forEach { found += splitFeatBlob(it.groupValues[1]) }
+    FEAT_SUFFIX.find(text)?.let { found += splitFeatBlob(it.groupValues[1]) }
+    return found.toList()
+}
+
+/**
+ * Full credit list for a song: album-artist primaries, extra track artists as
+ * featured, plus `feat.` parsed from the title and album title.
+ */
+fun allCreditsForSong(song: Song): List<ArtistCredit> {
+    val albumParsed = parseArtistCreditList(song.albumArtist)
+    val artistParsed = parseArtistCreditList(song.artist)
+    val titleFeats = featuredFromText(song.title)
+    val albumFeats = featuredFromText(song.album)
+    val artistFieldFeats = featuredFromText(song.artist) + featuredFromText(song.albumArtist)
+
+    val primaries = LinkedHashSet<String>()
+    albumParsed.filter { it.role == ArtistRole.PRIMARY }.forEach { primaries += it.name }
+    if (primaries.isEmpty()) {
+        artistParsed.firstOrNull { it.role == ArtistRole.PRIMARY }?.let { primaries += it.name }
+    }
+    if (primaries.isEmpty()) {
+        primaryArtistName(song.effectiveAlbumArtist)?.let { primaries += it }
+    }
+
+    fun isPrimary(name: String) = primaries.any { it.equals(name, ignoreCase = true) }
+
+    val featured = LinkedHashSet<String>()
+    fun addFeat(name: String) {
+        val n = name.trim()
+        if (n.length >= 2 && !isPrimary(n)) featured += n
+    }
+    albumParsed.filter { it.role == ArtistRole.FEATURED }.forEach { addFeat(it.name) }
+    artistParsed.forEach { c ->
+        if (c.role == ArtistRole.FEATURED || !isPrimary(c.name)) addFeat(c.name)
+    }
+    titleFeats.forEach { addFeat(it) }
+    albumFeats.forEach { addFeat(it) }
+    artistFieldFeats.forEach { addFeat(it) }
+
+    val out = ArrayList<ArtistCredit>(primaries.size + featured.size)
+    primaries.forEach { n -> out += ArtistCredit(n, ArtistRole.PRIMARY, out.size) }
+    featured.forEach { n -> out += ArtistCredit(n, ArtistRole.FEATURED, out.size) }
+    return out
+}
+
+fun isCombinedArtistName(name: String?): Boolean {
+    if (name.isNullOrBlank()) return false
+    if (name.contains(';')) return true
+    if (FEAT_IN_PARENS.containsMatchIn(name)) return true
+    if (FEAT_SPLIT.containsMatchIn(name)) return true
+    return false
+}
+
+/** Names only (primary then featured) — for linking. */
+fun parseArtistCredits(raw: String?): List<String> =
+    parseArtistCreditList(raw).map { it.name }
+
+fun primaryArtistName(raw: String?): String? =
+    parseArtistCreditList(raw).firstOrNull { it.role == ArtistRole.PRIMARY }?.name
+        ?: parseArtistCreditList(raw).firstOrNull()?.name
+
+fun featuredArtistNames(raw: String?): List<String> =
+    parseArtistCreditList(raw).filter { it.role == ArtistRole.FEATURED }.map { it.name }
+
+enum class ReleaseType {
+    SINGLE,
+    EP,
+    ALBUM,
+    COMPILATION,
+    OTHER;
+
+    val label: String
+        get() = when (this) {
+            SINGLE -> "Single"
+            EP -> "EP"
+            ALBUM -> "Album"
+            COMPILATION -> "Compilation"
+            OTHER -> "Release"
+        }
+}
+
+/**
+ * Heuristic release classification until MusicBrainz / Jellyfin types land.
+ * Track-count based (Spotify-adjacent).
+ */
+fun guessReleaseType(trackCount: Int): ReleaseType = when {
+    trackCount <= 3 -> ReleaseType.SINGLE
+    trackCount <= 8 -> ReleaseType.EP
+    else -> ReleaseType.ALBUM
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CatalogRepository.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CatalogRepository.kt
new file mode 100644
index 00000000..bf1f3cd8
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CatalogRepository.kt
@@ -0,0 +1,1042 @@
+package capital.yuri.yuriplayer.data
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.db.ArtistAliasEntity
+import capital.yuri.yuriplayer.data.db.CatalogAlbumEntity
+import capital.yuri.yuriplayer.data.db.CatalogArtistEntity
+import capital.yuri.yuriplayer.data.db.CatalogCreditEntity
+import capital.yuri.yuriplayer.data.db.CatalogDao
+import capital.yuri.yuriplayer.data.db.CatalogSources
+import capital.yuri.yuriplayer.data.db.CatalogTrackEntity
+import capital.yuri.yuriplayer.data.source.SourceInstanceRepository
+import capital.yuri.yuriplayer.data.source.SourceOffering
+import capital.yuri.yuriplayer.data.source.SourceType
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.withContext
+
+/**
+ * Shared, platform-agnostic catalog repository: local + remote-indexed tracks
+ * (Jellyfin / Subsonic). Local scanning is injected via [localScanner] so
+ * Android (MediaStore/SAF) and desktop (folder walk) both satisfy it.
+ */
+class CatalogRepository(
+    private val dao: CatalogDao,
+    private val sourceInstances: SourceInstanceRepository,
+    private val localScanner: LocalScanner,
+    private val coverCandidateBuilder: CoverCandidateBuilder = CoverCandidateBuilder { songs, path, url ->
+        // Default: no local filesystem probing; Android/JVM hosts inject their own.
+        PureCoverCandidates.build(songs, path, url)
+    }
+) {
+    private val lightAlbumsCache = object : LinkedHashMap<String, List<AlbumItem>>(32, 0.75f, true) {
+        override fun removeEldestEntry(eldest: MutableMap.MutableEntry<String, List<AlbumItem>>?): Boolean =
+            size > 48
+    }
+
+    fun observeTracks(): Flow<List<Song>> =
+        dao.observeTracks().map { rows -> rows.map { it.toSong() } }
+
+    fun observeAlbums(): Flow<List<CatalogAlbumEntity>> = dao.observeAlbums()
+
+    fun observeArtists(): Flow<List<CatalogArtistEntity>> = dao.observeArtists()
+
+    suspend fun getAllSongs(): List<Song> = withContext(Dispatchers.IO) {
+        dao.getAllTracks().map { it.toSong() }
+    }
+
+    suspend fun getLocalSongs(): List<Song> = withContext(Dispatchers.IO) {
+        dao.getTracksBySource(CatalogSources.LOCAL).map { it.toSong() }
+    }
+
+    suspend fun getSongsByKeys(keys: List<String>): List<Song> = withContext(Dispatchers.IO) {
+        if (keys.isEmpty()) return@withContext emptyList()
+        keys.chunked(400).flatMap { chunk ->
+            dao.getTracksByKeys(chunk).map { it.toSong() }
+        }
+    }
+
+    suspend fun searchSongs(query: String, limit: Int = 80): List<Song> =
+        withContext(Dispatchers.IO) {
+            val q = query.trim()
+            if (q.isEmpty()) return@withContext emptyList()
+            dao.searchTracks(q, limit).map { it.toSong() }
+        }
+
+    suspend fun searchAlbumRows(query: String, limit: Int = 12): List<CatalogAlbumEntity> =
+        withContext(Dispatchers.IO) {
+            val q = query.trim()
+            if (q.isEmpty()) return@withContext emptyList()
+            dao.searchAlbums(q, limit)
+        }
+
+    suspend fun searchArtistRows(query: String, limit: Int = 12): List<CatalogArtistEntity> =
+        withContext(Dispatchers.IO) {
+            val q = query.trim()
+            if (q.isEmpty()) return@withContext emptyList()
+            dao.searchArtists(q, limit)
+        }
+
+    suspend fun searchAlbumsAsItems(query: String, limit: Int = 12): List<AlbumItem> =
+        withContext(Dispatchers.IO) {
+            val q = query.trim()
+            if (q.isEmpty()) return@withContext emptyList()
+            val rows = dao.searchAlbums(q, limit)
+            val seen = LinkedHashSet<String>()
+            val out = ArrayList<AlbumItem>(rows.size)
+            for (row in rows) {
+                val item = lightAlbumItemLocked(row.albumKey) ?: continue
+                val mergeKey = albumKey(item.name, item.artist)
+                if (!seen.add(mergeKey)) continue
+                out += item
+            }
+            out.take(limit)
+        }
+
+    suspend fun searchArtistsAsItems(query: String, limit: Int = 12): List<ArtistItem> =
+        withContext(Dispatchers.IO) {
+            val q = query.trim()
+            if (q.isEmpty()) return@withContext emptyList()
+            val aliasKeys = dao.getAllAliases().map { it.aliasKey }.toHashSet()
+            val seen = LinkedHashSet<String>()
+            val out = ArrayList<ArtistItem>()
+            for (row in dao.searchArtists(q, limit * 3)) {
+                if (row.artistKey in aliasKeys) continue
+                if (ArtistAliasResolver.isAlias(row.artistKey)) continue
+                if (isCombinedArtistName(row.displayName)) continue
+                val name = primaryArtistName(row.displayName) ?: row.displayName
+                val key = artistKey(name) ?: continue
+                if (!seen.add(key)) continue
+                out += ArtistItem(
+                    name = name,
+                    trackCount = row.trackCount,
+                    albumCount = row.albumCount,
+                    songs = emptyList()
+                )
+                if (out.size >= limit) break
+            }
+            out
+        }
+
+    suspend fun tracksForAlbum(albumKey: String): List<Song> = withContext(Dispatchers.IO) {
+        if (albumKey.isBlank()) return@withContext emptyList()
+        expandAlbumTracksLocked(albumKey)
+    }
+
+    suspend fun tracksForArtist(artistKey: String): List<Song> = withContext(Dispatchers.IO) {
+        if (artistKey.isBlank()) return@withContext emptyList()
+        dedupeLogicalTracks(primaryTracksForArtistLocked(artistKey))
+    }
+
+    /** Releases this artist owns (primary). Local + remote copies merge by albumKey. */
+    suspend fun albumItemsForArtist(artistKey: String, displayName: String? = null): List<AlbumItem> =
+        withContext(Dispatchers.IO) {
+            synchronized(lightAlbumsCache) { lightAlbumsCache[artistKey] }?.let { return@withContext it }
+            val items = lightAlbumItemsForArtist(dao, artistKey, displayName)
+            synchronized(lightAlbumsCache) { lightAlbumsCache[artistKey] = items }
+            items
+        }
+
+    suspend fun lightAlbumItemForKey(albumKey: String): AlbumItem? = withContext(Dispatchers.IO) {
+        lightAlbumItemLocked(albumKey)
+    }
+
+    private suspend fun lightAlbumItemLocked(albumKey: String): AlbumItem? {
+        if (albumKey.isBlank()) return null
+        val row = dao.getAlbum(albumKey)
+        if (row != null) {
+            val seed = dao.getOneTrackForAlbum(albumKey)
+            return row.toLightAlbum(seed?.toLightSong())
+        }
+        val seed = dao.getOneTrackForAlbum(albumKey) ?: return null
+        return AlbumItem(
+            name = seed.album,
+            artist = seed.albumArtist ?: seed.artist,
+            trackCount = 1,
+            songs = listOf(seed.toLightSong())
+        )
+    }
+
+    /** Guest appearances on other artists' releases. */
+    suspend fun appearsOnAlbumItems(artistKey: String, displayName: String? = null): List<AlbumItem> =
+        withContext(Dispatchers.IO) {
+            lightAppearsOnForArtist(dao, artistKey, displayName)
+        }
+
+    suspend fun fastAlbumItem(
+        name: String?,
+        artist: String?,
+        albumKey: String?,
+        seed: List<Song> = emptyList()
+    ): AlbumItem? = withContext(Dispatchers.IO) {
+        val songs = fastExpandAlbumTracks(dao, name, artist, albumKey, seed)
+        if (songs.isEmpty() && seed.isEmpty()) return@withContext null
+        val row = albumKey?.takeIf { it.isNotBlank() }?.let { dao.getAlbum(it) }
+        val merged = dedupeAlbumPageTracks(songs + seed)
+        AlbumItem(
+            name = name ?: row?.name ?: merged.firstOrNull()?.album,
+            artist = artist ?: row?.artist ?: merged.firstOrNull()?.effectiveAlbumArtist,
+            trackCount = merged.size.coerceAtLeast(row?.trackCount ?: 0),
+            songs = merged
+        )
+    }
+
+    suspend fun albumTrackCount(albumKey: String): Int? = withContext(Dispatchers.IO) {
+        if (albumKey.isBlank()) return@withContext null
+        dao.getAlbum(albumKey)?.trackCount
+    }
+
+    suspend fun albumItemForKey(albumKey: String): AlbumItem? = withContext(Dispatchers.IO) {
+        albumItemForKeyLocked(albumKey)
+    }
+
+    private suspend fun albumItemForKeyLocked(albumKey: String): AlbumItem? {
+        if (albumKey.isBlank()) return null
+        val row = dao.getAlbum(albumKey)
+        AlbumLog.d(row?.name, "albumItemForKey '$albumKey' row=${row != null} count=${row?.trackCount}")
+        val tracks = expandAlbumTracksLocked(albumKey)
+        if (row == null && tracks.isEmpty()) return null
+        AlbumLog.i(row?.name ?: tracks.firstOrNull()?.album, "albumItemForKey '$albumKey' tracks=${tracks.size}")
+        return AlbumItem(
+            name = row?.name ?: tracks.firstOrNull()?.album,
+            artist = row?.artist ?: tracks.firstOrNull()?.effectiveAlbumArtist,
+            trackCount = if (tracks.isNotEmpty()) tracks.size else (row?.trackCount ?: 0),
+            songs = tracks
+        )
+    }
+
+    private suspend fun expandAlbumTracksLocked(albumKey: String): List<Song> =
+        expandAlbumTracks(dao, albumKey)
+
+    suspend fun artistItemForKey(artistKey: String, hintName: String? = null): ArtistItem? = withContext(Dispatchers.IO) {
+        if (artistKey.isBlank()) return@withContext null
+        val key = ArtistAliasResolver.resolve(artistKey)
+        val row = dao.getArtist(key)?.takeUnless { isCombinedArtistName(it.displayName) }
+            ?: dao.getArtist(artistKey)?.takeUnless { isCombinedArtistName(it.displayName) }
+        val tracks = dedupeLogicalTracks(primaryTracksForArtistLocked(key, hintName ?: row?.displayName))
+        if (row == null && tracks.isEmpty()) return@withContext null
+        val albums = tracks.mapNotNull { TrackIdentity.normalizeToken(it.album).takeIf { n -> n.isNotEmpty() } }.toSet()
+        val name = primaryArtistName(row?.displayName)
+            ?: row?.displayName
+            ?: primaryArtistName(hintName)
+            ?: hintName
+            ?: primaryArtistName(tracks.firstOrNull()?.effectiveAlbumArtist)
+            ?: tracks.firstOrNull()?.effectiveAlbumArtist
+        ArtistItem(
+            name = name,
+            trackCount = if (tracks.isNotEmpty()) tracks.size else (row?.trackCount ?: 0),
+            albumCount = if (albums.isNotEmpty()) albums.size else (row?.albumCount ?: 0),
+            songs = tracks
+        )
+    }
+
+    suspend fun coverCandidatesForAlbum(albumKey: String, tracks: List<Song> = emptyList()): List<CoverCandidate> =
+        withContext(Dispatchers.IO) {
+            val songs = tracks.ifEmpty { expandAlbumTracksLocked(albumKey) }
+            val row = dao.getAlbum(albumKey)
+            coverCandidateBuilder.build(songs, row?.coverPath, row?.coverUrl)
+        }
+
+    suspend fun countRemoteTracks(): Int = withContext(Dispatchers.IO) {
+        dao.countNonLocalTracks()
+    }
+
+    suspend fun getAlbum(albumKey: String): CatalogAlbumEntity? = withContext(Dispatchers.IO) {
+        dao.getAlbum(albumKey)
+    }
+
+    suspend fun getArtist(artistKey: String): CatalogArtistEntity? = withContext(Dispatchers.IO) {
+        dao.getArtist(artistKey)
+    }
+
+    suspend fun countTracksForSource(sourceType: String, sourceInstanceId: Long?): Int =
+        withContext(Dispatchers.IO) {
+            dao.countTracksForSource(sourceType, sourceInstanceId)
+        }
+
+    suspend fun songsForSource(sourceType: String, sourceInstanceId: Long?): List<Song> =
+        withContext(Dispatchers.IO) {
+            dao.getTracksForSourceInstance(sourceType, sourceInstanceId).map { it.toSong() }
+        }
+
+    suspend fun searchSongsForSource(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        query: String,
+        limit: Int = 80
+    ): List<Song> = withContext(Dispatchers.IO) {
+        val q = query.trim()
+        if (q.isEmpty()) return@withContext emptyList()
+        dao.searchTracksForSource(sourceType, sourceInstanceId, q, limit).map { it.toSong() }
+    }
+
+    suspend fun songsByExternalIds(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        ids: List<String>
+    ): Map<String, Song> = withContext(Dispatchers.IO) {
+        if (ids.isEmpty()) return@withContext emptyMap()
+        val out = HashMap<String, Song>(ids.size)
+        ids.chunked(400).forEach { chunk ->
+            dao.tracksByExternalIds(sourceType, sourceInstanceId, chunk).forEach { row ->
+                val id = row.externalId ?: return@forEach
+                out[id] = row.toSong()
+            }
+        }
+        out
+    }
+
+    suspend fun offeringsMatchingSong(song: Song, limit: Int = 12): List<SourceOffering> =
+        withContext(Dispatchers.IO) {
+            val title = song.title?.trim().orEmpty()
+            val album = song.album?.trim().orEmpty()
+            val candidates = LinkedHashMap<String, CatalogTrackEntity>()
+
+            if (title.isNotEmpty() || album.isNotEmpty()) {
+                dao.findTracksMatching(
+                    title,
+                    song.effectiveAlbumArtist?.trim().orEmpty(),
+                    album,
+                    limit
+                ).forEach { candidates[it.songKey] = it }
+            }
+
+            val needle = TrackIdentity.normalizeTitle(title).ifEmpty { title }
+            if (needle.isNotEmpty()) {
+                dao.searchTracks(needle.take(48), limit = 80).forEach { row ->
+                    if (candidates.size >= limit) return@forEach
+                    if (TrackIdentity.matches(song, row.toSong()) ||
+                        TrackIdentity.titlesMatch(song.title, row.title) &&
+                        TrackIdentity.albumsMatch(song.album, row.album)
+                    ) {
+                        candidates.putIfAbsent(row.songKey, row)
+                    }
+                }
+            }
+
+            val names = sourceInstanceNames()
+            val fromDb = candidates.values
+                .map { offeringFor(it, names) }
+                .distinctBy { "${it.sourceType.name}:${it.sourceId}:${it.song.songKey}" }
+                .sortedBy { it.sourceType.rank }
+                .take(limit)
+
+            if (fromDb.isNotEmpty()) return@withContext fromDb
+
+            listOf(
+                SourceOffering(
+                    sourceType = sourceTypeForSong(song),
+                    sourceId = null,
+                    sourceName = if (sourceTypeForSong(song) == SourceType.LOCAL) {
+                        "On this device"
+                    } else {
+                        sourceTypeForSong(song).displayName()
+                    },
+                    song = song
+                )
+            )
+        }
+
+    suspend fun patchTrackTags(
+        songKey: String,
+        title: String? = null,
+        artist: String? = null,
+        album: String? = null,
+        albumArtist: String? = null,
+        year: Int? = null,
+        genre: String? = null
+    ) = withContext(Dispatchers.IO) {
+        val row = dao.getTrack(songKey) ?: return@withContext
+        val nextTitle = title?.trim()?.takeIf { it.isNotEmpty() } ?: row.title
+        val nextArtist = artist?.trim()?.takeIf { it.isNotEmpty() } ?: row.artist
+        val nextAlbumArtist = albumArtist?.trim()?.takeIf { it.isNotEmpty() } ?: row.albumArtist
+        val nextAlbum = album?.trim()?.takeIf { it.isNotEmpty() } ?: row.album
+        val nextYear = year?.takeIf { it in 1000..2100 } ?: row.year
+        val effectiveArtist = nextAlbumArtist ?: nextArtist
+        val nextAlbumKey = if (nextAlbum != null) albumKey(nextAlbum, effectiveArtist) else row.albumKey
+        val nextArtistKey = artistKey(effectiveArtist) ?: row.artistKey
+        @Suppress("UNUSED_VARIABLE")
+        val ignoredGenre = genre
+        dao.upsertTrack(
+            row.copy(
+                title = nextTitle,
+                artist = nextArtist,
+                albumArtist = nextAlbumArtist,
+                album = nextAlbum,
+                year = nextYear,
+                albumKey = nextAlbumKey,
+                artistKey = nextArtistKey,
+                isTagged = true,
+                updatedAtMs = System.currentTimeMillis()
+            )
+        )
+        log.i { "patchTrackTags $songKey" }
+    }
+
+    suspend fun syncLocalLibrary(): List<Song> = withContext(Dispatchers.IO) {
+        val scanned = localScanner.scan()
+        val seenAt = System.currentTimeMillis()
+        val trackEntities = scanned.map { it.toLocalTrackEntity(seenAt) }
+
+        dao.upsertTracks(trackEntities)
+        persistCreditsLocked(scanned)
+        dao.pruneStaleTracks(CatalogSources.LOCAL, null, seenAt)
+        rebuildRollupsLocked()
+
+        val local = dao.getTracksBySource(CatalogSources.LOCAL).map { it.toSong() }
+        log.i { "local sync: ${local.size} local tracks" }
+        local
+    }
+
+    suspend fun ingestRemoteBatch(
+        songs: List<Song>,
+        sourceType: String,
+        sourceInstanceId: Long?,
+        seenAt: Long = System.currentTimeMillis()
+    ): IngestStats = withContext(Dispatchers.IO) {
+        ingestRemoteDeltaLocked(songs, sourceType, sourceInstanceId, seenAt)
+    }
+
+    data class IngestStats(
+        val inserted: Int = 0,
+        val updated: Int = 0,
+        val unchanged: Int = 0
+    ) {
+        val changed: Int get() = inserted + updated
+        val seen: Int get() = inserted + updated + unchanged
+        operator fun plus(other: IngestStats) = IngestStats(
+            inserted = inserted + other.inserted,
+            updated = updated + other.updated,
+            unchanged = unchanged + other.unchanged
+        )
+    }
+
+    private suspend fun ingestRemoteDeltaLocked(
+        songs: List<Song>,
+        sourceType: String,
+        sourceInstanceId: Long?,
+        seenAt: Long
+    ): IngestStats {
+        if (songs.isEmpty()) return IngestStats()
+        val incoming = songs.map { song ->
+            song.toTrackEntity(
+                sourceType = sourceType,
+                sourceInstanceId = sourceInstanceId,
+                externalId = song.path ?: song.contentUri,
+                seenAt = seenAt
+            )
+        }
+        val ids = incoming.mapNotNull { it.externalId }
+        val existing = HashMap<String, CatalogTrackEntity>(ids.size)
+        ids.chunked(400).forEach { chunk ->
+            dao.tracksByExternalIds(sourceType, sourceInstanceId, chunk).forEach { row ->
+                val key = row.externalId ?: return@forEach
+                existing[key] = row
+            }
+        }
+        val upsert = ArrayList<CatalogTrackEntity>()
+        val patchSongs = ArrayList<Song>()
+        val touch = ArrayList<String>()
+        var inserted = 0
+        var updated = 0
+        incoming.forEachIndexed { i, ent ->
+            val id = ent.externalId
+            val prev = id?.let { existing[it] }
+            when {
+                prev == null -> {
+                    upsert += ent
+                    patchSongs += songs[i]
+                    inserted++
+                }
+                prev.sameRemoteMeta(ent) -> {
+                    if (id != null) touch += id
+                }
+                else -> {
+                    upsert += ent.copy(id = prev.id, songKey = prev.songKey)
+                    patchSongs += songs[i]
+                    updated++
+                }
+            }
+        }
+        if (touch.isNotEmpty()) {
+            touch.chunked(400).forEach { chunk ->
+                dao.touchLastSeenByExternalIds(sourceType, sourceInstanceId, chunk, seenAt)
+            }
+        }
+        if (upsert.isNotEmpty()) {
+            dao.upsertTracks(upsert)
+            persistCreditsLocked(patchSongs)
+        }
+        return IngestStats(
+            inserted = inserted,
+            updated = updated,
+            unchanged = touch.size
+        )
+    }
+
+    suspend fun externalIdsForSource(sourceType: String, sourceInstanceId: Long?): Set<String> =
+        withContext(Dispatchers.IO) {
+            dao.externalIdsForSource(sourceType, sourceInstanceId).toHashSet()
+        }
+
+    /**
+     * Drop rows for this source whose [externalId] is not in [liveIds].
+     * Incomplete scans must not call this.
+     */
+    suspend fun pruneMissingExternalIds(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        liveIds: Set<String>,
+        keepSongKeys: Set<String>
+    ): Int = withContext(Dispatchers.IO) {
+        val existing = dao.externalIdsForSource(sourceType, sourceInstanceId)
+        val gone = existing.filter { it !in liveIds }
+        if (gone.isEmpty()) return@withContext 0
+        var deleted = 0
+        gone.chunked(400).forEach { chunk ->
+            val keys = dao.songKeysForExternalIds(sourceType, sourceInstanceId, chunk)
+                .filter { it !in keepSongKeys }
+            if (keys.isEmpty()) return@forEach
+            dao.deleteCreditsForTracks(keys)
+            deleted += dao.deleteTracksByKeys(keys)
+        }
+        if (deleted > 0) {
+            dao.deleteOrphanAlbums()
+            dao.deleteOrphanArtists()
+            log.i { "pruned $deleted missing $sourceType rows (live=${liveIds.size})" }
+        }
+        deleted
+    }
+
+    suspend fun ensureTracksPresent(songs: List<Song>) = withContext(Dispatchers.IO) {
+        if (songs.isEmpty()) return@withContext
+        val now = System.currentTimeMillis()
+        val keys = songs.map { it.songKey }.distinct()
+        val existing = keys.chunked(400).flatMap { dao.getTracksByKeys(it) }.map { it.songKey }.toHashSet()
+        val missing = songs.filter { it.songKey !in existing }
+        if (missing.isEmpty()) return@withContext
+        val entities = missing.map { song ->
+            val type = when {
+                song.path?.startsWith("jellyfin:", true) == true -> CatalogSources.JELLYFIN
+                song.path?.startsWith("subsonic:", true) == true -> CatalogSources.SUBSONIC
+                song.path?.startsWith("navidrome:", true) == true -> CatalogSources.NAVIDROME
+                else -> CatalogSources.LOCAL
+            }
+            song.toTrackEntity(
+                sourceType = type,
+                sourceInstanceId = null,
+                externalId = song.path ?: song.contentUri,
+                seenAt = now
+            )
+        }
+        dao.upsertTracks(entities)
+        log.i { "ensureTracksPresent: upserted ${entities.size}" }
+    }
+
+    suspend fun rebuildRollups() = withContext(Dispatchers.IO) {
+        rebuildRollupsLocked()
+    }
+
+    private suspend fun rebuildRollupsLocked() {
+        loadAliasesLocked()
+        applyMbidAliasesLocked()
+        normalizeTrackIdentityLocked()
+        persistCreditsLocked(dao.getAllTracks().map { it.toSong() }, replaceAll = true)
+
+        val prevAlbums = dao.getAllAlbums().associateBy { it.albumKey }
+        val prevArtists = dao.getAllArtists().associateBy { it.artistKey }
+
+        val albumRows = dao.aggregateAlbums()
+        val albums = albumRows.map { row ->
+            val existing = prevAlbums[row.albumKey]
+            val aKey = artistKey(row.artist)
+            CatalogAlbumEntity(
+                albumKey = row.albumKey,
+                name = row.name,
+                artist = primaryArtistName(row.artist) ?: row.artist,
+                artistKey = aKey,
+                year = row.year,
+                trackCount = row.trackCount,
+                releaseType = guessReleaseType(row.trackCount).name,
+                mbid = existing?.mbid,
+                coverPath = existing?.coverPath,
+                coverUrl = row.coverUrl ?: existing?.coverUrl,
+                primarySourceType = row.primarySourceType.ifBlank { CatalogSources.LOCAL },
+                updatedAtMs = System.currentTimeMillis()
+            )
+        }
+        dao.upsertAlbums(albums)
+
+        val artistRows = dao.aggregateArtists()
+        val artists = artistRows.map { row ->
+            val existing = prevArtists[row.artistKey]
+            CatalogArtistEntity(
+                artistKey = row.artistKey,
+                displayName = existing?.displayName?.takeUnless { isCombinedArtistName(it) }
+                    ?: primaryArtistName(row.displayName)
+                    ?: row.displayName.ifBlank { row.artistKey },
+                trackCount = row.trackCount,
+                albumCount = row.albumCount,
+                bio = existing?.bio,
+                imageUri = existing?.imageUri,
+                websiteUrl = existing?.websiteUrl,
+                linksJson = existing?.linksJson,
+                mbid = existing?.mbid,
+                updatedAtMs = System.currentTimeMillis()
+            )
+        }
+        dao.upsertArtists(artists)
+
+        dao.deleteOrphanAlbums()
+        dao.deleteOrphanArtists()
+        log.i { "rollups rebuilt (SQL): albums=${albums.size} artists=${artists.size}" }
+    }
+
+    suspend fun loadAliases() = withContext(Dispatchers.IO) {
+        loadAliasesLocked()
+    }
+
+    private suspend fun loadAliasesLocked() {
+        val rows = dao.getAllAliases()
+        ArtistAliasResolver.replace(rows.associate { it.aliasKey to it.canonicalKey })
+    }
+
+    /**
+     * Remember [fromName] as an alias of [intoName]. Track rows stay as-is;
+     * lookups expand through [ArtistAliasResolver].
+     */
+    suspend fun mergeArtists(fromName: String, intoName: String): ArtistItem? =
+        withContext(Dispatchers.IO) {
+            val fromKey = rawArtistKey(fromName) ?: return@withContext null
+            val intoKey = ArtistAliasResolver.resolve(rawArtistKey(intoName) ?: return@withContext null)
+            if (fromKey == intoKey) return@withContext artistItemForKey(intoKey, intoName)
+            dao.upsertAlias(
+                ArtistAliasEntity(
+                    aliasKey = fromKey,
+                    canonicalKey = intoKey,
+                    aliasName = fromName.trim(),
+                    source = ArtistAliasEntity.SOURCE_USER
+                )
+            )
+            dao.retargetAliases(fromKey, intoKey)
+            loadAliasesLocked()
+            artistItemForKey(intoKey, intoName)
+        }
+
+    suspend fun unmergeArtist(aliasKey: String) = withContext(Dispatchers.IO) {
+        dao.deleteAlias(aliasKey)
+        loadAliasesLocked()
+    }
+
+    suspend fun aliasesForArtist(artistKey: String): List<ArtistAliasEntity> =
+        withContext(Dispatchers.IO) {
+            val canonical = ArtistAliasResolver.resolve(artistKey)
+            dao.aliasesForCanonical(canonical)
+        }
+
+    private suspend fun applyMbidAliasesLocked() {
+        val groups = dao.artistsWithMbid().groupBy { it.mbid.orEmpty() }
+        var changed = false
+        for ((mbid, rows) in groups) {
+            if (mbid.isBlank() || rows.size < 2) continue
+            val canonical = rows.maxWith(
+                compareBy<CatalogArtistEntity> { it.trackCount }.thenBy { it.displayName }
+            )
+            for (other in rows) {
+                if (other.artistKey == canonical.artistKey) continue
+                if (ArtistAliasResolver.resolve(other.artistKey) == canonical.artistKey) continue
+                dao.upsertAlias(
+                    ArtistAliasEntity(
+                        aliasKey = other.artistKey,
+                        canonicalKey = canonical.artistKey,
+                        aliasName = other.displayName,
+                        source = ArtistAliasEntity.SOURCE_MBID
+                    )
+                )
+                changed = true
+            }
+        }
+        if (changed) loadAliasesLocked()
+    }
+
+    suspend fun pruneRemoteSource(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        beforeMs: Long,
+        keepSongKeys: Set<String>
+    ) = withContext(Dispatchers.IO) {
+        val deleted = if (keepSongKeys.isEmpty()) {
+            dao.pruneStaleTracks(sourceType, sourceInstanceId, beforeMs)
+        } else {
+            val keep = keepSongKeys.toList()
+            if (keep.size <= 400) {
+                dao.pruneStaleTracksExcept(sourceType, sourceInstanceId, beforeMs, keep)
+            } else {
+                val stale = dao.getTracksBySource(sourceType)
+                    .asSequence()
+                    .filter {
+                        (sourceInstanceId == null || it.sourceInstanceId == sourceInstanceId) &&
+                            it.lastSeenAtMs < beforeMs &&
+                            it.songKey !in keepSongKeys
+                    }
+                    .map { it.songKey }
+                    .toList()
+                stale.forEach { dao.deleteTrack(it) }
+                stale.size
+            }
+        }
+        if (deleted > 0) {
+            dao.deleteOrphanAlbums()
+            dao.deleteOrphanArtists()
+            log.i { "pruned $deleted stale $sourceType rows (kept ${keepSongKeys.size} My Stuff keys)" }
+        }
+    }
+
+    suspend fun getRemoteOfferings(limit: Int = 64): List<SourceOffering> =
+        withContext(Dispatchers.IO) {
+            val per = (limit.coerceAtLeast(1) / 3).coerceAtLeast(1)
+            val jelly = dao.getTracksBySourceLimited(CatalogSources.JELLYFIN, per)
+            val sub = dao.getTracksBySourceLimited(CatalogSources.SUBSONIC, per)
+            val navi = dao.getTracksBySourceLimited(CatalogSources.NAVIDROME, per)
+            val names = sourceInstanceNames()
+            (jelly + sub + navi).asSequence().take(limit).map { offeringFor(it, names) }.toList()
+        }
+
+    suspend fun importToMyStuff(song: Song, sourceType: String, sourceInstanceId: Long?, externalId: String?) =
+        withContext(Dispatchers.IO) {
+            val now = System.currentTimeMillis()
+            dao.upsertTrack(
+                song.toTrackEntity(
+                    sourceType = sourceType,
+                    sourceInstanceId = sourceInstanceId,
+                    externalId = externalId,
+                    seenAt = now
+                )
+            )
+            log.i { "imported to My Stuff: ${song.songKey} from $sourceType" }
+        }
+
+    suspend fun applyAlbumYear(albumKey: String, year: Int) = withContext(Dispatchers.IO) {
+        if (year !in 1000..2100) return@withContext
+        val album = dao.getAlbum(albumKey) ?: return@withContext
+        dao.upsertAlbum(album.copy(year = year, updatedAtMs = System.currentTimeMillis()))
+        val tracks = expandAlbumTracksLocked(albumKey).mapNotNull { song ->
+            dao.getTrack(song.songKey)?.let { t ->
+                val ty = t.year
+                if (ty == null || ty <= 0) t.copy(year = year) else t
+            }
+        }
+        if (tracks.isNotEmpty()) dao.upsertTracks(tracks)
+    }
+
+    suspend fun applyAlbumCover(albumKey: String, coverPath: String?, coverUrl: String?, mbid: String?) =
+        withContext(Dispatchers.IO) {
+            val album = dao.getAlbum(albumKey) ?: return@withContext
+            dao.upsertAlbum(
+                album.copy(
+                    coverPath = coverPath ?: album.coverPath,
+                    coverUrl = coverUrl ?: album.coverUrl,
+                    mbid = mbid ?: album.mbid,
+                    updatedAtMs = System.currentTimeMillis()
+                )
+            )
+        }
+
+    suspend fun applyArtistImage(artistKey: String, imageUri: String?) = withContext(Dispatchers.IO) {
+        val artist = dao.getArtist(artistKey) ?: return@withContext
+        if (imageUri.isNullOrBlank()) return@withContext
+        dao.upsertArtist(artist.copy(imageUri = imageUri, updatedAtMs = System.currentTimeMillis()))
+    }
+
+    suspend fun coverPathForAlbum(albumKey: String): String? =
+        dao.getAlbum(albumKey)?.coverPath
+
+    private suspend fun persistCreditsLocked(songs: List<Song>, replaceAll: Boolean = false) {
+        if (songs.isEmpty()) return
+        if (replaceAll) dao.deleteAllCredits()
+        val credits = ArrayList<CatalogCreditEntity>()
+        val albumSeen = HashSet<String>()
+        val artistStubs = LinkedHashMap<String, CatalogArtistEntity>()
+        val existingArtists = dao.getAllArtists().associateBy { it.artistKey }.toMutableMap()
+        for (song in songs) {
+            if (!replaceAll) dao.deleteCredits("TRACK", song.songKey)
+            allCreditsForSong(song).forEach { c ->
+                val key = artistKey(c.name) ?: return@forEach
+                credits += CatalogCreditEntity(
+                    subjectType = "TRACK",
+                    subjectKey = song.songKey,
+                    artistKey = key,
+                    displayName = c.name,
+                    role = c.role.name,
+                    position = c.position
+                )
+                if (key !in existingArtists && key !in artistStubs) {
+                    artistStubs[key] = CatalogArtistEntity(
+                        artistKey = key,
+                        displayName = c.name,
+                        trackCount = 0,
+                        albumCount = 0,
+                        updatedAtMs = System.currentTimeMillis()
+                    )
+                }
+            }
+            val aKey = albumKey(song.album, song.effectiveAlbumArtist)
+            if (aKey.isNotBlank() && albumSeen.add(aKey)) {
+                if (!replaceAll) dao.deleteCredits("ALBUM", aKey)
+                parseArtistCreditList(song.albumArtist ?: song.effectiveAlbumArtist).forEach { c ->
+                    val key = artistKey(c.name) ?: return@forEach
+                    credits += CatalogCreditEntity(
+                        subjectType = "ALBUM",
+                        subjectKey = aKey,
+                        artistKey = key,
+                        displayName = c.name,
+                        role = c.role.name,
+                        position = c.position
+                    )
+                }
+            }
+            song.musicBrainzArtistId?.takeIf { it.isNotBlank() }?.let { mbid ->
+                listOfNotNull(
+                    artistKey(song.effectiveAlbumArtist),
+                    artistKey(song.artist)
+                ).distinct().forEach { key ->
+                    val existing = existingArtists[key] ?: dao.getArtist(key)
+                    if (existing != null && existing.mbid.isNullOrBlank()) {
+                        val next = existing.copy(mbid = mbid, updatedAtMs = System.currentTimeMillis())
+                        dao.upsertArtist(next)
+                        existingArtists[key] = next
+                    }
+                }
+            }
+        }
+        if (artistStubs.isNotEmpty()) dao.upsertArtists(artistStubs.values.toList())
+        if (credits.isNotEmpty()) credits.chunked(500).forEach { dao.upsertCredits(it) }
+    }
+
+    private suspend fun normalizeTrackIdentityLocked() {
+        val tracks = dao.getAllTracks()
+        val changed = ArrayList<CatalogTrackEntity>()
+        for (row in tracks) {
+            val song = row.toSong()
+            val newAlbum = albumKey(song.album, song.effectiveAlbumArtist).takeIf { !song.album.isNullOrBlank() }
+            val newArtist = artistKey(song.effectiveAlbumArtist)
+            if (row.albumKey != newAlbum || row.artistKey != newArtist) {
+                changed += row.copy(albumKey = newAlbum, artistKey = newArtist)
+            }
+        }
+        val byKey = HashMap<String, CatalogTrackEntity>(tracks.size)
+        tracks.forEach { byKey[it.songKey] = it }
+        changed.forEach { byKey[it.songKey] = it }
+        coalesceSplitAlbums(byKey.values.toList()).forEach { row ->
+            val prev = byKey[row.songKey]
+            if (prev == null || prev != row) {
+                byKey[row.songKey] = row
+                val idx = changed.indexOfFirst { it.songKey == row.songKey }
+                if (idx >= 0) changed[idx] = row else changed += row
+            }
+        }
+        if (changed.isEmpty()) return
+        changed.chunked(400).forEach { dao.upsertTracks(it) }
+        log.i { "normalized identity on ${changed.size} tracks" }
+    }
+
+    /**
+     * Same remote library + same album title + unique disc/track slots =
+     * one release (Navidrome VA / split-artist albums). Do not merge when
+     * two albums share a title and collide on track numbers (Greatest Hits).
+     */
+    private fun coalesceSplitAlbums(tracks: List<CatalogTrackEntity>): List<CatalogTrackEntity> {
+        val out = ArrayList<CatalogTrackEntity>()
+        val groups = tracks
+            .filter { !it.album.isNullOrBlank() && it.sourceType != CatalogSources.LOCAL }
+            .groupBy { Triple(it.sourceType, it.sourceInstanceId, foldTagToken(it.album.orEmpty())) }
+        for ((_, group) in groups) {
+            if (group.size < 2) continue
+            val keys = group.mapNotNull { it.albumKey }.toHashSet()
+            if (keys.size <= 1) continue
+            if (hasCollidingTrackSlots(group)) continue
+            val canonicalArtist = pickCanonicalAlbumArtist(group) ?: continue
+            val canonicalKey = albumKey(group.first().album, canonicalArtist)
+            val canonicalArtistKey = artistKey(canonicalArtist)
+            for (row in group) {
+                val stamp = row.albumArtist.isNullOrBlank() ||
+                    row.albumArtist.equals(row.artist, ignoreCase = true)
+                val next = row.copy(
+                    albumArtist = if (stamp) canonicalArtist else row.albumArtist,
+                    albumKey = canonicalKey,
+                    artistKey = canonicalArtistKey
+                )
+                if (next != row) out += next
+            }
+        }
+        return out
+    }
+
+    private fun hasCollidingTrackSlots(group: List<CatalogTrackEntity>): Boolean {
+        data class Slot(val disc: Int, val track: Int)
+        val titles = HashMap<Slot, String>()
+        for (t in group) {
+            val tn = t.trackNumber ?: continue
+            val slot = Slot(t.discNumber ?: 1, tn)
+            val title = TrackIdentity.normalizeTitle(t.title)
+            if (title.isEmpty()) continue
+            val existing = titles[slot]
+            if (existing != null && existing != title) return true
+            titles[slot] = title
+        }
+        return false
+    }
+
+    private fun pickCanonicalAlbumArtist(group: List<CatalogTrackEntity>): String? {
+        val tagged = group.mapNotNull { row ->
+            val aa = row.albumArtist?.trim()?.takeIf { it.isNotEmpty() } ?: return@mapNotNull null
+            val ta = row.artist?.trim().orEmpty()
+            if (aa.equals(ta, ignoreCase = true)) null else primaryArtistName(aa) ?: aa
+        }
+        val pool = if (tagged.isNotEmpty()) {
+            tagged
+        } else {
+            group.mapNotNull {
+                primaryArtistName(it.albumArtist) ?: it.albumArtist?.trim()?.takeIf { n -> n.isNotEmpty() }
+                    ?: primaryArtistName(it.artist) ?: it.artist?.trim()?.takeIf { n -> n.isNotEmpty() }
+            }
+        }
+        if (pool.isEmpty()) return null
+        return pool.groupingBy { it }.eachCount()
+            .entries
+            .sortedWith(compareByDescending<Map.Entry<String, Int>> { it.value }.thenBy { it.key.lowercase() })
+            .first()
+            .key
+    }
+
+    private suspend fun primaryTracksForArtistLocked(artistKey: String, hintName: String? = null): List<Song> {
+        val keys = ArtistAliasResolver.identityKeys(artistKey)
+        val out = LinkedHashMap<String, Song>()
+        dao.getTracksForArtists(keys).map { it.toSong() }.forEach { out[it.songKey] = it }
+        dao.getTracksByCreditRoles(keys, ArtistRole.PRIMARY.name)
+            .map { it.toSong() }
+            .forEach { out.putIfAbsent(it.songKey, it) }
+        val names = buildList {
+            dao.getArtist(keys.first())?.displayName?.let { add(it) }
+            hintName?.let { add(it) }
+            dao.aliasesForCanonical(keys.first()).forEach { add(it.aliasName) }
+        }.distinct()
+        names.filter { it.length >= 3 }.forEach { name ->
+            dao.getTracksMentioning(name).forEach { entity ->
+                val song = entity.toSong()
+                val hit = allCreditsForSong(song).any {
+                    it.role == ArtistRole.PRIMARY &&
+                        ArtistAliasResolver.resolve(artistKey(it.name) ?: "") ==
+                        ArtistAliasResolver.resolve(artistKey)
+                }
+                if (hit) out.putIfAbsent(entity.songKey, song)
+            }
+        }
+        return out.values.toList()
+    }
+
+    private fun Song.toLocalTrackEntity(seenAt: Long) = toTrackEntity(
+        sourceType = CatalogSources.LOCAL,
+        sourceInstanceId = null,
+        externalId = null,
+        seenAt = seenAt
+    )
+
+    private fun Song.toTrackEntity(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        externalId: String?,
+        seenAt: Long
+    ): CatalogTrackEntity {
+        val aKey = albumKey(album, effectiveAlbumArtist)
+        val rKey = artistKey(effectiveAlbumArtist)
+        return CatalogTrackEntity(
+            songKey = songKey,
+            sourceType = sourceType,
+            sourceInstanceId = sourceInstanceId,
+            externalId = externalId,
+            title = title,
+            artist = artist,
+            albumArtist = albumArtist,
+            album = album,
+            year = year,
+            trackNumber = trackNumber,
+            discNumber = discNumber,
+            durationMs = durationMs,
+            albumKey = aKey.takeIf { album != null },
+            artistKey = rKey,
+            contentUri = contentUri,
+            path = path,
+            albumArtUri = albumArtUri?.toString(),
+            mimeType = mimeType,
+            isTagged = isTagged,
+            updatedAtMs = seenAt,
+            lastSeenAtMs = seenAt
+        )
+    }
+
+    private fun CatalogTrackEntity.sameRemoteMeta(incoming: CatalogTrackEntity): Boolean {
+        if (!incoming.title.isNullOrBlank() && title != incoming.title) return false
+        if (!incoming.artist.isNullOrBlank() && artist != incoming.artist) return false
+        if (!incoming.albumArtist.isNullOrBlank() && albumArtist != incoming.albumArtist) return false
+        if (!incoming.album.isNullOrBlank() && album != incoming.album) return false
+        if (incoming.year != null && year != incoming.year) return false
+        if (incoming.trackNumber != null && trackNumber != incoming.trackNumber) return false
+        if (incoming.discNumber != null && discNumber != incoming.discNumber) return false
+        val incDur = incoming.durationMs
+        if (incDur != null && incDur > 0 && durationMs != incDur) return false
+        if (incoming.albumArtUri != null && albumArtUri != incoming.albumArtUri) return false
+        if (incoming.mimeType != null && mimeType != incoming.mimeType) return false
+        return true
+    }
+
+    private suspend fun sourceInstanceNames(): Map<Long, String> =
+        sourceInstances.getAll().associate { it.id to it.name }
+
+    private fun offeringFor(
+        row: CatalogTrackEntity,
+        names: Map<Long, String>
+    ): SourceOffering {
+        val type = SourceType.from(row.sourceType)
+        val label = names[row.sourceInstanceId]?.takeIf { it.isNotBlank() }
+            ?: if (type == SourceType.LOCAL) "On this device" else type.displayName()
+        return SourceOffering(
+            sourceType = type,
+            sourceId = row.sourceInstanceId,
+            sourceName = label,
+            song = row.toSong()
+        )
+    }
+
+    companion object {
+        private val log = yuriLog("CatalogRepo")
+        fun sourceTypeForSong(song: Song): SourceType {
+            val p = song.path.orEmpty()
+            return when {
+                p.startsWith("jellyfin:", true) -> SourceType.JELLYFIN
+                p.startsWith("navidrome:", true) -> SourceType.NAVIDROME
+                p.startsWith("subsonic:", true) -> SourceType.SUBSONIC
+                else -> SourceType.LOCAL
+            }
+        }
+
+        fun friendlySourceName(raw: String): String =
+            raw.lowercase().replaceFirstChar { it.titlecase() }
+
+        fun isMultiSource(offerings: List<SourceOffering>): Boolean =
+            offerings.map { "${it.sourceType.name}:${it.sourceId}" }.toSet().size > 1
+
+        fun dedupeLogicalTracks(tracks: List<Song>): List<Song> {
+            if (tracks.isEmpty()) return emptyList()
+            return tracks
+                .groupBy { TrackIdentity.of(it) }
+                .values
+                .map { group ->
+                    val preferred = group.minByOrNull { sourceTypeForSong(it).rank } ?: group.first()
+                    TrackIdentity.withRichestDisplay(preferred, group)
+                }
+                .sortedWith(albumTrackOrder())
+        }
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CoverCandidate.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CoverCandidate.kt
new file mode 100644
index 00000000..45947fb5
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CoverCandidate.kt
@@ -0,0 +1,23 @@
+package capital.yuri.yuriplayer.data
+
+/**
+ * One selectable cover for an album (local tags, folder, remote HTTP, etc.).
+ * [uri] is a content/file/http URI used for decode + preference storage.
+ */
+data class CoverCandidate(
+    val id: String,
+    val label: String,
+    val uri: String,
+    /** Optional local song used to pull embedded/folder art. */
+    val seedSong: Song? = null,
+    val isLocal: Boolean = false
+)
+
+/**
+ * Platform seam for the cover-picker carousel. The Android implementation walks
+ * the filesystem / SAF content URIs ([CoverCandidates.build]); a JVM host can
+ * supply its own. Kept behind an interface so [CatalogRepository] stays pure.
+ */
+fun interface CoverCandidateBuilder {
+    fun build(songs: List<Song>, coverPath: String?, coverUrl: String?): List<CoverCandidate>
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CoverCandidates.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CoverCandidates.kt
new file mode 100644
index 00000000..84396f6f
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/CoverCandidates.kt
@@ -0,0 +1,79 @@
+package capital.yuri.yuriplayer.data
+
+import capital.yuri.yuriplayer.data.source.SourceType
+
+/**
+ * Pure, platform-agnostic cover-candidate assembly (no `java.io.File` /
+ * `android.net.Uri`). The Android client injects a fuller builder via
+ * [CoverCandidateBuilder] that additionally probes the local filesystem / SAF
+ * content URIs for embedded and folder art.
+ */
+object PureCoverCandidates {
+
+    fun build(
+        songs: List<Song>,
+        coverPath: String? = null,
+        coverUrl: String? = null
+    ): List<CoverCandidate> {
+        val out = LinkedHashMap<String, CoverCandidate>()
+
+        fun add(c: CoverCandidate) {
+            out.putIfAbsent(c.id, c)
+        }
+
+        // Local tag art carried directly on the Song (already a URI string).
+        songs.filter { CatalogRepository.sourceTypeForSong(it) == SourceType.LOCAL }.forEach { song ->
+            val artUri = song.albumArtUri?.takeIf { it.isNotBlank() }
+            if (artUri != null) {
+                add(
+                    CoverCandidate(
+                        id = "art:$artUri",
+                        label = "Local tag",
+                        uri = artUri,
+                        seedSong = song,
+                        isLocal = true
+                    )
+                )
+            }
+        }
+
+        coverPath?.takeIf { it.isNotBlank() }?.let { path ->
+            add(
+                CoverCandidate(
+                    id = "enriched:$path",
+                    label = "Saved cover",
+                    uri = path,
+                    isLocal = true
+                )
+            )
+        }
+
+        songs.forEach { song ->
+            val uri = song.albumArtUri ?: return@forEach
+            if (!uri.startsWith("http", ignoreCase = true)) return@forEach
+            val type = CatalogRepository.sourceTypeForSong(song)
+            add(
+                CoverCandidate(
+                    id = "remote:$uri",
+                    label = "${CatalogRepository.friendlySourceName(type.name)} cover",
+                    uri = uri,
+                    seedSong = song,
+                    isLocal = false
+                )
+            )
+        }
+
+        coverUrl?.takeIf { it.startsWith("http", ignoreCase = true) }?.let { url ->
+            add(
+                CoverCandidate(
+                    id = "catalog:$url",
+                    label = "Catalog cover",
+                    uri = url,
+                    isLocal = false
+                )
+            )
+        }
+
+        return out.values.sortedBy { if (it.isLocal) 0 else 1 }
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/FilenameMetadata.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/FilenameMetadata.kt
new file mode 100644
index 00000000..8b1f67f0
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/FilenameMetadata.kt
@@ -0,0 +1,80 @@
+package capital.yuri.yuriplayer.data
+
+/**
+ * Tags inferred from a file name / parent folder when the embedded tag is empty.
+ *
+ * Patterns:
+ *  - `08. Title` / `08 - Title` / `08_Title`
+ *  - `1-08 Title` / `01-08. Title` (disc-track)
+ *  - `CD2 - 08 Title` / `Disc 2 - 08. Title`
+ *  - parent folder `CD2` / `Disc 2`
+ */
+data class FilenameMetadata(
+    val trackNumber: Int? = null,
+    val discNumber: Int? = null,
+    val title: String? = null
+) {
+    val isEmpty: Boolean
+        get() = trackNumber == null && discNumber == null && title.isNullOrBlank()
+}
+
+object FilenameMetadataParser {
+
+    private val DISC_TRACK_TITLE = Regex(
+        """^(?:(?:CD|Disc|Disk)\s*)?(\d{1,2})\s*[-.]\s*(\d{1,3})\s*[-._)\s]+\s*(.+)$""",
+        RegexOption.IGNORE_CASE
+    )
+    private val CD_PREFIX_TRACK = Regex(
+        """^(?:CD|Disc|Disk)\s*(\d{1,2})\s*[-._ ]+\s*(\d{1,3})\s*[-._)\s]+\s*(.+)$""",
+        RegexOption.IGNORE_CASE
+    )
+    private val TRACK_TITLE = Regex(
+        """^(\d{1,3})\s*[-._)\s]+\s*(.+)$"""
+    )
+    private val DISC_FOLDER = Regex(
+        """^(?:CD|Disc|Disk)\s*(\d{1,2})$""",
+        RegexOption.IGNORE_CASE
+    )
+
+    fun parse(path: String?): FilenameMetadata {
+        if (path.isNullOrBlank()) return FilenameMetadata()
+        val slash = path.replace('\\', '/')
+        val fileName = slash.substringAfterLast('/').substringBeforeLast('.')
+        val parent = slash.substringBeforeLast('/').substringAfterLast('/')
+
+        var disc: Int? = null
+        var track: Int? = null
+        var title: String? = null
+
+        CD_PREFIX_TRACK.matchEntire(fileName)?.let { m ->
+            disc = m.groupValues[1].toIntOrNull()
+            track = m.groupValues[2].toIntOrNull()?.takeIf { it > 0 }
+            title = cleanTitle(m.groupValues[3])
+        } ?: DISC_TRACK_TITLE.matchEntire(fileName)?.let { m ->
+            val a = m.groupValues[1].toIntOrNull()
+            val b = m.groupValues[2].toIntOrNull()?.takeIf { it > 0 }
+            if (a != null && a in 1..99 && b != null) {
+                disc = a
+                track = b
+                title = cleanTitle(m.groupValues[3])
+            }
+        } ?: TRACK_TITLE.matchEntire(fileName)?.let { m ->
+            track = m.groupValues[1].toIntOrNull()?.takeIf { it in 1..999 }
+            title = cleanTitle(m.groupValues[2])
+        }
+
+        if (disc == null) {
+            disc = DISC_FOLDER.matchEntire(parent.trim())?.groupValues?.getOrNull(1)?.toIntOrNull()
+        }
+        return FilenameMetadata(
+            trackNumber = track,
+            discNumber = disc?.takeIf { it > 0 },
+            title = title
+        )
+    }
+
+    private fun cleanTitle(raw: String): String? {
+        val t = raw.trim().trim('.', '-', '_').trim()
+        return t.takeIf { it.length >= 1 }
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/LocalLibrary.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/LocalLibrary.kt
new file mode 100644
index 00000000..4c84ac50
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/LocalLibrary.kt
@@ -0,0 +1,16 @@
+package capital.yuri.yuriplayer.data
+
+/**
+ * Minimal, platform-agnostic view of the in-memory **local** library.
+ *
+ * Android wires [LibraryIndex]; a JVM host can back this with [SongLibrary]
+ * over its scanned songs. Kept behind an interface so album resolution stays in
+ * commonMain without importing Context / MediaStore.
+ */
+interface LocalLibrary {
+    /** Grouped album items (optionally only tagged releases). */
+    fun albums(taggedOnly: Boolean = true): List<AlbumItem>
+
+    /** Current flat local song list. */
+    fun songs(): List<Song>
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/LocalScanner.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/LocalScanner.kt
new file mode 100644
index 00000000..6a045211
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/LocalScanner.kt
@@ -0,0 +1,14 @@
+package capital.yuri.yuriplayer.data
+
+/**
+ * Platform seam for scanning the local device library into [Song] rows.
+ *
+ * - Android wires [MusicRepository.scanLibrary] (MediaStore / SAF).
+ * - JVM/desktop wires [LocalLibraryScanner.scanSongs] (folder walk).
+ *
+ * Kept as a single-method functional interface so [CatalogRepository] lives in
+ * commonMain without importing Context / MediaStore / File.
+ */
+fun interface LocalScanner {
+    suspend fun scan(): List<Song>
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/Song.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/Song.kt
new file mode 100644
index 00000000..b9943e53
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/Song.kt
@@ -0,0 +1,448 @@
+package capital.yuri.yuriplayer.data
+
+import kotlinx.serialization.Serializable
+
+/**
+ * All tag fields are nullable — missing tags stay null rather than "Unknown …".
+ * Use [displayTitle] / [displayArtist] / [displayAlbum] only for UI strings.
+ */
+@Serializable
+data class Song(
+    val id: Long,
+    val title: String? = null,
+    val artist: String? = null,
+    val albumArtist: String? = null,
+    val album: String? = null,
+    val durationMs: Long? = null,
+    val contentUri: String,
+    val albumArtUri: String? = null,
+    val trackNumber: Int? = null,
+    /** Disc / media set number (1-based). Null = single-disc or unknown. */
+    val discNumber: Int? = null,
+    val year: Int? = null,
+    /** Genre tag (may be semicolon-separated). */
+    val genre: String? = null,
+    val path: String? = null,
+    val mimeType: String? = null,
+    /** Explicit content flag when known from tags / remote metadata. */
+    val explicit: Boolean = false,
+    /** MusicBrainz artist id when the source publishes one (Navidrome / OpenSubsonic). */
+    val musicBrainzArtistId: String? = null,
+    /**
+     * Remote account id (`"local"`, a Jellyfin/Subsonic account UUID, …).
+     * Cross-platform so a [Song] can be refreshed with a live stream URL
+     * before playback without the host keeping an out-of-band identity map.
+     */
+    val sourceId: String? = null
+) {
+    val displayTitle: String
+        get() = title?.takeIf { it.isNotBlank() }
+            ?: path?.let { it.substringAfterLast('/').substringAfterLast('\\').substringBeforeLast('.') }
+            ?: "Unknown"
+
+    val displayArtist: String
+        get() = artist?.takeIf { it.isMeaningfulTag() }
+            ?: albumArtist?.takeIf { it.isMeaningfulTag() }
+            ?: "Unknown Artist"
+
+    /** Album cards / explore — never includes feat. credits. */
+    val primaryArtist: String
+        get() = primaryArtistName(effectiveAlbumArtist)
+            ?: primaryArtistName(artist)
+            ?: displayArtist
+
+    val displayAlbum: String
+        get() = album?.takeIf { it.isMeaningfulTag() } ?: "Unknown Album"
+
+    val effectiveAlbumArtist: String?
+        get() = albumArtist?.takeIf { it.isMeaningfulTag() }
+            ?: artist?.takeIf { it.isMeaningfulTag() }
+
+    val displayAlbumArtist: String
+        get() = effectiveAlbumArtist ?: "Unknown Artist"
+
+    val genres: List<String>
+        get() = genre.orEmpty()
+            .split(';', '/', ',', '|')
+            .map { it.trim() }
+            .filter { it.isNotEmpty() }
+            .distinctBy { it.lowercase() }
+
+    val creditArtists: List<String>
+        get() = allCreditsForSong(this).map { it.name }
+
+    val isTagged: Boolean
+        get() = artist.isMeaningfulTag() ||
+            albumArtist.isMeaningfulTag() ||
+            album.isMeaningfulTag()
+
+    val hasAlbum: Boolean get() = album.isMeaningfulTag()
+    val hasArtist: Boolean get() = artist.isMeaningfulTag() || albumArtist.isMeaningfulTag()
+    val hasTitle: Boolean get() = title.isMeaningfulTag()
+
+    val isExplicit: Boolean
+        get() {
+            if (explicit) return true
+            val t = title.orEmpty()
+            val g = genre.orEmpty()
+            return t.contains("explicit", ignoreCase = true) ||
+                t.contains("[e]", ignoreCase = true) ||
+                Regex("\\(e\\)", RegexOption.IGNORE_CASE).containsMatchIn(t) ||
+                g.contains("explicit", ignoreCase = true)
+        }
+
+    val songKey: String
+        get() = path?.lowercase() ?: contentUri
+
+    fun isSameAs(other: Song?): Boolean {
+        if (other == null) return false
+        if (path != null && other.path != null) return path == other.path
+        return id == other.id && contentUri == other.contentUri
+    }
+
+    companion object {
+        /**
+         * Minimal cross-platform construction. Platform-specific factories
+         * (e.g. from an Android `Uri` or a JVM `File`) live in per-platform
+         * extension functions and delegate here.
+         */
+        operator fun invoke(
+            id: Long,
+            contentUri: String,
+            path: String? = null,
+            title: String? = null,
+            artist: String? = null,
+            album: String? = null,
+            albumArtUri: String? = null,
+            durationMs: Long? = null
+        ): Song = Song(
+            id = id,
+            title = title,
+            artist = artist,
+            album = album,
+            durationMs = durationMs,
+            contentUri = contentUri,
+            albumArtUri = albumArtUri,
+            path = path
+        )
+    }
+}
+
+private fun String?.isMeaningfulTag(): Boolean {
+    if (this == null) return false
+    val t = trim()
+    if (t.isEmpty()) return false
+    if (t.equals("<unknown>", true)) return false
+    if (t.equals("Unknown", true)) return false
+    if (t.equals("Unknown Artist", true)) return false
+    if (t.equals("Unknown Album", true)) return false
+    return true
+}
+
+enum class SortMode {
+    TITLE,
+    ARTIST,
+    ALBUM,
+    TRACK
+}
+
+fun SortMode.label(): String = when (this) {
+    SortMode.TITLE -> "Title"
+    SortMode.ARTIST -> "Artist"
+    SortMode.ALBUM -> "Album"
+    SortMode.TRACK -> "Track #"
+}
+
+/** Cross-platform accent folding (replaces `java.text.Normalizer` NFKD). */
+private val ACCENT_MAP: Map<Char, Char> = mapOf(
+    'à' to 'a', 'á' to 'a', 'â' to 'a', 'ã' to 'a', 'ä' to 'a', 'å' to 'a',
+    'ç' to 'c',
+    'è' to 'e', 'é' to 'e', 'ê' to 'e', 'ë' to 'e',
+    'ì' to 'i', 'í' to 'i', 'î' to 'i', 'ï' to 'i',
+    'ñ' to 'n',
+    'ò' to 'o', 'ó' to 'o', 'ô' to 'o', 'õ' to 'o', 'ö' to 'o',
+    'ù' to 'u', 'ú' to 'u', 'û' to 'u', 'ü' to 'u',
+    'ý' to 'y', 'ÿ' to 'y',
+    'À' to 'A', 'Á' to 'A', 'Â' to 'A', 'Ã' to 'A', 'Ä' to 'A', 'Å' to 'A',
+    'Ç' to 'C',
+    'È' to 'E', 'É' to 'E', 'Ê' to 'E', 'Ë' to 'E',
+    'Ì' to 'I', 'Í' to 'I', 'Î' to 'I', 'Ï' to 'I',
+    'Ñ' to 'N',
+    'Ò' to 'O', 'Ó' to 'O', 'Ô' to 'O', 'Õ' to 'O', 'Ö' to 'O',
+    'Ù' to 'U', 'Ú' to 'U', 'Û' to 'U', 'Ü' to 'U',
+    'Ý' to 'Y'
+)
+
+private fun stripAccents(s: String): String =
+    s.map { ACCENT_MAP[it] ?: it }.joinToString("")
+
+/**
+ * Fold stylized / accented music tags so "Twenty Øne Piløts" and
+ * "Twenty One Pilots" share the same catalog keys.
+ */
+fun foldTagToken(value: String?): String {
+    var t = value.orEmpty().trim().replace(Regex("\\s+"), " ").lowercase()
+    t = stripAccents(t)
+    // Multi-char replacements MUST be Strings (Char literals only hold one code unit).
+    t = t
+        .replace('ø', 'o')
+        .replace("æ", "ae")
+        .replace("œ", "oe")
+        .replace('ł', 'l')
+        .replace('đ', 'd')
+        .replace("ß", "ss")
+    // Jenna's vs Jenna's (U+2019) split Clancy track 7 into two rows.
+    t = t.replace(APOSTROPHE_LIKE, "")
+    return t
+}
+
+/** Title identity: "Oh, Ms. Believer" and "Oh Ms. Believer" are the same song. */
+fun foldTitleToken(value: String?): String {
+    var t = foldTagToken(value)
+    t = t.replace(TITLE_DECORATIVE_PUNCT, " ")
+    return t.replace(Regex("\\s+"), " ").trim()
+}
+
+private val APOSTROPHE_LIKE = Regex(
+    "[\u0027\u0060\u00B4\u2018\u2019\u201A\u201B\u2032\u02BB\u02BC\uFF07]"
+)
+
+private val TITLE_DECORATIVE_PUNCT = Regex("[,.:;!?]")
+
+/** Banded Levenshtein; returns [max] + 1 when the titles are farther than [max]. */
+fun editDistanceAtMost(a: String, b: String, max: Int): Int {
+    if (a == b) return 0
+    if (kotlin.math.abs(a.length - b.length) > max) return max + 1
+    val m = b.length
+    var prev = IntArray(m + 1) { it }
+    var cur = IntArray(m + 1)
+    for (i in 1..a.length) {
+        cur[0] = i
+        var rowMin = i
+        val ca = a[i - 1]
+        for (j in 1..m) {
+            val cost = if (ca == b[j - 1]) 0 else 1
+            cur[j] = minOf(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)
+            if (cur[j] < rowMin) rowMin = cur[j]
+        }
+        if (rowMin > max) return max + 1
+        val tmp = prev
+        prev = cur
+        cur = tmp
+    }
+    return prev[m]
+}
+
+fun albumKey(name: String?, artist: String?): String {
+    val a = artistKey(artist) ?: foldTagToken(primaryArtistName(artist) ?: artist ?: "")
+    val n = foldTagToken(name ?: "")
+    return "$a|$n"
+}
+
+/** Folded artist key before user / MBID aliases. */
+fun rawArtistKey(name: String?): String? {
+    val primary = primaryArtistName(name) ?: name ?: return null
+    val t = foldTagToken(primary)
+    return t.takeIf { it.isNotEmpty() }
+}
+
+fun artistKey(name: String?): String? {
+    val raw = rawArtistKey(name) ?: return null
+    return ArtistAliasResolver.resolve(raw)
+}
+
+/**
+ * In-memory alias map (Nightcord → 25時、ナイトコードで。).
+ * CatalogRepository loads Room rows into this at start / after merge.
+ */
+object ArtistAliasResolver {
+    @Volatile
+    private var map: Map<String, String> = emptyMap()
+
+    @Volatile
+    private var reverse: Map<String, List<String>> = emptyMap()
+
+    fun replace(aliases: Map<String, String>) {
+        map = aliases
+        reverse = aliases.entries.groupBy({ it.value }, { it.key })
+    }
+
+    fun resolve(key: String): String {
+        if (map.isEmpty()) return key
+        var cur = key
+        val seen = HashSet<String>(4)
+        while (true) {
+            val next = map[cur] ?: return cur
+            if (next == cur || !seen.add(cur)) return next
+            cur = next
+        }
+    }
+
+    fun isAlias(key: String): Boolean = map.containsKey(key)
+
+    fun aliasKeysOf(canonicalKey: String): List<String> = reverse[canonicalKey].orEmpty()
+
+    /** Canonical key plus every alias that redirects here. */
+    fun identityKeys(key: String): List<String> {
+        val canonical = resolve(key)
+        val aliases = aliasKeysOf(canonical)
+        if (aliases.isEmpty()) return listOf(canonical)
+        return buildList(aliases.size + 1) {
+            add(canonical)
+            addAll(aliases)
+        }
+    }
+}
+
+/**
+ * Cross-source track identity.
+ *
+ * Titles match with or without `(feat. …)` / `ft.` / `featuring …`.
+ * Track artist may differ so long as album + album artist line up.
+ */
+object TrackIdentity {
+    private val FEAT_IN_PARENS = Regex(
+        """(?i)[\(\[\{]\s*(feat\.?|ft\.?|featuring)\s+[^\)\]\}]+[\)\]\}]"""
+    )
+    private val FEAT_SUFFIX = Regex(
+        """(?i)\s+(feat\.?|ft\.?|featuring)\s+.+$"""
+    )
+
+    fun normalizeTitle(raw: String?): String =
+        raw.orEmpty()
+            .replace(FEAT_IN_PARENS, " ")
+            .replace(FEAT_SUFFIX, " ")
+            .replace(Regex("\\s+"), " ")
+            .trim()
+
+    /** Folded token for name/album/artist comparisons. */
+    fun normalizeToken(raw: String?): String = foldTagToken(raw)
+
+    fun of(song: Song): String {
+        val t = foldTitleToken(normalizeTitle(song.title))
+        val al = foldTagToken(song.album ?: "")
+        val aa = foldTagToken(song.effectiveAlbumArtist ?: "")
+        return "k:$t|$aa|$al"
+    }
+
+    fun titlesMatch(a: String?, b: String?): Boolean =
+        foldTitleToken(normalizeTitle(a)) == foldTitleToken(normalizeTitle(b))
+
+    fun titlesNearlyMatch(a: String?, b: String?, minLen: Int = 6): Boolean {
+        val ta = normalizeTitle(a)
+        val tb = normalizeTitle(b)
+        if (ta.isEmpty() || tb.isEmpty()) return false
+        if (ta.length < minLen && tb.length < minLen) return ta.equals(tb, true)
+        val ftA = foldTitleToken(ta)
+        val ftB = foldTitleToken(tb)
+        if (ftA == ftB) return true
+        return editDistanceAtMost(ftA, ftB, 2) <= 2
+    }
+
+    fun albumsMatch(a: String?, b: String?): Boolean =
+        foldTagToken(a) == foldTagToken(b)
+
+    fun albumsNearlyMatch(a: String?, b: String?, max: Int = 2): Boolean {
+        val fa = foldTagToken(a)
+        val fb = foldTagToken(b)
+        if (fa.isEmpty() || fb.isEmpty()) return false
+        if (fa == fb) return true
+        return editDistanceAtMost(fa, fb, max) <= max
+    }
+
+    /**
+     * Loose album-artist comparison: ignores `feat.` credits and ordering of
+     * multiple (comma/slash/ampersand-separated) artists.
+     *
+     * Whole-name only — never substring — so "Rav" does NOT match
+     * "Ravenna Golden".
+     */
+    fun albumArtistsMatch(a: String?, b: String?): Boolean {
+        if (a.isNullOrBlank() || b.isNullOrBlank()) return false
+        val na = primaryArtistNames(a)
+        val nb = primaryArtistNames(b)
+        return na.isNotEmpty() && nb.isNotEmpty() && na.intersect(nb).isNotEmpty()
+    }
+
+    /**
+     * Folded set of PRIMARY artist names in a tag blob, splitting on the same
+     * separators [parseArtistCreditList] understands (comma/slash/ampersand,
+     * `feat.`), but without featured credits.
+     */
+    private fun primaryArtistNames(raw: String): Set<String> =
+        parseArtistCreditList(raw)
+            .filter { it.role == ArtistRole.PRIMARY }
+            .mapNotNull { foldTagToken(it.name).takeIf { n -> n.isNotEmpty() } }
+            .toSet()
+
+    fun matches(a: Song, b: Song): Boolean =
+        titlesNearlyMatch(a.title, b.title) &&
+            (albumsMatch(a.album, b.album) ||
+                albumsNearlyMatch(a.album, b.album) ||
+                a.album.isNullOrBlank() ||
+                b.album.isNullOrBlank())
+
+    private fun titleDetailScore(t: String?): Int {
+        if (t.isNullOrBlank()) return -1
+        var score = t.trim().length
+        if (FEAT_IN_PARENS.containsMatchIn(t) || FEAT_SUFFIX.containsMatchIn(t)) {
+            score += 100
+        } else {
+            val lower = t.lowercase()
+            if (lower.contains("feat.") || lower.contains("ft.") || lower.contains("featuring")) {
+                score += 80
+            }
+        }
+        return score
+    }
+
+    fun artistDetailScore(artist: String?): Int {
+        if (artist.isNullOrBlank()) return -1
+        val a = artist.trim()
+        var score = a.length
+        val lower = a.lowercase()
+        if (lower.contains("feat") || lower.contains("ft.")) score += 40
+        if (a.contains(',') || a.contains('&') || a.contains(';')) score += 20
+        return score
+    }
+
+    fun withRichestDisplay(playback: Song, candidates: List<Song>): Song {
+        if (candidates.isEmpty()) return playback
+        val all = candidates + playback
+        val bestTitle = all.mapNotNull { it.title?.takeIf { t -> t.isNotBlank() } }
+            .maxByOrNull { titleDetailScore(it) }
+        val bestArtist = all.mapNotNull { it.artist?.takeIf { t -> t.isNotBlank() } }
+            .maxByOrNull { artistDetailScore(it) }
+        val bestAlbumArtist = all.mapNotNull { it.albumArtist?.takeIf { t -> t.isNotBlank() } }
+            .maxByOrNull { artistDetailScore(it) }
+        val bestAlbum = all.mapNotNull { it.album?.takeIf { t -> t.isNotBlank() } }
+            .maxByOrNull { it.length }
+        val anyExplicit = all.any { it.explicit || it.isExplicit }
+
+        return playback.copy(
+            title = when {
+                bestTitle != null && titleDetailScore(bestTitle) > titleDetailScore(playback.title) ->
+                    bestTitle
+                else -> playback.title
+            },
+            artist = when {
+                bestArtist != null && artistDetailScore(bestArtist) > artistDetailScore(playback.artist) ->
+                    bestArtist
+                else -> playback.artist
+            },
+            albumArtist = when {
+                bestAlbumArtist != null &&
+                    artistDetailScore(bestAlbumArtist) > artistDetailScore(playback.albumArtist) ->
+                    bestAlbumArtist
+                else -> playback.albumArtist
+            },
+            album = when {
+                bestAlbum != null &&
+                    (playback.album.isNullOrBlank() || bestAlbum.length > playback.album.length) ->
+                    bestAlbum
+                else -> playback.album
+            },
+            explicit = playback.explicit || anyExplicit
+        )
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/CatalogDao.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/CatalogDao.kt
new file mode 100644
index 00000000..85420844
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/CatalogDao.kt
@@ -0,0 +1,439 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.Dao
+import androidx.room.Insert
+import androidx.room.OnConflictStrategy
+import androidx.room.Query
+import androidx.room.Transaction
+import kotlinx.coroutines.flow.Flow
+
+/** Light album rollup row produced entirely in SQLite (no full-track load). */
+data class AlbumAggregateRow(
+    val albumKey: String,
+    val name: String?,
+    val artist: String?,
+    val year: Int?,
+    val trackCount: Int,
+    val coverUrl: String?,
+    val primarySourceType: String
+)
+
+/** Light artist rollup row produced entirely in SQLite. */
+data class ArtistAggregateRow(
+    val artistKey: String,
+    val displayName: String,
+    val trackCount: Int,
+    val albumCount: Int
+)
+
+/**
+ * Persistent catalog = local library + remote-indexed tracks (Jellyfin / Subsonic).
+ * Search and key lookups must stay SQL — never load the full table onto Main.
+ */
+@Dao
+interface CatalogDao {
+
+    @Query("SELECT * FROM catalog_tracks ORDER BY title COLLATE NOCASE")
+    fun observeTracks(): Flow<List<CatalogTrackEntity>>
+
+    @Query("SELECT * FROM catalog_tracks ORDER BY title COLLATE NOCASE")
+    suspend fun getAllTracks(): List<CatalogTrackEntity>
+
+    @Query("SELECT * FROM catalog_tracks WHERE sourceType = :sourceType")
+    suspend fun getTracksBySource(sourceType: String): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT * FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "ORDER BY album COLLATE NOCASE, discNumber, trackNumber, title COLLATE NOCASE"
+    )
+    suspend fun getTracksForSourceInstance(
+        sourceType: String,
+        sourceInstanceId: Long?
+    ): List<CatalogTrackEntity>
+
+    @Query("SELECT * FROM catalog_tracks WHERE sourceType = :sourceType LIMIT :limit")
+    suspend fun getTracksBySourceLimited(sourceType: String, limit: Int): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT COUNT(*) FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL))"
+    )
+    suspend fun countTracksForSource(sourceType: String, sourceInstanceId: Long?): Int
+
+    @Query(
+        "SELECT externalId FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND externalId IS NOT NULL"
+    )
+    suspend fun externalIdsForSource(sourceType: String, sourceInstanceId: Long?): List<String>
+
+    @Query(
+        "SELECT * FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND externalId IN (:ids)"
+    )
+    suspend fun tracksByExternalIds(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        ids: List<String>
+    ): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT songKey FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND externalId IN (:ids)"
+    )
+    suspend fun songKeysForExternalIds(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        ids: List<String>
+    ): List<String>
+
+    @Query(
+        "UPDATE catalog_tracks SET lastSeenAtMs = :seenAt WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND externalId IN (:ids)"
+    )
+    suspend fun touchLastSeenByExternalIds(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        ids: List<String>,
+        seenAt: Long
+    ): Int
+
+    @Query("DELETE FROM catalog_tracks WHERE songKey IN (:keys)")
+    suspend fun deleteTracksByKeys(keys: List<String>): Int
+
+    @Query("DELETE FROM catalog_credits WHERE subjectType = 'TRACK' AND subjectKey IN (:keys)")
+    suspend fun deleteCreditsForTracks(keys: List<String>)
+
+    @Query("SELECT COUNT(*) FROM catalog_tracks WHERE sourceType != :localType")
+    suspend fun countNonLocalTracks(localType: String = CatalogSources.LOCAL): Int
+
+    @Query("SELECT * FROM catalog_tracks WHERE songKey = :songKey LIMIT 1")
+    suspend fun getTrack(songKey: String): CatalogTrackEntity?
+
+    @Query("SELECT * FROM catalog_tracks WHERE songKey IN (:keys)")
+    suspend fun getTracksByKeys(keys: List<String>): List<CatalogTrackEntity>
+
+    @Query(
+        """
+        SELECT * FROM catalog_tracks
+        WHERE IFNULL(title, '') = :title COLLATE NOCASE
+          AND IFNULL(COALESCE(albumArtist, artist), '') = :artist COLLATE NOCASE
+          AND IFNULL(album, '') = :album COLLATE NOCASE
+        LIMIT :limit
+        """
+    )
+    suspend fun findTracksMatching(
+        title: String,
+        artist: String,
+        album: String,
+        limit: Int = 12
+    ): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT * FROM catalog_tracks WHERE " +
+            "title LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR artist LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR albumArtist LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR album LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "LIMIT :limit"
+    )
+    suspend fun searchTracks(q: String, limit: Int): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT * FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND (title LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR artist LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR albumArtist LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR album LIKE '%' || :q || '%' COLLATE NOCASE) " +
+            "LIMIT :limit"
+    )
+    suspend fun searchTracksForSource(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        q: String,
+        limit: Int
+    ): List<CatalogTrackEntity>
+
+    @Query("SELECT * FROM catalog_tracks WHERE albumKey = :albumKey ORDER BY discNumber, trackNumber, title")
+    suspend fun getTracksForAlbum(albumKey: String): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT * FROM catalog_tracks WHERE album = :album COLLATE NOCASE " +
+            "ORDER BY discNumber, trackNumber, title LIMIT :limit"
+    )
+    suspend fun getTracksByAlbumName(album: String, limit: Int = 500): List<CatalogTrackEntity>
+
+    @Query(
+        """
+        SELECT * FROM catalog_tracks
+        WHERE album = :album COLLATE NOCASE
+          AND (
+            :artist = ''
+            OR IFNULL(albumArtist, '') = :artist COLLATE NOCASE
+            OR IFNULL(artist, '') = :artist COLLATE NOCASE
+            OR IFNULL(albumArtist, '') LIKE '%' || :artist || '%' COLLATE NOCASE
+            OR IFNULL(artist, '') LIKE '%' || :artist || '%' COLLATE NOCASE
+          )
+        ORDER BY discNumber, trackNumber, title
+        LIMIT :limit
+        """
+    )
+    suspend fun getTracksForAlbumNameArtist(
+        album: String,
+        artist: String,
+        limit: Int = 1000
+    ): List<CatalogTrackEntity>
+
+    @Query(
+        "SELECT DISTINCT albumKey FROM catalog_tracks " +
+            "WHERE album = :album COLLATE NOCASE AND albumKey IS NOT NULL AND albumKey != ''"
+    )
+    suspend fun albumKeysForAlbumName(album: String): List<String>
+
+    @Query(
+        "SELECT * FROM catalog_tracks WHERE albumKey = :albumKey " +
+            "ORDER BY CASE WHEN sourceType = 'LOCAL' THEN 0 ELSE 1 END, " +
+            "CASE WHEN albumArtUri IS NOT NULL AND albumArtUri != '' THEN 0 ELSE 1 END, " +
+            "discNumber, trackNumber LIMIT 1"
+    )
+    suspend fun getOneTrackForAlbum(albumKey: String): CatalogTrackEntity?
+
+    @Query(
+        """
+        SELECT * FROM catalog_tracks WHERE rowid IN (
+            SELECT MIN(rowid) FROM catalog_tracks
+            WHERE albumKey IN (:albumKeys)
+            GROUP BY albumKey
+        )
+        """
+    )
+    suspend fun oneTrackPerAlbum(albumKeys: List<String>): List<CatalogTrackEntity>
+
+    @Query("SELECT * FROM catalog_tracks WHERE artistKey IN (:keys) ORDER BY album, trackNumber, title")
+    suspend fun getTracksForArtists(keys: List<String>): List<CatalogTrackEntity>
+
+    @Query("SELECT * FROM catalog_tracks WHERE artistKey = :artistKey ORDER BY album, trackNumber, title")
+    suspend fun getTracksForArtist(artistKey: String): List<CatalogTrackEntity>
+
+    @Query(
+        """
+        SELECT t.* FROM catalog_tracks t
+        INNER JOIN catalog_credits c
+          ON c.subjectType = 'TRACK' AND c.subjectKey = t.songKey
+        WHERE c.artistKey IN (:keys) AND c.role = :role
+        ORDER BY t.album, t.trackNumber, t.title
+        """
+    )
+    suspend fun getTracksByCreditRoles(keys: List<String>, role: String): List<CatalogTrackEntity>
+
+    @Query(
+        """
+        SELECT t.* FROM catalog_tracks t
+        INNER JOIN catalog_credits c
+          ON c.subjectType = 'TRACK' AND c.subjectKey = t.songKey
+        WHERE c.artistKey = :artistKey AND c.role = :role
+        ORDER BY t.album, t.trackNumber, t.title
+        """
+    )
+    suspend fun getTracksByCreditRole(artistKey: String, role: String): List<CatalogTrackEntity>
+
+    @Query(
+        """
+        SELECT * FROM catalog_tracks
+        WHERE IFNULL(artist, '') LIKE '%' || :name || '%' COLLATE NOCASE
+           OR IFNULL(albumArtist, '') LIKE '%' || :name || '%' COLLATE NOCASE
+           OR IFNULL(title, '') LIKE '%' || :name || '%' COLLATE NOCASE
+           OR IFNULL(album, '') LIKE '%' || :name || '%' COLLATE NOCASE
+        LIMIT :limit
+        """
+    )
+    suspend fun getTracksMentioning(name: String, limit: Int = 8000): List<CatalogTrackEntity>
+
+    @Query("DELETE FROM catalog_credits")
+    suspend fun deleteAllCredits()
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertTracks(tracks: List<CatalogTrackEntity>)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertTrack(track: CatalogTrackEntity): Long
+
+    @Query(
+        "DELETE FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND lastSeenAtMs < :beforeMs"
+    )
+    suspend fun pruneStaleTracks(sourceType: String, sourceInstanceId: Long?, beforeMs: Long): Int
+
+    @Query(
+        "DELETE FROM catalog_tracks WHERE sourceType = :sourceType " +
+            "AND (sourceInstanceId IS :sourceInstanceId OR (sourceInstanceId IS NULL AND :sourceInstanceId IS NULL)) " +
+            "AND lastSeenAtMs < :beforeMs " +
+            "AND songKey NOT IN (:keepKeys)"
+    )
+    suspend fun pruneStaleTracksExcept(
+        sourceType: String,
+        sourceInstanceId: Long?,
+        beforeMs: Long,
+        keepKeys: List<String>
+    ): Int
+
+    @Query("DELETE FROM catalog_tracks WHERE songKey = :songKey")
+    suspend fun deleteTrack(songKey: String)
+
+    @Query(
+        """
+        SELECT albumKey AS albumKey,
+               MAX(album) AS name,
+               MAX(COALESCE(albumArtist, artist)) AS artist,
+               MAX(year) AS year,
+               COUNT(DISTINCT lower(IFNULL(title, '')) || '|' ||
+                     IFNULL(CAST(trackNumber AS TEXT), '') || '|' ||
+                     IFNULL(CAST(discNumber AS TEXT), '1')) AS trackCount,
+               MAX(CASE WHEN albumArtUri LIKE 'http%' THEN albumArtUri ELSE NULL END) AS coverUrl,
+               MIN(sourceType) AS primarySourceType
+        FROM catalog_tracks
+        WHERE albumKey IS NOT NULL AND albumKey != ''
+        GROUP BY albumKey
+        """
+    )
+    suspend fun aggregateAlbums(): List<AlbumAggregateRow>
+
+    @Query(
+        """
+        SELECT artistKey AS artistKey,
+               MAX(COALESCE(albumArtist, artist, artistKey)) AS displayName,
+               COUNT(DISTINCT lower(IFNULL(title, '')) || '|' ||
+                     IFNULL(CAST(trackNumber AS TEXT), '') || '|' ||
+                     lower(IFNULL(album, ''))) AS trackCount,
+               COUNT(DISTINCT albumKey) AS albumCount
+        FROM catalog_tracks
+        WHERE artistKey IS NOT NULL AND artistKey != ''
+        GROUP BY artistKey
+        """
+    )
+    suspend fun aggregateArtists(): List<ArtistAggregateRow>
+
+    @Query("SELECT * FROM catalog_albums ORDER BY artist COLLATE NOCASE, name COLLATE NOCASE")
+    fun observeAlbums(): Flow<List<CatalogAlbumEntity>>
+
+    @Query("SELECT * FROM catalog_albums ORDER BY artist COLLATE NOCASE, name COLLATE NOCASE")
+    suspend fun getAllAlbums(): List<CatalogAlbumEntity>
+
+    @Query("SELECT * FROM catalog_albums WHERE albumKey = :albumKey LIMIT 1")
+    suspend fun getAlbum(albumKey: String): CatalogAlbumEntity?
+
+    @Query("SELECT * FROM catalog_albums WHERE artistKey IN (:keys) ORDER BY year DESC, name COLLATE NOCASE")
+    suspend fun getAlbumsForArtists(keys: List<String>): List<CatalogAlbumEntity>
+
+    @Query("SELECT * FROM catalog_albums WHERE artistKey = :artistKey ORDER BY year DESC, name COLLATE NOCASE")
+    suspend fun getAlbumsForArtist(artistKey: String): List<CatalogAlbumEntity>
+
+    @Query(
+        "SELECT * FROM catalog_albums WHERE " +
+            "name LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "OR artist LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "LIMIT :limit"
+    )
+    suspend fun searchAlbums(q: String, limit: Int): List<CatalogAlbumEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertAlbum(album: CatalogAlbumEntity)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertAlbums(albums: List<CatalogAlbumEntity>)
+
+    @Query("DELETE FROM catalog_albums WHERE albumKey = :albumKey")
+    suspend fun deleteAlbum(albumKey: String)
+
+    @Query("SELECT * FROM catalog_artists ORDER BY displayName COLLATE NOCASE")
+    fun observeArtists(): Flow<List<CatalogArtistEntity>>
+
+    @Query("SELECT * FROM catalog_artists ORDER BY displayName COLLATE NOCASE")
+    suspend fun getAllArtists(): List<CatalogArtistEntity>
+
+    @Query("SELECT * FROM catalog_artists WHERE artistKey = :artistKey LIMIT 1")
+    suspend fun getArtist(artistKey: String): CatalogArtistEntity?
+
+    @Query(
+        "SELECT * FROM catalog_artists WHERE " +
+            "displayName LIKE '%' || :q || '%' COLLATE NOCASE " +
+            "LIMIT :limit"
+    )
+    suspend fun searchArtists(q: String, limit: Int): List<CatalogArtistEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertArtist(artist: CatalogArtistEntity)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertArtists(artists: List<CatalogArtistEntity>)
+
+    @Query("DELETE FROM catalog_artists WHERE artistKey = :artistKey")
+    suspend fun deleteArtist(artistKey: String)
+
+    @Transaction
+    suspend fun replaceLocalCatalog(tracks: List<CatalogTrackEntity>) {
+        deleteTracksByKeys(tracks.map { it.songKey })
+        upsertTracks(tracks)
+    }
+
+    @Query(
+        "DELETE FROM catalog_albums WHERE albumKey NOT IN " +
+            "(SELECT DISTINCT albumKey FROM catalog_tracks WHERE albumKey IS NOT NULL)"
+    )
+    suspend fun deleteOrphanAlbums()
+
+    @Query(
+        "DELETE FROM catalog_artists WHERE artistKey NOT IN " +
+            "(SELECT DISTINCT artistKey FROM catalog_tracks WHERE artistKey IS NOT NULL " +
+            "UNION SELECT DISTINCT artistKey FROM catalog_credits WHERE artistKey IS NOT NULL)"
+    )
+    suspend fun deleteOrphanArtists()
+
+    @Query("DELETE FROM catalog_credits WHERE subjectType = :subjectType AND subjectKey = :subjectKey")
+    suspend fun deleteCredits(subjectType: String, subjectKey: String)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertCredits(credits: List<CatalogCreditEntity>)
+
+    @Query("SELECT * FROM catalog_credits WHERE subjectType = :subjectType AND subjectKey = :subjectKey ORDER BY position")
+    suspend fun creditsFor(subjectType: String, subjectKey: String): List<CatalogCreditEntity>
+
+    @Query("SELECT * FROM artist_aliases")
+    suspend fun getAllAliases(): List<ArtistAliasEntity>
+
+    @Query("SELECT * FROM artist_aliases WHERE canonicalKey = :canonicalKey ORDER BY aliasName COLLATE NOCASE")
+    suspend fun aliasesForCanonical(canonicalKey: String): List<ArtistAliasEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertAlias(alias: ArtistAliasEntity)
+
+    @Query("DELETE FROM artist_aliases WHERE aliasKey = :aliasKey")
+    suspend fun deleteAlias(aliasKey: String)
+
+    @Query("DELETE FROM artist_aliases WHERE canonicalKey = :canonicalKey OR aliasKey = :canonicalKey")
+    suspend fun deleteAliasesInvolving(canonicalKey: String)
+
+    @Query("UPDATE artist_aliases SET canonicalKey = :intoKey WHERE canonicalKey = :fromKey")
+    suspend fun retargetAliases(fromKey: String, intoKey: String)
+
+    @Query("UPDATE catalog_tracks SET artistKey = :intoKey WHERE artistKey = :fromKey")
+    suspend fun retargetTrackArtistKey(fromKey: String, intoKey: String)
+
+    @Query("UPDATE catalog_credits SET artistKey = :intoKey WHERE artistKey = :fromKey")
+    suspend fun retargetCreditArtistKey(fromKey: String, intoKey: String)
+
+    @Query("UPDATE catalog_albums SET artistKey = :intoKey WHERE artistKey = :fromKey")
+    suspend fun retargetAlbumArtistKey(fromKey: String, intoKey: String)
+
+    @Query(
+        "SELECT * FROM catalog_artists WHERE mbid IS NOT NULL AND mbid != '' " +
+            "ORDER BY mbid, trackCount DESC"
+    )
+    suspend fun artistsWithMbid(): List<CatalogArtistEntity>
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/CatalogEntities.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/CatalogEntities.kt
new file mode 100644
index 00000000..78e8d20e
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/CatalogEntities.kt
@@ -0,0 +1,173 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.Entity
+import androidx.room.Index
+import androidx.room.PrimaryKey
+
+/**
+ * Built-in source type strings. Remote instances also live in [SourceInstanceEntity];
+ * local files use [SOURCE_TYPE_LOCAL] with [sourceInstanceId] = null.
+ */
+object CatalogSources {
+    const val LOCAL = "LOCAL"
+    const val JELLYFIN = "JELLYFIN"
+    const val SUBSONIC = "SUBSONIC"
+    /** Legacy alias — treat as [SUBSONIC] protocol. */
+    const val NAVIDROME = "NAVIDROME"
+    const val WEBDAV = "WEBDAV"
+    const val MUSICBRAINZ = "MUSICBRAINZ" // enrichment-only, not a playable source
+}
+
+/**
+ * One playable track from one source.
+ *
+ * Explore unions rows across sources; playback picks a row (local preferred
+ * unless a [SourceOverrideEntity] says otherwise). My Stuff / playlists
+ * reference [songKey].
+ */
+@Entity(
+    tableName = "catalog_tracks",
+    indices = [
+        Index(value = ["songKey"], unique = true),
+        Index(value = ["sourceType", "sourceInstanceId"]),
+        Index(value = ["sourceType", "sourceInstanceId", "externalId"]),
+        Index(value = ["albumKey"]),
+        Index(value = ["artistKey"]),
+        Index(value = ["title"]),
+        Index(value = ["lastSeenAtMs"])
+    ]
+)
+data class CatalogTrackEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    /** Stable identity: lowercase path, or content URI, or "source:externalId". */
+    val songKey: String,
+    /** LOCAL | JELLYFIN | SUBSONIC | … */
+    val sourceType: String,
+    /** FK-ish to source_instances.id; null for built-in local scanner. */
+    val sourceInstanceId: Long? = null,
+    /** Remote library id when source is not local. */
+    val externalId: String? = null,
+
+    val title: String? = null,
+    val artist: String? = null,
+    val albumArtist: String? = null,
+    val album: String? = null,
+    val year: Int? = null,
+    val trackNumber: Int? = null,
+    val discNumber: Int? = null,
+    val durationMs: Long? = null,
+
+    /** Normalized keys for joining albums / artists in Explore. */
+    val albumKey: String? = null,
+    val artistKey: String? = null,
+
+    val contentUri: String,
+    val path: String? = null,
+    val albumArtUri: String? = null,
+    val mimeType: String? = null,
+
+    val isTagged: Boolean = false,
+    val updatedAtMs: Long = System.currentTimeMillis(),
+    /** Bumped each successful sync; rows not seen can be pruned for that source. */
+    val lastSeenAtMs: Long = System.currentTimeMillis()
+)
+
+/**
+ * Normalized album identity shared across sources.
+ * Tracks point here via [CatalogTrackEntity.albumKey].
+ * Year / cover may be filled by MusicBrainz enrichment or a remote library.
+ */
+@Entity(
+    tableName = "catalog_albums",
+    indices = [
+        Index(value = ["albumKey"], unique = true),
+        Index(value = ["artistKey"]),
+        Index(value = ["year"])
+    ]
+)
+data class CatalogAlbumEntity(
+    @PrimaryKey val albumKey: String,
+    val name: String? = null,
+    val artist: String? = null,
+    val artistKey: String? = null,
+    val year: Int? = null,
+    val trackCount: Int = 0,
+    val releaseType: String? = null, // SINGLE | EP | ALBUM | …
+    val mbid: String? = null,
+    val coverPath: String? = null,
+    val coverUrl: String? = null,
+    /** Which source last contributed structural fields (name/artist/count). */
+    val primarySourceType: String = CatalogSources.LOCAL,
+    val updatedAtMs: Long = System.currentTimeMillis()
+)
+
+/**
+ * Normalized artist identity (one Explore page per name).
+ * Profile fields may come from local tags, MusicBrainz, Jellyfin, etc.
+ */
+@Entity(
+    tableName = "catalog_artists",
+    indices = [Index(value = ["artistKey"], unique = true)]
+)
+data class CatalogArtistEntity(
+    @PrimaryKey val artistKey: String,
+    val displayName: String,
+    val trackCount: Int = 0,
+    val albumCount: Int = 0,
+    val bio: String? = null,
+    val imageUri: String? = null,
+    val websiteUrl: String? = null,
+    val linksJson: String? = null,
+    val mbid: String? = null,
+    val updatedAtMs: Long = System.currentTimeMillis()
+)
+
+/**
+ * Redirects one folded artistKey to another. User merges (Nightcord → 25時)
+ * and MusicBrainz-id collapses both write rows here.
+ */
+@Entity(
+    tableName = "artist_aliases",
+    indices = [Index(value = ["canonicalKey"])]
+)
+data class ArtistAliasEntity(
+    @PrimaryKey val aliasKey: String,
+    val canonicalKey: String,
+    val aliasName: String,
+    val source: String = SOURCE_USER,
+    val createdAtMs: Long = System.currentTimeMillis()
+) {
+    companion object {
+        const val SOURCE_USER = "USER"
+        const val SOURCE_MBID = "MBID"
+    }
+}
+
+enum class CreditSubject {
+    TRACK,
+    ALBUM
+}
+
+/**
+ * Primary vs featured credits for a track or album.
+ * Album cards / explore show [ArtistRole.PRIMARY] only.
+ */
+@Entity(
+    tableName = "catalog_credits",
+    indices = [
+        Index(value = ["subjectType", "subjectKey"]),
+        Index(value = ["artistKey"])
+    ]
+)
+data class CatalogCreditEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    /** TRACK | ALBUM */
+    val subjectType: String,
+    /** songKey or albumKey */
+    val subjectKey: String,
+    val artistKey: String,
+    val displayName: String,
+    /** PRIMARY | FEATURED */
+    val role: String,
+    val position: Int = 0
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/Daos.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/Daos.kt
new file mode 100644
index 00000000..2c5b497b
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/Daos.kt
@@ -0,0 +1,221 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.Dao
+import androidx.room.Insert
+import androidx.room.OnConflictStrategy
+import androidx.room.Query
+import androidx.room.Transaction
+import androidx.room.Update
+import kotlinx.coroutines.flow.Flow
+
+@Dao
+interface AlbumPrefsDao {
+    @Query("SELECT * FROM album_prefs WHERE albumKey = :key LIMIT 1")
+    suspend fun get(key: String): AlbumPrefsEntity?
+
+    @Query("SELECT * FROM album_prefs WHERE albumKey = :key LIMIT 1")
+    fun observe(key: String): Flow<AlbumPrefsEntity?>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: AlbumPrefsEntity): Long
+
+    @Query("SELECT * FROM album_prefs WHERE pinnedToMyStuff = 1")
+    fun observePinned(): Flow<List<AlbumPrefsEntity>>
+}
+
+@Dao
+interface AlbumMetadataDao {
+    @Query("SELECT * FROM album_metadata WHERE albumKey = :key LIMIT 1")
+    suspend fun get(key: String): AlbumMetadataEntity?
+
+    @Query("SELECT * FROM album_metadata WHERE albumKey = :key LIMIT 1")
+    fun observe(key: String): Flow<AlbumMetadataEntity?>
+
+    @Query("SELECT * FROM album_metadata")
+    suspend fun getAll(): List<AlbumMetadataEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: AlbumMetadataEntity): Long
+
+    @Query("DELETE FROM album_metadata WHERE albumKey = :key")
+    suspend fun delete(key: String)
+}
+
+@Dao
+interface PlaylistPrefsDao {
+    @Query("SELECT * FROM playlist_prefs WHERE playlistId = :id LIMIT 1")
+    suspend fun get(id: String): PlaylistPrefsEntity?
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: PlaylistPrefsEntity): Long
+}
+
+/** Row from GROUP BY count query. */
+data class PlaylistTrackCount(
+    val playlistId: String,
+    val trackCount: Int
+)
+
+@Dao
+interface PlaylistDao {
+    @Query("SELECT * FROM playlists ORDER BY updatedAtMs DESC")
+    fun observeAll(): Flow<List<PlaylistEntity>>
+
+    @Query("SELECT * FROM playlists WHERE id = :id LIMIT 1")
+    fun observe(id: String): Flow<PlaylistEntity?>
+
+    @Query("SELECT * FROM playlists WHERE id = :id LIMIT 1")
+    suspend fun get(id: String): PlaylistEntity?
+
+    @Query("SELECT * FROM playlists")
+    suspend fun getAll(): List<PlaylistEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: PlaylistEntity)
+
+    @Query("DELETE FROM playlists WHERE id = :id")
+    suspend fun delete(id: String)
+
+    @Query("SELECT * FROM playlist_tracks WHERE playlistId = :playlistId ORDER BY position ASC")
+    fun observeTracks(playlistId: String): Flow<List<PlaylistTrackEntity>>
+
+    @Query("SELECT * FROM playlist_tracks WHERE playlistId = :playlistId ORDER BY position ASC")
+    suspend fun getTracks(playlistId: String): List<PlaylistTrackEntity>
+
+    @Query("SELECT playlistId, COUNT(*) AS trackCount FROM playlist_tracks GROUP BY playlistId")
+    fun observeTrackCounts(): Flow<List<PlaylistTrackCount>>
+
+    @Query("SELECT * FROM playlist_tracks")
+    fun observeAllTracks(): Flow<List<PlaylistTrackEntity>>
+
+    @Query("SELECT playlistId FROM playlist_tracks WHERE songKey = :songKey")
+    suspend fun playlistIdsContaining(songKey: String): List<String>
+
+    @Query("DELETE FROM playlist_tracks WHERE playlistId = :playlistId")
+    suspend fun clearTracks(playlistId: String)
+
+    @Query("DELETE FROM playlist_tracks WHERE playlistId = :playlistId AND songKey = :songKey")
+    suspend fun deleteTrackByKey(playlistId: String, songKey: String)
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun insertTracks(tracks: List<PlaylistTrackEntity>)
+
+    @Query("DELETE FROM playlist_tracks WHERE playlistId = :playlistId AND position = :position")
+    suspend fun deleteTrackAt(playlistId: String, position: Int)
+
+    @Transaction
+    suspend fun replaceTracks(playlistId: String, songKeys: List<String>) {
+        clearTracks(playlistId)
+        if (songKeys.isEmpty()) return
+        insertTracks(
+            songKeys.mapIndexed { index, key ->
+                PlaylistTrackEntity(playlistId = playlistId, position = index, songKey = key)
+            }
+        )
+    }
+
+    // ── multi covers ──────────────────────────────────────────────────────
+
+    @Query("SELECT * FROM playlist_covers WHERE playlistId = :playlistId ORDER BY sortOrder ASC, createdAtMs ASC")
+    fun observeCovers(playlistId: String): Flow<List<PlaylistCoverEntity>>
+
+    @Query("SELECT * FROM playlist_covers WHERE playlistId = :playlistId ORDER BY sortOrder ASC, createdAtMs ASC")
+    suspend fun getCovers(playlistId: String): List<PlaylistCoverEntity>
+
+    @Query("SELECT * FROM playlist_covers WHERE id = :coverId LIMIT 1")
+    suspend fun getCover(coverId: String): PlaylistCoverEntity?
+
+    /** Covers currently marked active that are secret (session-only art). */
+    @Query(
+        """
+        SELECT c.* FROM playlist_covers c
+        INNER JOIN playlists p ON p.activeCoverId = c.id
+        WHERE c.isSecret = 1
+        """
+    )
+    suspend fun getActiveSecretCovers(): List<PlaylistCoverEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsertCover(entity: PlaylistCoverEntity)
+
+    @Query("DELETE FROM playlist_covers WHERE id = :coverId")
+    suspend fun deleteCover(coverId: String)
+
+    @Query("DELETE FROM playlist_covers WHERE playlistId = :playlistId")
+    suspend fun clearCovers(playlistId: String)
+
+    @Query("SELECT COALESCE(MAX(sortOrder), -1) FROM playlist_covers WHERE playlistId = :playlistId")
+    suspend fun maxCoverSortOrder(playlistId: String): Int
+}
+
+@Dao
+interface ArtistProfileDao {
+    @Query("SELECT * FROM artist_profiles WHERE artistKey = :key LIMIT 1")
+    suspend fun get(key: String): ArtistProfileEntity?
+
+    @Query("SELECT * FROM artist_profiles WHERE artistKey = :key LIMIT 1")
+    fun observe(key: String): Flow<ArtistProfileEntity?>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: ArtistProfileEntity)
+
+    @Query("DELETE FROM artist_profiles WHERE artistKey = :key")
+    suspend fun delete(key: String)
+}
+
+@Dao
+interface SourceOverrideDao {
+    @Query("SELECT * FROM source_overrides WHERE scope = :scope AND scopeKey = :scopeKey LIMIT 1")
+    suspend fun get(scope: String, scopeKey: String): SourceOverrideEntity?
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: SourceOverrideEntity): Long
+
+    @Query("DELETE FROM source_overrides WHERE scope = :scope AND scopeKey = :scopeKey")
+    suspend fun delete(scope: String, scopeKey: String)
+}
+
+@Dao
+interface AppSettingsDao {
+    @Query("SELECT * FROM app_settings WHERE `key` = :key LIMIT 1")
+    suspend fun get(key: String): AppSettingEntity?
+
+    @Query("SELECT * FROM app_settings")
+    fun observeAll(): Flow<List<AppSettingEntity>>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: AppSettingEntity)
+
+    @Query("DELETE FROM app_settings WHERE `key` = :key")
+    suspend fun delete(key: String)
+}
+
+@Dao
+interface SourceInstanceDao {
+    @Query("SELECT * FROM source_instances ORDER BY sortOrder, id")
+    fun observeAll(): Flow<List<SourceInstanceEntity>>
+
+    @Query("SELECT * FROM source_instances ORDER BY sortOrder, id")
+    suspend fun getAll(): List<SourceInstanceEntity>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: SourceInstanceEntity): Long
+
+    @Update
+    suspend fun update(entity: SourceInstanceEntity)
+
+    @Query("DELETE FROM source_instances WHERE id = :id")
+    suspend fun delete(id: Long)
+}
+
+@Dao
+interface ScrobblerInstanceDao {
+    @Query("SELECT * FROM scrobbler_instances ORDER BY id")
+    fun observeAll(): Flow<List<ScrobblerInstanceEntity>>
+
+    @Insert(onConflict = OnConflictStrategy.REPLACE)
+    suspend fun upsert(entity: ScrobblerInstanceEntity): Long
+
+    @Query("DELETE FROM scrobbler_instances WHERE id = :id")
+    suspend fun delete(id: Long)
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/Entities.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/Entities.kt
new file mode 100644
index 00000000..444d8b49
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/Entities.kt
@@ -0,0 +1,156 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.Entity
+import androidx.room.Index
+import androidx.room.PrimaryKey
+
+@Entity(
+    tableName = "album_prefs",
+    indices = [Index(value = ["albumKey"], unique = true)]
+)
+data class AlbumPrefsEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val albumKey: String,
+    val shuffleDefault: Boolean = false,
+    val repeatMode: String = "ALL",
+    val pinnedToMyStuff: Boolean = false,
+    val updatedAtMs: Long = System.currentTimeMillis()
+)
+
+@Entity(
+    tableName = "album_metadata",
+    indices = [Index(value = ["albumKey"], unique = true)]
+)
+data class AlbumMetadataEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val albumKey: String,
+    val year: Int? = null,
+    val mbid: String? = null,
+    val coverPath: String? = null,
+    val coverUrl: String? = null,
+    /** JSON string array of genre names from remote enrichment. */
+    val genresJson: String? = null,
+    val source: String = "musicbrainz",
+    val updatedAtMs: Long = System.currentTimeMillis(),
+    val lookupFailed: Boolean = false
+)
+
+@Entity(
+    tableName = "playlist_prefs",
+    indices = [Index(value = ["playlistId"], unique = true)]
+)
+data class PlaylistPrefsEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val playlistId: String,
+    val shuffleDefault: Boolean = false,
+    val repeatMode: String = "ALL",
+    val pinnedToMyStuff: Boolean = false,
+    val updatedAtMs: Long = System.currentTimeMillis()
+)
+
+@Entity(tableName = "playlists")
+data class PlaylistEntity(
+    @PrimaryKey val id: String,
+    val name: String,
+    val description: String? = null,
+    /**
+     * Legacy single custom image. Prefer [activeCoverId] + [PlaylistCoverEntity]
+     * when present; this remains the fast list-thumb path and migration fallback.
+     */
+    val customImageUri: String? = null,
+    /** Active [PlaylistCoverEntity.id] for public display. */
+    val activeCoverId: String? = null,
+    val createdAtMs: Long = System.currentTimeMillis(),
+    val updatedAtMs: Long = System.currentTimeMillis()
+)
+
+/**
+ * One custom cover image for a playlist. Multiple rows per playlist are allowed.
+ * [isSecret] covers are kept out of the default active slot unless the user
+ * explicitly sets them active (handy for private / alternate art).
+ */
+@Entity(
+    tableName = "playlist_covers",
+    indices = [
+        Index(value = ["playlistId"]),
+        Index(value = ["playlistId", "sortOrder"])
+    ]
+)
+data class PlaylistCoverEntity(
+    @PrimaryKey val id: String,
+    val playlistId: String,
+    val uri: String,
+    val isSecret: Boolean = false,
+    val sortOrder: Int = 0,
+    val createdAtMs: Long = System.currentTimeMillis()
+)
+
+@Entity(
+    tableName = "playlist_tracks",
+    primaryKeys = ["playlistId", "position"],
+    indices = [
+        Index(value = ["playlistId"]),
+        Index(value = ["songKey"])
+    ]
+)
+data class PlaylistTrackEntity(
+    val playlistId: String,
+    val position: Int,
+    val songKey: String
+)
+
+@Entity(tableName = "artist_profiles")
+data class ArtistProfileEntity(
+    @PrimaryKey val artistKey: String,
+    val displayName: String,
+    val bio: String? = null,
+    val imageUri: String? = null,
+    val websiteUrl: String? = null,
+    val linksJson: String? = null,
+    val genresJson: String? = null,
+    val source: String = "local",
+    val updatedAtMs: Long = System.currentTimeMillis()
+)
+
+@Entity(
+    tableName = "source_overrides",
+    indices = [Index(value = ["scope", "scopeKey"], unique = true)]
+)
+data class SourceOverrideEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val scope: String,
+    val scopeKey: String,
+    val preferredSourceId: Long? = null,
+    val preferredSourceType: String? = null
+)
+
+@Entity(tableName = "app_settings")
+data class AppSettingEntity(
+    @PrimaryKey val key: String,
+    val value: String
+)
+
+@Entity(tableName = "source_instances")
+data class SourceInstanceEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val type: String,
+    val name: String,
+    val baseUrl: String? = null,
+    val username: String? = null,
+    val secret: String? = null,
+    val enabled: Boolean = true,
+    val sortOrder: Int = 0,
+    val extraJson: String? = null
+)
+
+@Entity(tableName = "scrobbler_instances")
+data class ScrobblerInstanceEntity(
+    @PrimaryKey(autoGenerate = true) val id: Long = 0,
+    val type: String,
+    val name: String,
+    val baseUrl: String? = null,
+    val username: String? = null,
+    val token: String? = null,
+    val enabled: Boolean = false,
+    val extraJson: String? = null
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.kt
new file mode 100644
index 00000000..4a2464ca
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.kt
@@ -0,0 +1,52 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.ConstructedBy
+import androidx.room.Database
+import androidx.room.RoomDatabase
+import androidx.room.RoomDatabaseConstructor
+
+@Database(
+    entities = [
+        AlbumPrefsEntity::class,
+        AlbumMetadataEntity::class,
+        CatalogTrackEntity::class,
+        CatalogAlbumEntity::class,
+        CatalogArtistEntity::class,
+        CatalogCreditEntity::class,
+        ArtistAliasEntity::class,
+        PlaylistPrefsEntity::class,
+        PlaylistEntity::class,
+        PlaylistCoverEntity::class,
+        PlaylistTrackEntity::class,
+        ArtistProfileEntity::class,
+        SourceOverrideEntity::class,
+        AppSettingEntity::class,
+        SourceInstanceEntity::class,
+        ScrobblerInstanceEntity::class
+    ],
+    version = 10,
+    exportSchema = false
+)
+@ConstructedBy(YuriDatabaseConstructor::class)
+abstract class YuriDatabase : RoomDatabase() {
+    abstract fun albumPrefs(): AlbumPrefsDao
+    abstract fun albumMetadata(): AlbumMetadataDao
+    abstract fun catalog(): CatalogDao
+    abstract fun playlistPrefs(): PlaylistPrefsDao
+    abstract fun playlists(): PlaylistDao
+    abstract fun artistProfiles(): ArtistProfileDao
+    abstract fun sourceOverrides(): SourceOverrideDao
+    abstract fun appSettings(): AppSettingsDao
+    abstract fun sources(): SourceInstanceDao
+    abstract fun scrobblers(): ScrobblerInstanceDao
+}
+
+/**
+ * KMP Room constructor. The [YuriDatabase] `@Database` class targets non-Android
+ * platforms (JVM/desktop) as well as Android, so Room requires this `expect`
+ * object. Room's KSP processor generates the matching `actual` (plus the
+ * `YuriDatabase_Impl` implementation) for each platform target.
+ */
+expect object YuriDatabaseConstructor : RoomDatabaseConstructor<YuriDatabase> {
+    override fun initialize(): YuriDatabase
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/YuriMigrations.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/YuriMigrations.kt
new file mode 100644
index 00000000..c3be4676
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/db/YuriMigrations.kt
@@ -0,0 +1,137 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.migration.Migration
+import androidx.sqlite.SQLiteConnection
+import androidx.sqlite.execSQL
+
+/**
+ * Additive Room migrations. Register every new Migration here and bump
+ * [YuriDatabase] version — never use fallbackToDestructiveMigration.
+ *
+ * Uses the KMP `SQLiteConnection` path so it compiles on all targets
+ * (Android + JVM/desktop) with the bundled SQLite driver.
+ */
+object YuriMigrations {
+
+    val MIGRATION_4_5 = object : Migration(4, 5) {
+        override fun migrate(connection: SQLiteConnection) = sql4to5 { connection.execSQL(it) }
+    }
+
+    val MIGRATION_5_6 = object : Migration(5, 6) {
+        override fun migrate(connection: SQLiteConnection) = sql5to6 { connection.execSQL(it) }
+    }
+
+    val MIGRATION_6_7 = object : Migration(6, 7) {
+        override fun migrate(connection: SQLiteConnection) = sql6to7 { connection.execSQL(it) }
+    }
+
+    val MIGRATION_7_8 = object : Migration(7, 8) {
+        override fun migrate(connection: SQLiteConnection) = sql7to8 { connection.execSQL(it) }
+    }
+
+    val MIGRATION_8_9 = object : Migration(8, 9) {
+        override fun migrate(connection: SQLiteConnection) = sql8to9 { connection.execSQL(it) }
+    }
+
+    val MIGRATION_9_10 = object : Migration(9, 10) {
+        override fun migrate(connection: SQLiteConnection) = sql9to10 { connection.execSQL(it) }
+    }
+
+    val ALL: Array<Migration> = arrayOf(
+        MIGRATION_4_5,
+        MIGRATION_5_6,
+        MIGRATION_6_7,
+        MIGRATION_7_8,
+        MIGRATION_8_9,
+        MIGRATION_9_10
+    )
+
+    private fun sql4to5(exec: (String) -> Unit) {
+        exec("ALTER TABLE artist_profiles ADD COLUMN genresJson TEXT")
+    }
+
+    private fun sql5to6(exec: (String) -> Unit) {
+        exec("ALTER TABLE album_metadata ADD COLUMN genresJson TEXT")
+    }
+
+    private fun sql6to7(exec: (String) -> Unit) {
+        exec(
+            """
+            CREATE TABLE IF NOT EXISTS playlist_covers (
+                id TEXT NOT NULL PRIMARY KEY,
+                playlistId TEXT NOT NULL,
+                uri TEXT NOT NULL,
+                isSecret INTEGER NOT NULL DEFAULT 0,
+                sortOrder INTEGER NOT NULL DEFAULT 0,
+                createdAtMs INTEGER NOT NULL
+            )
+            """.trimIndent()
+        )
+        exec("CREATE INDEX IF NOT EXISTS index_playlist_covers_playlistId ON playlist_covers(playlistId)")
+        exec("CREATE INDEX IF NOT EXISTS index_playlist_covers_playlistId_sortOrder ON playlist_covers(playlistId, sortOrder)")
+        exec("ALTER TABLE playlists ADD COLUMN activeCoverId TEXT")
+        exec(
+            """
+            INSERT INTO playlist_covers (id, playlistId, uri, isSecret, sortOrder, createdAtMs)
+            SELECT
+                id || '-legacy',
+                id,
+                customImageUri,
+                0,
+                0,
+                COALESCE(updatedAtMs, createdAtMs, 0)
+            FROM playlists
+            WHERE customImageUri IS NOT NULL AND length(customImageUri) > 0
+            """.trimIndent()
+        )
+        exec(
+            """
+            UPDATE playlists
+            SET activeCoverId = id || '-legacy'
+            WHERE customImageUri IS NOT NULL AND length(customImageUri) > 0
+            """.trimIndent()
+        )
+    }
+
+    private fun sql7to8(exec: (String) -> Unit) {
+        exec("ALTER TABLE catalog_artists ADD COLUMN mbid TEXT")
+        exec(
+            """
+            CREATE TABLE IF NOT EXISTS catalog_credits (
+                id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
+                subjectType TEXT NOT NULL,
+                subjectKey TEXT NOT NULL,
+                artistKey TEXT NOT NULL,
+                displayName TEXT NOT NULL,
+                role TEXT NOT NULL,
+                position INTEGER NOT NULL DEFAULT 0
+            )
+            """.trimIndent()
+        )
+        exec("CREATE INDEX IF NOT EXISTS index_catalog_credits_subjectType_subjectKey ON catalog_credits(subjectType, subjectKey)")
+        exec("CREATE INDEX IF NOT EXISTS index_catalog_credits_artistKey ON catalog_credits(artistKey)")
+    }
+
+    private fun sql8to9(exec: (String) -> Unit) {
+        exec(
+            "CREATE INDEX IF NOT EXISTS " +
+                "index_catalog_tracks_sourceType_sourceInstanceId_externalId " +
+                "ON catalog_tracks(sourceType, sourceInstanceId, externalId)"
+        )
+    }
+
+    private fun sql9to10(exec: (String) -> Unit) {
+        exec(
+            """
+            CREATE TABLE IF NOT EXISTS artist_aliases (
+                aliasKey TEXT NOT NULL PRIMARY KEY,
+                canonicalKey TEXT NOT NULL,
+                aliasName TEXT NOT NULL,
+                source TEXT NOT NULL,
+                createdAtMs INTEGER NOT NULL
+            )
+            """.trimIndent()
+        )
+        exec("CREATE INDEX IF NOT EXISTS index_artist_aliases_canonicalKey ON artist_aliases(canonicalKey)")
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt
new file mode 100644
index 00000000..89e47cfe
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/source/SourceInstanceRepository.kt
@@ -0,0 +1,72 @@
+package capital.yuri.yuriplayer.data.source
+
+import capital.yuri.yuriplayer.data.db.SourceInstanceDao
+import capital.yuri.yuriplayer.data.db.SourceInstanceEntity
+import capital.yuri.yuriplayer.core.http.normalizeBaseUrl
+import kotlinx.coroutines.flow.Flow
+
+/**
+ * Persisted remote library servers (Jellyfin, Subsonic/OpenSubsonic, …).
+ * Local scan is not a [SourceInstanceEntity] — it is always present.
+ */
+class SourceInstanceRepository(
+    private val dao: SourceInstanceDao
+) {
+    fun observeAll(): Flow<List<SourceInstanceEntity>> = dao.observeAll()
+
+    suspend fun getAll(): List<SourceInstanceEntity> = dao.getAll()
+
+    suspend fun get(id: Long): SourceInstanceEntity? =
+        dao.getAll().firstOrNull { it.id == id }
+
+    suspend fun upsert(entity: SourceInstanceEntity): Long = dao.upsert(entity)
+
+    suspend fun delete(id: Long) = dao.delete(id)
+
+    suspend fun setEnabled(id: Long, enabled: Boolean) {
+        val row = get(id) ?: return
+        dao.update(row.copy(enabled = enabled))
+    }
+
+    suspend fun addJellyfin(
+        name: String,
+        baseUrl: String,
+        username: String,
+        passwordOrToken: String
+    ): Long = upsert(
+        SourceInstanceEntity(
+            type = SourceType.JELLYFIN.name,
+            name = name.ifBlank { "Jellyfin" },
+            baseUrl = normalizeBaseUrl(baseUrl),
+            username = username,
+            secret = passwordOrToken,
+            enabled = true
+        )
+    )
+
+    suspend fun addSubsonic(
+        name: String,
+        baseUrl: String,
+        username: String,
+        password: String
+    ): Long = upsert(
+        SourceInstanceEntity(
+            type = SourceType.SUBSONIC.name,
+            name = name.ifBlank { "Subsonic" },
+            baseUrl = normalizeBaseUrl(baseUrl),
+            username = username,
+            secret = password,
+            enabled = true
+        )
+    )
+
+    companion object {
+        /**
+         * Delegates to the shared [capital.yuri.yuriplayer.core.http.normalizeBaseUrl].
+         * Fully-qualified on purpose: the unqualified name would shadow the
+         * top-level import and recurse into this companion member.
+         */
+        fun normalizeBaseUrl(raw: String): String =
+            capital.yuri.yuriplayer.core.http.normalizeBaseUrl(raw)
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/source/SourceType.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/source/SourceType.kt
new file mode 100644
index 00000000..089179f3
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/data/source/SourceType.kt
@@ -0,0 +1,39 @@
+package capital.yuri.yuriplayer.data.source
+
+import capital.yuri.yuriplayer.data.Song
+
+enum class SourceType(val rank: Int) {
+    LOCAL(0),
+    JELLYFIN(10),
+    /** OpenSubsonic / Subsonic protocol (Navidrome, Gonic, Official, …). */
+    SUBSONIC(20),
+    /** @deprecated Prefer [SUBSONIC]; kept for existing source_instances rows. */
+    NAVIDROME(20),
+    WEBDAV(30),
+    OTHER(100);
+
+    fun displayName(): String = when (this) {
+        LOCAL -> "Local"
+        JELLYFIN -> "Jellyfin"
+        SUBSONIC -> "Subsonic"
+        NAVIDROME -> "Navidrome"
+        WEBDAV -> "WebDAV"
+        OTHER -> "Other"
+    }
+
+    companion object {
+        fun from(raw: String?): SourceType =
+            entries.firstOrNull { it.name.equals(raw, ignoreCase = true) } ?: OTHER
+
+        /** True for Subsonic-protocol backends including legacy NAVIDROME rows. */
+        fun isSubsonicFamily(type: SourceType): Boolean =
+            type == SUBSONIC || type == NAVIDROME
+    }
+}
+
+data class SourceOffering(
+    val sourceType: SourceType,
+    val sourceId: Long? = null,
+    val sourceName: String,
+    val song: Song
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt
new file mode 100644
index 00000000..ed526c45
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/MusicServiceAutoPlay.kt
@@ -0,0 +1,64 @@
+package capital.yuri.yuriplayer.player
+
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.player.radio.RadioBatch
+import capital.yuri.yuriplayer.player.radio.RadioEngine
+import capital.yuri.yuriplayer.player.radio.RadioSession
+
+/**
+ * Thin adapter: [QueueManager] ↔ [RadioEngine].
+ * Exhaust path loads a full [RadioBatch] into cold queue.
+ * Restock keeps cold topped up while radio is active.
+ */
+class MusicServiceAutoPlay(
+    private val engine: RadioEngine
+) {
+    val radioEngine: RadioEngine get() = engine
+
+    fun noteSource(source: ColdSource?) {
+        engine.noteSource(source)
+    }
+
+    fun maybePick(
+        seedSong: Song?,
+        finishedSource: ColdSource?,
+        repeatMode: RepeatMode
+    ): LegacyPick? {
+        val batch: RadioBatch = engine.maybePlan(seedSong, finishedSource, repeatMode)
+            ?: return null
+        return LegacyPick(
+            songs = batch.songs,
+            source = batch.source,
+            session = batch.session,
+            upcoming = emptyList()
+        )
+    }
+
+    /**
+     * Top-up songs for the active radio session.
+     * If the engine lost its in-memory session (process restore) but the queue
+     * still has an active [queueSession], rehydrate first so restock can run.
+     */
+    fun restock(
+        currentColdSize: Int,
+        alreadyQueuedKeys: Set<String>,
+        queueSession: RadioSession? = null
+    ): List<Song> {
+        val live = queueSession?.takeIf { it.active }
+        if (live != null && engine.session?.active != true) {
+            engine.adoptSession(live)
+        }
+        return engine.restockSongs(currentColdSize, alreadyQueuedKeys)
+    }
+
+    fun currentSession(): RadioSession? = engine.session
+
+    fun stopRadio() = engine.stopRadio()
+
+    data class LegacyPick(
+        val songs: List<Song>,
+        val source: ColdSource,
+        val session: RadioSession? = null,
+        val upcoming: List<Song> = emptyList()
+    )
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueEvents.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueEvents.kt
new file mode 100644
index 00000000..b2b76430
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueEvents.kt
@@ -0,0 +1,28 @@
+package capital.yuri.yuriplayer.player
+
+import capital.yuri.yuriplayer.data.Song
+
+/**
+ * Discrete queue moments — not continuous UI state (that stays on [QueueManager.snapshot]).
+ *
+ * Collectors: auto-play, (later) scrobblers, analytics, multi-device sync.
+ */
+sealed interface QueueEvent {
+    /** Cold+hot empty, repeat off / no repopulate. Opportunity for radio / auto-play. */
+    data class Exhausted(
+        val seed: Song?,
+        val source: ColdSource?,
+        val repeatMode: RepeatMode
+    ) : QueueEvent
+
+    /** A new cold source was loaded via [QueueManager.playSource]. */
+    data class SourceChanged(
+        val source: ColdSource?,
+        val songCount: Int,
+        val startSong: Song?
+    ) : QueueEvent
+
+    data class RepeatModeChanged(val mode: RepeatMode) : QueueEvent
+
+    data class ShuffleChanged(val enabled: Boolean) : QueueEvent
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueManager.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueManager.kt
new file mode 100644
index 00000000..6dc549f9
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueManager.kt
@@ -0,0 +1,931 @@
+package capital.yuri.yuriplayer.player
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.player.radio.RadioSession
+import capital.yuri.yuriplayer.player.radio.RadioSourcePrefs
+import kotlinx.coroutines.channels.BufferOverflow
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharedFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asSharedFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlin.random.Random
+
+/**
+ * Dual-queue + optional radio session.
+ *
+ * While radio is active, [ensureRadioStock] continuously tops the cold queue:
+ *   shuffle songs → random tracks until maxRadioQueue
+ *   shuffle releases / ordered → next whole release while under max
+ * Called after advance, radio start, cold remove, and prefs apply.
+ */
+class QueueManager {
+
+    private val hotQueue = mutableListOf<Song>()
+    private var coldOriginal: List<Song> = emptyList()
+    private val coldQueue = mutableListOf<Song>()
+    private var coldSource: ColdSource? = null
+    private var lane = QueueLane.COLD
+    private var indexInLane = -1
+    private var shuffleEnabled = false
+    private var repeatMode = RepeatMode.OFF
+    private var floatingCurrent: Song? = null
+    private val playedStack = mutableListOf<Song>()
+
+    private var radioSession: RadioSession? = null
+    private var radioUpcoming: List<Song> = emptyList()
+
+    private val _snapshot = MutableStateFlow(QueueSnapshot())
+    val snapshot: StateFlow<QueueSnapshot> = _snapshot.asStateFlow()
+
+    private val _events = MutableSharedFlow<QueueEvent>(
+        extraBufferCapacity = 32,
+        onBufferOverflow = BufferOverflow.DROP_OLDEST
+    )
+    val events: SharedFlow<QueueEvent> = _events.asSharedFlow()
+
+    @Volatile
+    var autoPlayHelper: MusicServiceAutoPlay? = null
+
+    private fun emit(event: QueueEvent) {
+        _events.tryEmit(event)
+    }
+
+    fun currentSong(): Song? {
+        floatingCurrent?.let { return it }
+        return when (lane) {
+            QueueLane.HOT -> hotQueue.getOrNull(indexInLane)
+            QueueLane.COLD -> coldQueue.getOrNull(indexInLane)
+        }
+    }
+
+    fun getSnapshot(): QueueSnapshot = _snapshot.value
+    fun coldSource(): ColdSource? = coldSource
+    fun isRadioActive(): Boolean = radioSession?.active == true
+
+    fun setRadioSession(session: RadioSession?) {
+        radioSession = session
+        if (session != null) {
+            shuffleEnabled = session.prefs.shuffle
+            if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
+            // Keep engine session in sync for restock
+            autoPlayHelper?.radioEngine?.adoptSession(session)
+        }
+        publish()
+        if (session?.active == true) ensureRadioStock()
+    }
+
+    fun setRadioUpcoming(songs: List<Song>) {
+        radioUpcoming = songs
+        publish()
+    }
+
+    fun clearRadio() {
+        radioSession = null
+        radioUpcoming = emptyList()
+        autoPlayHelper?.stopRadio()
+        publish()
+    }
+
+    fun peekNext(): Song? {
+        if (repeatMode == RepeatMode.ONE) return null
+        if (floatingCurrent != null) {
+            if (hotQueue.isNotEmpty()) return hotQueue.first()
+            if (coldQueue.isNotEmpty()) return coldQueue.first()
+            if (radioUpcoming.isNotEmpty()) return radioUpcoming.first()
+            if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty()) {
+                return if (shuffleEnabled) coldOriginal.random() else coldOriginal.first()
+            }
+            return null
+        }
+        when (lane) {
+            QueueLane.HOT -> {
+                if (indexInLane in hotQueue.indices && indexInLane < hotQueue.lastIndex) {
+                    return hotQueue[indexInLane + 1]
+                }
+                if (coldQueue.isNotEmpty()) return coldQueue.first()
+                if (radioUpcoming.isNotEmpty()) return radioUpcoming.first()
+                if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty()) {
+                    return if (shuffleEnabled) coldOriginal.random() else coldOriginal.first()
+                }
+                return null
+            }
+            QueueLane.COLD -> {
+                if (hotQueue.isNotEmpty()) return hotQueue.first()
+                if (indexInLane in coldQueue.indices && indexInLane < coldQueue.lastIndex) {
+                    return coldQueue[indexInLane + 1]
+                }
+                if (radioUpcoming.isNotEmpty()) return radioUpcoming.first()
+                if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty()) {
+                    return if (shuffleEnabled) coldOriginal.random() else coldOriginal.first()
+                }
+                return null
+            }
+        }
+    }
+
+    fun peekPrevious(): Song? {
+        linearPrevious()?.let { return it }
+        return playedStack.lastOrNull()
+    }
+
+    /** Previous item still sitting in the queue (unshuffled album/playlist). */
+    private fun linearPrevious(): Song? {
+        if (shuffleEnabled || floatingCurrent != null) return null
+        return when (lane) {
+            QueueLane.HOT -> hotQueue.getOrNull(indexInLane - 1)
+            QueueLane.COLD -> coldQueue.getOrNull(indexInLane - 1)
+        }
+    }
+
+    /** Next [limit] songs after current, hot then cold then radio. */
+    fun upcoming(limit: Int = 2): List<Song> {
+        if (limit <= 0 || repeatMode == RepeatMode.ONE) return emptyList()
+        val out = ArrayList<Song>(limit)
+        fun take(song: Song?) {
+            if (song == null || out.size >= limit) return
+            if (out.any { it.songKey == song.songKey }) return
+            out += song
+        }
+        if (floatingCurrent != null) {
+            hotQueue.forEach { take(it) }
+            if (out.size >= limit) return out
+            coldQueue.forEach { take(it) }
+            if (out.size >= limit) return out
+            radioUpcoming.forEach { take(it) }
+            return out
+        }
+        when (lane) {
+            QueueLane.HOT -> {
+                if (indexInLane in hotQueue.indices) {
+                    for (i in (indexInLane + 1) until hotQueue.size) {
+                        take(hotQueue[i])
+                        if (out.size >= limit) return out
+                    }
+                }
+                coldQueue.forEach { take(it) }
+                if (out.size >= limit) return out
+                radioUpcoming.forEach { take(it) }
+            }
+            QueueLane.COLD -> {
+                hotQueue.forEach { take(it) }
+                if (out.size >= limit) return out
+                if (indexInLane in coldQueue.indices) {
+                    for (i in (indexInLane + 1) until coldQueue.size) {
+                        take(coldQueue[i])
+                        if (out.size >= limit) return out
+                    }
+                }
+                radioUpcoming.forEach { take(it) }
+            }
+        }
+        return out
+    }
+
+    private fun publish() {
+        _snapshot.value = QueueSnapshot(
+            hotQueue = hotQueue.toList(),
+            coldQueue = coldQueue.toList(),
+            coldOriginal = coldOriginal,
+            coldSource = coldSource,
+            lane = lane,
+            indexInLane = indexInLane,
+            shuffleEnabled = shuffleEnabled,
+            repeatMode = repeatMode,
+            playedStack = playedStack.toList(),
+            radioSession = radioSession,
+            radioUpcoming = radioUpcoming,
+            floatingCurrent = floatingCurrent
+        )
+    }
+
+    /** Hot-lane mutations: don't copy the (often huge) cold lists. */
+    private fun publishHot() {
+        _snapshot.value = _snapshot.value.copy(
+            hotQueue = hotQueue.toList(),
+            lane = lane,
+            indexInLane = indexInLane,
+            floatingCurrent = floatingCurrent
+        )
+    }
+
+    /** Repeat flag only — leave song lists shared. */
+    private fun publishRepeat() {
+        _snapshot.value = _snapshot.value.copy(repeatMode = repeatMode)
+    }
+
+    private fun pushPlayed(song: Song) {
+        if (playedStack.lastOrNull()?.let { sameSong(it, song) } == true) return
+        playedStack.add(song)
+        while (playedStack.size > MAX_PLAYED_STACK) {
+            playedStack.removeAt(0)
+        }
+    }
+
+    private fun detachCurrentWithoutHistory() {
+        if (floatingCurrent != null) {
+            floatingCurrent = null
+            return
+        }
+        when (lane) {
+            QueueLane.HOT -> {
+                if (indexInLane in hotQueue.indices) hotQueue.removeAt(indexInLane)
+            }
+            QueueLane.COLD -> {
+                if (indexInLane in coldQueue.indices) coldQueue.removeAt(indexInLane)
+            }
+        }
+        indexInLane = -1
+    }
+
+    private fun tryAutoPlayRescue(seed: Song?, source: ColdSource?): AdvanceResult? {
+        val helper = autoPlayHelper ?: return null
+        val pick = helper.maybePick(seed, source, repeatMode) ?: return null
+        val songs = pick.songs
+        if (songs.isEmpty()) return null
+        log.i { "radio/auto-play rescue → ${songs.size} tracks (${pick.source.title})" }
+        if (pick.session != null) {
+            radioSession = pick.session
+            shuffleEnabled = pick.session.prefs.shuffle
+            if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
+        }
+        radioUpcoming = pick.upcoming
+        playSource(songs, startIndex = 0, source = pick.source, keepRadio = true)
+        ensureRadioStock()
+        val next = currentSong() ?: return null
+        return AdvanceResult(song = next)
+    }
+
+    /**
+     * Continuously top up cold while radio is active.
+     * Safe to call often — no-ops when already at/above target or pool empty.
+     */
+    fun ensureRadioStock() {
+        val sess = radioSession?.takeIf { it.active } ?: return
+        val helper = autoPlayHelper ?: return
+        val keys = buildSet {
+            coldQueue.forEach { add(songKey(it)) }
+            currentSong()?.let { add(songKey(it)) }
+            floatingCurrent?.let { add(songKey(it)) }
+            playedStack.takeLast(80).forEach { add(songKey(it)) }
+        }
+        // coldQueue includes the currently playing track when lane is COLD
+        val add = helper.restock(
+            currentColdSize = coldQueue.size,
+            alreadyQueuedKeys = keys,
+            queueSession = sess
+        )
+        if (add.isEmpty()) return
+        coldQueue.addAll(add)
+        coldOriginal = coldOriginal + add
+        log.i { "radio stock +${add.size} cold=${coldQueue.size} " +
+                "shuffle=${sess.prefs.shuffle} unit=${sess.prefs.shuffleUnit}" }
+        publish()
+    }
+
+    fun restore(snap: QueueSnapshot) {
+        hotQueue.clear()
+        hotQueue.addAll(snap.hotQueue)
+        coldOriginal = snap.coldOriginal.ifEmpty { snap.coldQueue }
+        coldQueue.clear()
+        coldQueue.addAll(snap.coldQueue)
+        coldSource = snap.coldSource
+        lane = snap.lane
+        indexInLane = snap.indexInLane
+        shuffleEnabled = snap.shuffleEnabled
+        repeatMode = snap.repeatMode
+        floatingCurrent = snap.floatingCurrent
+        playedStack.clear()
+        playedStack.addAll(snap.playedStack)
+        radioSession = snap.radioSession
+        radioUpcoming = snap.radioUpcoming
+        if (radioSession?.active == true && repeatMode == RepeatMode.COLD) {
+            repeatMode = RepeatMode.OFF
+        }
+        val max = when (lane) {
+            QueueLane.HOT -> hotQueue.lastIndex
+            QueueLane.COLD -> coldQueue.lastIndex
+        }
+        if (max >= 0) indexInLane = indexInLane.coerceIn(0, max)
+        // Rehydrate engine so restock works after process restore
+        radioSession?.takeIf { it.active }?.let { autoPlayHelper?.radioEngine?.adoptSession(it) }
+        publish()
+        if (radioSession?.active == true) ensureRadioStock()
+    }
+
+    fun playSource(
+        songs: List<Song>,
+        startIndex: Int = 0,
+        source: ColdSource? = null,
+        keepRadio: Boolean = false
+    ) {
+        if (songs.isEmpty()) return
+        log.i { "playSource size=${songs.size} start=$startIndex source=$source keepRadio=$keepRadio" }
+        floatingCurrent = null
+        playedStack.clear()
+        coldSource = source
+
+        if (!keepRadio && source?.type != ColdSourceType.RADIO) {
+            radioSession = null
+            radioUpcoming = emptyList()
+            autoPlayHelper?.stopRadio()
+        }
+
+        coldOriginal = songs.toList()
+        coldQueue.clear()
+
+        val isRadio = source?.type == ColdSourceType.RADIO || keepRadio || radioSession?.active == true
+        if (!isRadio && shuffleEnabled) {
+            coldQueue.addAll(songs.shuffled(Random(System.nanoTime())))
+            val tapped = songs.getOrNull(startIndex)
+            if (tapped != null) {
+                coldQueue.removeAll { sameSong(it, tapped) }
+                coldQueue.add(0, tapped)
+            }
+            indexInLane = 0
+        } else {
+            coldQueue.addAll(songs)
+            indexInLane = startIndex.coerceIn(0, coldQueue.lastIndex)
+            if (indexInLane > 0) {
+                for (i in 0 until indexInLane) {
+                    pushPlayed(coldQueue[i])
+                }
+                repeat(indexInLane) { coldQueue.removeAt(0) }
+                indexInLane = 0
+            }
+        }
+        lane = QueueLane.COLD
+        publish()
+        emit(
+            QueueEvent.SourceChanged(
+                source = source,
+                songCount = songs.size,
+                startSong = currentSong()
+            )
+        )
+        // Immediately top up toward maxRadioQueue so the queue page fills live
+        if (isRadio) ensureRadioStock()
+    }
+
+    fun updateColdFromSource(songs: List<Song>, sourceId: String): Boolean {
+        val src = coldSource ?: return false
+        if (!src.id.equals(sourceId, ignoreCase = true)) return false
+        if (songs.isEmpty()) return false
+        if (src.type == ColdSourceType.RADIO) return false
+
+        val newKeys = songs.map { songKey(it) }
+        val oldKeys = coldOriginal.map { songKey(it) }
+        if (newKeys == oldKeys) return false
+
+        val current = currentSong()
+        coldOriginal = songs.toList()
+
+        val ordered = if (shuffleEnabled) {
+            songs.shuffled(Random(System.nanoTime())).toMutableList()
+        } else {
+            songs.toMutableList()
+        }
+
+        if (current != null && ordered.any { sameSong(it, current) }) {
+            ordered.removeAll { sameSong(it, current) }
+            when {
+                floatingCurrent != null -> {
+                    coldQueue.clear()
+                    coldQueue.addAll(ordered)
+                }
+                lane == QueueLane.COLD -> {
+                    coldQueue.clear()
+                    coldQueue.add(current)
+                    coldQueue.addAll(ordered)
+                    indexInLane = 0
+                }
+                else -> {
+                    coldQueue.clear()
+                    coldQueue.addAll(ordered)
+                }
+            }
+        } else {
+            coldQueue.clear()
+            coldQueue.addAll(ordered)
+            if (lane == QueueLane.COLD && floatingCurrent == null) {
+                indexInLane = if (coldQueue.isEmpty()) -1 else 0
+            }
+        }
+
+        log.i { "updateColdFromSource id=$sourceId size=${songs.size} " +
+                "cold=${coldQueue.size} shuffle=$shuffleEnabled (overrides reset)" }
+        publish()
+        return true
+    }
+
+    fun replaceColdKeepingCurrent(
+        songs: List<Song>,
+        source: ColdSource? = null,
+        session: RadioSession? = null
+    ) {
+        if (songs.isEmpty()) return
+        if (session != null) {
+            radioSession = session
+            shuffleEnabled = session.prefs.shuffle
+            if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
+            autoPlayHelper?.radioEngine?.adoptSession(session)
+        }
+        if (source != null) coldSource = source
+
+        val current = currentSong()
+        coldOriginal = songs.toList()
+        val ordered = songs.toMutableList()
+
+        if (current != null) {
+            ordered.removeAll { sameSong(it, current) }
+            if (floatingCurrent != null) {
+                coldQueue.clear()
+                coldQueue.addAll(ordered)
+            } else if (lane == QueueLane.COLD) {
+                coldQueue.clear()
+                coldQueue.add(current)
+                coldQueue.addAll(ordered)
+                indexInLane = 0
+            } else {
+                coldQueue.clear()
+                coldQueue.addAll(ordered)
+            }
+        } else {
+            coldQueue.clear()
+            coldQueue.addAll(ordered)
+            if (lane == QueueLane.COLD) {
+                indexInLane = if (coldQueue.isEmpty()) -1 else 0
+            }
+        }
+        radioUpcoming = emptyList()
+        log.i { "replaceColdKeepingCurrent cold=${coldQueue.size}" }
+        publish()
+        if (radioSession?.active == true) ensureRadioStock()
+    }
+
+    fun addToQueue(song: Song) {
+        hotQueue.add(song)
+        publishHot()
+    }
+
+    fun addToQueue(songs: List<Song>) {
+        if (songs.isEmpty()) return
+        hotQueue.addAll(songs)
+        publishHot()
+    }
+
+    fun clearHotQueue() {
+        if (lane == QueueLane.HOT && indexInLane in hotQueue.indices) {
+            floatingCurrent = hotQueue[indexInLane]
+            hotQueue.clear()
+            indexInLane = -1
+            publishHot()
+            return
+        }
+        hotQueue.clear()
+        publishHot()
+    }
+
+    fun removeFromQueue(index: Int): Boolean {
+        if (index !in hotQueue.indices) return false
+        val removingCurrent = floatingCurrent == null && lane == QueueLane.HOT && index == indexInLane
+        hotQueue.removeAt(index)
+        if (lane == QueueLane.HOT && floatingCurrent == null) {
+            when {
+                hotQueue.isEmpty() -> {
+                    indexInLane = -1
+                    publishHot()
+                    return removingCurrent
+                }
+                index < indexInLane -> indexInLane--
+                removingCurrent -> {
+                    if (indexInLane > hotQueue.lastIndex) indexInLane = hotQueue.lastIndex
+                }
+            }
+        }
+        publishHot()
+        return removingCurrent
+    }
+
+    fun removeFromContext(index: Int): Boolean {
+        if (index !in coldQueue.indices) return false
+        val removingCurrent = floatingCurrent == null && lane == QueueLane.COLD && index == indexInLane
+        coldQueue.removeAt(index)
+        if (lane == QueueLane.COLD && floatingCurrent == null) {
+            when {
+                coldQueue.isEmpty() -> {
+                    indexInLane = -1
+                    publish()
+                    if (radioSession?.active == true) ensureRadioStock()
+                    return removingCurrent
+                }
+                index < indexInLane -> indexInLane--
+                removingCurrent -> {
+                    if (indexInLane > coldQueue.lastIndex) indexInLane = coldQueue.lastIndex
+                }
+            }
+        }
+        publish()
+        if (radioSession?.active == true) ensureRadioStock()
+        return removingCurrent
+    }
+
+    fun moveColdToHot(coldIndex: Int): Boolean {
+        if (coldIndex !in coldQueue.indices) return false
+        val removingCurrent = floatingCurrent == null && lane == QueueLane.COLD && coldIndex == indexInLane
+        val song = coldQueue.removeAt(coldIndex)
+        if (lane == QueueLane.COLD && floatingCurrent == null) {
+            when {
+                coldQueue.isEmpty() -> indexInLane = -1
+                coldIndex < indexInLane -> indexInLane--
+                removingCurrent -> indexInLane = indexInLane.coerceAtMost(coldQueue.lastIndex)
+            }
+        }
+        hotQueue.add(song)
+        publish()
+        if (radioSession?.active == true) ensureRadioStock()
+        return removingCurrent
+    }
+
+    fun moveInQueue(from: Int, to: Int) {
+        if (from !in hotQueue.indices || to !in hotQueue.indices || from == to) return
+        val item = hotQueue.removeAt(from)
+        hotQueue.add(to, item)
+        if (lane == QueueLane.HOT && floatingCurrent == null) {
+            indexInLane = remapIndex(indexInLane, from, to)
+        }
+        publishHot()
+    }
+
+    fun moveInContext(from: Int, to: Int) {
+        if (from !in coldQueue.indices || to !in coldQueue.indices || from == to) return
+        val item = coldQueue.removeAt(from)
+        coldQueue.add(to, item)
+        if (lane == QueueLane.COLD && floatingCurrent == null) {
+            indexInLane = remapIndex(indexInLane, from, to)
+        }
+        _snapshot.value = _snapshot.value.copy(
+            coldQueue = coldQueue.toList(),
+            indexInLane = indexInLane
+        )
+    }
+
+    fun playItem(laneTarget: QueueLane, index: Int) {
+        when (laneTarget) {
+            QueueLane.HOT -> {
+                if (index !in hotQueue.indices) return
+                val target = hotQueue[index]
+                val current = currentSong()
+                if (current != null && !sameSong(current, target)) pushPlayed(current)
+                if (current == null || !sameSong(current, target)) detachCurrentWithoutHistory()
+
+                var targetIdx = hotQueue.indexOfFirst { sameSong(it, target) }
+                if (targetIdx < 0) {
+                    hotQueue.add(0, target)
+                    targetIdx = 0
+                }
+                if (targetIdx > 0) repeat(targetIdx) { hotQueue.removeAt(0) }
+
+                floatingCurrent = null
+                lane = QueueLane.HOT
+                indexInLane = 0
+                publish()
+            }
+            QueueLane.COLD -> {
+                if (index !in coldQueue.indices) return
+                val target = coldQueue[index]
+                val current = currentSong()
+                if (current != null && !sameSong(current, target)) pushPlayed(current)
+                if (current == null || !sameSong(current, target)) detachCurrentWithoutHistory()
+
+                var targetIdx = coldQueue.indexOfFirst { sameSong(it, target) }
+                if (targetIdx < 0) {
+                    coldQueue.add(0, target)
+                    targetIdx = 0
+                }
+                if (targetIdx > 0) {
+                    for (i in 0 until targetIdx) pushPlayed(coldQueue[i])
+                    repeat(targetIdx) { coldQueue.removeAt(0) }
+                }
+
+                floatingCurrent = null
+                lane = QueueLane.COLD
+                indexInLane = 0
+                publish()
+            }
+        }
+    }
+
+    fun setShuffle(enabled: Boolean) {
+        if (radioSession?.active == true) {
+            val helper = autoPlayHelper
+            val next = helper?.radioEngine?.setShufflePrefs(enabled)
+            if (next != null) {
+                radioSession = radioSession?.copy(prefs = next)
+                shuffleEnabled = next.shuffle
+                val batch = helper.radioEngine.planBatch()
+                if (batch != null && batch.songs.isNotEmpty()) {
+                    replaceColdKeepingCurrent(batch.songs, batch.source, batch.session)
+                    return
+                }
+                publish()
+                emit(QueueEvent.ShuffleChanged(next.shuffle))
+            }
+            return
+        }
+
+        val current = currentSong()
+        if (!enabled) {
+            if (!shuffleEnabled) return
+            shuffleEnabled = false
+            coldQueue.clear()
+            coldQueue.addAll(coldOriginal)
+            if (current != null && lane == QueueLane.COLD && floatingCurrent == null) {
+                val idx = coldQueue.indexOfFirst { sameSong(it, current) }
+                indexInLane = if (idx >= 0) idx else 0
+            }
+            publish()
+            emit(QueueEvent.ShuffleChanged(false))
+            return
+        }
+        shuffleEnabled = true
+        val shuffled = coldOriginal.shuffled(Random(System.nanoTime())).toMutableList()
+        if (current != null && (lane == QueueLane.COLD || floatingCurrent != null)) {
+            shuffled.removeAll { sameSong(it, current) }
+            if (floatingCurrent == null && lane == QueueLane.COLD) {
+                shuffled.add(0, current)
+                coldQueue.clear()
+                coldQueue.addAll(shuffled)
+                indexInLane = 0
+            } else {
+                coldQueue.clear()
+                coldQueue.addAll(shuffled)
+            }
+        } else {
+            coldQueue.clear()
+            coldQueue.addAll(shuffled)
+        }
+        publish()
+        emit(QueueEvent.ShuffleChanged(true))
+    }
+
+    fun applyRadioPrefs(prefs: RadioSourcePrefs) {
+        val helper = autoPlayHelper ?: return
+        helper.radioEngine.updatePrefs(prefs)
+        val sess = helper.radioEngine.session ?: return
+        radioSession = sess
+        shuffleEnabled = sess.prefs.shuffle
+        if (repeatMode == RepeatMode.COLD) repeatMode = RepeatMode.OFF
+        val batch = helper.radioEngine.planBatch()
+        if (batch != null && batch.songs.isNotEmpty()) {
+            replaceColdKeepingCurrent(batch.songs, batch.source, batch.session)
+        } else {
+            publish()
+            ensureRadioStock()
+        }
+        emit(QueueEvent.ShuffleChanged(sess.prefs.shuffle))
+    }
+
+    fun cycleRepeatMode() {
+        repeatMode = if (radioSession?.active == true) {
+            when (repeatMode) {
+                RepeatMode.OFF -> RepeatMode.ONE
+                else -> RepeatMode.OFF
+            }
+        } else {
+            when (repeatMode) {
+                RepeatMode.OFF -> RepeatMode.ONE
+                RepeatMode.ONE -> RepeatMode.COLD
+                RepeatMode.COLD -> RepeatMode.OFF
+            }
+        }
+        publishRepeat()
+        emit(QueueEvent.RepeatModeChanged(repeatMode))
+    }
+
+    fun setRepeatMode(mode: RepeatMode) {
+        val resolved = if (radioSession?.active == true && mode == RepeatMode.COLD) {
+            RepeatMode.OFF
+        } else mode
+        if (repeatMode == resolved) return
+        repeatMode = resolved
+        publishRepeat()
+        emit(QueueEvent.RepeatModeChanged(resolved))
+    }
+
+    fun advance(userInitiated: Boolean): AdvanceResult {
+        if (repeatMode == RepeatMode.ONE && !userInitiated) {
+            return AdvanceResult(song = currentSong(), reload = true)
+        }
+
+        val wasFloating = floatingCurrent != null
+        val fromLane = lane
+        val fromIndex = indexInLane
+        val seedBefore = currentSong()
+        val sourceBefore = coldSource
+
+        if (floatingCurrent != null) {
+            pushPlayed(floatingCurrent!!)
+            floatingCurrent = null
+        } else {
+            when (fromLane) {
+                QueueLane.HOT -> {
+                    if (fromIndex in hotQueue.indices) pushPlayed(hotQueue.removeAt(fromIndex))
+                }
+                QueueLane.COLD -> {
+                    if (fromIndex in coldQueue.indices) pushPlayed(coldQueue.removeAt(fromIndex))
+                }
+            }
+        }
+
+        // Top up radio cold as each track leaves
+        ensureRadioStock()
+
+        if (wasFloating) return resolveNextFromHeads(seedBefore, sourceBefore)
+
+        if (fromLane == QueueLane.HOT && fromIndex in hotQueue.indices) {
+            lane = QueueLane.HOT
+            indexInLane = fromIndex
+            publish()
+            return AdvanceResult(song = hotQueue[indexInLane])
+        }
+
+        if (hotQueue.isNotEmpty() && fromLane != QueueLane.HOT) {
+            lane = QueueLane.HOT
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = hotQueue[0])
+        }
+
+        if (fromLane == QueueLane.COLD && fromIndex in coldQueue.indices) {
+            lane = QueueLane.COLD
+            indexInLane = fromIndex
+            publish()
+            return AdvanceResult(song = coldQueue[indexInLane])
+        }
+
+        if (coldQueue.isNotEmpty()) {
+            lane = QueueLane.COLD
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = coldQueue[0])
+        }
+
+        // Cold emptied — try one more restock before rescue/finish
+        ensureRadioStock()
+        if (coldQueue.isNotEmpty()) {
+            lane = QueueLane.COLD
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = coldQueue[0])
+        }
+
+        if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty() && radioSession?.active != true) {
+            repopulateCold()
+            lane = QueueLane.COLD
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = coldQueue[0])
+        }
+
+        val seed = seedBefore ?: playedStack.lastOrNull()
+        emit(QueueEvent.Exhausted(seed = seed, source = sourceBefore, repeatMode = repeatMode))
+        tryAutoPlayRescue(seed, sourceBefore)?.let { return it }
+
+        indexInLane = -1
+        publish()
+        return AdvanceResult(finished = true)
+    }
+
+    private fun resolveNextFromHeads(
+        seedBefore: Song?,
+        sourceBefore: ColdSource?
+    ): AdvanceResult {
+        if (hotQueue.isNotEmpty()) {
+            lane = QueueLane.HOT
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = hotQueue[0])
+        }
+        if (coldQueue.isNotEmpty()) {
+            lane = QueueLane.COLD
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = coldQueue[0])
+        }
+        ensureRadioStock()
+        if (coldQueue.isNotEmpty()) {
+            lane = QueueLane.COLD
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = coldQueue[0])
+        }
+        if (repeatMode == RepeatMode.COLD && coldOriginal.isNotEmpty() && radioSession?.active != true) {
+            repopulateCold()
+            lane = QueueLane.COLD
+            indexInLane = 0
+            publish()
+            return AdvanceResult(song = coldQueue[0])
+        }
+        val seed = seedBefore ?: playedStack.lastOrNull()
+        emit(QueueEvent.Exhausted(seed = seed, source = sourceBefore, repeatMode = repeatMode))
+        tryAutoPlayRescue(seed, sourceBefore)?.let { return it }
+        indexInLane = -1
+        publish()
+        return AdvanceResult(finished = true)
+    }
+
+    fun skipPrevious(
+        currentPositionMs: Long,
+        forceTrackChange: Boolean = false
+    ): AdvanceResult {
+        val current = currentSong()
+        if (!forceTrackChange && currentPositionMs >= PREV_RESTART_MS) {
+            return AdvanceResult(song = current, seekToStart = true)
+        }
+
+        linearPrevious()?.let { prev ->
+            indexInLane -= 1
+            publish()
+            log.i { "skipPrevious linear → '${prev.displayTitle}' idx=$indexInLane" }
+            return AdvanceResult(song = prev)
+        }
+
+        if (playedStack.isEmpty()) {
+            return AdvanceResult(song = current, seekToStart = true)
+        }
+
+        val prev = playedStack.removeAt(playedStack.lastIndex)
+
+        if (floatingCurrent != null) {
+            floatingCurrent = null
+        } else {
+            when (lane) {
+                QueueLane.HOT -> {
+                    if (indexInLane in hotQueue.indices) hotQueue.removeAt(indexInLane)
+                }
+                QueueLane.COLD -> {
+                    if (indexInLane in coldQueue.indices) coldQueue.removeAt(indexInLane)
+                }
+            }
+        }
+
+        val useCold = coldSource != null || coldQueue.isNotEmpty() || coldOriginal.isNotEmpty()
+        if (useCold) {
+            if (current != null) coldQueue.add(0, current)
+            coldQueue.add(0, prev)
+            lane = QueueLane.COLD
+            indexInLane = 0
+        } else {
+            if (current != null) hotQueue.add(0, current)
+            hotQueue.add(0, prev)
+            lane = QueueLane.HOT
+            indexInLane = 0
+        }
+        floatingCurrent = null
+
+        publish()
+        log.i { "skipPrevious history → '${prev.displayTitle}'" }
+        return AdvanceResult(song = prev)
+    }
+
+    private fun repopulateCold() {
+        coldQueue.clear()
+        if (shuffleEnabled) {
+            coldQueue.addAll(coldOriginal.shuffled(Random(System.nanoTime())))
+        } else {
+            coldQueue.addAll(coldOriginal)
+        }
+        playedStack.clear()
+    }
+
+    private fun remapIndex(current: Int, from: Int, to: Int): Int = when {
+        current == from -> to
+        from < current && to >= current -> current - 1
+        from > current && to <= current -> current + 1
+        else -> current
+    }
+
+    private fun sameSong(a: Song, b: Song): Boolean {
+        if (a.path != null && b.path != null) return a.path == b.path
+        return a.contentUri == b.contentUri || a.id == b.id
+    }
+
+    private fun songKey(s: Song): String =
+        s.path?.lowercase() ?: s.contentUri
+
+    data class AdvanceResult(
+        val song: Song? = null,
+        val finished: Boolean = false,
+        val reload: Boolean = false,
+        val seekToStart: Boolean = false
+    )
+
+    companion object {
+        private val log = yuriLog("Queue")
+        const val PREV_RESTART_MS = 3_000L
+        private const val MAX_PLAYED_STACK = 200
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueModels.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueModels.kt
new file mode 100644
index 00000000..824755dc
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/QueueModels.kt
@@ -0,0 +1,64 @@
+package capital.yuri.yuriplayer.player
+
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.player.radio.RadioSession
+import kotlinx.serialization.Serializable
+
+// Re-export the shared queue types from :core so app code can keep importing
+// them from `capital.yuri.yuriplayer.player`. The canonical definitions live in
+// `capital.yuri.yuriplayer.core.player`.
+typealias RepeatMode = capital.yuri.yuriplayer.core.player.RepeatMode
+typealias QueueLane = capital.yuri.yuriplayer.core.player.QueueLane
+typealias ColdSourceType = capital.yuri.yuriplayer.core.player.ColdSourceType
+typealias ColdSource = capital.yuri.yuriplayer.core.player.ColdSource
+
+/**
+ * Snapshot of the dual-queue system for UI + persistence.
+ *
+ * [radioSession] names the station when radio is active.
+ * [radioUpcoming] is the prefetched next radio release (not yet in cold).
+ *
+ * Shuffle in radio mode only reorders the **current** cold segment; the next
+ * radio release is still algorithm-picked (see [RadioSession] KDoc).
+ */
+@Serializable
+data class QueueSnapshot(
+    val hotQueue: List<Song> = emptyList(),
+    val coldQueue: List<Song> = emptyList(),
+    val coldOriginal: List<Song> = emptyList(),
+    val coldSource: ColdSource? = null,
+    val lane: QueueLane = QueueLane.COLD,
+    val indexInLane: Int = -1,
+    val shuffleEnabled: Boolean = false,
+    val repeatMode: RepeatMode = RepeatMode.OFF,
+    val playedStack: List<Song> = emptyList(),
+    val radioSession: RadioSession? = null,
+    val radioUpcoming: List<Song> = emptyList(),
+    /** Playing item when it is not at [indexInLane] (search / one-off). */
+    val floatingCurrent: Song? = null
+) {
+    val currentSong: Song?
+        get() = floatingCurrent ?: when (lane) {
+            QueueLane.HOT -> hotQueue.getOrNull(indexInLane)
+            QueueLane.COLD -> coldQueue.getOrNull(indexInLane)
+        }
+
+    val flatQueue: List<Song>
+        get() = hotQueue + coldQueue
+
+    /**
+     * True when a radio session is active **or** the cold source is typed RADIO.
+     * Label text alone is not enough — some stations set coldSource without
+     * keeping [radioSession].active, which hid the tune button.
+     */
+    val isRadio: Boolean
+        get() = radioSession?.active == true || coldSource?.type == ColdSourceType.RADIO
+
+    fun isPlayingFromAlbum(albumKey: String): Boolean =
+        coldSource?.matches(ColdSourceType.ALBUM, albumKey) == true ||
+            (coldSource?.type == ColdSourceType.RADIO &&
+                coldSource.id.equals(albumKey, ignoreCase = true))
+
+    fun isPlayingFromPlaylist(playlistId: String): Boolean =
+        coldSource?.matches(ColdSourceType.PLAYLIST, playlistId) == true
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt
new file mode 100644
index 00000000..e9b1153a
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/AlbumRadioSeed.kt
@@ -0,0 +1,101 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.artistKey
+
+/**
+ * Album radio pool: every credited artist on the release, plus genre keys
+ * when those tags exist (Song has no genre field yet — empty list is fine).
+ */
+object AlbumRadioSeed {
+
+    fun fromAlbum(album: AlbumItem): Pair<ReleasePoolConfig, RadioSession> {
+        val artists = LinkedHashSet<String>()
+        val displayArtists = LinkedHashSet<String>()
+
+        album.artist?.trim()?.takeIf { it.isNotEmpty() }?.let {
+            displayArtists += it
+            artistKey(it)?.let(artists::add)
+        }
+
+        for (s in album.songs) {
+            collectArtist(s, artists, displayArtists)
+        }
+
+        val genres = collectGenres(album.songs)
+        val cfg = ReleasePoolConfig(
+            artistKeys = artists.toList(),
+            genreKeys = genres,
+            includeLps = true,
+            includeEps = true,
+            includeSingles = true,
+            allowExternalFetch = false,
+            avoidRecentPerKind = 1
+        )
+
+        val seedKey = ReleaseClassifier.releaseKey(album)
+        val label = album.name?.takeIf { it.isNotBlank() } ?: "Album"
+        val session = RadioSession(
+            kind = RadioSessionKind.ALBUM,
+            displayName = "Radio · $label",
+            algorithmId = RadioAlgorithmId.RELEASE_POOL,
+            seedId = seedKey,
+            seedTitle = label
+        )
+        return cfg to session
+    }
+
+    fun fromTracksForPlaylist(
+        songs: List<Song>,
+        playlistName: String?
+    ): Pair<ReleasePoolConfig, RadioSession> {
+        val cfg = PlaylistRadioSeed.fromTracks(songs)
+        val label = playlistName?.takeIf { it.isNotBlank() } ?: "Playlist"
+        val session = RadioSession(
+            kind = RadioSessionKind.PLAYLIST,
+            displayName = "Radio · $label",
+            algorithmId = RadioAlgorithmId.RELEASE_POOL,
+            seedId = label.lowercase(),
+            seedTitle = label
+        )
+        return cfg to session
+    }
+
+    fun artistSession(artistName: String): RadioSession {
+        val label = artistName.trim().ifBlank { "Artist" }
+        return RadioSession(
+            kind = RadioSessionKind.ARTIST,
+            displayName = "Radio · $label",
+            algorithmId = RadioAlgorithmId.PLAYBACK,
+            seedId = artistKey(label),
+            seedTitle = label
+        )
+    }
+
+    private fun collectArtist(
+        s: Song,
+        keys: MutableSet<String>,
+        display: MutableSet<String>
+    ) {
+        s.effectiveAlbumArtist?.trim()?.takeIf { it.isNotEmpty() }?.let {
+            display += it
+            artistKey(it)?.let(keys::add)
+        }
+        s.artist?.trim()?.takeIf { it.isNotEmpty() }?.let {
+            display += it
+            artistKey(it)?.let(keys::add)
+        }
+        s.creditArtists.forEach { name ->
+            display += name
+            artistKey(name)?.let(keys::add)
+        }
+    }
+
+    /** Collect the distinct genre tags across the seeded release. */
+    private fun collectGenres(songs: List<Song>): List<String> =
+        songs.flatMap { it.genres }
+            .map { it.lowercase().trim() }
+            .filter { it.isNotEmpty() }
+            .distinct()
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt
new file mode 100644
index 00000000..93adf089
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/PlaylistRadioSeed.kt
@@ -0,0 +1,37 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.artistKey
+
+/**
+ * Build a [ReleasePoolConfig] from playlist (or any track list) contents.
+ * Artists are derived on-device from tags; genres land here when the catalog
+ * has them. No network.
+ */
+object PlaylistRadioSeed {
+
+    fun fromTracks(
+        songs: List<Song>,
+        includeLps: Boolean = true,
+        includeEps: Boolean = true,
+        includeSingles: Boolean = true
+    ): ReleasePoolConfig {
+        val artists = LinkedHashSet<String>()
+        for (s in songs) {
+            artistKey(s.effectiveAlbumArtist)?.let { artists += it }
+            artistKey(s.artist)?.let { artists += it }
+            s.creditArtists.forEach { name ->
+                artistKey(name)?.let { artists += it }
+            }
+        }
+        return ReleasePoolConfig(
+            artistKeys = artists.toList(),
+            genreKeys = emptyList(), // filled when Song.genre exists
+            includeLps = includeLps,
+            includeEps = includeEps,
+            includeSingles = includeSingles,
+            allowExternalFetch = false,
+            avoidRecentPerKind = 1
+        )
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt
new file mode 100644
index 00000000..e9beffc1
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioAlgorithm.kt
@@ -0,0 +1,44 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.data.AlbumItem
+
+/**
+ * On-device catalog view for algorithms. Keep this free of Android / Room so the
+ * radio package can move to a shared KMP module or a self-hosted worker.
+ */
+fun interface ReleaseCatalog {
+    fun albums(): List<AlbumItem>
+}
+
+/**
+ * Pluggable radio strategy. Implementations must be pure w.r.t. I/O except via
+ * [ReleaseCatalog] (and future optional NetworkReleaseSource behind a privacy gate).
+ */
+interface RadioAlgorithm {
+    val id: RadioAlgorithmId
+
+    /**
+     * @return next release to queue, or null if this strategy has nothing.
+     * Algorithms must not mutate global player state — only their own memory
+     * (via [RecentReleaseMemory] passed in context side-channels if needed).
+     */
+    fun pick(
+        catalog: ReleaseCatalog,
+        context: RadioContext,
+        memory: RecentReleaseMemory
+    ): RadioPick?
+}
+
+/**
+ * Optional network extension point. Always no-op until the user opts in and a
+ * concrete source (Jellyfin / Navidrome / …) is configured.
+ */
+interface ExternalReleaseSource {
+    val isEnabled: Boolean
+    /** Suspend-friendly later; sync stub for now. */
+    fun fetchCandidates(context: RadioContext): List<AlbumItem> = emptyList()
+}
+
+object NoExternalReleaseSource : ExternalReleaseSource {
+    override val isEnabled: Boolean = false
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioEngine.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioEngine.kt
new file mode 100644
index 00000000..0f9605fc
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioEngine.kt
@@ -0,0 +1,400 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.data.artistKey
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.ColdSourceType
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import kotlin.random.Random
+
+/**
+ * Plans the radio cold queue (visible on the queue page) and restocks it.
+ *
+ * Shuffle OFF: whole LP/EP/Single blocks until ≥ maxRadioQueue (may exceed);
+ *   restock appends the next release only when cold size < max.
+ * Shuffle ON + SONGS: random tracks up to maxRadioQueue; restock tops cold every time.
+ * Shuffle ON + RELEASES: shuffled whole releases (tracks ordered within);
+ *   restock appends the next shuffled release when under target.
+ */
+class RadioEngine(
+    private val catalog: ReleaseCatalog,
+    private val autoPlayEnabled: () -> Boolean,
+    private val playbackAlgo: RadioPlaybackAlgorithm = RadioPlaybackAlgorithm(),
+    private val poolAlgo: ReleasePoolAlgorithm = ReleasePoolAlgorithm()
+) {
+    private val memory = RecentReleaseMemory()
+
+    @Volatile
+    var activeAlgorithm: RadioAlgorithmId = RadioAlgorithmId.PLAYBACK
+        private set
+
+    @Volatile
+    var session: RadioSession? = null
+        private set
+
+    /** Pool of candidate releases for the active session (artist/album/playlist). */
+    private var poolReleases: List<AlbumItem> = emptyList()
+
+    fun configurePlayback(config: RadioPlaybackConfig) {
+        playbackAlgo.config = config
+    }
+
+    fun configurePool(config: ReleasePoolConfig) {
+        poolAlgo.config = config
+        rebuildPoolFromConfig(config)
+    }
+
+    fun startAlbumRadio(album: AlbumItem, prefs: RadioSourcePrefs = RadioSourcePrefs()): RadioSession {
+        val (cfg, sess) = AlbumRadioSeed.fromAlbum(album)
+        val withPrefs = sess.copy(prefs = prefs)
+        configurePool(cfg)
+        activeAlgorithm = RadioAlgorithmId.RELEASE_POOL
+        session = withPrefs
+        memory.note(ReleaseClassifier.releaseKey(album), ReleaseClassifier.kindOf(album))
+        log.i { "album radio '${withPrefs.displayName}' artists=${cfg.artistKeys.size}" }
+        return withPrefs
+    }
+
+    fun startArtistRadio(artistName: String, prefs: RadioSourcePrefs = RadioSourcePrefs()): RadioSession {
+        val sess = AlbumRadioSeed.artistSession(artistName).copy(prefs = prefs)
+        activeAlgorithm = RadioAlgorithmId.PLAYBACK
+        session = sess
+        poolReleases = releasesForArtist(artistName)
+        log.i { "artist radio '${sess.displayName}' releases=${poolReleases.size}" }
+        return sess
+    }
+
+    fun startPlaylistRadio(
+        songs: List<Song>,
+        playlistName: String?,
+        prefs: RadioSourcePrefs = RadioSourcePrefs()
+    ): RadioSession {
+        val (cfg, sess) = AlbumRadioSeed.fromTracksForPlaylist(songs, playlistName)
+        val withPrefs = sess.copy(prefs = prefs)
+        configurePool(cfg)
+        activeAlgorithm = RadioAlgorithmId.RELEASE_POOL
+        session = withPrefs
+        log.i { "playlist radio '${withPrefs.displayName}'" }
+        return withPrefs
+    }
+
+    /**
+     * Re-attach a session that was persisted on the queue but lost from this
+     * in-memory engine (e.g. after process death). Rebuilds the release pool.
+     */
+    fun adoptSession(sess: RadioSession) {
+        if (!sess.active) return
+        session = sess
+        activeAlgorithm = sess.algorithmId
+        when (sess.kind) {
+            RadioSessionKind.ARTIST -> {
+                val name = sess.seedTitle
+                    ?: sess.displayName.removePrefix("Radio · ").trim()
+                poolReleases = releasesForArtist(name)
+            }
+            RadioSessionKind.ALBUM,
+            RadioSessionKind.PLAYLIST,
+            RadioSessionKind.CUSTOM -> {
+                // Fall back to full catalog; seed-specific pool is best-effort.
+                if (poolReleases.isEmpty()) {
+                    poolReleases = catalog.albums().filter { it.songs.isNotEmpty() }
+                }
+            }
+        }
+        log.i { "adoptSession '${sess.displayName}' kind=${sess.kind} " +
+                "pool=${poolReleases.size} shuffle=${sess.prefs.shuffle}" }
+    }
+
+    fun ensureAutoPlaySession(seedSong: Song?, finishedSource: ColdSource?): RadioSession {
+        session?.takeIf { it.active }?.let { return it }
+        val artist = seedSong?.effectiveAlbumArtist
+            ?: seedSong?.artist
+            ?: finishedSource?.title
+            ?: finishedSource?.id?.substringBefore('|')
+            ?: "Radio"
+        return startArtistRadio(artist.trim().ifBlank { "Radio" })
+    }
+
+    fun updatePrefs(prefs: RadioSourcePrefs) {
+        val s = session ?: return
+        session = s.copy(prefs = prefs)
+        log.i { "prefs shuffle=${prefs.shuffle} unit=${prefs.shuffleUnit} max=${prefs.maxRadioQueue} " +
+                "lib=${prefs.useLibraryDiscovery} jf=${prefs.useJellyfinInstantMix} " +
+                "sub=${prefs.useSubsonicSimilar} mono=${prefs.useMonochromeDiscovery}" }
+    }
+
+    fun setShufflePrefs(enabled: Boolean): RadioSourcePrefs? {
+        val s = session ?: return null
+        if (s.prefs.shuffle == enabled) return null
+        val next = s.prefs.copy(shuffle = enabled)
+        session = s.copy(prefs = next)
+        log.i { "prefs shuffle=${next.shuffle} unit=${next.shuffleUnit} max=${next.maxRadioQueue}" }
+        return next
+    }
+
+    fun toggleShufflePrefs(): RadioSourcePrefs? {
+        val s = session ?: return null
+        return setShufflePrefs(!s.prefs.shuffle)
+    }
+
+    fun stopRadio() {
+        session = null
+        poolReleases = emptyList()
+        log.i { "radio stopped" }
+    }
+
+    fun noteSource(source: ColdSource?) {
+        if (source?.type != ColdSourceType.ALBUM && source?.type != ColdSourceType.RADIO) return
+        val id = source.id.takeIf { it.isNotBlank() } ?: return
+        memory.note(id, ReleaseKind.UNKNOWN)
+    }
+
+    fun planBatch(
+        seedSong: Song? = null,
+        finishedSource: ColdSource? = null,
+        excludeKeys: Set<String> = emptySet()
+    ): RadioBatch? {
+        val sess = session?.takeIf { it.active } ?: return null
+        val prefs = sess.prefs
+        val max = prefs.maxRadioQueue.coerceIn(1, 500)
+        val releases = availableReleases(excludeKeys)
+        if (releases.isEmpty()) {
+            log.i { "planBatch: no releases" }
+            return null
+        }
+
+        val songs = when {
+            !prefs.shuffle -> planReleaseBlocks(releases, max, excludeKeys)
+            prefs.shuffleUnit == RadioShuffleUnit.RELEASES ->
+                planShuffledReleases(releases, max, excludeKeys)
+            else -> planShuffledSongs(releases, max, excludeKeys)
+        }
+        if (songs.isEmpty()) return null
+
+        songs.forEach { s ->
+            val k = albumKeyOf(s)
+            if (k.isNotBlank()) memory.note(k, ReleaseKind.UNKNOWN)
+        }
+
+        val source = ColdSource(
+            type = ColdSourceType.RADIO,
+            id = sess.seedId ?: sess.displayName,
+            title = sess.displayName
+        )
+        val reason = when {
+            !prefs.shuffle -> "release-blocks"
+            prefs.shuffleUnit == RadioShuffleUnit.RELEASES -> "shuffle-releases"
+            else -> "shuffle-songs"
+        }
+        log.i { "planBatch '${sess.displayName}' songs=${songs.size} " +
+                "shuffle=${prefs.shuffle} unit=${prefs.shuffleUnit} max=$max pool=${releases.size}" }
+        return RadioBatch(
+            songs = songs,
+            source = source,
+            session = sess,
+            reason = reason
+        )
+    }
+
+    fun restockSongs(
+        currentColdSize: Int,
+        alreadyQueuedKeys: Set<String>
+    ): List<Song> {
+        val sess = session?.takeIf { it.active } ?: return emptyList()
+        val max = sess.prefs.maxRadioQueue.coerceIn(1, 500)
+        val prefs = sess.prefs
+
+        if (prefs.shuffle && prefs.shuffleUnit == RadioShuffleUnit.SONGS) {
+            val need = max - currentColdSize
+            if (need <= 0) return emptyList()
+            val pool = songPool(availableReleases(emptySet()))
+                .filter { songKey(it) !in alreadyQueuedKeys }
+            if (pool.isEmpty()) {
+                log.i { "restock songs: empty pool (cold=$currentColdSize max=$max)" }
+                return emptyList()
+            }
+            val pick = pool.shuffled(Random(System.nanoTime())).take(need)
+            log.i { "restock songs +${pick.size} (cold was $currentColdSize / $max)" }
+            return pick
+        }
+
+        // Ordered or RELEASES: pull next whole release whenever under max
+        if (currentColdSize >= max) return emptyList()
+
+        val next = if (prefs.shuffle && prefs.shuffleUnit == RadioShuffleUnit.RELEASES) {
+            nextShuffledRelease(alreadyQueuedKeys)
+        } else {
+            nextOrderedRelease(alreadyQueuedKeys)
+        } ?: run {
+            log.i { "restock release: no candidate (cold=$currentColdSize max=$max)" }
+            return emptyList()
+        }
+
+        val tracks = sortedTracks(next).filter { songKey(it) !in alreadyQueuedKeys }
+        if (tracks.isEmpty()) return emptyList()
+        memory.note(ReleaseClassifier.releaseKey(next), ReleaseClassifier.kindOf(next))
+        log.i { "restock release +${tracks.size} from '${next.displayName}' " +
+                "(cold was $currentColdSize / $max)" }
+        return tracks
+    }
+
+    fun maybePlan(
+        seedSong: Song?,
+        finishedSource: ColdSource?,
+        repeatMode: RepeatMode
+    ): RadioBatch? {
+        val radioActive = session?.active == true
+        if (!radioActive && !autoPlayEnabled()) {
+            log.d { "skip — no session & auto-play off" }
+            return null
+        }
+        if (repeatMode != RepeatMode.OFF) return null
+
+        if (session?.active != true) {
+            ensureAutoPlaySession(seedSong, finishedSource)
+        }
+        return planBatch(seedSong, finishedSource)
+    }
+
+    // ── planning helpers ──────────────────────────────────────────────────
+
+    private fun planShuffledSongs(
+        releases: List<AlbumItem>,
+        max: Int,
+        excludeAlbumKeys: Set<String>
+    ): List<Song> {
+        val pool = songPool(
+            releases.filter { ReleaseClassifier.releaseKey(it) !in excludeAlbumKeys }
+        )
+        if (pool.isEmpty()) return emptyList()
+        return pool.shuffled(Random(System.nanoTime())).take(max)
+    }
+
+    private fun planShuffledReleases(
+        releases: List<AlbumItem>,
+        max: Int,
+        excludeAlbumKeys: Set<String>
+    ): List<Song> {
+        val pool = releases
+            .filter { ReleaseClassifier.releaseKey(it) !in excludeAlbumKeys && it.songs.isNotEmpty() }
+            .shuffled(Random(System.nanoTime()))
+        val out = ArrayList<Song>(max + 32)
+        for (rel in pool) {
+            val tracks = sortedTracks(rel)
+            if (tracks.isEmpty()) continue
+            out.addAll(tracks)
+            memory.note(ReleaseClassifier.releaseKey(rel), ReleaseClassifier.kindOf(rel))
+            if (out.size >= max) break
+        }
+        return out
+    }
+
+    private fun planReleaseBlocks(
+        releases: List<AlbumItem>,
+        max: Int,
+        excludeAlbumKeys: Set<String>
+    ): List<Song> {
+        val ordered = orderedReleases(releases, excludeAlbumKeys)
+        val out = ArrayList<Song>(max + 32)
+        for (rel in ordered) {
+            val tracks = sortedTracks(rel)
+            if (tracks.isEmpty()) continue
+            out.addAll(tracks)
+            memory.note(ReleaseClassifier.releaseKey(rel), ReleaseClassifier.kindOf(rel))
+            if (out.size >= max) break
+        }
+        return out
+    }
+
+    private fun nextOrderedRelease(alreadyQueuedKeys: Set<String>): AlbumItem? {
+        val ordered = orderedReleases(availableReleases(emptySet()), emptySet())
+        for (rel in ordered) {
+            val tracks = sortedTracks(rel)
+            if (tracks.isEmpty()) continue
+            val allQueued = tracks.all { songKey(it) in alreadyQueuedKeys }
+            if (!allQueued) return rel
+        }
+        return null
+    }
+
+    private fun nextShuffledRelease(alreadyQueuedKeys: Set<String>): AlbumItem? {
+        val candidates = availableReleases(emptySet()).filter { rel ->
+            val tracks = sortedTracks(rel)
+            tracks.isNotEmpty() && tracks.any { songKey(it) !in alreadyQueuedKeys }
+        }
+        if (candidates.isEmpty()) return null
+        return candidates.random(Random(System.nanoTime()))
+    }
+
+    private fun orderedReleases(
+        releases: List<AlbumItem>,
+        excludeAlbumKeys: Set<String>
+    ): List<AlbumItem> =
+        releases
+            .filter { ReleaseClassifier.releaseKey(it) !in excludeAlbumKeys }
+            .sortedWith(
+                compareByDescending<AlbumItem> {
+                    it.songs.mapNotNull { s -> s.year }.maxOrNull() ?: Int.MIN_VALUE
+                }.thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayName }
+            )
+
+    private fun sortedTracks(rel: AlbumItem): List<Song> =
+        rel.songs.sortedWith(
+            compareBy<Song> { it.discNumber ?: Int.MAX_VALUE }
+                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.displayTitle }
+        )
+
+    private fun availableReleases(excludeKeys: Set<String>): List<AlbumItem> {
+        val base = if (poolReleases.isNotEmpty()) poolReleases else catalog.albums()
+        return base.filter { it.songs.isNotEmpty() && ReleaseClassifier.releaseKey(it) !in excludeKeys }
+    }
+
+    private fun songPool(releases: List<AlbumItem>): List<Song> =
+        releases.flatMap { it.songs }.distinctBy { songKey(it) }
+
+    private fun releasesForArtist(artistName: String): List<AlbumItem> {
+        val norm = artistKey(artistName) ?: return emptyList()
+        return catalog.albums().filter { album ->
+            artistKey(album.artist) == norm ||
+                album.songs.any { s ->
+                    artistKey(s.effectiveAlbumArtist) == norm ||
+                        artistKey(s.artist) == norm ||
+                        s.creditArtists.any { artistKey(it) == norm }
+                }
+        }
+    }
+
+    private fun rebuildPoolFromConfig(config: ReleasePoolConfig) {
+        val keys = config.artistKeys.mapNotNull { artistKey(it) }.toSet()
+        poolReleases = if (keys.isEmpty()) {
+            catalog.albums().filter { it.songs.isNotEmpty() }
+        } else {
+            catalog.albums().filter { album ->
+                album.songs.isNotEmpty() && (
+                    artistKey(album.artist)?.let { it in keys } == true ||
+                        album.songs.any { s ->
+                            artistKey(s.effectiveAlbumArtist)?.let { it in keys } == true ||
+                                artistKey(s.artist)?.let { it in keys } == true ||
+                                s.creditArtists.any { artistKey(it)?.let { k -> k in keys } == true }
+                        }
+                    )
+            }
+        }
+    }
+
+    private fun albumKeyOf(s: Song): String {
+        val a = (s.effectiveAlbumArtist ?: "").trim().lowercase()
+        val n = (s.album ?: "").trim().lowercase()
+        return "$a|$n"
+    }
+
+    private fun songKey(s: Song): String =
+        s.path?.lowercase() ?: s.contentUri
+
+    companion object {
+        private val log = yuriLog("Radio")
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioModels.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioModels.kt
new file mode 100644
index 00000000..5eef1991
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioModels.kt
@@ -0,0 +1,134 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import kotlinx.serialization.Serializable
+
+enum class ReleaseKind {
+    LP,
+    EP,
+    SINGLE,
+    UNKNOWN
+}
+
+data class RadioPick(
+    val album: AlbumItem,
+    val source: ColdSource,
+    val kind: ReleaseKind,
+    val algorithmId: String,
+    val reason: String = ""
+)
+
+/**
+ * A planned radio segment: the songs RadioEngine wants in the cold queue.
+ * Queue UI shows this list as the radio cold queue.
+ */
+data class RadioBatch(
+    val songs: List<Song>,
+    val source: ColdSource,
+    val session: RadioSession,
+    val reason: String = ""
+)
+
+data class RadioContext(
+    val seedSong: Song?,
+    val finishedSource: ColdSource?,
+    val repeatMode: RepeatMode,
+    val focusArtistKeys: Set<String> = emptySet(),
+    val focusGenreKeys: Set<String> = emptySet()
+)
+
+@Serializable
+data class RadioPlaybackConfig(
+    val avoidRecentLps: Int = 1,
+    val avoidRecentEps: Int = 1,
+    val avoidRecentSingles: Int = 1,
+    val globalRecentExclude: Int = 1,
+    val weightLp: Float = 1.0f,
+    val weightEp: Float = 1.0f,
+    val weightSingle: Float = 0.85f,
+    val softPenaltyFactor: Float = 0.55f,
+    val softHistorySize: Int = 12,
+    val sameArtistBias: Float = 1.0f
+)
+
+@Serializable
+data class ReleasePoolConfig(
+    val artistKeys: List<String> = emptyList(),
+    val genreKeys: List<String> = emptyList(),
+    val includeLps: Boolean = true,
+    val includeEps: Boolean = true,
+    val includeSingles: Boolean = true,
+    val allowExternalFetch: Boolean = false,
+    val avoidRecentPerKind: Int = 1
+)
+
+/** How shuffle fills the radio cold queue. */
+@Serializable
+enum class RadioShuffleUnit {
+    /** Random tracks from the whole pool (default). */
+    SONGS,
+    /** Random order of whole LP/EP/Single blocks; tracks stay in release order. */
+    RELEASES
+}
+
+/**
+ * Per radio-source preferences (artist / album / playlist station).
+ *
+ * Defaults: shuffle ON with [RadioShuffleUnit.SONGS]. Ordered whole-release
+ * mode remains available by turning shuffle off.
+ *
+ * Discovery flags: combine any set of sources for similar artists/songs.
+ */
+@Serializable
+data class RadioSourcePrefs(
+    /**
+     * true  → use [shuffleUnit] to fill cold up to [maxRadioQueue].
+     * false → whole LP/EP/Single blocks in year-desc order (legacy ordered mode).
+     */
+    val shuffle: Boolean = true,
+    val shuffleUnit: RadioShuffleUnit = RadioShuffleUnit.SONGS,
+    val maxRadioQueue: Int = DEFAULT_MAX_RADIO_QUEUE,
+    /** On-device catalog / already-scanned sources. */
+    val useLibraryDiscovery: Boolean = true,
+    /** Jellyfin Instant Mix when a matching item exists on an enabled server. */
+    val useJellyfinInstantMix: Boolean = false,
+    /** Subsonic / OpenSubsonic similar-songs / similar-artists. */
+    val useSubsonicSimilar: Boolean = false,
+    /**
+     * monochrome.tf community hifi-api recommendations
+     * (`/recommendations`, `/artist/similar`, `/mix`) — discovery only.
+     */
+    val useMonochromeDiscovery: Boolean = false
+) {
+    companion object {
+        const val DEFAULT_MAX_RADIO_QUEUE = 50
+    }
+}
+
+@Serializable
+enum class RadioAlgorithmId {
+    PLAYBACK,
+    RELEASE_POOL
+}
+
+@Serializable
+enum class RadioSessionKind {
+    ARTIST,
+    ALBUM,
+    PLAYLIST,
+    CUSTOM
+}
+
+@Serializable
+data class RadioSession(
+    val kind: RadioSessionKind,
+    val displayName: String,
+    val algorithmId: RadioAlgorithmId,
+    val seedId: String? = null,
+    val seedTitle: String? = null,
+    val active: Boolean = true,
+    val prefs: RadioSourcePrefs = RadioSourcePrefs()
+)
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt
new file mode 100644
index 00000000..74caf9f7
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RadioPlaybackAlgorithm.kt
@@ -0,0 +1,144 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.artistKey
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.ColdSourceType
+import kotlin.math.pow
+import kotlin.random.Random
+
+/**
+ * Continuous radio after a queue ends: prefer the seed artist, avoid repeating
+ * the same LP / EP / Single too soon, weighted random among the rest.
+ *
+ * Entropy levers ([RadioPlaybackConfig]):
+ * 1. **Hard per-kind cooldown** — last N LPs / EPs / Singles never candidates
+ * 2. **Global cooldown** — last M releases of any kind excluded
+ * 3. **Soft history penalty** — older plays still eligible but down-weighted
+ * 4. **Type weights** — bias toward LPs vs singles
+ * 5. **Weighted sample** — not uniform; uses (typeWeight × softPenalty)
+ *
+ * Future settings UI can expose these without changing the algorithm class.
+ */
+class RadioPlaybackAlgorithm(
+    var config: RadioPlaybackConfig = RadioPlaybackConfig()
+) : RadioAlgorithm {
+
+    override val id: RadioAlgorithmId = RadioAlgorithmId.PLAYBACK
+
+    override fun pick(
+        catalog: ReleaseCatalog,
+        context: RadioContext,
+        memory: RecentReleaseMemory
+    ): RadioPick? {
+        val focus = context.focusArtistKeys
+        if (focus.isEmpty()) {
+            log.i { "no focus artists" }
+            return null
+        }
+
+        val all = catalog.albums().filter { it.songs.isNotEmpty() }
+        val sameArtist = all.filter { albumMatchesFocus(it, focus) }
+        if (sameArtist.isEmpty()) {
+            log.i { "no albums for focus=$focus" }
+            return null
+        }
+
+        val softOrder = memory.softOrderNewestFirst()
+        val softIndex = softOrder.mapIndexed { i, k -> k.lowercase() to i }.toMap()
+
+        data class Cand(val album: AlbumItem, val key: String, val kind: ReleaseKind, val weight: Double)
+
+        val candidates = sameArtist.mapNotNull { album ->
+            val key = ReleaseClassifier.releaseKey(album)
+            val kind = ReleaseClassifier.kindOf(album)
+            val hard = memory.hardExclude(
+                kind = kind,
+                perKind = perKindLimit(kind),
+                globalCount = config.globalRecentExclude
+            )
+            if (key in hard || hard.any { it.equals(key, true) }) return@mapNotNull null
+
+            val typeW = typeWeight(kind).toDouble().coerceAtLeast(0.01)
+            val softIdx = softIndex[key.lowercase()]
+            val softW = if (softIdx == null) {
+                1.0
+            } else {
+                config.softPenaltyFactor.toDouble().pow(softIdx + 1)
+                    .coerceAtLeast(0.05)
+            }
+            Cand(album, key, kind, typeW * softW)
+        }
+
+        if (candidates.isEmpty()) {
+            // Exhausted hard filters — fall back to anything same-artist except
+            // the single most recent global key so radio never dead-ends.
+            val last = memory.softOrderNewestFirst().firstOrNull()
+            val fallback = sameArtist.filter {
+                ReleaseClassifier.releaseKey(it) != last
+            }.ifEmpty { sameArtist }
+            val album = fallback[Random.nextInt(fallback.size)]
+            return toPick(album, "fallback-after-cooldown")
+        }
+
+        val picked = weightedSample(candidates) { it.weight } ?: return null
+        return toPick(picked.album, "weighted kind=${picked.kind} w=${"%.2f".format(picked.weight)}")
+    }
+
+    private fun perKindLimit(kind: ReleaseKind): Int = when (kind) {
+        ReleaseKind.LP -> config.avoidRecentLps
+        ReleaseKind.EP -> config.avoidRecentEps
+        ReleaseKind.SINGLE -> config.avoidRecentSingles
+        ReleaseKind.UNKNOWN -> config.globalRecentExclude
+    }
+
+    private fun typeWeight(kind: ReleaseKind): Float = when (kind) {
+        ReleaseKind.LP -> config.weightLp
+        ReleaseKind.EP -> config.weightEp
+        ReleaseKind.SINGLE -> config.weightSingle
+        ReleaseKind.UNKNOWN -> 0.5f
+    }
+
+    private fun albumMatchesFocus(album: AlbumItem, focus: Set<String>): Boolean {
+        val a = artistKey(album.artist)
+        if (a != null && a in focus) return true
+        return album.songs.any { song ->
+            artistKey(song.effectiveAlbumArtist)?.let { it in focus } == true ||
+                artistKey(song.artist)?.let { it in focus } == true ||
+                song.creditArtists.any { artistKey(it)?.let { k -> k in focus } == true }
+        }
+    }
+
+    private fun toPick(album: AlbumItem, reason: String): RadioPick {
+        val key = ReleaseClassifier.releaseKey(album)
+        val kind = ReleaseClassifier.kindOf(album)
+        return RadioPick(
+            album = album,
+            source = ColdSource(
+                type = ColdSourceType.ALBUM,
+                id = key,
+                title = album.name
+            ),
+            kind = kind,
+            algorithmId = id.name,
+            reason = reason
+        )
+    }
+
+    private fun <T> weightedSample(items: List<T>, weight: (T) -> Double): T? {
+        if (items.isEmpty()) return null
+        val total = items.sumOf { weight(it).coerceAtLeast(0.0) }
+        if (total <= 0.0) return items[Random.nextInt(items.size)]
+        var r = Random.nextDouble() * total
+        for (item in items) {
+            r -= weight(item).coerceAtLeast(0.0)
+            if (r <= 0.0) return item
+        }
+        return items.last()
+    }
+
+    companion object {
+        private val log = yuriLog("RadioPlay")
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt
new file mode 100644
index 00000000..9736712d
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/RecentReleaseMemory.kt
@@ -0,0 +1,47 @@
+package capital.yuri.yuriplayer.player.radio
+
+/**
+ * Per-kind + global recent release keys for hard cooldowns and soft weighting.
+ * In-memory for now; RadioEngine can persist later with playback state.
+ */
+class RecentReleaseMemory(
+    private val softCapacity: Int = 12
+) {
+    private val byKind = mutableMapOf<
+        ReleaseKind,
+        ArrayDeque<String>
+    >(
+        ReleaseKind.LP to ArrayDeque(),
+        ReleaseKind.EP to ArrayDeque(),
+        ReleaseKind.SINGLE to ArrayDeque(),
+        ReleaseKind.UNKNOWN to ArrayDeque()
+    )
+
+    private val global = ArrayDeque<String>()
+
+    fun note(key: String, kind: ReleaseKind) {
+        if (key.isBlank() || key == "|") return
+        push(byKind.getOrPut(kind) { ArrayDeque() }, key, max = 8)
+        push(global, key, max = softCapacity.coerceAtLeast(8))
+    }
+
+    fun hardExclude(
+        kind: ReleaseKind,
+        perKind: Int,
+        globalCount: Int
+    ): Set<String> = buildSet {
+        byKind[kind]?.takeLast(perKind.coerceAtLeast(0))?.let { addAll(it) }
+        global.takeLast(globalCount.coerceAtLeast(0)).let { addAll(it) }
+    }
+
+    /** Index 0 = most recent. Used for soft weight decay. */
+    fun softOrderNewestFirst(): List<String> = global.toList().asReversed()
+
+    fun lastOf(kind: ReleaseKind): String? = byKind[kind]?.lastOrNull()
+
+    private fun push(q: ArrayDeque<String>, key: String, max: Int) {
+        q.removeAll { it.equals(key, ignoreCase = true) }
+        q.addLast(key)
+        while (q.size > max) q.removeFirst()
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt
new file mode 100644
index 00000000..859be4e2
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/ReleaseClassifier.kt
@@ -0,0 +1,26 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.data.AlbumItem
+
+/**
+ * Heuristic release typing until tags/MB release-group types are reliable.
+ * Matches the Spotify-ish bands we already use on artist pages.
+ */
+object ReleaseClassifier {
+
+    fun kindOf(album: AlbumItem): ReleaseKind {
+        val n = album.trackCount
+        return when {
+            n <= 0 -> ReleaseKind.UNKNOWN
+            n == 1 -> ReleaseKind.SINGLE
+            n <= 6 -> ReleaseKind.EP
+            else -> ReleaseKind.LP
+        }
+    }
+
+    fun releaseKey(album: AlbumItem): String {
+        val a = (album.artist ?: "").trim().lowercase()
+        val n = (album.name ?: "").trim().lowercase()
+        return "$a|$n"
+    }
+}
diff --git a/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt
new file mode 100644
index 00000000..61113ee4
--- /dev/null
+++ b/core/src/commonMain/kotlin/capital/yuri/yuriplayer/player/radio/ReleasePoolAlgorithm.kt
@@ -0,0 +1,112 @@
+package capital.yuri.yuriplayer.player.radio
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.AlbumItem
+import capital.yuri.yuriplayer.data.artistKey
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.ColdSourceType
+import kotlin.random.Random
+
+/**
+ * Draws random releases from a user-defined artist (and later genre) pool.
+ * Used for playlist-derived radios and explicit “station” configs.
+ *
+ * Network: [ExternalReleaseSource] is consulted only when
+ * [ReleasePoolConfig.allowExternalFetch] is true **and** the source is enabled.
+ * Default is local-only — privacy gate stays closed until the user opts in.
+ */
+class ReleasePoolAlgorithm(
+    var config: ReleasePoolConfig = ReleasePoolConfig(),
+    private val external: ExternalReleaseSource = NoExternalReleaseSource
+) : RadioAlgorithm {
+
+    override val id: RadioAlgorithmId = RadioAlgorithmId.RELEASE_POOL
+
+    override fun pick(
+        catalog: ReleaseCatalog,
+        context: RadioContext,
+        memory: RecentReleaseMemory
+    ): RadioPick? {
+        val artistFocus = (config.artistKeys.mapNotNull { artistKey(it) } +
+            context.focusArtistKeys).toSet()
+
+        if (artistFocus.isEmpty() && config.genreKeys.isEmpty()) {
+            log.i { "empty pool" }
+            return null
+        }
+
+        var pool = catalog.albums().filter { it.songs.isNotEmpty() }
+
+        if (artistFocus.isNotEmpty()) {
+            pool = pool.filter { albumMatchesArtists(it, artistFocus) }
+        }
+        if (config.genreKeys.isNotEmpty()) {
+            val genreNorm = config.genreKeys.map { it.lowercase() }.toSet()
+            pool = pool.filter { albumMatchesGenres(it, genreNorm) }
+        }
+
+        pool = pool.filter { album ->
+            when (ReleaseClassifier.kindOf(album)) {
+                ReleaseKind.LP -> config.includeLps
+                ReleaseKind.EP -> config.includeEps
+                ReleaseKind.SINGLE -> config.includeSingles
+                ReleaseKind.UNKNOWN -> true
+            }
+        }
+
+        if (config.allowExternalFetch && external.isEnabled) {
+            // Stub: merge external candidates when privacy gate opens.
+            val remote = external.fetchCandidates(context)
+            if (remote.isNotEmpty()) {
+                log.i { "external returned ${remote.size} (not persisted)" }
+                pool = pool + remote.filter { it.songs.isNotEmpty() }
+            }
+        }
+
+        if (pool.isEmpty()) {
+            log.i { "no local releases in pool artists=$artistFocus" }
+            return null
+        }
+
+        val filtered = pool.filter { album ->
+            val key = ReleaseClassifier.releaseKey(album)
+            val kind = ReleaseClassifier.kindOf(album)
+            val hard = memory.hardExclude(
+                kind = kind,
+                perKind = config.avoidRecentPerKind,
+                globalCount = config.avoidRecentPerKind
+            )
+            key !in hard && hard.none { it.equals(key, true) }
+        }.ifEmpty { pool }
+
+        val album = filtered[Random.nextInt(filtered.size)]
+        val key = ReleaseClassifier.releaseKey(album)
+        val kind = ReleaseClassifier.kindOf(album)
+        log.i { "pool pick '${album.displayName}' kind=$kind from ${filtered.size}" }
+        return RadioPick(
+            album = album,
+            source = ColdSource(ColdSourceType.ALBUM, key, album.name),
+            kind = kind,
+            algorithmId = id.name,
+            reason = "pool artists=${artistFocus.size}"
+        )
+    }
+
+    private fun albumMatchesArtists(album: AlbumItem, focus: Set<String>): Boolean {
+        artistKey(album.artist)?.let { if (it in focus) return true }
+        return album.songs.any { song ->
+            artistKey(song.effectiveAlbumArtist)?.let { it in focus } == true ||
+                artistKey(song.artist)?.let { it in focus } == true ||
+                song.creditArtists.any { artistKey(it)?.let { k -> k in focus } == true }
+        }
+    }
+
+    private fun albumMatchesGenres(album: AlbumItem, genreNorm: Set<String>): Boolean =
+        album.songs.any { song ->
+            song.genres.any { it.lowercase() in genreNorm }
+        }
+
+    companion object {
+        private val log = yuriLog("RadioPool")
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistInfoClient.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistInfoClient.kt
new file mode 100644
index 00000000..cf5249fe
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistInfoClient.kt
@@ -0,0 +1,522 @@
+package capital.yuri.yuriplayer.core.artist
+
+import capital.yuri.yuriplayer.core.http.url
+import io.ktor.client.HttpClient
+import io.ktor.client.request.get
+import io.ktor.client.request.header
+import io.ktor.client.statement.bodyAsBytes
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.HttpHeaders
+import io.ktor.http.isSuccess
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.async
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.contentOrNull
+import kotlinx.serialization.json.jsonArray
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.json.jsonPrimitive
+
+/**
+ * Same public sources as mobile: Wikipedia, TheAudioDB, Deezer, MusicBrainz, Wikidata,
+ * plus library servers (Jellyfin / Navidrome) supplied by the host.
+ */
+class ArtistInfoClient(
+    private val http: HttpClient,
+    private val store: ArtistProfileStore,
+    private val libraryImages: suspend (String) -> List<ArtistImageCandidate> = { emptyList() }
+) {
+    private val json = Json { ignoreUnknownKeys = true; isLenient = true }
+
+    suspend fun resolve(name: String, force: Boolean = false): ArtistProfile = withContext(Dispatchers.IO) {
+        val cached = store.load(name)
+        val bannerLooksWrong = cached?.bannerUri.let { uri ->
+            uri.isNullOrBlank() ||
+                uri.contains("wikipedia", true) ||
+                uri.contains("wikimedia", true)
+        }
+        val fresh = cached != null &&
+            !force &&
+            !bannerLooksWrong &&
+            (System.currentTimeMillis() - cached.updatedAtMs) < CACHE_TTL_MS &&
+            (!cached.bio.isNullOrBlank() || !cached.bannerUri.isNullOrBlank() || cached.bannerCleared)
+        if (fresh && cached != null) return@withContext cached
+
+        val remote = fetchRemote(name)
+        var merged = merge(name, cached, remote)
+        if (!merged.bannerCleared) {
+            val wide = pickWideBanner(name, merged.bannerUri)
+            if (wide != null) merged = merged.copy(bannerUri = wide)
+        }
+        store.save(merged)
+        merged
+    }
+
+    suspend fun bannerCandidates(name: String): List<ArtistImageCandidate> = withContext(Dispatchers.IO) {
+        coroutineScope {
+            val wiki = async { wikipediaImages(name) }
+            val adb = async { audioDbImages(name) }
+            val deezer = async { deezerImages(name) }
+            val mb = async { musicBrainzImages(name) }
+            val wd = async { wikidataImages(name) }
+            val lib = async { runCatching { libraryImages(name) }.getOrDefault(emptyList()) }
+            (adb.await() + lib.await() + wiki.await() + deezer.await() + mb.await() + wd.await())
+                .distinctBy { it.url }
+                .sortedByDescending { it.headerScore() }
+        }
+    }
+
+    suspend fun applyBannerUrl(name: String, url: String): ArtistProfile {
+        val bytes = getBytes(url) ?: error("Couldn't download image")
+        val uri = store.writeBannerBytes(name, bytes) ?: error("Couldn't save banner")
+        val current = store.load(name) ?: ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = name
+        )
+        val next = current.copy(
+            bannerUri = uri,
+            bannerCleared = false,
+            source = listOf(current.source, "user").filter { it.isNotBlank() }.distinct().joinToString(","),
+            updatedAtMs = System.currentTimeMillis()
+        )
+        store.save(next)
+        return next
+    }
+
+    fun applyLocalBanner(name: String, file: java.io.File): ArtistProfile {
+        val uri = store.setLocalBanner(name, file) ?: error("Couldn't save banner")
+        val current = store.load(name) ?: ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = name
+        )
+        val next = current.copy(
+            bannerUri = uri,
+            bannerCleared = false,
+            source = "user",
+            updatedAtMs = System.currentTimeMillis()
+        )
+        store.save(next)
+        return next
+    }
+
+    fun clearBanner(name: String): ArtistProfile {
+        store.clearBanner(name)
+        val current = store.load(name) ?: ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = name
+        )
+        val next = current.copy(
+            bannerUri = null,
+            bannerCleared = true,
+            updatedAtMs = System.currentTimeMillis()
+        )
+        store.save(next)
+        return next
+    }
+
+    private suspend fun fetchRemote(name: String): ArtistProfile {
+        return coroutineScope {
+            val parts = listOf(
+                async { wikipediaProfile(name) },
+                async { audioDbProfile(name) },
+                async { musicBrainzProfile(name) },
+                async { wikidataProfile(name) }
+            ).map { runCatching { it.await() }.getOrNull() }
+            parts.fold(null as ArtistProfile?) { acc, p -> merge(name, acc, p) }
+                ?: ArtistProfile(
+                    artistKey = artistKey(name) ?: name.lowercase(),
+                    displayName = name.trim(),
+                    updatedAtMs = System.currentTimeMillis()
+                )
+        }
+    }
+
+    private fun merge(name: String, a: ArtistProfile?, b: ArtistProfile?): ArtistProfile {
+        val key = artistKey(name) ?: name.lowercase()
+        if (a == null && b == null) {
+            return ArtistProfile(artistKey = key, displayName = name.trim(), updatedAtMs = System.currentTimeMillis())
+        }
+        if (a == null) return b!!.copy(updatedAtMs = System.currentTimeMillis())
+        if (b == null) return a.copy(updatedAtMs = System.currentTimeMillis())
+        return a.copy(
+            displayName = a.displayName.ifBlank { b.displayName },
+            bio = preferBio(a.bio, b.bio),
+            imageUri = a.imageUri ?: b.imageUri,
+            bannerUri = when {
+                a.bannerCleared -> null
+                a.bannerUri.isWideHeaderUrl() -> a.bannerUri
+                b.bannerUri.isWideHeaderUrl() -> b.bannerUri
+                !a.bannerUri.isNullOrBlank() && !a.bannerUri.isPortraitSource() -> a.bannerUri
+                else -> b.bannerUri?.takeUnless { it.isPortraitSource() }
+            },
+            genres = (a.genres + b.genres).map { it.trim() }.filter { it.isNotEmpty() }.distinctBy { it.lowercase() },
+            source = listOf(a.source, b.source).filter { it.isNotBlank() }.distinct().joinToString(","),
+            bannerCleared = a.bannerCleared,
+            updatedAtMs = System.currentTimeMillis()
+        )
+    }
+
+    private fun preferBio(a: String?, b: String?): String? {
+        val aa = a?.trim()?.takeIf { it.isNotBlank() }
+        val bb = b?.trim()?.takeIf { it.isNotBlank() }
+        if (aa == null) return bb
+        if (bb == null) return aa
+        return if (aa.length >= bb.length) aa else bb
+    }
+
+    private suspend fun wikipediaProfile(name: String): ArtistProfile? {
+        val summary = wikipediaSummary(name) ?: return null
+        val title = summary.str("title") ?: name
+        val extract = summary.str("extract")?.takeIf { it.isNotBlank() } ?: return null
+        if (isWork(summary.str("description"), extract)) return null
+        val image = summary.obj("originalimage")?.str("source")
+            ?: summary.obj("thumbnail")?.str("source")
+        val banner = summary.obj("originalimage")?.let { img ->
+            val w = img.int("width") ?: 0
+            val h = img.int("height") ?: 1
+            if (h > 0 && w.toFloat() / h >= 2.4f) img.str("source") else null
+        }
+        return ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = title,
+            bio = extract,
+            imageUri = image,
+            bannerUri = banner,
+            source = "wikipedia"
+        )
+    }
+
+    private suspend fun wikipediaImages(name: String): List<ArtistImageCandidate> {
+        val summary = wikipediaSummary(name) ?: return emptyList()
+        val title = summary.str("title") ?: name
+        val out = ArrayList<ArtistImageCandidate>()
+        summary.obj("originalimage")?.str("source")?.let {
+            out += ArtistImageCandidate(it, "wikipedia", "Wikipedia · $title", summary.obj("originalimage")?.int("width"), summary.obj("originalimage")?.int("height"))
+        }
+        summary.obj("thumbnail")?.str("source")?.let {
+            out += ArtistImageCandidate(it, "wikipedia", "Wikipedia thumb · $title")
+        }
+        return out
+    }
+
+    private suspend fun wikipediaSummary(name: String): JsonObject? {
+        val titles = listOf(
+            name.trim(),
+            "${name.trim()} (band)",
+            "${name.trim()} (musician)",
+            "${name.trim()} (duo)"
+        )
+        for (title in titles) {
+            val requestUrl = url("https://en.wikipedia.org") {
+                path("api", "rest_v1", "page", "summary", title.replace(' ', '_'), encodeSlash = true)
+            }
+            val body = getText(requestUrl) ?: continue
+            val root = runCatching { json.parseToJsonElement(body).jsonObject }.getOrNull() ?: continue
+            if (root.str("type") == "disambiguation") continue
+            val desc = root.str("description").orEmpty()
+            val extract = root.str("extract").orEmpty()
+            if (isWork(desc, extract)) continue
+            if (root.str("title").isNullOrBlank()) continue
+            return root
+        }
+        return null
+    }
+
+    private suspend fun audioDbProfile(name: String): ArtistProfile? {
+        val a = audioDbArtist(name) ?: return null
+        val bio = a.str("strBiographyEN")?.takeIf { it.isNotBlank() && it != "null" }
+        val banner = listOf("strArtistBanner", "strArtistFanart", "strArtistFanart2", "strArtistFanart3", "strArtistWideThumb")
+            .firstNotNullOfOrNull { field -> a.str(field)?.takeIf { it.isNotBlank() && it != "null" } }
+        val thumb = a.str("strArtistThumb")?.takeIf { it.isNotBlank() && it != "null" }
+        val genres = buildList {
+            a.str("strGenre")?.takeIf { it != "null" }?.let { add(it) }
+            a.str("strStyle")?.takeIf { it != "null" }?.let { add(it) }
+        }.flatMap { it.split(',', '/', '|') }.map { it.trim() }.filter { it.isNotEmpty() }.distinctBy { it.lowercase() }
+        return ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = a.str("strArtist")?.ifBlank { name } ?: name,
+            bio = bio,
+            imageUri = thumb,
+            bannerUri = banner,
+            genres = genres,
+            source = "theaudiodb"
+        )
+    }
+
+    private suspend fun audioDbImages(name: String): List<ArtistImageCandidate> {
+        val a = audioDbArtist(name) ?: return emptyList()
+        val display = a.str("strArtist") ?: name
+        val fields = listOf(
+            "strArtistBanner" to "AudioDB banner",
+            "strArtistFanart" to "AudioDB fanart",
+            "strArtistFanart2" to "AudioDB fanart 2",
+            "strArtistFanart3" to "AudioDB fanart 3",
+            "strArtistWideThumb" to "AudioDB wide"
+        )
+        return fields.mapNotNull { (field, label) ->
+            val u = a.str(field)?.takeIf { it.isNotBlank() && it != "null" } ?: return@mapNotNull null
+            val banner = label.contains("banner", true)
+            ArtistImageCandidate(
+                u, "theaudiodb", "$label · $display",
+                width = if (banner) 1500 else 1280,
+                height = if (banner) 500 else 720
+            )
+        }
+    }
+
+    private suspend fun audioDbArtist(name: String): JsonObject? {
+        val requestUrl = url("https://www.theaudiodb.com") {
+            path("api", "v1", "json", "2", "search.php")
+            param("s", name.trim())
+        }
+        val body = getText(requestUrl) ?: return null
+        val root = runCatching { json.parseToJsonElement(body).jsonObject }.getOrNull() ?: return null
+        return root["artists"]?.jsonArray?.firstOrNull()?.jsonObject
+    }
+
+    private suspend fun deezerImages(name: String): List<ArtistImageCandidate> {
+        val requestUrl = url("https://api.deezer.com") {
+            path("search", "artist")
+            param("q", name.trim())
+            param("limit", 8)
+        }
+        val body = getText(requestUrl) ?: return emptyList()
+        val data = runCatching { json.parseToJsonElement(body).jsonObject["data"]?.jsonArray }.getOrNull()
+            ?: return emptyList()
+        val out = ArrayList<ArtistImageCandidate>()
+        for (el in data) {
+            val a = el.jsonObject
+            val artistName = a.str("name") ?: continue
+            val pic = listOf("picture_xl", "picture_big", "picture_medium")
+                .firstNotNullOfOrNull { a.str(it) }
+                ?.takeIf { !it.contains("artist-default") } ?: continue
+            out += ArtistImageCandidate(pic, "deezer", "Deezer · $artistName", 1000, 1000)
+        }
+        return out
+    }
+
+    private suspend fun musicBrainzProfile(name: String): ArtistProfile? {
+        val searchUrl = url("https://musicbrainz.org") {
+            path("ws", "2", "artist")
+            param("query", "artist:\"${name.trim()}\"")
+            param("fmt", "json")
+            param("limit", 3)
+        }
+        val body = getText(searchUrl) ?: return null
+        val artists = runCatching { json.parseToJsonElement(body).jsonObject["artists"]?.jsonArray }.getOrNull()
+            ?: return null
+        val first = artists.firstOrNull()?.jsonObject ?: return null
+        val mbid = first.str("id") ?: return null
+        val display = first.str("name") ?: name
+        val genres = first["tags"]?.jsonArray.orEmpty().mapNotNull {
+            it.jsonObject.str("name")
+        }.take(8)
+        val detailUrl = url("https://musicbrainz.org") {
+            path("ws", "2", "artist", mbid)
+            param("inc", "url-rels+tags+genres")
+            param("fmt", "json")
+        }
+        val detailBody = getText(detailUrl)
+        val detail = detailBody?.let { runCatching { json.parseToJsonElement(it).jsonObject }.getOrNull() }
+        val moreGenres = detail?.get("genres")?.jsonArray.orEmpty().mapNotNull { it.jsonObject.str("name") }
+        val relations = detail?.get("relations")?.jsonArray
+        var wikiImage: String? = null
+        relations?.forEach { rel ->
+            val obj = rel.jsonObject
+            val type = obj.str("type").orEmpty()
+            val urlStr = obj.obj("url")?.str("resource") ?: return@forEach
+            if (type.contains("wikidata", true)) {
+                val qid = Regex("Q\\d+").find(urlStr)?.value
+                if (qid != null) wikiImage = wikidataP18(qid).firstOrNull()
+            }
+        }
+        return ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = display,
+            imageUri = wikiImage,
+            genres = (genres + moreGenres).distinctBy { it.lowercase() },
+            source = "musicbrainz"
+        )
+    }
+
+    private suspend fun musicBrainzImages(name: String): List<ArtistImageCandidate> {
+        val p = musicBrainzProfile(name) ?: return emptyList()
+        val url = p.imageUri ?: return emptyList()
+        return listOf(ArtistImageCandidate(url, "musicbrainz", "MusicBrainz · ${p.displayName}"))
+    }
+
+    private suspend fun wikidataProfile(name: String): ArtistProfile? {
+        val qid = wikidataSearch(name) ?: return null
+        val genres = wikidataGenres(qid)
+        val images = wikidataP18(qid)
+        return ArtistProfile(
+            artistKey = artistKey(name) ?: name.lowercase(),
+            displayName = name.trim(),
+            imageUri = images.firstOrNull(),
+            genres = genres,
+            source = "wikidata"
+        )
+    }
+
+    private suspend fun wikidataImages(name: String): List<ArtistImageCandidate> {
+        val qid = wikidataSearch(name) ?: return emptyList()
+        return wikidataP18(qid).mapIndexed { i, u ->
+            ArtistImageCandidate(u, "wikidata", "Wikidata P18${if (i > 0) " #${i + 1}" else ""} · $name")
+        }
+    }
+
+    private suspend fun wikidataSearch(name: String): String? {
+        val requestUrl = url("https://www.wikidata.org") {
+            path("w", "api.php")
+            param("action", "wbsearchentities")
+            param("search", name.trim())
+            param("language", "en")
+            param("type", "item")
+            param("limit", 8)
+            param("format", "json")
+        }
+        val body = getText(requestUrl) ?: return null
+        val search = runCatching { json.parseToJsonElement(body).jsonObject["search"]?.jsonArray }.getOrNull()
+            ?: return null
+        val hints = listOf("musician", "singer", "rapper", "band", "duo", "group", "artist", "dj")
+        val works = listOf("album", "song", "single", "ep", "soundtrack")
+        for (el in search) {
+            val o = el.jsonObject
+            val id = o.str("id") ?: continue
+            if (!id.startsWith("Q")) continue
+            val desc = o.str("description").orEmpty().lowercase()
+            if (works.any { desc.contains(it) } && hints.none { desc.contains(it) }) continue
+            return id
+        }
+        return search.firstOrNull()?.jsonObject?.str("id")
+    }
+
+    private suspend fun wikidataP18(qid: String): List<String> {
+        val claims = wikidataClaims(qid) ?: return emptyList()
+        val p18 = claims["P18"]?.jsonArray ?: return emptyList()
+        return p18.mapNotNull { claim ->
+            val file = claim.jsonObject.obj("mainsnak")?.obj("datavalue")?.str("value") ?: return@mapNotNull null
+            url("https://commons.wikimedia.org") {
+                path("wiki", "Special:FilePath", file.replace(' ', '_'), encodeSlash = true)
+                param("width", 1200)
+            }
+        }
+    }
+
+    private suspend fun wikidataGenres(qid: String): List<String> {
+        val claims = wikidataClaims(qid) ?: return emptyList()
+        val p136 = claims["P136"]?.jsonArray ?: return emptyList()
+        val ids = p136.mapNotNull { claim ->
+            claim.jsonObject.obj("mainsnak")?.obj("datavalue")?.obj("value")?.str("id")
+        }.take(10)
+        if (ids.isEmpty()) return emptyList()
+        val requestUrl = url("https://www.wikidata.org") {
+            path("w", "api.php")
+            param("action", "wbgetentities")
+            param("ids", ids.joinToString("|"))
+            param("props", "labels")
+            param("languages", "en")
+            param("format", "json")
+        }
+        val body = getText(requestUrl) ?: return emptyList()
+        val entities = runCatching { json.parseToJsonElement(body).jsonObject["entities"]?.jsonObject }.getOrNull()
+            ?: return emptyList()
+        return ids.mapNotNull { id ->
+            entities[id]?.jsonObject?.obj("labels")?.obj("en")?.str("value")
+        }
+    }
+
+    private suspend fun wikidataClaims(qid: String): JsonObject? {
+        val requestUrl = url("https://www.wikidata.org") {
+            path("w", "api.php")
+            param("action", "wbgetentities")
+            param("ids", qid)
+            param("props", "claims")
+            param("format", "json")
+        }
+        val body = getText(requestUrl) ?: return null
+        return runCatching {
+            json.parseToJsonElement(body).jsonObject["entities"]?.jsonObject
+                ?.get(qid)?.jsonObject?.obj("claims")
+        }.getOrNull()
+    }
+
+    private suspend fun pickWideBanner(name: String, current: String?): String? {
+        if (current.isWideHeaderUrl() && !current.isPortraitSource()) return current
+        val cands = runCatching { bannerCandidates(name) }.getOrDefault(emptyList())
+        return cands.firstOrNull { it.headerScore() >= 50 }?.url
+            ?: current?.takeUnless { it.isPortraitSource() }
+    }
+
+    private fun ArtistImageCandidate.headerScore(): Int {
+        val w = width ?: 0
+        val h = height ?: 0
+        val ratio = if (h > 0) w.toFloat() / h else 0f
+        val label = label.lowercase()
+        var score = 0
+        if (ratio >= 2.4f) score += 80
+        else if (ratio >= 1.7f) score += 50
+        else if (ratio in 0.01f..0.99f) score -= 40
+        if (label.contains("banner")) score += 40
+        if (label.contains("fanart") || label.contains("backdrop") || label.contains("wide")) score += 25
+        if (sourceId == "theaudiodb" || sourceId == "jellyfin") score += 10
+        if (sourceId == "wikipedia" || sourceId == "wikidata" || sourceId == "deezer") score -= 20
+        return score
+    }
+
+    private fun String?.isWideHeaderUrl(): Boolean {
+        val u = this ?: return false
+        if (u.startsWith("file:")) return true
+        return u.contains("banner", true) || u.contains("fanart", true) || u.contains("Backdrop", true)
+    }
+
+    private fun String?.isPortraitSource(): Boolean {
+        val u = this ?: return false
+        return u.contains("wikipedia", true) ||
+            u.contains("wikimedia", true) ||
+            u.contains("deezer.com", true)
+    }
+
+    private fun kotlinx.serialization.json.JsonArray?.orEmpty() =
+        this ?: kotlinx.serialization.json.JsonArray(emptyList())
+
+    private fun isWork(description: String?, extract: String): Boolean {
+        val d = (description.orEmpty() + " " + extract.take(280)).lowercase()
+        val work = listOf(" album", " song by", " single by", " ep by", " soundtrack", " mixtape")
+        val artist = listOf("musician", "singer", "rapper", "band", "duo", "group", "artist", "dj")
+        if (work.any { d.contains(it) } && artist.none { d.contains(it) }) return true
+        return false
+    }
+
+    private suspend fun getText(url: String): String? = runCatching {
+        val response = http.get(url) {
+            header(HttpHeaders.UserAgent, USER_AGENT)
+            header(HttpHeaders.Accept, "application/json")
+        }
+        if (response.status.isSuccess()) response.bodyAsText() else null
+    }.getOrNull()
+
+    private suspend fun getBytes(url: String): ByteArray? = runCatching {
+        val response = http.get(url) {
+            header(HttpHeaders.UserAgent, USER_AGENT)
+        }
+        if (response.status.isSuccess()) response.bodyAsBytes() else null
+    }.getOrNull()
+
+    private fun JsonObject.str(key: String): String? =
+        this[key]?.jsonPrimitive?.contentOrNull?.takeIf { it.isNotBlank() }
+
+    private fun JsonObject.int(key: String): Int? =
+        this[key]?.jsonPrimitive?.contentOrNull?.toIntOrNull()
+
+    private fun JsonObject.obj(key: String): JsonObject? =
+        this[key]?.jsonObject
+
+    companion object {
+        private const val CACHE_TTL_MS = 14L * 24 * 60 * 60 * 1000
+        private const val USER_AGENT =
+            "YuriPlayer/1.0 (desktop; https://github.com/LizAinslie/yuriplayer)"
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistProfileStore.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistProfileStore.kt
new file mode 100644
index 00000000..c79bba5f
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/artist/ArtistProfileStore.kt
@@ -0,0 +1,60 @@
+package capital.yuri.yuriplayer.core.artist
+
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+
+class ArtistProfileStore(configDir: String, cacheDir: String) {
+    private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
+    private val dir = File(configDir, "artists").also { it.mkdirs() }
+    private val bannerDir = File(cacheDir, "artist-banners").also { it.mkdirs() }
+
+    fun load(name: String): ArtistProfile? {
+        val key = artistKey(name) ?: return null
+        val file = File(dir, "$key.json")
+        if (!file.isFile) return null
+        return runCatching { json.decodeFromString<ArtistProfile>(file.readText()) }.getOrNull()
+    }
+
+    fun save(profile: ArtistProfile) {
+        runCatching {
+            File(dir, "${profile.artistKey}.json").writeText(json.encodeToString(profile))
+        }
+    }
+
+    fun bannerFile(name: String): File? {
+        val prefix = filePrefix(name) ?: return null
+        return bannerDir.listFiles()?.filter { it.name.startsWith(prefix) }?.maxByOrNull { it.lastModified() }
+    }
+
+    fun setLocalBanner(name: String, file: File): String? {
+        val prefix = filePrefix(name) ?: return null
+        return runCatching {
+            clearBannerFiles(prefix)
+            val dest = File(bannerDir, "$prefix-${System.currentTimeMillis()}.jpg")
+            file.copyTo(dest, overwrite = true)
+            dest.toURI().toString()
+        }.getOrNull()
+    }
+
+    fun writeBannerBytes(name: String, bytes: ByteArray): String? {
+        val prefix = filePrefix(name) ?: return null
+        return runCatching {
+            clearBannerFiles(prefix)
+            val dest = File(bannerDir, "$prefix-${System.currentTimeMillis()}.jpg")
+            dest.writeBytes(bytes)
+            dest.toURI().toString()
+        }.getOrNull()
+    }
+
+    fun clearBanner(name: String) {
+        filePrefix(name)?.let { clearBannerFiles(it) }
+    }
+
+    private fun filePrefix(name: String): String? =
+        artistKey(name)?.replace(Regex("[^a-z0-9]+"), "-")?.trim('-')?.takeIf { it.isNotEmpty() }
+
+    private fun clearBannerFiles(prefix: String) {
+        bannerDir.listFiles()?.filter { it.name.startsWith(prefix) }?.forEach { it.delete() }
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.kt
new file mode 100644
index 00000000..f0ce96c6
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/library/CoverPixels.kt
@@ -0,0 +1,64 @@
+package capital.yuri.yuriplayer.core.library
+
+import org.jaudiotagger.audio.AudioFileIO
+import java.awt.RenderingHints
+import java.awt.image.BufferedImage
+import java.io.ByteArrayInputStream
+import java.io.File
+import java.net.URI
+import javax.imageio.ImageIO
+
+actual fun sampleCoverArgb(artworkUri: String?, audioPath: String?, size: Int): IntArray? =
+    CoverPixels.argb(artworkUri, audioPath, size)
+
+/** Downsampled ARGB for theme extraction. Folder art first, then embedded. */
+object CoverPixels {
+    fun argb(artworkUri: String?, audioPath: String?, size: Int = 48): IntArray? {
+        val image = load(artworkUri) ?: loadEmbedded(audioPath) ?: return null
+        return downsample(image, size)
+    }
+
+    private fun load(uri: String?): BufferedImage? {
+        if (uri.isNullOrBlank()) return null
+        return try {
+            when {
+                uri.startsWith("http://", true) || uri.startsWith("https://", true) ->
+                    ImageIO.read(URI(uri).toURL())
+                uri.startsWith("file:") -> {
+                    val file = File(URI(uri))
+                    if (!file.isFile) null else ImageIO.read(file)
+                }
+                else -> {
+                    val file = File(uri)
+                    if (!file.isFile) null else ImageIO.read(file)
+                }
+            }
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun loadEmbedded(audioPath: String?): BufferedImage? {
+        if (audioPath.isNullOrBlank()) return null
+        val file = File(audioPath)
+        if (!file.isFile) return null
+        return try {
+            val art = AudioFileIO.read(file).tag?.firstArtwork ?: return null
+            val bytes = art.binaryData ?: return null
+            ImageIO.read(ByteArrayInputStream(bytes))
+        } catch (_: Exception) {
+            null
+        }
+    }
+
+    private fun downsample(src: BufferedImage, size: Int): IntArray {
+        val dst = BufferedImage(size, size, BufferedImage.TYPE_INT_ARGB)
+        val g = dst.createGraphics()
+        g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR)
+        g.drawImage(src, 0, 0, size, size, null)
+        g.dispose()
+        val pixels = IntArray(size * size)
+        dst.getRGB(0, 0, size, size, pixels, 0, size)
+        return pixels
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/library/LocalLibraryScanner.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/library/LocalLibraryScanner.kt
new file mode 100644
index 00000000..f976dc88
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/library/LocalLibraryScanner.kt
@@ -0,0 +1,153 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.core.platform.appDirectories
+import capital.yuri.yuriplayer.core.platform.coverCacheDir
+import capital.yuri.yuriplayer.data.Song
+import org.jaudiotagger.audio.AudioFileIO
+import org.jaudiotagger.tag.FieldKey
+import java.io.File
+import java.util.logging.Level
+import java.util.logging.Logger
+
+object LocalLibraryScanner {
+    const val SOURCE_LOCAL = "local"
+    private val AUDIO_EXTENSIONS = setOf(
+        "flac", "mp3", "ogg", "opus", "m4a", "mp4", "aac",
+        "wav", "aiff", "aif", "wma", "alac"
+    )
+    private val COVER_NAMES = listOf(
+        "cover.jpg", "cover.jpeg", "cover.png", "cover.webp",
+        "folder.jpg", "folder.jpeg", "folder.png",
+        "AlbumArt.jpg", "AlbumArt.png", "AlbumArtSmall.jpg",
+        "front.jpg", "front.png", "album.jpg", "album.png"
+    )
+    private val IMAGE_EXT = setOf("jpg", "jpeg", "png", "webp")
+
+    init {
+        Logger.getLogger("org.jaudiotagger").level = Level.OFF
+    }
+
+    fun defaultRoots(): List<File> =
+        appDirectories().defaultMusicRoots.map { File(it) }.filter { it.isDirectory }
+
+    fun scan(roots: List<File> = defaultRoots()): List<Song> = scanSongs(roots)
+
+    fun scanSongs(roots: List<File> = defaultRoots()): List<Song> {
+        if (roots.isEmpty()) return emptyList()
+        val out = ArrayList<Song>(512)
+        val seen = HashSet<String>()
+        val coverByDir = HashMap<String, String?>()
+        File(coverCacheDir()).mkdirs()
+        for (root in roots) {
+            if (!root.isDirectory) continue
+            root.walkTopDown()
+                .maxDepth(12)
+                .onEnter { dir -> !dir.isHidden && !dir.name.startsWith('.') }
+                .filter { it.isFile && it.extension.lowercase() in AUDIO_EXTENSIONS }
+                .forEach { file ->
+                    val path = file.absolutePath
+                    if (!seen.add(path)) return@forEach
+                    out += readSong(file, coverByDir)
+                }
+        }
+        out.sortWith(
+            compareBy<Song> { it.displayAlbum.lowercase() }
+                .thenBy { it.discNumber ?: 1 }
+                .thenBy { it.trackNumber ?: Int.MAX_VALUE }
+                .thenBy { it.displayTitle.lowercase() }
+        )
+        return out
+    }
+
+    private fun readSong(file: File, coverByDir: MutableMap<String, String?>): Song {
+        val fallbackTitle = file.nameWithoutExtension
+        return try {
+            val audio = AudioFileIO.read(file)
+            val tag = audio.tag
+            val header = audio.audioHeader
+            fun field(key: FieldKey): String? =
+                tag?.getFirst(key)?.trim()?.takeIf { it.isNotEmpty() }
+            Song(
+                id = file.absolutePath.hashCode().toLong(),
+                title = field(FieldKey.TITLE) ?: fallbackTitle,
+                artist = field(FieldKey.ARTIST),
+                albumArtist = field(FieldKey.ALBUM_ARTIST),
+                album = field(FieldKey.ALBUM),
+                durationMs = header?.trackLength?.toLong()?.times(1000),
+                contentUri = file.toURI().toString(),
+                albumArtUri = resolveCover(file, audio, coverByDir),
+                trackNumber = field(FieldKey.TRACK)?.substringBefore('/')?.toIntOrNull(),
+                discNumber = field(FieldKey.DISC_NO)?.substringBefore('/')?.toIntOrNull(),
+                year = field(FieldKey.YEAR)?.take(4)?.toIntOrNull(),
+                genre = field(FieldKey.GENRE),
+                path = file.absolutePath,
+                sourceId = SOURCE_LOCAL
+            )
+        } catch (_: Exception) {
+            Song(
+                id = file.absolutePath.hashCode().toLong(),
+                title = fallbackTitle,
+                contentUri = file.toURI().toString(),
+                albumArtUri = resolveCover(file, null, coverByDir),
+                path = file.absolutePath,
+                sourceId = SOURCE_LOCAL
+            )
+        }
+    }
+
+    private fun resolveCover(
+        file: File,
+        audio: org.jaudiotagger.audio.AudioFile?,
+        coverByDir: MutableMap<String, String?>
+    ): String? {
+        val dir = file.parentFile ?: return extractEmbedded(file, audio)
+        val key = dir.absolutePath
+        coverByDir[key]?.let { return it }
+        val folder = namedCover(dir) ?: namedCover(dir.parentFile) ?: firstImage(dir)
+        if (folder != null) {
+            val uri = folder.toURI().toString()
+            coverByDir[key] = uri
+            return uri
+        }
+        val embedded = extractEmbedded(file, audio)
+        coverByDir[key] = embedded
+        return embedded
+    }
+
+    private fun namedCover(dir: File?): File? {
+        if (dir == null || !dir.isDirectory) return null
+        for (name in COVER_NAMES) {
+            val f = File(dir, name)
+            if (f.isFile && f.length() > 32) return f
+        }
+        return null
+    }
+
+    private fun firstImage(dir: File): File? {
+        val images = dir.listFiles { f ->
+            f.isFile && f.extension.lowercase() in IMAGE_EXT && f.length() > 32 &&
+                !f.name.startsWith('.') &&
+                !f.name.contains("fanart", true) &&
+                !f.name.contains("artist", true) &&
+                !f.name.contains("logo", true)
+        } ?: return null
+        return images.minByOrNull { it.name.length }
+    }
+
+    private fun extractEmbedded(
+        file: File,
+        audio: org.jaudiotagger.audio.AudioFile?
+    ): String? {
+        val cache = File(coverCacheDir(), "${file.parentFile?.absolutePath.hashCode() and 0x7fffffff}.jpg")
+        if (cache.isFile && cache.length() > 32) return cache.toURI().toString()
+        return try {
+            val art = (audio ?: AudioFileIO.read(file)).tag?.firstArtwork ?: return null
+            val bytes = art.binaryData?.takeIf { it.size > 32 } ?: return null
+            cache.parentFile?.mkdirs()
+            cache.writeBytes(bytes)
+            cache.toURI().toString()
+        } catch (_: Exception) {
+            null
+        }
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.jvm.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.jvm.kt
new file mode 100644
index 00000000..781d0c1d
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/log/YuriLog.jvm.kt
@@ -0,0 +1,16 @@
+package capital.yuri.yuriplayer.core.log
+
+import org.slf4j.LoggerFactory
+
+actual fun platformLog(level: LogLevel, tag: String, message: String, throwable: Throwable?) {
+    val log = LoggerFactory.getLogger("YuriPlayer.$tag")
+    when (level) {
+        LogLevel.TRACE -> if (throwable != null) log.trace(message, throwable) else log.trace(message)
+        LogLevel.DEBUG -> if (throwable != null) log.debug(message, throwable) else log.debug(message)
+        LogLevel.INFO -> if (throwable != null) log.info(message, throwable) else log.info(message)
+        LogLevel.WARN -> if (throwable != null) log.warn(message, throwable) else log.warn(message)
+        LogLevel.ERROR -> if (throwable != null) log.error(message, throwable) else log.error(message)
+    }
+}
+
+actual fun platformLogEnabled(level: LogLevel): Boolean = true
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.jvm.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.jvm.kt
new file mode 100644
index 00000000..58d84d25
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectories.jvm.kt
@@ -0,0 +1,128 @@
+package capital.yuri.yuriplayer.core.platform
+
+import java.io.File
+import java.nio.file.Files
+import java.nio.file.Path
+import java.nio.file.Paths
+
+private const val APP_ID = "yuriplayer"
+private const val APP_NAME = "YuriPlayer"
+
+class JvmAppDirectories(
+    private val os: HostOs = hostOs()
+) : AppDirectories {
+
+    private val home: String
+        get() = System.getProperty("user.home") ?: "."
+
+    override val configDir: String
+        get() = when (os) {
+            HostOs.LINUX, HostOs.UNKNOWN ->
+                xdg("XDG_CONFIG_HOME", ".config") + File.separator + APP_ID
+            HostOs.MACOS ->
+                macLibrary("Application Support")
+            HostOs.WINDOWS ->
+                winAppData()
+            HostOs.ANDROID -> error("use AndroidAppDirectories")
+        }.also { File(it).mkdirs() }
+
+    override val cacheDir: String
+        get() = when (os) {
+            HostOs.LINUX, HostOs.UNKNOWN ->
+                xdg("XDG_CACHE_HOME", ".cache") + File.separator + APP_ID
+            HostOs.MACOS ->
+                macLibrary("Caches")
+            HostOs.WINDOWS ->
+                winLocalAppData() + File.separator + "Cache"
+            HostOs.ANDROID -> error("use AndroidAppDirectories")
+        }.also { File(it).mkdirs() }
+
+    override val dataDir: String
+        get() = when (os) {
+            HostOs.LINUX, HostOs.UNKNOWN ->
+                xdg("XDG_DATA_HOME", ".local/share") + File.separator + APP_ID
+            HostOs.MACOS ->
+                macLibrary("Application Support")
+            HostOs.WINDOWS ->
+                winLocalAppData()
+            HostOs.ANDROID -> error("use AndroidAppDirectories")
+        }.also { File(it).mkdirs() }
+
+    override val defaultMusicRoots: List<String>
+        get() = when (os) {
+            HostOs.LINUX, HostOs.UNKNOWN -> linuxMusicRoots()
+            HostOs.MACOS -> listOfNotNull(existing(File(home, "Music")))
+            HostOs.WINDOWS -> windowsMusicRoots()
+            HostOs.ANDROID -> emptyList()
+        }
+
+    private fun xdg(env: String, fallbackUnderHome: String): String {
+        val value = System.getenv(env)?.trim()?.takeIf { it.isNotEmpty() }
+        return value ?: (home + File.separator + fallbackUnderHome.replace('/', File.separatorChar))
+    }
+
+    private fun macLibrary(folder: String): String =
+        listOf(home, "Library", folder, APP_NAME).joinToString(File.separator)
+
+    private fun winAppData(): String {
+        val roaming = System.getenv("APPDATA")?.trim()?.takeIf { it.isNotEmpty() }
+        return (roaming ?: (home + File.separator + "AppData" + File.separator + "Roaming")) +
+            File.separator + APP_NAME
+    }
+
+    private fun winLocalAppData(): String {
+        val local = System.getenv("LOCALAPPDATA")?.trim()?.takeIf { it.isNotEmpty() }
+        return (local ?: (home + File.separator + "AppData" + File.separator + "Local")) +
+            File.separator + APP_NAME
+    }
+
+    private fun linuxMusicRoots(): List<String> {
+        val fromXdg = readXdgMusicDir()
+        val homeMusic = File(home, "Music").absolutePath
+        return listOfNotNull(fromXdg, homeMusic).distinct().filter { File(it).isDirectory }
+    }
+
+    private fun readXdgMusicDir(): String? {
+        val env = System.getenv("XDG_MUSIC_DIR")?.trim()?.takeIf { it.isNotEmpty() }
+        if (env != null) return expandHome(env)
+        val dirsFile = File(xdg("XDG_CONFIG_HOME", ".config"), "user-dirs.dirs")
+        if (!dirsFile.isFile) return null
+        dirsFile.useLines { lines ->
+            for (line in lines) {
+                val t = line.trim()
+                if (!t.startsWith("XDG_MUSIC_DIR")) continue
+                val raw = t.substringAfter('=').trim().trim('"')
+                return expandHome(raw)
+            }
+        }
+        return null
+    }
+
+    private fun windowsMusicRoots(): List<String> {
+        val userMusic = System.getenv("USERPROFILE")?.let { File(it, "Music") }
+            ?: File(home, "Music")
+        val publicMusic = System.getenv("PUBLIC")?.let { File(it, "Music") }
+        return listOfNotNull(existing(userMusic), publicMusic?.let { existing(it) })
+    }
+
+    private fun expandHome(raw: String): String {
+        if (raw.startsWith("\$HOME")) return home + raw.removePrefix("\$HOME")
+        if (raw.startsWith("~")) return home + raw.substring(1)
+        return raw
+    }
+
+    private fun existing(file: File): String? =
+        file.absolutePath.takeIf { file.isDirectory }
+
+    companion object {
+        fun ensure(path: String): Path {
+            val p = Paths.get(path)
+            Files.createDirectories(p)
+            return p
+        }
+    }
+}
+
+private val defaultDirs = JvmAppDirectories()
+
+actual fun appDirectories(): AppDirectories = defaultDirs
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.jvm.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.jvm.kt
new file mode 100644
index 00000000..c4c881b9
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/platform/HostOs.jvm.kt
@@ -0,0 +1,11 @@
+package capital.yuri.yuriplayer.core.platform
+
+actual fun hostOs(): HostOs {
+    val name = System.getProperty("os.name").orEmpty().lowercase()
+    return when {
+        name.contains("linux") -> HostOs.LINUX
+        name.contains("mac") || name.contains("darwin") -> HostOs.MACOS
+        name.contains("win") -> HostOs.WINDOWS
+        else -> HostOs.UNKNOWN
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/JellyfinCatalog.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/JellyfinCatalog.kt
new file mode 100644
index 00000000..b55806e5
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/JellyfinCatalog.kt
@@ -0,0 +1,293 @@
+package capital.yuri.yuriplayer.core.source
+
+import capital.yuri.yuriplayer.core.http.normalizeBaseUrl
+import capital.yuri.yuriplayer.core.http.url
+import capital.yuri.yuriplayer.data.Song
+import io.ktor.client.HttpClient
+import io.ktor.client.request.header
+import io.ktor.client.request.post
+import io.ktor.client.request.get
+import io.ktor.client.request.setBody
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.ContentType
+import io.ktor.http.content.TextContent
+import io.ktor.http.isSuccess
+import kotlinx.coroutines.ensureActive
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+
+class JellyfinCatalog(
+    private val http: HttpClient,
+    private val deviceId: String,
+    private val json: Json = Json { ignoreUnknownKeys = true; isLenient = true }
+) {
+    suspend fun authenticate(account: RemoteAccount): Result<RemoteAccount> = runCatching {
+        val root = normalizeBaseUrl(account.baseUrl)
+        val response = http.post("$root/Users/AuthenticateByName") {
+            header("X-Emby-Authorization", authHeader(token = null))
+            setBody(
+                TextContent(
+                    json.encodeToString(
+                        AuthRequest.serializer(),
+                        AuthRequest(account.username.trim(), account.secret)
+                    ),
+                    ContentType.Application.Json
+                )
+            )
+        }
+        if (!response.status.isSuccess()) {
+            if (response.status.value == 401) error("Invalid username or password")
+            error("Jellyfin HTTP ${response.status.value}")
+        }
+        val body = json.decodeFromString<AuthResponse>(response.bodyAsText())
+        val token = body.accessToken ?: error("No access token")
+        val userId = body.user?.id ?: error("No user id")
+        account.copy(
+            baseUrl = root,
+            accessToken = token,
+            userId = userId,
+            name = account.name.ifBlank { body.user?.name ?: "Jellyfin" }
+        )
+    }
+
+    suspend fun audioCount(account: RemoteAccount): Result<Int> = runCatching {
+        val token = account.accessToken ?: error("Not signed in")
+        val userId = account.userId ?: error("Not signed in")
+        val root = normalizeBaseUrl(account.baseUrl)
+        val requestUrl = url(root) {
+            path("Users", userId, "Items")
+            param("IncludeItemTypes", "Audio")
+            param("Recursive", "true")
+            param("Limit", 0)
+        }
+        val response = http.get(requestUrl) {
+            header("X-Emby-Authorization", authHeader(token))
+            header("X-Emby-Token", token)
+        }
+        if (!response.status.isSuccess()) error("Items HTTP ${response.status.value}")
+        json.decodeFromString<ItemsResponse>(response.bodyAsText()).total ?: 0
+    }
+
+    suspend fun listTracks(
+        account: RemoteAccount,
+        maxItems: Int = 50_000,
+        sortBy: String = "Album,SortName",
+        sortOrder: String = "Ascending",
+        startFrom: Int = 0,
+        onPage: suspend (page: List<Song>, cursor: Int, total: Int?) -> Unit = { _, _, _ -> }
+    ): Result<List<Song>> =
+        runCatching {
+            val token = account.accessToken ?: error("Not signed in")
+            val userId = account.userId ?: error("Not signed in")
+            val root = normalizeBaseUrl(account.baseUrl)
+            val out = ArrayList<Song>(512)
+            var start = startFrom.coerceAtLeast(0)
+            val pageSize = 400
+            while (out.size < maxItems) {
+                kotlinx.coroutines.currentCoroutineContext().ensureActive()
+                val take = minOf(pageSize, maxItems - out.size)
+                val requestUrl = url(root) {
+                    path("Users", userId, "Items")
+                    param("IncludeItemTypes", "Audio")
+                    param("Recursive", "true")
+                    param("Fields", "Album,AlbumArtist,Artists,RunTimeTicks,IndexNumber,ParentIndexNumber,ProductionYear,Genres,PrimaryImageAspectRatio,Container")
+                    param("EnableImageTypes", "Primary")
+                    param("ImageTypeLimit", "1")
+                    param("StartIndex", start)
+                    param("Limit", take)
+                    param("SortBy", sortBy)
+                    param("SortOrder", sortOrder)
+                }
+                val response = http.get(requestUrl) {
+                    header("X-Emby-Authorization", authHeader(token))
+                    header("X-Emby-Token", token)
+                }
+                if (!response.status.isSuccess()) error("Items HTTP ${response.status.value}")
+                val page = json.decodeFromString<ItemsResponse>(response.bodyAsText())
+                val items = page.items
+                if (items.isEmpty()) break
+                val mapped = items.mapNotNull { toSong(account.copy(baseUrl = root), it) }
+                out += mapped
+                start += items.size
+                onPage(mapped, start, page.total)
+                if (items.size < take) break
+                val total = page.total
+                if (total != null && start >= total) break
+            }
+            out
+        }
+
+    suspend fun searchTracks(account: RemoteAccount, query: String, limit: Int = 80): Result<List<Song>> =
+        runCatching {
+            val token = account.accessToken ?: error("Not signed in")
+            val userId = account.userId ?: error("Not signed in")
+            val root = normalizeBaseUrl(account.baseUrl)
+            val requestUrl = url(root) {
+                path("Users", userId, "Items")
+                param("SearchTerm", query)
+                param("IncludeItemTypes", "Audio")
+                param("Recursive", "true")
+                param("Fields", "Album,AlbumArtist,Artists,RunTimeTicks,IndexNumber,ParentIndexNumber,ProductionYear,Genres,PrimaryImageAspectRatio,Container")
+                param("EnableImageTypes", "Primary")
+                param("ImageTypeLimit", "1")
+                param("Limit", limit)
+            }
+            val response = http.get(requestUrl) {
+                header("X-Emby-Authorization", authHeader(token))
+                header("X-Emby-Token", token)
+            }
+            if (!response.status.isSuccess()) error("Search HTTP ${response.status.value}")
+            val page = json.decodeFromString<ItemsResponse>(response.bodyAsText())
+            page.items.mapNotNull { toSong(account.copy(baseUrl = root), it) }
+        }
+
+    suspend fun searchArtistImages(account: RemoteAccount, query: String): Result<List<capital.yuri.yuriplayer.core.artist.ArtistImageCandidate>> =
+        runCatching {
+            val token = account.accessToken ?: error("Not signed in")
+            val userId = account.userId ?: error("Not signed in")
+            val root = normalizeBaseUrl(account.baseUrl)
+            val requestUrl = url(root) {
+                path("Users", userId, "Items")
+                param("SearchTerm", query)
+                param("IncludeItemTypes", "MusicArtist")
+                param("Recursive", "true")
+                param("EnableImages", "true")
+                param("EnableImageTypes", "Primary,Backdrop")
+                param("ImageTypeLimit", "2")
+                param("Limit", 8)
+            }
+            val response = http.get(requestUrl) {
+                header("X-Emby-Authorization", authHeader(token))
+                header("X-Emby-Token", token)
+            }
+            if (!response.status.isSuccess()) error("Search HTTP ${response.status.value}")
+            val page = json.decodeFromString<ItemsResponse>(response.bodyAsText())
+            val out = ArrayList<capital.yuri.yuriplayer.core.artist.ArtistImageCandidate>()
+            for (item in page.items) {
+                val id = item.id ?: continue
+                val name = item.name ?: continue
+                if (item.imageTags?.containsKey("Primary") == true) {
+                    out += capital.yuri.yuriplayer.core.artist.ArtistImageCandidate(
+                        url = url(root) {
+                            path("Items", id, "Images", "Primary")
+                            param("maxWidth", 800)
+                            param("quality", 90)
+                            param("api_key", token)
+                        },
+                        sourceId = "jellyfin",
+                        label = "Jellyfin · ${account.name} · $name",
+                        width = 800,
+                        height = 800
+                    )
+                }
+                if (!item.backdropTags.isNullOrEmpty() || item.imageTags?.containsKey("Backdrop") == true) {
+                    out += capital.yuri.yuriplayer.core.artist.ArtistImageCandidate(
+                        url = url(root) {
+                            path("Items", id, "Images", "Backdrop")
+                            param("maxWidth", 1920)
+                            param("quality", 90)
+                            param("api_key", token)
+                        },
+                        sourceId = "jellyfin",
+                        label = "Jellyfin backdrop · ${account.name} · $name",
+                        width = 1920,
+                        height = 1080
+                    )
+                }
+            }
+            out
+        }
+
+    private fun toSong(account: RemoteAccount, item: JfItem): Song? {
+        val id = item.id ?: return null
+        val token = account.accessToken ?: return null
+        val artist = item.artists.firstOrNull()?.takeIf { it.isNotBlank() } ?: item.albumArtist
+        val artId = when {
+            item.imageTags?.containsKey("Primary") == true -> id
+            !item.albumId.isNullOrBlank() -> item.albumId
+            else -> null
+        }
+        val art = artId?.let {
+            url(account.baseUrl) {
+                path("Items", it, "Images", "Primary")
+                param("maxWidth", 600)
+                param("quality", 90)
+                param("api_key", token)
+            }
+        }
+        val stream = streamUrl(account, id, item.container)
+        val path = "jellyfin:$id"
+        return Song(
+            id = id.hashCode().toLong(),
+            title = item.name,
+            artist = artist,
+            albumArtist = item.albumArtist ?: artist,
+            album = item.album,
+            durationMs = item.runTimeTicks?.div(10_000L)?.takeIf { it > 0 },
+            contentUri = stream,
+            albumArtUri = art,
+            trackNumber = item.indexNumber,
+            discNumber = item.parentIndexNumber,
+            year = item.year,
+            path = path,
+            sourceId = account.id
+        )
+    }
+
+    fun streamUrl(account: RemoteAccount, itemId: String, container: String? = null): String {
+        val token = account.accessToken.orEmpty()
+        return url(account.baseUrl) {
+            path("Audio", itemId, "stream")
+            param("static", true)
+            if (token.isNotBlank()) param("api_key", token)
+            container?.let { param("Container", it) }
+        }
+    }
+
+    private fun authHeader(token: String?): String {
+        val base = "MediaBrowser Client=\"Yuri Player\", Device=\"Desktop\", DeviceId=\"$deviceId\", Version=\"1.0\""
+        return if (token.isNullOrBlank()) base else "$base, Token=\"$token\""
+    }
+
+    @Serializable
+    private data class AuthRequest(
+        @SerialName("Username") val username: String,
+        @SerialName("Pw") val password: String
+    )
+
+    @Serializable
+    private data class AuthResponse(
+        @SerialName("AccessToken") val accessToken: String? = null,
+        @SerialName("User") val user: AuthUser? = null
+    )
+
+    @Serializable
+    private data class AuthUser(
+        @SerialName("Id") val id: String? = null,
+        @SerialName("Name") val name: String? = null
+    )
+
+    @Serializable
+    private data class ItemsResponse(
+        @SerialName("Items") val items: List<JfItem> = emptyList(),
+        @SerialName("TotalRecordCount") val total: Int? = null
+    )
+
+    @Serializable
+    private data class JfItem(
+        @SerialName("Id") val id: String? = null,
+        @SerialName("Name") val name: String? = null,
+        @SerialName("Album") val album: String? = null,
+        @SerialName("AlbumArtist") val albumArtist: String? = null,
+        @SerialName("Artists") val artists: List<String> = emptyList(),
+        @SerialName("RunTimeTicks") val runTimeTicks: Long? = null,
+        @SerialName("IndexNumber") val indexNumber: Int? = null,
+        @SerialName("ParentIndexNumber") val parentIndexNumber: Int? = null,
+        @SerialName("ProductionYear") val year: Int? = null,
+        @SerialName("AlbumId") val albumId: String? = null,
+        @SerialName("ImageTags") val imageTags: Map<String, String>? = null,
+        @SerialName("BackdropImageTags") val backdropTags: List<String>? = null,
+        @SerialName("Container") val container: String? = null
+    )
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/LibrarySourceStore.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/LibrarySourceStore.kt
new file mode 100644
index 00000000..d4c1ee12
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/LibrarySourceStore.kt
@@ -0,0 +1,85 @@
+package capital.yuri.yuriplayer.core.source
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+import java.util.UUID
+
+class LibrarySourceStore(configDir: String) {
+    private val file = File(configDir, "sources.json")
+    private val json = Json { prettyPrint = true; ignoreUnknownKeys = true; encodeDefaults = true }
+
+    private val _folders = MutableStateFlow<List<String>>(emptyList())
+    val extraFolders: StateFlow<List<String>> = _folders.asStateFlow()
+
+    private val _remotes = MutableStateFlow<List<RemoteAccount>>(emptyList())
+    val remotes: StateFlow<List<RemoteAccount>> = _remotes.asStateFlow()
+
+    var deviceId: String = UUID.randomUUID().toString()
+        private set
+
+    init {
+        load()
+    }
+
+    fun addFolder(path: String) {
+        val p = path.trim()
+        if (p.isEmpty()) return
+        if (_folders.value.any { it.equals(p, ignoreCase = true) }) return
+        _folders.value = _folders.value + p
+        persist()
+    }
+
+    fun removeFolder(path: String) {
+        _folders.value = _folders.value.filterNot { it.equals(path, ignoreCase = true) }
+        persist()
+    }
+
+    fun upsertRemote(account: RemoteAccount) {
+        val cur = _remotes.value.toMutableList()
+        val i = cur.indexOfFirst { it.id == account.id }
+        if (i >= 0) cur[i] = account else cur += account
+        _remotes.value = cur
+        persist()
+    }
+
+    fun removeRemote(id: String) {
+        _remotes.value = _remotes.value.filterNot { it.id == id }
+        persist()
+    }
+
+    fun setRemoteEnabled(id: String, enabled: Boolean) {
+        _remotes.value = _remotes.value.map {
+            if (it.id == id) it.copy(enabled = enabled) else it
+        }
+        persist()
+    }
+
+    private fun load() {
+        if (!file.exists()) return
+        runCatching {
+            val data = json.decodeFromString<LibrarySourcesFile>(file.readText())
+            _folders.value = data.extraFolders
+            _remotes.value = data.remotes
+            if (data.deviceId.isNotBlank()) deviceId = data.deviceId
+        }
+    }
+
+    private fun persist() {
+        runCatching {
+            file.parentFile?.mkdirs()
+            file.writeText(
+                json.encodeToString(
+                    LibrarySourcesFile(
+                        extraFolders = _folders.value,
+                        remotes = _remotes.value,
+                        deviceId = deviceId
+                    )
+                )
+            )
+        }
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/SubsonicCatalog.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/SubsonicCatalog.kt
new file mode 100644
index 00000000..d6b9e061
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/source/SubsonicCatalog.kt
@@ -0,0 +1,331 @@
+package capital.yuri.yuriplayer.core.source
+
+import capital.yuri.yuriplayer.core.http.UrlScope
+import capital.yuri.yuriplayer.core.http.normalizeBaseUrl
+import capital.yuri.yuriplayer.core.http.url
+import capital.yuri.yuriplayer.data.Song
+import io.ktor.client.HttpClient
+import io.ktor.client.request.get
+import io.ktor.client.statement.bodyAsText
+import io.ktor.http.isSuccess
+import kotlinx.coroutines.ensureActive
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import java.security.MessageDigest
+import java.util.UUID
+
+class SubsonicCatalog(
+    private val http: HttpClient,
+    private val json: Json = Json { ignoreUnknownKeys = true; isLenient = true }
+) {
+    data class Session(
+        val baseUrl: String,
+        val username: String,
+        val password: String,
+        val clientName: String = "YuriPlayer"
+    )
+
+    suspend fun ping(account: RemoteAccount): Result<RemoteAccount> = runCatching {
+        val session = sessionOf(account)
+        val body = apiGet(session, "ping")
+        val resp = json.decodeFromString<SubsonicResponse>(body).subsonicResponse
+        if (resp.status != "ok") error(resp.error?.message ?: "Could not reach server")
+        account.copy(
+            name = account.name.ifBlank {
+                resp.type?.replaceFirstChar { it.uppercase() } ?: "Subsonic"
+            },
+            baseUrl = session.baseUrl
+        )
+    }
+
+    suspend fun listTracks(
+        account: RemoteAccount,
+        maxSongs: Int = 80_000,
+        startAlbumOffset: Int = 0,
+        onPage: suspend (page: List<Song>, albumOffset: Int, complete: Boolean) -> Unit = { _, _, _ -> }
+    ): Result<List<Song>> =
+        runCatching {
+            val session = sessionOf(account)
+            val out = ArrayList<Song>(512)
+            var offset = startAlbumOffset.coerceAtLeast(0)
+            val pageSize = 100
+            while (out.size < maxSongs) {
+                kotlinx.coroutines.currentCoroutineContext().ensureActive()
+                val page = listAlbums(session, offset, pageSize, type = "alphabeticalByName")
+                if (page.isEmpty()) break
+                val batch = ArrayList<Song>()
+                for (album in page) {
+                    kotlinx.coroutines.currentCoroutineContext().ensureActive()
+                    val id = album.id ?: continue
+                    batch += songsForAlbum(session, id, album, account.id)
+                    if (out.size + batch.size >= maxSongs) break
+                }
+                out += batch
+                offset += page.size
+                val done = page.size < pageSize
+                onPage(batch, offset, done)
+                if (done) break
+            }
+            out
+        }
+
+    suspend fun listNewestTracks(account: RemoteAccount, maxAlbums: Int = 40): Result<List<Song>> =
+        runCatching {
+            val session = sessionOf(account)
+            val albums = listAlbums(session, offset = 0, size = maxAlbums, type = "newest")
+            val out = ArrayList<Song>(albums.size * 12)
+            for (album in albums) {
+                kotlinx.coroutines.currentCoroutineContext().ensureActive()
+                val id = album.id ?: continue
+                out += songsForAlbum(session, id, album, account.id)
+            }
+            out
+        }
+
+    private suspend fun listAlbums(
+        session: Session,
+        offset: Int,
+        size: Int,
+        type: String = "alphabeticalByName"
+    ): List<SubsonicAlbum> {
+        val body = apiGet(session, "getAlbumList2") {
+            param("type", type)
+            param("size", size)
+            param("offset", offset)
+        }
+        return json.decodeFromString<SubsonicResponse>(body)
+            .subsonicResponse.albumList2?.album.orEmpty()
+    }
+
+    private suspend fun songsForAlbum(
+        session: Session,
+        albumId: String,
+        albumRef: SubsonicAlbum,
+        sourceId: String
+    ): List<Song> {
+        val body = apiGet(session, "getAlbum") { param("id", albumId) }
+        val album = json.decodeFromString<SubsonicResponse>(body).subsonicResponse.album
+            ?: return emptyList()
+        val cover = coverUrl(session, album.coverArt ?: album.id ?: albumRef.coverArt)
+        val albumName = album.name ?: albumRef.name
+        val albumArtist = album.albumArtist ?: album.artist ?: albumRef.artist
+        return album.song.orEmpty().mapNotNull { child ->
+            val sid = child.id ?: return@mapNotNull null
+            if (child.isDir == true) return@mapNotNull null
+            val path = "subsonic:$sid"
+            Song(
+                id = sid.hashCode().toLong(),
+                title = child.title ?: child.name,
+                artist = child.artist ?: albumArtist,
+                albumArtist = albumArtist,
+                album = child.album ?: albumName,
+                durationMs = child.duration?.times(1000L),
+                contentUri = streamUrl(session, sid),
+                albumArtUri = coverUrl(session, child.coverArt) ?: cover,
+                trackNumber = child.track,
+                discNumber = child.discNumber,
+                year = child.year ?: album.year,
+                genre = child.genre,
+                path = path,
+                sourceId = sourceId
+            )
+        }
+    }
+
+    suspend fun searchTracks(account: RemoteAccount, query: String, limit: Int = 80): Result<List<Song>> =
+        runCatching {
+            val session = sessionOf(account)
+            val body = apiGet(session, "search3") {
+                param("query", query)
+                param("songCount", limit)
+                param("albumCount", 12)
+                param("artistCount", 12)
+            }
+            val songs = json.decodeFromString<SubsonicResponse>(body)
+                .subsonicResponse.searchResult3?.song.orEmpty()
+            songs.mapNotNull { child ->
+                if (child.isDir == true) return@mapNotNull null
+                val sid = child.id ?: return@mapNotNull null
+                val path = "subsonic:$sid"
+                Song(
+                    id = sid.hashCode().toLong(),
+                    title = child.title ?: child.name,
+                    artist = child.artist,
+                    albumArtist = child.artist,
+                    album = child.album,
+                    durationMs = child.duration?.times(1000L),
+                    contentUri = streamUrl(session, sid),
+                    albumArtUri = coverUrl(session, child.coverArt),
+                    trackNumber = child.track,
+                    discNumber = child.discNumber,
+                    year = child.year,
+                    genre = child.genre,
+                    path = path,
+                    sourceId = account.id
+                )
+            }
+        }
+
+    suspend fun searchArtistImages(account: RemoteAccount, query: String): Result<List<capital.yuri.yuriplayer.core.artist.ArtistImageCandidate>> =
+        runCatching {
+            val session = sessionOf(account)
+            val body = apiGet(session, "search3") {
+                param("query", query)
+                param("songCount", 0)
+                param("albumCount", 0)
+                param("artistCount", 12)
+            }
+            val artists = json.decodeFromString<SubsonicResponse>(body)
+                .subsonicResponse.searchResult3?.artist.orEmpty()
+            artists.mapNotNull { a ->
+                val cover = a.coverArt ?: return@mapNotNull null
+                val name = a.name ?: return@mapNotNull null
+                capital.yuri.yuriplayer.core.artist.ArtistImageCandidate(
+                    url = coverUrl(session, cover, 1200) ?: return@mapNotNull null,
+                    sourceId = "navidrome",
+                    label = "Navidrome · ${account.name} · $name",
+                    width = 1200,
+                    height = 1200
+                )
+            }
+        }
+
+    fun streamUrl(account: RemoteAccount, songId: String): String =
+        streamUrl(sessionOf(account), songId)
+
+    fun coverUrl(account: RemoteAccount, coverArtId: String?, size: Int = 600): String? =
+        coverUrl(sessionOf(account), coverArtId, size)
+
+    fun streamUrl(session: Session, id: String): String =
+        restUrl(session, "stream") {
+            param("id", id)
+            param("format", "raw")
+        }
+
+    fun coverUrl(session: Session, coverArtId: String?, size: Int = 600): String? {
+        if (coverArtId.isNullOrBlank()) return null
+        return restUrl(session, "getCoverArt") {
+            param("id", coverArtId)
+            param("size", size)
+        }
+    }
+
+    private fun sessionOf(account: RemoteAccount) = Session(
+        baseUrl = normalizeBaseUrl(account.baseUrl),
+        username = account.username,
+        password = account.secret
+    )
+
+    private fun restUrl(session: Session, action: String, extra: UrlScope.() -> Unit = {}): String {
+        val (token, salt) = tokenPair(session.password)
+        return url(session.baseUrl) {
+            path("rest", "$action.view")
+            param("u", session.username)
+            param("t", token)
+            param("s", salt)
+            param("v", API_VERSION)
+            param("c", session.clientName)
+            extra()
+        }
+    }
+
+    private suspend fun apiGet(
+        session: Session,
+        action: String,
+        extra: UrlScope.() -> Unit = {}
+    ): String {
+        val requestUrl = restUrl(session, action) {
+            param("f", "json")
+            extra()
+        }
+        val response = http.get(requestUrl)
+        if (!response.status.isSuccess()) error("$action HTTP ${response.status.value}")
+        return response.bodyAsText()
+    }
+
+    private fun tokenPair(password: String): Pair<String, String> {
+        val salt = UUID.randomUUID().toString().replace("-", "").take(12)
+        val token = md5(password + salt)
+        return token to salt
+    }
+
+    private fun md5(value: String): String {
+        val digest = MessageDigest.getInstance("MD5").digest(value.toByteArray(Charsets.UTF_8))
+        return digest.joinToString("") { "%02x".format(it) }
+    }
+
+    @Serializable
+    private data class SubsonicResponse(
+        @SerialName("subsonic-response") val subsonicResponse: SubsonicBody
+    )
+
+    @Serializable
+    private data class SubsonicBody(
+        val status: String? = null,
+        val type: String? = null,
+        val error: SubsonicError? = null,
+        val albumList2: SubsonicAlbumList? = null,
+        val album: SubsonicAlbumDetail? = null,
+        val searchResult3: SubsonicSearchResult? = null
+    )
+
+    @Serializable
+    private data class SubsonicSearchResult(
+        val song: List<SubsonicChild> = emptyList(),
+        val artist: List<SubsonicArtistRef> = emptyList()
+    )
+
+    @Serializable
+    private data class SubsonicArtistRef(
+        val id: String? = null,
+        val name: String? = null,
+        val coverArt: String? = null
+    )
+
+    @Serializable
+    private data class SubsonicError(val message: String? = null)
+
+    @Serializable
+    private data class SubsonicAlbumList(val album: List<SubsonicAlbum> = emptyList())
+
+    @Serializable
+    private data class SubsonicAlbum(
+        val id: String? = null,
+        val name: String? = null,
+        val artist: String? = null,
+        val coverArt: String? = null,
+        val year: Int? = null
+    )
+
+    @Serializable
+    private data class SubsonicAlbumDetail(
+        val id: String? = null,
+        val name: String? = null,
+        val artist: String? = null,
+        val albumArtist: String? = null,
+        val coverArt: String? = null,
+        val year: Int? = null,
+        val song: List<SubsonicChild> = emptyList()
+    )
+
+    @Serializable
+    private data class SubsonicChild(
+        val id: String? = null,
+        val title: String? = null,
+        val name: String? = null,
+        val artist: String? = null,
+        val album: String? = null,
+        val coverArt: String? = null,
+        val duration: Int? = null,
+        val track: Int? = null,
+        val discNumber: Int? = null,
+        val year: Int? = null,
+        val genre: String? = null,
+        val isDir: Boolean? = null
+    )
+
+    companion object {
+        private const val API_VERSION = "1.16.1"
+    }
+}
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.jvm.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.jvm.kt
new file mode 100644
index 00000000..8a618371
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/core/text/StringSimilarity.jvm.kt
@@ -0,0 +1,23 @@
+package capital.yuri.yuriplayer.core.text
+
+import java.text.Normalizer
+
+internal actual fun foldCompare(s: String): String {
+    var t = s.trim().lowercase()
+    t = Normalizer.normalize(t, Normalizer.Form.NFKC)
+    t = katakanaToHiragana(t)
+    t = Normalizer.normalize(t, Normalizer.Form.NFD)
+    t = t.replace(Regex("\\p{M}+"), "")
+    t = latinAscii(t)
+    t = t.replace(Regex("[\\s\\p{Punct}]+"), " ").trim()
+    return t
+}
+
+internal actual fun isCjkCodePoint(cp: Int): Boolean =
+    cp in 0x3400..0x4DBF || // CJK Extension A
+        cp in 0x4E00..0x9FFF || // CJK Unified Ideographs
+        cp in 0x3040..0x30FF || // Hiragana + Katakana
+        cp in 0x31F0..0x31FF || // Katakana phonetic extensions
+        cp in 0xAC00..0xD7AF || // Hangul syllables
+        cp in 0x3100..0x312F || // Bopomofo
+        cp in 0x31A0..0x31BF // Bopomofo Extended
diff --git a/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.jvm.kt b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.jvm.kt
new file mode 100644
index 00000000..4969a06c
--- /dev/null
+++ b/core/src/jvmMain/kotlin/capital/yuri/yuriplayer/data/db/YuriDatabase.jvm.kt
@@ -0,0 +1,18 @@
+package capital.yuri.yuriplayer.data.db
+
+import androidx.room.Room
+import androidx.sqlite.driver.bundled.BundledSQLiteDriver
+import kotlinx.coroutines.Dispatchers
+
+/**
+ * JVM/desktop factory for the shared [YuriDatabase] schema using the bundled
+ * SQLite driver (no Android Context needed).
+ */
+fun createYuriDatabase(name: String): YuriDatabase =
+    Room.databaseBuilder<YuriDatabase>(
+        java.io.File(name).absolutePath
+    )
+        .setDriver(BundledSQLiteDriver())
+        .setQueryCoroutineContext(Dispatchers.IO)
+        .addMigrations(*YuriMigrations.ALL)
+        .build()
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/AlbumCollapseTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/AlbumCollapseTest.kt
new file mode 100644
index 00000000..6a21f307
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/AlbumCollapseTest.kt
@@ -0,0 +1,90 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.Song
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class AlbumCollapseTest {
+    private fun clancy(source: String, prefix: String) = (1..14).map { n ->
+        Song(
+            id = "$prefix-$n".hashCode().toLong(),
+            contentUri = if (source == "local") "file:///Clancy/$n.flac" else "https://navi/stream/$n",
+            title = titles[n - 1],
+            artist = "twenty one pilots",
+            albumArtist = "twenty one pilots",
+            album = "Clancy",
+            trackNumber = n,
+            discNumber = 1,
+            path = "$prefix-$n",
+            sourceId = source
+        )
+    }
+
+    @Test
+    fun localAndNavidromeCollapseToFourteen() {
+        val mixed = clancy("local", "file") + clancy("navidrome", "subsonic")
+        val collapsed = collapseAlbumTracks(mixed)
+        assertEquals(14, collapsed.size)
+        assertTrue(collapsed.all { it.multiSource })
+        assertEquals("Overcompensate", collapsed.first().preferred.title)
+        assertEquals(1, collapsed.first().preferred.trackNumber)
+        assertEquals("Paladin Strait", collapsed.last().preferred.title)
+        assertTrue(collapsed.first().preferred.contentUri.startsWith("file:"))
+    }
+
+    @Test
+    fun preferredSourceWins() {
+        val mixed = clancy("local", "file") + clancy("navidrome", "subsonic")
+        val id = albumPageIdentity(mixed.first())
+        val collapsed = collapseAlbumTracks(mixed, mapOf(id to "subsonic-1"))
+        assertEquals("subsonic-1", collapsed.first().preferred.songKey)
+    }
+
+    @Test
+    fun playlistKeepsSnapshotWhenKeyMissing() {
+        val snap = Song(
+            id = 1L,
+            contentUri = "https://navi/stream/old",
+            title = "BIRDBRAIN",
+            artist = "Jamie Paige feat. OK Glass",
+            album = "BIRDBRAIN",
+            trackNumber = 1,
+            path = "subsonic:old"
+        )
+        val other = Song(
+            id = 2L,
+            contentUri = "https://navi/stream/new",
+            title = "Sahara",
+            artist = "Hoshimachi Suisei",
+            album = "Still Still Stellar",
+            trackNumber = 1,
+            path = "subsonic:new"
+        )
+        val byKey = HashMap<String, Song>()
+        byKey[other.songKey] = other
+        byKey.putIfAbsent(snap.songKey, snap)
+        byKey.putIfAbsent(snap.catalogKey(), snap)
+        val trackIds = listOf("k:missing", other.songKey)
+        val snapshots = listOf(snap, other)
+        val seen = HashSet<String>()
+        val out = ArrayList<Song>()
+        fun add(t: Song) {
+            if (t.playlistKeys().any { it in seen }) return
+            seen += t.playlistKeys()
+            out += t
+        }
+        for (key in trackIds) byKey[key]?.let(::add)
+        for (s in snapshots) add(byKey[s.songKey] ?: byKey[s.catalogKey()] ?: s)
+        assertEquals(2, out.size)
+        assertTrue(out.any { it.displayTitle == "BIRDBRAIN" })
+        assertTrue(out.any { it.displayTitle == "Sahara" })
+    }
+
+    private val titles = listOf(
+        "Overcompensate", "Next Semester", "Backslide", "Midwest Indigo",
+        "Routines In The Night", "Vignette", "The Craving (Jenna's Version)",
+        "Lavish", "Navigating", "Snap Back", "Oldies Station",
+        "At The Risk Of Feeling Dumb", "The Craving (single)", "Paladin Strait"
+    )
+}
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/ArtistIdentityTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/ArtistIdentityTest.kt
new file mode 100644
index 00000000..7a15713d
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/ArtistIdentityTest.kt
@@ -0,0 +1,39 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.TrackIdentity
+import kotlin.test.Test
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class ArtistIdentityTest {
+
+    @Test
+    fun prefixArtistDoesNotMatchLongerName() {
+        // Regression: "Rav" must never collapse with "Ravenna Golden" just
+        // because the folded shorter name is a substring of the longer one.
+        assertFalse(TrackIdentity.albumArtistsMatch("Rav", "Ravenna Golden"))
+        assertFalse("Rav".matchesArtistName("Ravenna Golden"))
+        assertFalse("Ravenna Golden".matchesArtistName("Rav"))
+        assertFalse("Rav".matchesCreditedArtist("Ravenna Golden"))
+    }
+
+    @Test
+    fun samePrimaryArtistMatchesIgnoringCaseAndStylization() {
+        assertTrue(TrackIdentity.albumArtistsMatch("Lemon Demon", "lemon demon"))
+        assertTrue("Lemon Demon".matchesArtistName("LEMON DEMON"))
+        assertTrue("Twenty Øne Piløts".matchesArtistName("twenty one pilots"))
+    }
+
+    @Test
+    fun featCreditStillResolvesPrimary() {
+        // "Camellia feat. nanahira" primary is "Camellia".
+        assertTrue(TrackIdentity.albumArtistsMatch("Camellia", "Camellia feat. nanahira"))
+        assertTrue("Camellia".matchesArtistName("Camellia feat. nanahira"))
+    }
+
+    @Test
+    fun featuredCreditMatchesAppearsOn() {
+        assertTrue("Lemon Demon feat. Rav".matchesCreditedArtist("Rav"))
+        assertTrue("Rav".matchesCreditedArtist("Rav"))
+    }
+}
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/TrackCatalogKeyTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/TrackCatalogKeyTest.kt
new file mode 100644
index 00000000..a9e1442a
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/TrackCatalogKeyTest.kt
@@ -0,0 +1,62 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.Song
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class TrackCatalogKeyTest {
+    @Test
+    fun localAndSubsonicShareIdentity() {
+        val local = Song(
+            id = 1L,
+            contentUri = "file:///music/BIRDBRAIN.flac",
+            title = "BIRDBRAIN",
+            artist = "Jamie Paige feat. OK Glass",
+            album = "BIRDBRAIN",
+            trackNumber = 1,
+            path = "/music/BIRDBRAIN.flac",
+            sourceId = "local"
+        )
+        val remote = Song(
+            id = 2L,
+            contentUri = "https://navi.example/stream/abc",
+            title = "BIRDBRAIN",
+            artist = "Jamie Paige feat. OK Glass",
+            album = "BIRDBRAIN",
+            trackNumber = 1,
+            path = "subsonic:abc",
+            sourceId = "navidrome-1"
+        )
+        assertEquals(local.catalogKey(), remote.catalogKey())
+        assertTrue(local.catalogKey() in remote.playlistKeys())
+    }
+
+    @Test
+    fun navidromeSearchAndScanShareLooseKey() {
+        val search = Song(
+            id = 1L,
+            contentUri = "https://navi/stream/abc",
+            title = "BIRDBRAIN",
+            artist = "Jamie Paige feat. OK Glass",
+            album = "BIRDBRAIN",
+            trackNumber = 1,
+            path = "subsonic:abc",
+            sourceId = "navi-1"
+        )
+        val scanned = Song(
+            id = 1L,
+            contentUri = "https://navi/stream/abc",
+            title = "BIRDBRAIN",
+            artist = "Jamie Paige",
+            albumArtist = "Jamie Paige",
+            album = "BIRDBRAIN",
+            trackNumber = 1,
+            path = "subsonic:abc",
+            sourceId = "navi-1"
+        )
+        assertEquals(search.looseKey(), scanned.looseKey())
+        assertTrue(search.looseKey() in scanned.indexKeys())
+        assertTrue("abc" in scanned.indexKeys())
+    }
+}
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/TrackSearchTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/TrackSearchTest.kt
new file mode 100644
index 00000000..3ea95126
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/library/TrackSearchTest.kt
@@ -0,0 +1,35 @@
+package capital.yuri.yuriplayer.core.library
+
+import capital.yuri.yuriplayer.data.Song
+import kotlin.test.Test
+import kotlin.test.assertTrue
+
+class TrackSearchTest {
+    @Test
+    fun matchesStylizedTwentyOnePilots() {
+        val track = Song(
+            id = 1L,
+            contentUri = "file:///music/Twenty Øne Piløts/Clancy/01.flac",
+            title = "Overcompensate",
+            artist = "Twenty Øne Piløts",
+            album = "Clancy",
+            path = "/home/mey/Music/Twenty One Pilots/Clancy/01.flac"
+        )
+        assertTrue(track.matchesQuery("twenty one pilots"))
+        assertTrue(track.matchesQuery("Twenty Øne Piløts"))
+        assertTrue(track.matchesQuery("clancy"))
+        assertTrue("Twenty Øne Piløts".matchesSearch("twenty one pilots"))
+    }
+
+    @Test
+    fun matchesFolderWhenTagsMissing() {
+        val track = Song(
+            id = 2L,
+            contentUri = "file:///data/Twenty One Pilots/Vessel/02.flac",
+            title = "02",
+            path = "/data/Twenty One Pilots/Vessel/02.flac"
+        )
+        assertTrue(track.matchesQuery("twenty one pilots"))
+        assertTrue(track.matchesQuery("vessel"))
+    }
+}
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/log/YuriLogTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/log/YuriLogTest.kt
new file mode 100644
index 00000000..f3015a16
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/log/YuriLogTest.kt
@@ -0,0 +1,26 @@
+package capital.yuri.yuriplayer.core.log
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class YuriLogTest {
+    @Test
+    fun redactsStreamTokens() {
+        val raw = "https://navidrome.example/rest/stream.view?u=lizzy&t=deadbeef&s=salt&id=abc"
+        val out = redactSecrets(raw)
+        assertFalse("deadbeef" in out)
+        assertTrue("t=***" in out)
+        assertTrue("id=abc" in out)
+    }
+
+    @Test
+    fun normalizesTags() {
+        assertEquals("Radio", normalizeLogTag("YuriPlayer.Radio"))
+        assertEquals("Radio", normalizeLogTag("Radio"))
+        assertEquals("App", normalizeLogTag("YuriPlayer"))
+        assertEquals("App", normalizeLogTag("YuriPlayer."))
+        assertEquals("Vlcj", yuriLog("YuriPlayer.Vlcj").tag)
+    }
+}
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectoriesTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectoriesTest.kt
new file mode 100644
index 00000000..b0414364
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/platform/AppDirectoriesTest.kt
@@ -0,0 +1,18 @@
+package capital.yuri.yuriplayer.core.platform
+
+import java.io.File
+import kotlin.test.Test
+import kotlin.test.assertTrue
+
+class AppDirectoriesTest {
+    @Test
+    fun dirsAreCreatedAndDefaultMusicIsHomeMusicOrXdg() {
+        val dirs = JvmAppDirectories()
+        assertTrue(File(dirs.configDir).isDirectory)
+        assertTrue(File(dirs.cacheDir).isDirectory)
+        assertTrue(File(dirs.dataDir).isDirectory)
+        dirs.defaultMusicRoots.forEach { root ->
+            assertTrue(File(root).isDirectory, root)
+        }
+    }
+}
diff --git a/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/player/PlayerSessionTest.kt b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/player/PlayerSessionTest.kt
new file mode 100644
index 00000000..d7a2be27
--- /dev/null
+++ b/core/src/jvmTest/kotlin/capital/yuri/yuriplayer/core/player/PlayerSessionTest.kt
@@ -0,0 +1,5 @@
+package capital.yuri.yuriplayer.core.player
+
+// Removed with the legacy Track-based `PlayerSession` queue host.
+// Desktop/Android now share the Song-based `QueueManager`; see
+// `capital.yuri.yuriplayer.player.QueueManager` and its QueueSnapshot.
diff --git a/desktop/build.gradle.kts b/desktop/build.gradle.kts
new file mode 100644
index 00000000..a2ee53fb
--- /dev/null
+++ b/desktop/build.gradle.kts
@@ -0,0 +1,219 @@
+import java.io.File
+import java.net.URI
+import java.util.zip.ZipInputStream
+import org.jetbrains.compose.desktop.application.dsl.TargetFormat
+import org.jetbrains.compose.desktop.application.tasks.AbstractJPackageTask
+
+plugins {
+    alias(libs.plugins.kotlin.jvm)
+    alias(libs.plugins.kotlin.compose)
+    alias(libs.plugins.compose.multiplatform)
+    alias(libs.plugins.kotlin.serialization)
+}
+
+kotlin {
+    jvmToolchain(17)
+    compilerOptions {
+        jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    }
+}
+
+dependencies {
+    implementation(project(":core"))
+    implementation(project(":components"))
+    implementation(compose.desktop.currentOs)
+    implementation(compose.material3)
+    implementation(compose.materialIconsExtended)
+    implementation(libs.kotlinx.coroutines.swing)
+    implementation(libs.kotlinx.serialization.json)
+    implementation(libs.koin.core)
+    implementation(libs.vlcj)
+//    implementation(libs.dbus.java.core)
+//    implementation(libs.dbus.java.transport.native.unix)
+    implementation(libs.junixsocket.core)
+    implementation(libs.jna)
+    implementation(libs.jna.platform)
+    implementation(libs.logback.classic)
+    implementation(libs.coil.compose)
+    implementation(libs.coil.network.ktor3)
+    implementation(libs.ktor.client.cio)
+    implementation(libs.jaudiotagger)
+    implementation(project(":mediasession"))
+    testImplementation(kotlin("test"))
+}
+
+val libvlcRoot = layout.buildDirectory.dir("libvlc")
+val libvlcResources = layout.buildDirectory.dir("libvlc-resources")
+val downloadAllLibVlc = (findProperty("yuri.libvlc.all") as String?) == "true"
+val hostLibVlc = hostLibVlcPlatform()
+val bundleLibVlcOnHost = !hostLibVlc.startsWith("linux")
+
+/** Official VideoLAN natives for Windows/macOS installers. Linux uses distro VLC. */
+val downloadLibVlc by tasks.registering {
+    group = "vlc"
+    description = "Download bundled LibVLC for Windows/macOS (Linux packages depend on system vlc)."
+    val destRoot = libvlcRoot
+    val all = downloadAllLibVlc
+    val host = hostLibVlc
+    outputs.dir(destRoot)
+    notCompatibleWithConfigurationCache("LibVLC download uses script helpers")
+    doLast {
+        val wanted = if (all) {
+            listOf("windows-x64", "macos-x64", "macos-arm64")
+        } else if (host.startsWith("linux")) {
+            emptyList()
+        } else {
+            listOf(host)
+        }
+        if (wanted.isEmpty()) {
+            println("Linux: not bundling LibVLC (installer Depends/Requires vlc)")
+            destRoot.get().asFile.mkdirs()
+            return@doLast
+        }
+        wanted.forEach { platform ->
+            val dest = destRoot.get().asFile.resolve(platform)
+            if (hasLibvlc(dest)) {
+                println("LibVLC $platform already present")
+                return@forEach
+            }
+            dest.mkdirs()
+            println("Downloading LibVLC for $platform…")
+            when {
+                platform.startsWith("windows") -> unpackNuget(
+                    "https://api.nuget.org/v3-flatcontainer/videolan.libvlc.windows/3.0.23.1/videolan.libvlc.windows.3.0.23.1.nupkg",
+                    dest,
+                    "libvlc.dll"
+                )
+                platform.startsWith("macos") -> unpackNuget(
+                    "https://api.nuget.org/v3-flatcontainer/videolan.libvlc.mac/3.1.3.1/videolan.libvlc.mac.3.1.3.1.nupkg",
+                    dest,
+                    "libvlc.dylib"
+                )
+                else -> println("Skip $platform")
+            }
+        }
+    }
+}
+
+val copyLibVlcResources by tasks.registering {
+    dependsOn(downloadLibVlc)
+    outputs.dir(libvlcResources)
+    notCompatibleWithConfigurationCache("LibVLC copy")
+    doLast {
+        val root = libvlcRoot.get().asFile
+        val out = libvlcResources.get().asFile
+        out.mkdirs()
+        root.listFiles()
+            ?.filter { it.isDirectory && !it.name.startsWith("linux") }
+            ?.forEach { src ->
+                src.copyRecursively(out.resolve(src.name), overwrite = true)
+            }
+    }
+}
+
+compose.desktop {
+    application {
+        mainClass = "capital.yuri.yuriplayer.desktop.MainKt"
+        nativeDistributions {
+            targetFormats(
+                TargetFormat.Deb,
+                TargetFormat.Rpm,
+                TargetFormat.Dmg,
+                TargetFormat.Pkg,
+                TargetFormat.Msi,
+                TargetFormat.Exe
+            )
+            packageName = "Yuri Player"
+            packageVersion = "0.1.0"
+            description = "Yuri Player"
+            copyright = "AGPL-3.0"
+            vendor = "Yuri"
+            appResourcesRootDir.set(libvlcResources)
+            linux {
+                packageName = "yuri-player"
+                debMaintainer = "yuri@yuri.capital"
+                menuGroup = "AudioVideo"
+                appCategory = "AudioVideo"
+                appRelease = "1"
+                rpmLicenseType = "AGPLv3"
+            }
+            windows {
+                menuGroup = "Yuri"
+                dirChooser = true
+            }
+            macOS {
+                bundleID = "capital.yuri.yuriplayer"
+                dockName = "Yuri Player"
+                packageVersion = "1.0.0"
+            }
+        }
+    }
+}
+
+afterEvaluate {
+    tasks.matching { it.name.contains("prepareAppResources", ignoreCase = true) }.configureEach {
+        dependsOn(copyLibVlcResources)
+    }
+    tasks.matching { it.name == "run" }.configureEach {
+        if (bundleLibVlcOnHost) {
+            dependsOn(downloadLibVlc)
+            if (this is JavaExec) {
+                systemProperty("yuri.libvlc.dir", libvlcRoot.get().asFile.resolve(hostLibVlc).absolutePath)
+            }
+        }
+    }
+    tasks.withType<AbstractJPackageTask>().configureEach {
+        if (targetFormat == TargetFormat.Deb || targetFormat == TargetFormat.Rpm) {
+            freeArgs.addAll(listOf("--linux-package-deps", "vlc"))
+        }
+        if (targetFormat == TargetFormat.Msi ||
+            targetFormat == TargetFormat.Exe ||
+            targetFormat == TargetFormat.Dmg ||
+            targetFormat == TargetFormat.Pkg
+        ) {
+            dependsOn(copyLibVlcResources)
+        }
+    }
+}
+
+fun hostLibVlcPlatform(): String {
+    val os = System.getProperty("os.name").lowercase()
+    val arch = System.getProperty("os.arch").lowercase()
+    val family = when {
+        os.contains("win") -> "windows"
+        os.contains("mac") || os.contains("darwin") -> "macos"
+        else -> "linux"
+    }
+    val cpu = when {
+        arch.contains("aarch64") || arch.contains("arm64") -> "arm64"
+        else -> "x64"
+    }
+    return "$family-$cpu"
+}
+
+fun hasLibvlc(dir: File): Boolean {
+    val names = dir.list()?.toList().orEmpty()
+    return names.any { it.startsWith("libvlc") && (it.endsWith(".dll") || it.endsWith(".so") || it.endsWith(".dylib") || it.contains(".so.")) }
+}
+
+fun unpackNuget(url: String, dest: File, nativeLib: String) {
+    dest.mkdirs()
+    val zip = ZipInputStream(URI(url).toURL().openStream())
+    zip.use { input ->
+        var entry = input.nextEntry
+        while (entry != null) {
+            val name = entry.name
+            if (!entry.isDirectory &&
+                (name.contains("libvlc") || name.contains("/plugins/") || name.endsWith(".dll") || name.endsWith(".dylib") || name.endsWith(".so"))
+            ) {
+                val target = File(dest, File(name).name)
+                if (target.name == nativeLib || name.contains("/plugins/")) {
+                    target.parentFile?.mkdirs()
+                    target.outputStream().use { out -> input.copyTo(out) }
+                }
+            }
+            input.closeEntry()
+            entry = input.nextEntry
+        }
+    }
+}
diff --git a/desktop/libvlc/README.md b/desktop/libvlc/README.md
new file mode 100644
index 00000000..1268c8e9
--- /dev/null
+++ b/desktop/libvlc/README.md
@@ -0,0 +1,25 @@
+# LibVLC on desktop
+
+| Ship as | LibVLC |
+| --- | --- |
+| Windows `.msi` / `.exe` | Bundled official [VideoLAN.LibVLC.Windows](https://www.nuget.org/packages/VideoLAN.LibVLC.Windows) in app resources |
+| macOS `.dmg` / `.pkg` | Bundled official [VideoLAN.LibVLC.Mac](https://www.nuget.org/packages/VideoLAN.LibVLC.Mac) in app resources |
+| Linux `.deb` / `.rpm` | **Depends on distro `vlc`** (libvlc + plugins from the OS). Not vendored. |
+
+Natives for Windows/macOS are downloaded at package time (`:desktop:downloadLibVlc`), not committed.
+
+```bash
+# Linux packages (this host) — requires system VLC at runtime
+./gradlew :desktop:packageDeb
+./gradlew :desktop:packageRpm
+
+# Windows/macOS natives into the installer (on those OSes, or with -Pyuri.libvlc.all=true)
+./gradlew :desktop:packageMsi
+./gradlew :desktop:packageDmg
+```
+
+`:desktop:run` on Linux uses NativeDiscovery against `/usr/lib`. Install `vlc` or `libvlc-dev` + `vlc-plugin-base`.
+
+Override lookup with `YURI_LIBVLC=/path/to/libvlc` or `-Dyuri.libvlc.dir=...`.
+
+Windows/macOS installers that bundle LibVLC are covered by VLC's GPL, which is compatible with this repo's AGPL-3.0.
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopCollection.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopCollection.kt
new file mode 100644
index 00000000..7b2ca30a
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopCollection.kt
@@ -0,0 +1,112 @@
+package capital.yuri.yuriplayer.desktop
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import java.io.File
+import java.util.Properties
+
+/**
+ * Desktop My Stuff: liked songs + pinned albums/artists, newest first.
+ */
+class DesktopCollection(configDir: String) {
+    private val file = File(configDir, "collection.properties")
+
+    private val _liked = MutableStateFlow<Set<String>>(emptySet())
+    val liked: StateFlow<Set<String>> = _liked.asStateFlow()
+
+    private val _pinned = MutableStateFlow<List<Pin>>(emptyList())
+    val pinned: StateFlow<List<Pin>> = _pinned.asStateFlow()
+
+    private val _saved = MutableStateFlow<List<Pin>>(emptyList())
+    val saved: StateFlow<List<Pin>> = _saved.asStateFlow()
+
+    data class Pin(val kind: Kind, val id: String, val title: String, val subtitle: String)
+
+    enum class Kind { ALBUM, ARTIST, SONG, PLAYLIST }
+
+    init {
+        load()
+    }
+
+    fun isLiked(trackId: String): Boolean = trackId in _liked.value
+
+    fun toggleLike(trackId: String) {
+        val next = _liked.value.toMutableSet()
+        if (!next.add(trackId)) next.remove(trackId)
+        _liked.value = next
+        persist()
+    }
+
+    fun pin(pin: Pin) {
+        val cur = _pinned.value.toMutableList()
+        cur.removeAll { it.kind == pin.kind && it.id == pin.id }
+        cur.add(0, pin)
+        _pinned.value = cur
+        persist()
+    }
+
+    fun isPinned(kind: Kind, id: String): Boolean =
+        _pinned.value.any { it.kind == kind && it.id == id }
+
+    fun isSaved(kind: Kind, id: String): Boolean =
+        _saved.value.any { it.kind == kind && it.id == id }
+
+    fun toggleSaved(pin: Pin) {
+        val cur = _saved.value.toMutableList()
+        val had = cur.removeAll { it.kind == pin.kind && it.id == pin.id }
+        if (!had) cur.add(0, pin)
+        _saved.value = cur
+        persist()
+    }
+
+    fun togglePin(pin: Pin) {
+        if (isPinned(pin.kind, pin.id)) unpin(pin.kind, pin.id) else pin(pin)
+    }
+
+    fun unpin(kind: Kind, id: String) {
+        _pinned.value = _pinned.value.filterNot { it.kind == kind && it.id == id }
+        persist()
+    }
+
+    private fun load() {
+        if (!file.exists()) return
+        runCatching {
+            val p = Properties()
+            file.inputStream().use { p.load(it) }
+            _liked.value = p.getProperty("liked").orEmpty()
+                .split('|').filter { it.isNotBlank() }.toSet()
+            val pins = p.getProperty("pins").orEmpty().split('\n').mapNotNull { line ->
+                val parts = line.split('\t')
+                if (parts.size < 4) return@mapNotNull null
+                val kind = runCatching { Kind.valueOf(parts[0]) }.getOrNull() ?: return@mapNotNull null
+                Pin(kind, parts[1], parts[2], parts[3])
+            }
+            _pinned.value = pins
+            val saved = p.getProperty("saved").orEmpty().split('\n').mapNotNull { line ->
+                val parts = line.split('\t')
+                if (parts.size < 4) return@mapNotNull null
+                val kind = runCatching { Kind.valueOf(parts[0]) }.getOrNull() ?: return@mapNotNull null
+                Pin(kind, parts[1], parts[2], parts[3])
+            }
+            _saved.value = saved
+        }
+    }
+
+    private fun persist() {
+        runCatching {
+            file.parentFile?.mkdirs()
+            val p = Properties()
+            p.setProperty("liked", _liked.value.joinToString("|"))
+            p.setProperty(
+                "pins",
+                _pinned.value.joinToString("\n") { "${it.kind}\t${it.id}\t${it.title}\t${it.subtitle}" }
+            )
+            p.setProperty(
+                "saved",
+                _saved.value.joinToString("\n") { "${it.kind}\t${it.id}\t${it.title}\t${it.subtitle}" }
+            )
+            file.outputStream().use { p.store(it, "Yuri Player collection") }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopIndexStore.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopIndexStore.kt
new file mode 100644
index 00000000..8285159e
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopIndexStore.kt
@@ -0,0 +1,66 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.data.Song
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+
+/**
+ * Durable library index + per-source scan cursors, matching mobile's
+ * Room catalog + [ScanCheckpointStore]. Survives process death so a
+ * 40k-track Jellyfin walk does not restart from zero.
+ */
+class DesktopIndexStore(cacheDir: String) {
+    private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
+    private val tracksFile = File(cacheDir, "index-tracks.json")
+    private val cpFile = File(cacheDir, "index-checkpoints.json")
+
+    fun loadTracks(): List<Song> {
+        if (!tracksFile.isFile) return emptyList()
+        return runCatching {
+            json.decodeFromString<List<Song>>(tracksFile.readText())
+        }.getOrDefault(emptyList())
+    }
+
+    fun saveTracks(tracks: List<Song>) {
+        runCatching {
+            tracksFile.parentFile?.mkdirs()
+            val tmp = File(tracksFile.parentFile, "${tracksFile.name}.tmp")
+            tmp.writeText(json.encodeToString(tracks))
+            if (!tmp.renameTo(tracksFile)) {
+                tmp.copyTo(tracksFile, overwrite = true)
+                tmp.delete()
+            }
+            PlaylistLog.index("saved ${tracks.size} tracks → ${tracksFile.absolutePath}")
+        }.onFailure {
+            PlaylistLog.index("save FAILED: ${it.message}")
+        }
+    }
+
+    fun loadCheckpoints(): List<StoredCheckpoint> {
+        if (!cpFile.isFile) return emptyList()
+        return runCatching {
+            json.decodeFromString<List<StoredCheckpoint>>(cpFile.readText())
+        }.getOrDefault(emptyList())
+    }
+
+    fun saveCheckpoints(rows: List<StoredCheckpoint>) {
+        runCatching {
+            cpFile.parentFile?.mkdirs()
+            cpFile.writeText(json.encodeToString(rows))
+        }
+    }
+
+    @Serializable
+    data class StoredCheckpoint(
+        val id: String,
+        val name: String,
+        val status: String,
+        val startIndex: Int = 0,
+        val delivered: Int = 0,
+        val totalHint: Int? = null,
+        val count: Int = 0,
+        val detail: String = ""
+    )
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopLayoutStore.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopLayoutStore.kt
new file mode 100644
index 00000000..45be43b6
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopLayoutStore.kt
@@ -0,0 +1,61 @@
+package capital.yuri.yuriplayer.desktop
+
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import java.io.File
+import java.util.Properties
+
+class DesktopLayoutStore(configDir: String) {
+    private val file = File(configDir, "layout.properties")
+
+    private val _left = MutableStateFlow(DEFAULT_LEFT)
+    val leftFraction: StateFlow<Float> = _left.asStateFlow()
+
+    private val _right = MutableStateFlow(DEFAULT_RIGHT)
+    val rightFraction: StateFlow<Float> = _right.asStateFlow()
+
+    init {
+        load()
+    }
+
+    fun setLeft(fraction: Float, persist: Boolean = true) {
+        _left.value = fraction.coerceIn(MIN_LEFT, MAX_LEFT)
+        if (persist) persist()
+    }
+
+    fun setRight(fraction: Float, persist: Boolean = true) {
+        _right.value = fraction.coerceIn(MIN_RIGHT, MAX_RIGHT)
+        if (persist) persist()
+    }
+
+    fun persist() {
+        runCatching {
+            file.parentFile?.mkdirs()
+            val p = Properties()
+            p.setProperty("left", _left.value.toString())
+            p.setProperty("right", _right.value.toString())
+            file.outputStream().use { p.store(it, "Yuri Player layout") }
+        }
+    }
+
+    private fun load() {
+        if (!file.exists()) return
+        runCatching {
+            val p = Properties()
+            file.inputStream().use { p.load(it) }
+            p.getProperty("left")?.toFloatOrNull()?.let { _left.value = it.coerceIn(MIN_LEFT, MAX_LEFT) }
+            p.getProperty("right")?.toFloatOrNull()?.let { _right.value = it.coerceIn(MIN_RIGHT, MAX_RIGHT) }
+        }
+    }
+
+    companion object {
+        const val DEFAULT_LEFT = 0.22f
+        const val DEFAULT_RIGHT = 0.26f
+        const val MIN_LEFT = 0.10f
+        const val MAX_LEFT = 0.55f
+        const val MIN_RIGHT = 0.12f
+        const val MAX_RIGHT = 0.55f
+        const val MIN_CENTER = 0.28f
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopNetworkMonitor.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopNetworkMonitor.kt
new file mode 100644
index 00000000..30d7ad6d
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopNetworkMonitor.kt
@@ -0,0 +1,55 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.network.NetworkMonitor
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import java.net.InetSocketAddress
+import java.net.Socket
+
+/**
+ * Desktop has no ConnectivityManager, so "online" is a periodic TCP reachability
+ * probe to a well-known anycast host. Retries every [PROBE_INTERVAL_MS].
+ */
+class DesktopNetworkMonitor : NetworkMonitor {
+    private val log = yuriLog("Network")
+
+    private val _isOnline = MutableStateFlow(true)
+    override val isOnline: StateFlow<Boolean> = _isOnline.asStateFlow()
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
+
+    init {
+        scope.launch {
+            while (isActive) {
+                _isOnline.value = probe()
+                delay(PROBE_INTERVAL_MS)
+            }
+        }
+    }
+
+    private fun probe(): Boolean {
+        return runCatching {
+            Socket().use { s ->
+                s.connect(InetSocketAddress(PROBE_HOST, PROBE_PORT), PROBE_TIMEOUT_MS)
+            }
+            true
+        }.onFailure { t ->
+            log.w { "offline probe failed: ${t.message}" }
+        }.getOrDefault(false)
+    }
+
+    companion object {
+        private const val PROBE_HOST = "1.1.1.1"
+        private const val PROBE_PORT = 443
+        private const val PROBE_TIMEOUT_MS = 3_000
+        private const val PROBE_INTERVAL_MS = 15_000L
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopPlaybackStore.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopPlaybackStore.kt
new file mode 100644
index 00000000..76c2a18e
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopPlaybackStore.kt
@@ -0,0 +1,118 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.PlaybackSnapshot
+import capital.yuri.yuriplayer.core.player.QueueLane
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import capital.yuri.yuriplayer.data.Song
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+
+/**
+ * Same job as Android PlaybackStateStore: queue + position survive restart.
+ * Restore is always paused.
+ */
+class DesktopPlaybackStore(configDir: String) {
+    private val file = File(configDir, "playback_state.json")
+    private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
+
+    fun save(snap: PlaybackSnapshot) {
+        if (snap.queue.isEmpty() && snap.coldQueue.isEmpty() && snap.hotQueue.isEmpty()) {
+            clear()
+            return
+        }
+        runCatching {
+            file.parentFile?.mkdirs()
+            val dto = Dto(
+                positionMs = snap.positionMs.coerceAtLeast(0L),
+                index = snap.index,
+                shuffle = snap.shuffle,
+                repeat = snap.repeat.name,
+                volume = snap.volume,
+                queue = snap.queue,
+                linear = snap.linear,
+                history = snap.history,
+                hotQueue = snap.hotQueue,
+                coldQueue = snap.coldQueue,
+                coldOriginal = snap.coldOriginal,
+                coldSource = snap.coldSource,
+                lane = snap.lane.name,
+                indexInLane = snap.indexInLane,
+                savedAt = System.currentTimeMillis()
+            )
+            val tmp = File(file.parentFile, "playback_state.json.tmp")
+            tmp.writeText(json.encodeToString(dto))
+            if (!tmp.renameTo(file)) {
+                tmp.copyTo(file, overwrite = true)
+                tmp.delete()
+            }
+        }
+    }
+
+    fun load(): PlaybackSnapshot? {
+        if (!file.isFile) return null
+        return runCatching {
+            val dto = json.decodeFromString<Dto>(file.readText())
+            if (dto.queue.isEmpty() && dto.coldQueue.isEmpty() && dto.hotQueue.isEmpty()) {
+                return@runCatching null
+            }
+
+            // Legacy files only carried `queue` (flattened, queue[0] = current)
+            // and `linear` (full context). Reconstruct the lanes so the current
+            // track is preserved instead of always pointing at linear[0].
+            val isLegacy = dto.coldQueue.isEmpty() && dto.hotQueue.isEmpty()
+            val cold = dto.coldQueue.ifEmpty { dto.linear.ifEmpty { dto.queue } }
+            val coldOrig = dto.coldOriginal.ifEmpty { dto.linear.ifEmpty { dto.queue } }
+            val indexInLane = if (isLegacy) {
+                val currentId = dto.queue.firstOrNull()?.songKey
+                cold.indexOfFirst { it.songKey == currentId }
+                    .takeIf { it >= 0 }
+                    ?: dto.indexInLane.coerceIn(cold.indices)
+            } else {
+                dto.indexInLane.coerceIn(cold.indices)
+            }
+
+            PlaybackSnapshot(
+                queue = dto.queue,
+                linear = dto.linear.ifEmpty { coldOrig },
+                index = dto.index,
+                history = dto.history,
+                shuffle = dto.shuffle,
+                repeat = runCatching { RepeatMode.valueOf(dto.repeat) }.getOrDefault(RepeatMode.OFF),
+                volume = dto.volume.coerceIn(0f, 1f),
+                positionMs = dto.positionMs,
+                hotQueue = dto.hotQueue,
+                coldQueue = cold,
+                coldOriginal = coldOrig,
+                coldSource = dto.coldSource,
+                lane = runCatching { QueueLane.valueOf(dto.lane) }.getOrDefault(QueueLane.COLD),
+                indexInLane = indexInLane
+            )
+        }.getOrNull()
+    }
+
+    fun clear() {
+        runCatching { if (file.exists()) file.delete() }
+    }
+
+    @Serializable
+    private data class Dto(
+        val positionMs: Long = 0L,
+        val index: Int = 0,
+        val shuffle: Boolean = false,
+        val repeat: String = "OFF",
+        val volume: Float = 1f,
+        val queue: List<Song> = emptyList(),
+        val linear: List<Song> = emptyList(),
+        val history: List<Song> = emptyList(),
+        val hotQueue: List<Song> = emptyList(),
+        val coldQueue: List<Song> = emptyList(),
+        val coldOriginal: List<Song> = emptyList(),
+        val coldSource: ColdSource? = null,
+        val lane: String = "COLD",
+        val indexInLane: Int = 0,
+        val savedAt: Long = 0L
+    )
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopPlaylistStore.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopPlaylistStore.kt
new file mode 100644
index 00000000..0628f932
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopPlaylistStore.kt
@@ -0,0 +1,362 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.core.library.indexKeys
+import capital.yuri.yuriplayer.core.library.playlistKeys
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.Song
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+import java.util.UUID
+import javax.imageio.ImageIO
+
+/**
+ * Desktop playlists: JSON + cover files on disk.
+ * Secret covers stay in the file but are not the active slot after a cold start.
+ */
+class DesktopPlaylistStore(configDir: String) {
+    private val log = yuriLog("Playlist")
+
+    private val root = File(configDir, "playlists")
+    private val jsonFile = File(root, "playlists.json")
+    private val coversDir = File(root, "covers")
+    private val json = Json { ignoreUnknownKeys = true; prettyPrint = true; encodeDefaults = true }
+
+    private val _playlists = MutableStateFlow<List<DesktopPlaylist>>(emptyList())
+    val playlists: StateFlow<List<DesktopPlaylist>> = _playlists.asStateFlow()
+
+    init {
+        root.mkdirs()
+        coversDir.mkdirs()
+        load()
+        resetSecretActiveCoversToPublic()
+    }
+
+    fun get(id: String): DesktopPlaylist? = _playlists.value.firstOrNull { it.id == id }
+
+    fun create(name: String, description: String? = null, trackIds: List<String> = emptyList()): DesktopPlaylist {
+        val now = System.currentTimeMillis()
+        val pl = DesktopPlaylist(
+            id = UUID.randomUUID().toString(),
+            name = name.trim().ifEmpty { "New playlist" },
+            description = description?.trim()?.takeIf { it.isNotEmpty() },
+            trackIds = trackIds,
+            covers = emptyList(),
+            activeCoverId = null,
+            createdAtMs = now,
+            updatedAtMs = now
+        )
+        _playlists.value = listOf(pl) + _playlists.value
+        persist()
+        return pl
+    }
+
+    fun rename(id: String, name: String, description: String?) {
+        update(id) {
+            it.copy(
+                name = name.trim().ifEmpty { it.name },
+                description = description?.trim()?.takeIf { it.isNotEmpty() }
+            )
+        }
+    }
+
+    fun setTracks(id: String, trackIds: List<String>) {
+        update(id) { pl ->
+            val byId = pl.orderedEntries().associateBy { it.snapshot.songKey }
+            val next = trackIds.mapIndexedNotNull { i, key ->
+                byId[key]?.copy(ordinal = i)
+            }
+            pl.withEntries(next)
+        }
+    }
+
+    fun addTracks(id: String, tracks: List<Song>) {
+        if (tracks.isEmpty()) return
+        update(id) { pl ->
+            val current = pl.orderedEntries().toMutableList()
+            var nextOrdinal = (current.maxOfOrNull { it.ordinal } ?: -1) + 1
+            for (t in tracks) {
+                PlaylistLog.add(pl.name, t)
+                val i = current.indexOfFirst { e -> e.matches(t) }
+                if (i >= 0) {
+                    current[i] = current[i].copy(
+                        snapshot = t,
+                        keys = t.indexKeys().toList()
+                    )
+                } else {
+                    current += PlaylistEntry(
+                        ordinal = nextOrdinal++,
+                        snapshot = t,
+                        keys = t.indexKeys().toList()
+                    )
+                }
+            }
+            pl.withEntries(current)
+        }
+    }
+
+    fun remember(tracks: List<Song>) {
+        if (tracks.isEmpty()) return
+        var any = false
+        val next = _playlists.value.map { pl ->
+            val current = pl.orderedEntries().toMutableList()
+            var hit = false
+            for (t in tracks) {
+                val i = current.indexOfFirst { e -> e.matches(t) }
+                if (i < 0) continue
+                current[i] = current[i].copy(snapshot = t, keys = t.indexKeys().toList())
+                hit = true
+            }
+            if (!hit) pl else {
+                any = true
+                pl.withEntries(current)
+            }
+        }
+        if (any) {
+            _playlists.value = next
+            persist()
+        }
+    }
+
+    fun playlistsContaining(trackId: String): Set<String> =
+        playlistsContaining(Song(id = 0, contentUri = "", path = trackId))
+
+    fun playlistsContaining(track: Song): Set<String> {
+        val keys = track.indexKeys()
+        return _playlists.value.filter { pl ->
+            pl.orderedEntries().any { e -> e.allKeys().any { it in keys } }
+        }.map { it.id }.toSet()
+    }
+
+    fun removeTracks(id: String, tracks: List<Song>) {
+        val drop = tracks.flatMap { it.indexKeys() }.toHashSet()
+        update(id) { pl ->
+            pl.withEntries(
+                pl.orderedEntries().filterNot { e -> e.allKeys().any { it in drop } }
+            )
+        }
+    }
+
+    fun moveTrack(id: String, from: Int, to: Int) {
+        update(id) { pl ->
+            val list = pl.orderedEntries().toMutableList()
+            if (from !in list.indices || to !in list.indices || from == to) return@update pl
+            val item = list.removeAt(from)
+            list.add(to, item)
+            pl.withEntries(list)
+        }
+    }
+
+    fun addCover(playlistId: String, source: File, isSecret: Boolean, makeActive: Boolean = !isSecret): DesktopCover? {
+        val pl = get(playlistId) ?: return null
+        if (!source.isFile) return null
+        val coverId = UUID.randomUUID().toString()
+        val destDir = File(coversDir, playlistId).also { it.mkdirs() }
+        val dest = File(destDir, "$coverId.jpg")
+        copyAsJpeg(source, dest)
+        val cover = DesktopCover(
+            id = coverId,
+            path = dest.absolutePath,
+            isSecret = isSecret,
+            sortOrder = (pl.covers.maxOfOrNull { it.sortOrder } ?: -1) + 1
+        )
+        update(playlistId) {
+            val next = it.copy(covers = it.covers + cover)
+            if (makeActive) next.copy(activeCoverId = coverId) else next
+        }
+        return cover
+    }
+
+    fun setActiveCover(playlistId: String, coverId: String) {
+        update(playlistId) { pl ->
+            if (pl.covers.none { it.id == coverId }) pl
+            else pl.copy(activeCoverId = coverId)
+        }
+    }
+
+    fun setCoverSecret(playlistId: String, coverId: String, secret: Boolean) {
+        update(playlistId) { pl ->
+            pl.copy(covers = pl.covers.map { if (it.id == coverId) it.copy(isSecret = secret) else it })
+        }
+    }
+
+    fun removeCover(playlistId: String, coverId: String) {
+        val pl = get(playlistId) ?: return
+        val cover = pl.covers.firstOrNull { it.id == coverId } ?: return
+        File(cover.path).delete()
+        update(playlistId) {
+            val remaining = it.covers.filterNot { c -> c.id == coverId }
+            val active = if (it.activeCoverId == coverId) {
+                remaining.firstOrNull { c -> !c.isSecret }?.id ?: remaining.firstOrNull()?.id
+            } else it.activeCoverId
+            it.copy(covers = remaining, activeCoverId = active)
+        }
+    }
+
+    fun delete(id: String) {
+        File(coversDir, id).deleteRecursively()
+        _playlists.value = _playlists.value.filterNot { it.id == id }
+        persist()
+    }
+
+    fun resetSecretActiveCoversToPublic() {
+        var changed = false
+        val next = _playlists.value.map { pl ->
+            val active = pl.covers.firstOrNull { it.id == pl.activeCoverId }
+            if (active?.isSecret != true) return@map pl
+            changed = true
+            val pub = pl.covers.firstOrNull { !it.isSecret }
+            pl.copy(activeCoverId = pub?.id)
+        }
+        if (changed) {
+            _playlists.value = next
+            persist()
+        }
+    }
+
+    private fun update(id: String, transform: (DesktopPlaylist) -> DesktopPlaylist) {
+        _playlists.value = _playlists.value.map {
+            if (it.id != id) it
+            else transform(it).copy(updatedAtMs = System.currentTimeMillis())
+        }
+        persist()
+    }
+
+    private fun load() {
+        if (!jsonFile.exists()) return
+        runCatching {
+            val file = json.decodeFromString<PlaylistFile>(jsonFile.readText())
+            _playlists.value = file.playlists.map { it.withEntries(it.orderedEntries()) }
+        }.onFailure {
+            log.w { "load failed: ${it.message}" }
+        }
+    }
+
+    private fun persist() {
+        runCatching {
+            root.mkdirs()
+            jsonFile.writeText(json.encodeToString(PlaylistFile(_playlists.value)))
+        }.onFailure {
+            log.w { "save failed: ${it.message}" }
+        }
+    }
+
+    private fun copyAsJpeg(source: File, dest: File) {
+        dest.parentFile.mkdirs()
+        val img = ImageIO.read(source)
+        if (img != null) {
+            ImageIO.write(img, "jpg", dest)
+        } else {
+            source.copyTo(dest, overwrite = true)
+        }
+    }
+
+    @Serializable
+    private data class PlaylistFile(val playlists: List<DesktopPlaylist> = emptyList())
+}
+
+@Serializable
+data class DesktopPlaylist(
+    val id: String,
+    val name: String,
+    val description: String? = null,
+    val trackIds: List<String> = emptyList(),
+    val covers: List<DesktopCover> = emptyList(),
+    val activeCoverId: String? = null,
+    val createdAtMs: Long = 0L,
+    val updatedAtMs: Long = 0L,
+    val snapshots: List<Song> = emptyList(),
+    val entries: List<PlaylistEntry> = emptyList()
+) {
+    fun artworkUri(library: List<Song>): String? {
+        val active = covers.firstOrNull { it.id == activeCoverId } ?: covers.firstOrNull { !it.isSecret }
+        if (active != null) return File(active.path).toURI().toString()
+        return tracks(library).firstOrNull()?.albumArtUri
+    }
+
+    fun orderedEntries(): List<PlaylistEntry> {
+        if (entries.isNotEmpty()) return entries.sortedBy { it.ordinal }
+        return migrateLegacyEntries()
+    }
+
+    fun withEntries(list: List<PlaylistEntry>): DesktopPlaylist {
+        val compact = list.sortedBy { it.ordinal }.mapIndexed { i, e ->
+            e.copy(ordinal = i, keys = e.snapshot.indexKeys().toList().ifEmpty { e.keys })
+        }
+        return copy(
+            entries = compact,
+            trackIds = compact.map { it.snapshot.songKey },
+            snapshots = compact.map { it.snapshot }
+        )
+    }
+
+    fun tracks(library: List<Song>): List<Song> {
+        val index = HashMap<String, Song>()
+        for (t in library) {
+            for (k in t.indexKeys()) index.putIfAbsent(k, t)
+        }
+        val ordered = orderedEntries()
+        val seen = HashSet<String>()
+        val out = ArrayList<Song>(ordered.size)
+        for (entry in ordered) {
+            val live = entry.allKeys().firstNotNullOfOrNull { index[it] } ?: entry.snapshot
+            if (live.indexKeys().any { it in seen }) continue
+            seen += live.indexKeys()
+            out += live
+        }
+        return out
+    }
+
+    private fun migrateLegacyEntries(): List<PlaylistEntry> {
+        val byKey = HashMap<String, Song>()
+        for (t in snapshots) {
+            for (k in t.indexKeys()) byKey.putIfAbsent(k, t)
+        }
+        val used = HashSet<String>()
+        val out = ArrayList<PlaylistEntry>()
+        fun take(t: Song) {
+            if (t.indexKeys().any { it in used }) return
+            used += t.indexKeys()
+            out += PlaylistEntry(
+                ordinal = out.size,
+                snapshot = t,
+                keys = t.indexKeys().toList()
+            )
+        }
+        for (key in trackIds) {
+            val hit = byKey[key] ?: snapshots.firstOrNull { key in it.indexKeys() }
+            if (hit != null) take(hit)
+        }
+        for (s in snapshots) take(s)
+        return out
+    }
+}
+
+@Serializable
+data class PlaylistEntry(
+    val ordinal: Int,
+    val snapshot: Song,
+    val keys: List<String> = emptyList()
+) {
+    fun allKeys(): Set<String> = buildSet {
+        addAll(keys)
+        addAll(snapshot.indexKeys())
+    }
+
+    fun matches(track: Song): Boolean {
+        val theirs = track.indexKeys()
+        return allKeys().any { it in theirs }
+    }
+}
+
+@Serializable
+data class DesktopCover(
+    val id: String,
+    val path: String,
+    val isSecret: Boolean = false,
+    val sortOrder: Int = 0
+)
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopSession.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopSession.kt
new file mode 100644
index 00000000..e3e0970c
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopSession.kt
@@ -0,0 +1,890 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.core.artist.ArtistImageCandidate
+import capital.yuri.yuriplayer.core.artist.ArtistInfoClient
+import capital.yuri.yuriplayer.core.artist.ArtistProfileStore
+import capital.yuri.yuriplayer.core.library.CoverPixels
+import capital.yuri.yuriplayer.core.library.LocalLibraryScanner
+import capital.yuri.yuriplayer.core.library.indexKeys
+import capital.yuri.yuriplayer.core.library.rawSourceId
+import capital.yuri.yuriplayer.core.network.NetworkMonitor
+import capital.yuri.yuriplayer.core.os.OsMediaControls
+import capital.yuri.yuriplayer.core.platform.appDirectories
+import capital.yuri.yuriplayer.core.player.PlaybackSnapshot
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import capital.yuri.yuriplayer.core.source.JellyfinCatalog
+import capital.yuri.yuriplayer.core.source.LibrarySourceStore
+import capital.yuri.yuriplayer.core.source.RemoteAccount
+import capital.yuri.yuriplayer.core.source.SourceKind
+import capital.yuri.yuriplayer.core.source.SubsonicCatalog
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.desktop.player.DesktopPlayerHost
+import io.ktor.client.HttpClient
+import io.ktor.client.engine.cio.CIO
+import kotlinx.coroutines.async
+import kotlinx.coroutines.coroutineScope
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.swing.Swing
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import java.io.File
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicReference
+
+enum class DesktopScanStatus { IDLE, RUNNING, PAUSED, STOPPED, DONE, ERROR }
+
+data class DesktopScanSource(
+    val id: String,
+    val name: String,
+    val status: DesktopScanStatus,
+    val detail: String = "",
+    val count: Int = 0,
+    val startIndex: Int = 0,
+    val delivered: Int = 0,
+    val totalHint: Int? = null
+)
+
+class DesktopSession(
+    val player: DesktopPlayerHost,
+    private val media: OsMediaControls
+) {
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Swing)
+    private val http = HttpClient(CIO)
+    val network: NetworkMonitor = DesktopNetworkMonitor()
+
+    private val _engineMessage = MutableStateFlow<String?>(null)
+    val engineMessage: StateFlow<String?> = _engineMessage.asStateFlow()
+
+    private val _tracks = MutableStateFlow<List<Song>>(emptyList())
+    val tracks: StateFlow<List<Song>> = _tracks.asStateFlow()
+
+    private val _scanMessage = MutableStateFlow("Scanning…")
+    val scanMessage: StateFlow<String> = _scanMessage.asStateFlow()
+
+    private val _isScanning = MutableStateFlow(false)
+    val isScanning: StateFlow<Boolean> = _isScanning.asStateFlow()
+
+    private val _scanSources = MutableStateFlow<List<DesktopScanSource>>(emptyList())
+    val scanSources: StateFlow<List<DesktopScanSource>> = _scanSources.asStateFlow()
+
+    private val _positionMs = MutableStateFlow(0L)
+    val positionMs: StateFlow<Long> = _positionMs.asStateFlow()
+
+    private val _durationMs = MutableStateFlow(0L)
+    val durationMs: StateFlow<Long> = _durationMs.asStateFlow()
+
+    private val _coverPixels = MutableStateFlow<IntArray?>(null)
+    val coverPixels: StateFlow<IntArray?> = _coverPixels.asStateFlow()
+
+    val dirs = appDirectories()
+    val theme = DesktopThemeStore(dirs.configDir)
+    val layout = DesktopLayoutStore(dirs.configDir)
+    val collection = DesktopCollection(dirs.configDir)
+    val playlists = DesktopPlaylistStore(dirs.configDir)
+    val sourcePrefs = DesktopSourcePrefs(dirs.configDir)
+    val sources = LibrarySourceStore(dirs.configDir)
+    private val index = DesktopIndexStore(dirs.cacheDir)
+    private val playbackStore = DesktopPlaybackStore(dirs.configDir)
+    val jellyfin = JellyfinCatalog(http, sources.deviceId)
+    val subsonic = SubsonicCatalog(http)
+    val artists = ArtistInfoClient(
+        http,
+        ArtistProfileStore(dirs.configDir, dirs.cacheDir)
+    ) { name -> libraryArtistImages(name) }
+
+    private var ticker: Job? = null
+    private var persistJob: Job? = null
+    private var scanJob: Job? = null
+    private var sourceJob: Job? = null
+    private val scanGate = Mutex()
+    private val stopAll = AtomicBoolean(false)
+    private val pauseAll = AtomicBoolean(false)
+    private val pausedIds = ConcurrentHashMap.newKeySet<String>()
+    private val stoppedIds = ConcurrentHashMap.newKeySet<String>()
+    private val currentSourceId = AtomicReference<String?>(null)
+
+    var onRaise: (() -> Unit)? = null
+
+    init {
+        media.attach(object : OsMediaControls.Callbacks {
+            override fun onPlay() {
+                if (!player.isPlaying.value) player.togglePlay()
+            }
+            override fun onPause() = player.pause()
+            override fun onPlayPause() = player.togglePlay()
+            override fun onStop() = player.stop()
+            override fun onNext() = player.next()
+            override fun onPrevious() = player.previous()
+            override fun onSeek(positionMs: Long) = player.seekTo(positionMs)
+            override fun onVolume(value: Float) = player.setVolume(value)
+            override fun onLoop(mode: RepeatMode) = player.setRepeat(mode)
+            override fun onShuffle(enabled: Boolean) = player.setShuffle(enabled)
+            override fun onRaise() { onRaise?.invoke() }
+            override fun onQuit() = release()
+        })
+        ticker = scope.launch {
+            while (isActive) {
+                _positionMs.value = player.positionMs()
+                _durationMs.value = player.durationMs()
+                media.update(
+                    track = player.current.value,
+                    playing = player.isPlaying.value,
+                    positionMs = _positionMs.value,
+                    durationMs = _durationMs.value,
+                    volume = player.volume.value
+                )
+                media.setLoop(player.repeat.value)
+                media.setShuffle(player.shuffle.value)
+                delay(250)
+            }
+        }
+        scope.launch(Dispatchers.IO) {
+            player.current.collect { track ->
+                _coverPixels.value = CoverPixels.argb(track?.albumArtUri, track?.path)
+            }
+        }
+        scope.launch {
+            sources.remotes.collect { refreshScanSources() }
+        }
+        player.mediaFor = ::freshMedia
+        hydrateIndex()
+        restorePlayback()
+        media.update(
+            track = player.current.value,
+            playing = player.isPlaying.value,
+            positionMs = player.positionMs(),
+            durationMs = player.durationMs(),
+            volume = player.volume.value
+        )
+        media.setLoop(player.repeat.value)
+        media.setShuffle(player.shuffle.value)
+        startPersist()
+    }
+
+    private fun hydrateIndex() {
+        val cached = index.loadTracks()
+        if (cached.isNotEmpty()) _tracks.value = cached
+        val cps = index.loadCheckpoints()
+        if (cps.isNotEmpty()) {
+            _scanSources.value = cps.map { row ->
+                DesktopScanSource(
+                    id = row.id,
+                    name = row.name,
+                    status = runCatching { DesktopScanStatus.valueOf(row.status) }
+                        .getOrDefault(DesktopScanStatus.IDLE),
+                    detail = row.detail,
+                    count = row.count,
+                    startIndex = row.startIndex,
+                    delivered = row.delivered,
+                    totalHint = row.totalHint
+                )
+            }
+        }
+        _scanMessage.value = when {
+            cached.isEmpty() -> "Indexing…"
+            else -> "${cached.size} tracks"
+        }
+        val snaps = playlists.playlists.value.flatMap { it.snapshots }
+        if (snaps.isNotEmpty()) mergeTracks(snaps)
+        requestScan(force = cached.isEmpty())
+    }
+
+    private fun restorePlayback() {
+        val snap = playbackStore.load() ?: return
+        player.restore(resolveSnap(snap), play = false)
+        _positionMs.value = player.positionMs()
+        _durationMs.value = player.durationMs()
+    }
+
+    private fun freshMedia(track: Song): Song {
+        val remote = sources.remotes.value.firstOrNull { it.id == track.sourceId && it.enabled }
+            ?: return track
+        val raw = track.rawSourceId() ?: return track
+        return when (remote.kind) {
+            SourceKind.SUBSONIC -> track.copy(
+                contentUri = subsonic.streamUrl(remote, raw),
+                albumArtUri = track.albumArtUri ?: subsonic.coverUrl(remote, raw)
+            )
+            SourceKind.JELLYFIN -> track.copy(contentUri = jellyfin.streamUrl(remote, raw))
+            SourceKind.LOCAL -> track
+        }
+    }
+
+    private fun resolveSnap(snap: PlaybackSnapshot): PlaybackSnapshot {
+        val lib = _tracks.value
+        if (lib.isEmpty()) return snap
+        val byKey = HashMap<String, Song>(lib.size * 2)
+        for (t in lib) {
+            t.indexKeys().forEach { byKey.putIfAbsent(it, t) }
+        }
+        fun resolve(list: List<Song>) = list.map { t ->
+            t.indexKeys().firstNotNullOfOrNull { byKey[it] } ?: t
+        }
+        return snap.copy(
+            queue = resolve(snap.queue),
+            linear = resolve(snap.linear),
+            history = resolve(snap.history),
+            hotQueue = resolve(snap.hotQueue),
+            coldQueue = resolve(snap.coldQueue),
+            coldOriginal = resolve(snap.coldOriginal.ifEmpty { snap.linear })
+        )
+    }
+
+    private fun startPersist() {
+        persistJob = scope.launch {
+            while (isActive) {
+                delay(2_000)
+                persistPlayback()
+            }
+        }
+    }
+
+    fun persistPlayback() {
+        playbackStore.save(player.snapshot())
+    }
+
+    fun playTrack(track: Song) {
+        val list = _tracks.value
+        val i = list.indexOfFirst { it.songKey == track.songKey }.coerceAtLeast(0)
+        player.play(if (list.isNotEmpty()) list else listOf(track), i)
+    }
+
+    fun replaceTracks(updated: List<Song>) {
+        if (updated.isEmpty()) return
+        val byId = updated.associateBy { it.songKey }
+        _tracks.value = _tracks.value.map { byId[it.songKey] ?: it }
+    }
+
+    fun addFolder(path: String) {
+        sources.addFolder(path)
+        indexFolder(path)
+    }
+
+    fun removeFolder(path: String) {
+        sources.removeFolder(path)
+        rescan()
+    }
+
+    fun addJellyfin(name: String, baseUrl: String, username: String, password: String) {
+        saveRemote(
+            existingId = null,
+            kind = SourceKind.JELLYFIN,
+            name = name,
+            baseUrl = baseUrl,
+            username = username,
+            password = password,
+            enabled = true
+        )
+    }
+
+    fun addSubsonic(name: String, baseUrl: String, username: String, password: String) {
+        saveRemote(
+            existingId = null,
+            kind = SourceKind.SUBSONIC,
+            name = name,
+            baseUrl = baseUrl,
+            username = username,
+            password = password,
+            enabled = true
+        )
+    }
+
+    fun saveRemote(
+        existingId: String?,
+        kind: SourceKind,
+        name: String,
+        baseUrl: String,
+        username: String,
+        password: String,
+        enabled: Boolean,
+        onDone: (ok: Boolean, message: String) -> Unit = { ok, msg ->
+            if (!ok) _scanMessage.value = msg
+        }
+    ) {
+        scope.launch(Dispatchers.IO) {
+            val existing = existingId?.let { id -> sources.remotes.value.firstOrNull { it.id == id } }
+            val seed = RemoteAccount(
+                id = existing?.id ?: UUID.randomUUID().toString(),
+                kind = kind,
+                name = name.ifBlank {
+                    if (kind == SourceKind.JELLYFIN) "Jellyfin" else "Subsonic"
+                },
+                baseUrl = baseUrl,
+                username = username,
+                secret = password.ifBlank { existing?.secret.orEmpty() },
+                enabled = enabled,
+                accessToken = existing?.accessToken,
+                userId = existing?.userId
+            )
+            val result = when (kind) {
+                SourceKind.JELLYFIN -> jellyfin.authenticate(seed)
+                SourceKind.SUBSONIC -> subsonic.ping(seed)
+                SourceKind.LOCAL -> Result.failure(IllegalArgumentException("Not a remote provider"))
+            }
+            result
+                .onSuccess { signed ->
+                    val saved = signed.copy(enabled = enabled, name = seed.name)
+                    sources.upsertRemote(saved)
+                    if (enabled) indexRemote(saved)
+                    withContext(Dispatchers.Swing) { onDone(true, "Saved — indexing ${saved.name}") }
+                }
+                .onFailure {
+                    withContext(Dispatchers.Swing) {
+                        onDone(false, it.message ?: "Could not reach server")
+                    }
+                }
+        }
+    }
+
+    suspend fun testConnection(
+        kind: SourceKind,
+        url: String,
+        username: String,
+        password: String
+    ): Result<String> {
+        val seed = RemoteAccount(
+            id = "test",
+            kind = kind,
+            name = "",
+            baseUrl = url,
+            username = username,
+            secret = password
+        )
+        return when (kind) {
+            SourceKind.JELLYFIN -> jellyfin.authenticate(seed).map { signed ->
+                val who = signed.userId?.take(8)?.plus("…") ?: signed.username
+                "Connected as $who"
+            }
+            SourceKind.SUBSONIC -> subsonic.ping(seed).map { "Ping ok" }
+            SourceKind.LOCAL -> Result.failure(IllegalArgumentException("Not a remote provider"))
+        }
+    }
+
+    fun setRemoteEnabled(id: String, enabled: Boolean) {
+        sources.setRemoteEnabled(id, enabled)
+        if (enabled) {
+            sources.remotes.value.firstOrNull { it.id == id }?.let { indexRemote(it) }
+        }
+    }
+
+    fun removeRemote(id: String) {
+        sources.removeRemote(id)
+        replaceSourceTracks(id, emptyList())
+        persistIndex()
+        refreshScanSources()
+    }
+
+    fun indexFolder(path: String) {
+        requestScan(force = true, sourceId = LOCAL_SCAN_ID)
+    }
+
+    fun indexRemote(account: RemoteAccount) {
+        if (!account.enabled || account.kind == SourceKind.LOCAL) return
+        requestScan(force = true, sourceId = account.id)
+    }
+
+    private fun mergeTracks(incoming: List<Song>) {
+        if (incoming.isEmpty()) return
+        val before = _tracks.value.size
+        _tracks.value = (_tracks.value + incoming).distinctBy { it.songKey }
+        PlaylistLog.index("merge +${incoming.size} $before→${_tracks.value.size}")
+    }
+
+    fun ensureTracks(incoming: List<Song>) {
+        if (incoming.isEmpty()) return
+        PlaylistLog.index("ensure ${incoming.map { "${it.displayTitle}/${it.songKey}" }}")
+        mergeTracks(incoming)
+        persistIndex()
+        playlists.remember(incoming)
+    }
+
+    private fun playlistRefs(): Set<String> =
+        playlists.playlists.value.flatMap { pl ->
+            pl.trackIds + pl.snapshots.flatMap { it.indexKeys() }
+        }.toHashSet()
+
+    private fun replaceSourceTracks(sourceId: String, incoming: List<Song>) {
+        val referenced = playlistRefs()
+        val existing = _tracks.value
+        val incomingIds = incoming.map { it.songKey }.toHashSet()
+        val orphans = existing.filter { t ->
+            (t.sourceId ?: LOCAL_SCAN_ID) == sourceId &&
+                t.songKey !in incomingIds &&
+                t.indexKeys().any { it in referenced }
+        }
+        val rest = existing.filterNot { (it.sourceId ?: LOCAL_SCAN_ID) == sourceId }
+        val dropped = existing.count {
+            (it.sourceId ?: LOCAL_SCAN_ID) == sourceId &&
+                it.songKey !in incomingIds &&
+                it.indexKeys().none { k -> k in referenced }
+        }
+        PlaylistLog.index(
+            "replace source=$sourceId incoming=${incoming.size} orphans=${orphans.size} dropped=$dropped refs=${referenced.size}"
+        )
+        _tracks.value = (rest + incoming + orphans).distinctBy { it.songKey }
+        val snaps = playlists.playlists.value.flatMap { it.snapshots }
+        if (snaps.isNotEmpty()) mergeTracks(snaps)
+    }
+
+    private fun persistIndex() {
+        index.saveTracks(_tracks.value)
+        persistCheckpoints()
+    }
+
+    private fun persistCheckpoints() {
+        index.saveCheckpoints(
+            _scanSources.value.map {
+                DesktopIndexStore.StoredCheckpoint(
+                    id = it.id,
+                    name = it.name,
+                    status = it.status.name,
+                    startIndex = it.startIndex,
+                    delivered = it.delivered,
+                    totalHint = it.totalHint,
+                    count = it.count,
+                    detail = it.detail
+                )
+            }
+        )
+    }
+
+    fun rescan() = requestScan(force = true)
+
+    fun requestScan(force: Boolean = false, sourceId: String? = null) {
+        if (force && sourceId == null) {
+            pausedIds.clear()
+            stoppedIds.clear()
+            sourceJob?.cancel()
+            scanJob?.cancel()
+            _scanSources.value = _scanSources.value.map {
+                it.copy(startIndex = 0, delivered = 0)
+            }
+        }
+        if (force && sourceId != null) {
+            _scanSources.value = _scanSources.value.map {
+                if (it.id == sourceId) it.copy(startIndex = 0, delivered = 0) else it
+            }
+        }
+        stopAll.set(false)
+        pauseAll.set(false)
+        if (sourceId != null) {
+            pausedIds.remove(sourceId)
+            stoppedIds.remove(sourceId)
+        } else if (force) {
+            pausedIds.clear()
+            stoppedIds.clear()
+        }
+        scanJob = scope.launch(Dispatchers.IO) {
+            scanGate.withLock {
+                runScan(force = force, onlySourceId = sourceId)
+            }
+        }
+    }
+
+    fun pauseScan(sourceId: String? = null) {
+        if (sourceId == null) {
+            pauseAll.set(true)
+            sourceJob?.cancel()
+            markRunning(DesktopScanStatus.PAUSED, "Paused")
+            _scanMessage.value = "Paused"
+            persistIndex()
+        } else {
+            pausedIds.add(sourceId)
+            patchScan(sourceId, DesktopScanStatus.PAUSED, "Paused")
+            if (currentSourceId.get() == sourceId) sourceJob?.cancel()
+        }
+    }
+
+    fun stopScan(sourceId: String? = null) {
+        if (sourceId == null) {
+            stopAll.set(true)
+            sourceJob?.cancel()
+            markRunning(DesktopScanStatus.STOPPED, "Stopped")
+            _isScanning.value = false
+            _scanMessage.value = "Stopped"
+            persistIndex()
+        } else {
+            stoppedIds.add(sourceId)
+            patchScan(sourceId, DesktopScanStatus.STOPPED, "Stopped")
+            if (currentSourceId.get() == sourceId) sourceJob?.cancel()
+        }
+    }
+
+    private suspend fun runScan(force: Boolean, onlySourceId: String?) {
+        _isScanning.value = true
+        refreshScanSources()
+        try {
+            coroutineScope {
+                val doLocal = onlySourceId == null || onlySourceId == LOCAL_SCAN_ID
+                val remotes = sources.remotes.value.filter { it.enabled }
+                    .filter { onlySourceId == null || it.id == onlySourceId }
+
+                val localTracks = if (doLocal) {
+                    scanOneSource(LOCAL_SCAN_ID, "Local library", force, onlySourceId) {
+                        scanLocalLibrary()
+                    }
+                } else {
+                    emptyList()
+                }
+                if (halted()) return@coroutineScope
+
+                val remoteTracks = mutableListOf<Song>()
+                for (remote in remotes) {
+                    if (halted()) break
+                    val got = scanOneSource(remote.id, remote.name, force, onlySourceId) {
+                        fetchRemote(remote, force = force)
+                    }
+                    remoteTracks += got
+                }
+
+                if (stopAll.get() || pauseAll.get()) return@coroutineScope
+
+                if (onlySourceId == null && force) {
+                    val keepIds = buildSet {
+                        if (doLocal) add(LOCAL_SCAN_ID)
+                        remotes.forEach { add(it.id) }
+                    }
+                    val leftovers = _tracks.value.filterNot {
+                        (it.sourceId ?: LOCAL_SCAN_ID) in keepIds
+                    }
+                    _tracks.value = (leftovers + localTracks + remoteTracks).distinctBy { it.songKey }
+                } else if (onlySourceId != null && force) {
+                    replaceSourceTracks(onlySourceId, localTracks + remoteTracks)
+                } else {
+                    mergeTracks(localTracks + remoteTracks)
+                }
+                persistIndex()
+                _scanMessage.value = when {
+                    _tracks.value.isEmpty() ->
+                        "No tracks yet — add a folder or a server in Settings → Library"
+                    else -> "${_tracks.value.size} tracks"
+                }
+            }
+        } catch (e: CancellationException) {
+            if (pauseAll.get()) {
+                markRunning(DesktopScanStatus.PAUSED, "Paused")
+                _scanMessage.value = "Paused"
+            } else {
+                markRunning(DesktopScanStatus.STOPPED, "Stopped")
+                _scanMessage.value = "Stopped"
+            }
+            throw e
+        } finally {
+            currentSourceId.set(null)
+            sourceJob = null
+            _isScanning.value = false
+        }
+    }
+
+    private fun halted(): Boolean = stopAll.get() || pauseAll.get()
+
+    private fun shouldScan(id: String, force: Boolean, onlySourceId: String?): Boolean {
+        if (id in stoppedIds && onlySourceId != id) return false
+        if (id in pausedIds && onlySourceId != id && !force) return false
+        val src = _scanSources.value.firstOrNull { it.id == id }
+        if (force) return true
+        if (onlySourceId == id) return true
+        if (src?.status == DesktopScanStatus.PAUSED || src?.status == DesktopScanStatus.STOPPED) {
+            return true
+        }
+        if (src?.status == DesktopScanStatus.DONE && src.count > 0) {
+            val othersNeedFirst = _scanSources.value.any {
+                it.id != id && it.count == 0 &&
+                    it.status != DesktopScanStatus.DONE &&
+                    it.status != DesktopScanStatus.PAUSED
+            }
+            return !othersNeedFirst
+        }
+        return true
+    }
+
+    private suspend fun scanOneSource(
+        id: String,
+        name: String,
+        force: Boolean,
+        onlySourceId: String?,
+        block: suspend () -> List<Song>
+    ): List<Song> {
+        if (!shouldScan(id, force, onlySourceId)) {
+            val src = _scanSources.value.firstOrNull { it.id == id }
+            if (src?.status == DesktopScanStatus.DONE) {
+                _scanMessage.value = "$name: indexed (${src.count}) — skip"
+            }
+            return emptyList()
+        }
+        if (id in stoppedIds) {
+            patchScan(id, DesktopScanStatus.STOPPED, "Stopped")
+            return emptyList()
+        }
+        if (id in pausedIds || pauseAll.get()) {
+            patchScan(id, DesktopScanStatus.PAUSED, "Paused")
+            return emptyList()
+        }
+        if (stopAll.get()) {
+            patchScan(id, DesktopScanStatus.STOPPED, "Stopped")
+            return emptyList()
+        }
+        currentSourceId.set(id)
+        patchScan(id, DesktopScanStatus.RUNNING, if (force) "Full scan…" else "Checking…")
+        _scanMessage.value = if (force) "Full scan · $name" else "Partial scan · $name"
+        return coroutineScope {
+            val child = async { block() }
+            sourceJob = child
+            try {
+                val incoming = child.await()
+                val prev = _scanSources.value.firstOrNull { it.id == id }?.count ?: 0
+                val nextCount = if (force) incoming.size else maxOf(prev, incoming.size)
+                patchScan(
+                    id,
+                    DesktopScanStatus.DONE,
+                    when {
+                        incoming.isEmpty() && !force -> "up to date"
+                        incoming.isEmpty() -> "0 tracks"
+                        else -> "${incoming.size} tracks"
+                    },
+                    nextCount
+                )
+                persistIndex()
+                incoming
+            } catch (e: CancellationException) {
+                when {
+                    stopAll.get() || id in stoppedIds ->
+                        patchScan(id, DesktopScanStatus.STOPPED, "Stopped")
+                    pauseAll.get() || id in pausedIds ->
+                        patchScan(id, DesktopScanStatus.PAUSED, "Paused")
+                    else -> patchScan(id, DesktopScanStatus.STOPPED, "Stopped")
+                }
+                if (halted()) throw e
+                emptyList()
+            } catch (e: Exception) {
+                patchScan(id, DesktopScanStatus.ERROR, e.message ?: "Failed")
+                _scanMessage.value = "$name: ${e.message}"
+                emptyList()
+            } finally {
+                if (currentSourceId.get() == id) currentSourceId.set(null)
+                if (sourceJob === child) sourceJob = null
+            }
+        }
+    }
+
+    private fun scanLocalLibrary(): List<Song> {
+        val defaultRoots = LocalLibraryScanner.defaultRoots()
+        val extra = sources.extraFolders.value.map { File(it) }.filter { it.isDirectory }
+        val roots = (defaultRoots + extra).distinctBy { it.absolutePath }
+        _scanMessage.value = if (roots.isEmpty()) {
+            "No local folders yet"
+        } else {
+            "Scanning ${roots.joinToString { it.name }}…"
+        }
+        return if (roots.isEmpty()) emptyList() else LocalLibraryScanner.scan(roots)
+    }
+
+    private suspend fun fetchRemote(remote: RemoteAccount, force: Boolean): List<Song> {
+        val src = _scanSources.value.firstOrNull { it.id == remote.id }
+        val known = src?.count ?: _tracks.value.count { it.sourceId == remote.id }
+        val already = known > 0 && src?.status == DesktopScanStatus.DONE
+        val incremental = !force && already
+        val resumeFrom = if (force || incremental) 0 else src?.startIndex ?: 0
+        val priorDelivered = if (force || incremental) 0 else src?.delivered ?: 0
+
+        return when (remote.kind) {
+            SourceKind.JELLYFIN -> {
+                val authed = if (remote.accessToken.isNullOrBlank()) {
+                    jellyfin.authenticate(remote).getOrElse { throw it }
+                        .also { sources.upsertRemote(it) }
+                } else remote
+                if (incremental) {
+                    val total = jellyfin.audioCount(authed).getOrElse { -1 }
+                    if (total in 0..known) return emptyList()
+                    val cap = if (total > known) (total - known + 64).coerceIn(1, 2_000) else 256
+                    jellyfin.listTracks(
+                        authed,
+                        maxItems = cap,
+                        sortBy = "DateCreated",
+                        sortOrder = "Descending"
+                    ).getOrElse { throw it }
+                } else {
+                    walkJellyfin(authed, remote, resumeFrom, priorDelivered)
+                }
+            }
+            SourceKind.SUBSONIC -> {
+                if (incremental) {
+                    subsonic.listNewestTracks(remote).getOrElse { throw it }
+                } else {
+                    walkSubsonic(remote, resumeFrom, priorDelivered)
+                }
+            }
+            SourceKind.LOCAL -> emptyList()
+        }
+    }
+
+    private suspend fun walkJellyfin(
+        authed: RemoteAccount,
+        remote: RemoteAccount,
+        startFrom: Int,
+        priorDelivered: Int
+    ): List<Song> {
+        var cursor = startFrom
+        var delivered = priorDelivered
+        val collected = ArrayList<Song>()
+        val result = jellyfin.listTracks(authed, startFrom = startFrom) { page, next, total ->
+            collected += page
+            cursor = next
+            delivered += page.size
+            mergeTracks(page)
+            patchScan(
+                id = remote.id,
+                status = DesktopScanStatus.RUNNING,
+                detail = if (total != null) "$delivered / $total" else "$delivered",
+                count = delivered,
+                startIndex = cursor,
+                delivered = delivered,
+                totalHint = total
+            )
+            persistCheckpoints()
+            if (pauseAll.get() || remote.id in pausedIds) {
+                throw CancellationException("paused")
+            }
+            if (stopAll.get() || remote.id in stoppedIds) {
+                throw CancellationException("stopped")
+            }
+        }
+        return result.getOrElse { throw it }.ifEmpty { collected }
+    }
+
+    private suspend fun walkSubsonic(
+        remote: RemoteAccount,
+        startAlbumOffset: Int,
+        priorDelivered: Int
+    ): List<Song> {
+        var cursor = startAlbumOffset
+        var delivered = priorDelivered
+        val collected = ArrayList<Song>()
+        val result = subsonic.listTracks(remote, startAlbumOffset = startAlbumOffset) { page, next, _ ->
+            collected += page
+            cursor = next
+            delivered += page.size
+            mergeTracks(page)
+            patchScan(
+                id = remote.id,
+                status = DesktopScanStatus.RUNNING,
+                detail = "$delivered",
+                count = delivered,
+                startIndex = cursor,
+                delivered = delivered
+            )
+            persistCheckpoints()
+            if (pauseAll.get() || remote.id in pausedIds) throw CancellationException("paused")
+            if (stopAll.get() || remote.id in stoppedIds) throw CancellationException("stopped")
+        }
+        return result.getOrElse { throw it }.ifEmpty { collected }
+    }
+
+    private fun refreshScanSources() {
+        val existing = _scanSources.value.associateBy { it.id }
+        val local = existing[LOCAL_SCAN_ID]
+            ?: DesktopScanSource(LOCAL_SCAN_ID, "Local library", DesktopScanStatus.IDLE)
+        val remotes = sources.remotes.value.filter { it.enabled }.map { remote ->
+            val prev = existing[remote.id]
+            DesktopScanSource(
+                id = remote.id,
+                name = remote.name,
+                status = prev?.status ?: DesktopScanStatus.IDLE,
+                detail = prev?.detail.orEmpty(),
+                count = prev?.count ?: 0,
+                startIndex = prev?.startIndex ?: 0,
+                delivered = prev?.delivered ?: 0,
+                totalHint = prev?.totalHint
+            )
+        }
+        _scanSources.value = listOf(local.copy(name = "Local library")) + remotes
+    }
+
+    private fun patchScan(
+        id: String,
+        status: DesktopScanStatus,
+        detail: String,
+        count: Int? = null,
+        startIndex: Int? = null,
+        delivered: Int? = null,
+        totalHint: Int? = null
+    ) {
+        _scanSources.value = _scanSources.value.map {
+            if (it.id != id) it
+            else it.copy(
+                status = status,
+                detail = detail,
+                count = count ?: it.count,
+                startIndex = startIndex ?: it.startIndex,
+                delivered = delivered ?: it.delivered,
+                totalHint = totalHint ?: it.totalHint
+            )
+        }
+    }
+
+    private fun markRunning(status: DesktopScanStatus, detail: String) {
+        _scanSources.value = _scanSources.value.map {
+            if (it.status == DesktopScanStatus.RUNNING) it.copy(status = status, detail = detail)
+            else it
+        }
+    }
+
+    fun extraScan(path: String) = addFolder(path)
+
+    private suspend fun libraryArtistImages(name: String): List<ArtistImageCandidate> {
+        val out = ArrayList<ArtistImageCandidate>()
+        for (remote in sources.remotes.value.filter { it.enabled }) {
+            val result = when (remote.kind) {
+                SourceKind.JELLYFIN -> jellyfin.searchArtistImages(remote, name)
+                SourceKind.SUBSONIC -> subsonic.searchArtistImages(remote, name)
+                SourceKind.LOCAL -> continue
+            }
+            result.onSuccess { out += it }
+        }
+        return out
+    }
+
+    suspend fun searchRemotes(query: String, sourceIds: Set<String>?): List<Song> {
+        val q = query.trim()
+        if (q.isEmpty()) return emptyList()
+        val remotes = sources.remotes.value.filter { it.enabled }
+            .filter { sourceIds == null || it.id in sourceIds }
+        val out = ArrayList<Song>()
+        for (remote in remotes) {
+            val result = when (remote.kind) {
+                SourceKind.JELLYFIN -> jellyfin.searchTracks(remote, q)
+                SourceKind.SUBSONIC -> subsonic.searchTracks(remote, q)
+                SourceKind.LOCAL -> continue
+            }
+            result.onSuccess { out += it }
+        }
+        return out
+    }
+
+    fun release() {
+        persistJob?.cancel()
+        ticker?.cancel()
+        persistPlayback()
+        media.release()
+        player.release()
+        runCatching { http.close() }
+        scope.coroutineContext[Job]?.cancel()
+    }
+
+    companion object {
+        const val LOCAL_SCAN_ID = "local"
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopSourcePrefs.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopSourcePrefs.kt
new file mode 100644
index 00000000..544f9259
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopSourcePrefs.kt
@@ -0,0 +1,52 @@
+package capital.yuri.yuriplayer.desktop
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.json.Json
+import java.io.File
+
+/**
+ * Preferred playback source per collapsed track identity — same role as
+ * Android SourceResolver overrides.
+ */
+class DesktopSourcePrefs(configDir: String) {
+    private val file = File(configDir, "source_prefs.json")
+    private val json = Json { ignoreUnknownKeys = true; encodeDefaults = true }
+    private val lock = Any()
+    private var map: MutableMap<String, String> = load()
+
+    fun snapshot(): Map<String, String> = synchronized(lock) { map.toMap() }
+
+    fun get(identity: String): String? = synchronized(lock) { map[identity] }
+
+    fun set(identity: String, trackId: String) {
+        synchronized(lock) {
+            map[identity] = trackId
+            persist()
+        }
+    }
+
+    fun clear(identity: String) {
+        synchronized(lock) {
+            map.remove(identity)
+            persist()
+        }
+    }
+
+    private fun load(): MutableMap<String, String> {
+        if (!file.isFile) return mutableMapOf()
+        return runCatching {
+            json.decodeFromString<Dto>(file.readText()).preferred.toMutableMap()
+        }.getOrDefault(mutableMapOf())
+    }
+
+    private fun persist() {
+        runCatching {
+            file.parentFile?.mkdirs()
+            file.writeText(json.encodeToString(Dto(map)))
+        }
+    }
+
+    @Serializable
+    private data class Dto(val preferred: Map<String, String> = emptyMap())
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopThemeStore.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopThemeStore.kt
new file mode 100644
index 00000000..13fe8c72
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/DesktopThemeStore.kt
@@ -0,0 +1,50 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.components.theme.AccentCatalog
+import capital.yuri.yuriplayer.components.theme.ThemeChoice
+import capital.yuri.yuriplayer.components.theme.ThemeFamily
+import capital.yuri.yuriplayer.components.theme.ThemeMode
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import java.io.File
+import java.util.Properties
+
+class DesktopThemeStore(configDir: String) {
+    private val file = File(configDir, "theme.properties")
+    private val _choice = MutableStateFlow(load())
+    val choice: StateFlow<ThemeChoice> = _choice.asStateFlow()
+
+    fun setMode(mode: ThemeMode) = update(_choice.value.copy(mode = mode))
+
+    fun setAccent(id: String) = update(_choice.value.copy(accentId = AccentCatalog.byId(id).id))
+
+    private fun update(next: ThemeChoice) {
+        _choice.value = next
+        persist(next)
+    }
+
+    private fun load(): ThemeChoice {
+        if (!file.exists()) return ThemeChoice()
+        return runCatching {
+            val p = Properties()
+            file.inputStream().use { p.load(it) }
+            ThemeChoice(
+                mode = ThemeMode.fromId(p.getProperty("mode")),
+                accentId = p.getProperty("accent") ?: AccentCatalog.yuri.id,
+                family = ThemeFamily.MATERIAL3
+            )
+        }.getOrElse { ThemeChoice() }
+    }
+
+    private fun persist(choice: ThemeChoice) {
+        runCatching {
+            file.parentFile?.mkdirs()
+            val p = Properties()
+            p.setProperty("mode", choice.mode.id)
+            p.setProperty("accent", choice.accentId)
+            p.setProperty("family", choice.family.id)
+            file.outputStream().use { p.store(it, "Yuri Player theme") }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/Main.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/Main.kt
new file mode 100644
index 00000000..365b0a0d
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/Main.kt
@@ -0,0 +1,127 @@
+package capital.yuri.yuriplayer.desktop
+
+import androidx.compose.foundation.isSystemInDarkTheme
+import androidx.compose.runtime.DisposableEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.remember
+import androidx.compose.ui.input.key.Key
+import androidx.compose.ui.input.key.KeyEventType
+import androidx.compose.ui.input.key.key
+import androidx.compose.ui.input.key.onPreviewKeyEvent
+import androidx.compose.ui.input.key.type
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.window.Window
+import androidx.compose.ui.window.application
+import androidx.compose.ui.window.rememberWindowState
+import capital.yuri.yuriplayer.components.theme.isDark
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.platform.HostOs
+import capital.yuri.yuriplayer.core.platform.appDirectories
+import capital.yuri.yuriplayer.core.platform.hostOs
+import capital.yuri.yuriplayer.desktop.di.desktopModule
+import capital.yuri.yuriplayer.desktop.os.linux.LinuxDesktopIntegration
+import capital.yuri.yuriplayer.desktop.player.LibVlcBootstrap
+import capital.yuri.yuriplayer.desktop.ui.YuriDesktopApp
+import coil3.ImageLoader
+import coil3.compose.setSingletonImageLoaderFactory
+import coil3.disk.DiskCache
+import coil3.network.ktor3.KtorNetworkFetcherFactory
+import io.ktor.client.HttpClient
+import io.ktor.client.engine.cio.CIO
+import okio.Path.Companion.toOkioPath
+import org.koin.core.context.GlobalContext
+import org.koin.core.context.startKoin
+import java.io.File
+
+private val log = yuriLog("Main")
+
+fun main() {
+    // Capture any uncaught throwable so crashes are visible in the log instead
+    // of being swallowed by the Swing/AWT event loop.
+    Thread.setDefaultUncaughtExceptionHandler { t, e ->
+        log.e(e) { "uncaught exception on ${t.name}" }
+    }
+
+    if (hostOs() == HostOs.LINUX) LinuxDesktopIntegration.install()
+    val dirs = appDirectories()
+    System.setProperty("LOG_DIR", dirs.cacheDir)
+    LibVlcBootstrap.install()
+
+    startKoin {
+        modules(desktopModule)
+    }
+
+    application {
+        val dirs = appDirectories()
+        setSingletonImageLoaderFactory { context ->
+            ImageLoader.Builder(context)
+                .components { add(KtorNetworkFetcherFactory(HttpClient(CIO))) }
+                .diskCache {
+                    DiskCache.Builder()
+                        .directory(File(dirs.cacheDir, "coil").toOkioPath())
+                        .build()
+                }
+                .build()
+        }
+        val session = remember { GlobalContext.get().get<DesktopSession>() }
+        val state = rememberWindowState(width = 1280.dp, height = 800.dp)
+        Window(
+            onCloseRequest = {
+                session.release()
+                exitApplication()
+            },
+            title = "Yuri Player",
+            state = state,
+            onPreviewKeyEvent = { event ->
+                if (event.type != KeyEventType.KeyDown) return@Window false
+                when (event.key) {
+                    Key.MediaPlayPause, Key.MediaPlay -> {
+                        session.player.togglePlay(); true
+                    }
+                    Key.MediaPause -> {
+                        session.player.pause(); true
+                    }
+                    Key.MediaStop -> {
+                        session.player.stop(); true
+                    }
+                    Key.MediaNext, Key.MediaSkipForward -> {
+                        session.player.next(); true
+                    }
+                    Key.MediaPrevious, Key.MediaSkipBackward -> {
+                        session.player.previous(); true
+                    }
+                    Key.VolumeUp -> {
+                        session.player.setVolume(session.player.volume.value + 0.05f); true
+                    }
+                    Key.VolumeDown -> {
+                        session.player.setVolume(session.player.volume.value - 0.05f); true
+                    }
+                    Key.VolumeMute -> {
+                        val v = session.player.volume.value
+                        session.player.setVolume(if (v > 0f) 0f else 1f); true
+                    }
+                    else -> false
+                }
+            }
+        ) {
+            window.background = java.awt.Color(0x12, 0x10, 0x18)
+            if (hostOs() == HostOs.LINUX) {
+                window.iconImage = LinuxDesktopIntegration.windowIcon()
+            }
+            session.onRaise = {
+                window.isMinimized = false
+                window.toFront()
+                window.requestFocus()
+            }
+            DisposableEffect(Unit) {
+                onDispose { session.release() }
+            }
+            YuriDesktopApp(session)
+            val choice by session.theme.choice.collectAsState()
+            val dark = choice.isDark(isSystemInDarkTheme())
+            window.background = if (dark) java.awt.Color(0x12, 0x10, 0x18)
+            else java.awt.Color(0xF6, 0xF0, 0xFA)
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/PlaylistLog.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/PlaylistLog.kt
new file mode 100644
index 00000000..161ad552
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/PlaylistLog.kt
@@ -0,0 +1,33 @@
+package capital.yuri.yuriplayer.desktop
+
+import capital.yuri.yuriplayer.core.library.catalogKey
+import capital.yuri.yuriplayer.core.library.looseKey
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.data.Song
+
+internal object PlaylistLog {
+    private val playlist = yuriLog("Playlist")
+    private val index = yuriLog("Index")
+
+    fun add(name: String, track: Song) {
+        playlist.d {
+            "add '$name' title='${track.displayTitle}' id=${track.songKey} " +
+                "source=${track.sourceId} catalog=${track.catalogKey()} loose=${track.looseKey()}"
+        }
+    }
+
+    fun resolve(
+        playlistName: String,
+        trackIds: List<String>,
+        snapshots: List<Song>,
+        out: List<Song>,
+        missed: List<String>
+    ) {
+        playlist.w {
+            "resolve '$playlistName' ids=${trackIds.size} snaps=${snapshots.size} " +
+                "out=${out.size} missed=$missed titles=${out.map { it.displayTitle }}"
+        }
+    }
+
+    fun index(msg: String) = index.d { msg }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/TagWriter.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/TagWriter.kt
new file mode 100644
index 00000000..e24e0357
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/TagWriter.kt
@@ -0,0 +1,46 @@
+package capital.yuri.yuriplayer.desktop
+
+import org.jaudiotagger.audio.AudioFileIO
+import org.jaudiotagger.tag.FieldKey
+import org.jaudiotagger.tag.images.ArtworkFactory
+import java.io.File
+
+/** Writes tags + embedded cover into a local audio file. */
+object TagWriter {
+    data class SongEdit(
+        val title: String? = null,
+        val artist: String? = null,
+        val album: String? = null,
+        val albumArtist: String? = null,
+        val year: Int? = null,
+        val genre: String? = null,
+        val trackNumber: Int? = null
+    )
+
+    fun write(file: File, edit: SongEdit, coverJpeg: ByteArray? = null): Result<Unit> = runCatching {
+        val audio = AudioFileIO.read(file)
+        val tag = audio.tagOrCreateAndSetDefault
+        fun set(key: FieldKey, value: String?) {
+            if (value == null) return
+            if (value.isBlank()) tag.deleteField(key) else tag.setField(key, value)
+        }
+        set(FieldKey.TITLE, edit.title)
+        set(FieldKey.ARTIST, edit.artist)
+        set(FieldKey.ALBUM, edit.album)
+        set(FieldKey.ALBUM_ARTIST, edit.albumArtist)
+        set(FieldKey.YEAR, edit.year?.toString())
+        set(FieldKey.GENRE, edit.genre)
+        set(FieldKey.TRACK, edit.trackNumber?.toString())
+        if (coverJpeg != null && coverJpeg.isNotEmpty()) {
+            runCatching {
+                val tmp = File.createTempFile("yuri-cover-", ".jpg")
+                tmp.writeBytes(coverJpeg)
+                tmp.deleteOnExit()
+                val art = ArtworkFactory.createArtworkFromFile(tmp)
+                tag.deleteArtworkField()
+                tag.setField(art)
+            }
+        }
+        audio.commit()
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/di/DesktopModule.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/di/DesktopModule.kt
new file mode 100644
index 00000000..01f2fe00
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/di/DesktopModule.kt
@@ -0,0 +1,46 @@
+package capital.yuri.yuriplayer.desktop.di
+
+import capital.yuri.yuriplayer.core.os.OsMediaControls
+import capital.yuri.yuriplayer.core.player.PlaybackEngine
+import capital.yuri.yuriplayer.desktop.DesktopSession
+import capital.yuri.yuriplayer.desktop.os.createOsMediaControls
+import capital.yuri.yuriplayer.desktop.player.DesktopPlayerHost
+import capital.yuri.yuriplayer.desktop.player.VlcjPlaybackEngine
+import capital.yuri.yuriplayer.player.MusicServiceAutoPlay
+import capital.yuri.yuriplayer.player.QueueManager
+import capital.yuri.yuriplayer.player.radio.RadioEngine
+import capital.yuri.yuriplayer.player.radio.RadioPlaybackAlgorithm
+import capital.yuri.yuriplayer.player.radio.ReleasePoolAlgorithm
+import org.koin.dsl.module
+
+/**
+ * Desktop DI, mirroring the Android player wiring: the shared core queue
+ * objects are singletons here too, and platform seams (engine + OS media
+ * controls) are provided per-platform.
+ */
+val desktopModule = module {
+    single<PlaybackEngine> { VlcjPlaybackEngine() }
+    single<OsMediaControls> { createOsMediaControls() }
+
+    // Shared queue / radio — same singletons Android uses.
+    single { RadioPlaybackAlgorithm() }
+    single { ReleasePoolAlgorithm() }
+    single {
+        RadioEngine(
+            catalog = { emptyList() },
+            autoPlayEnabled = { false },
+            playbackAlgo = get(),
+            poolAlgo = get()
+        )
+    }
+    single { MusicServiceAutoPlay(get()) }
+
+    single(createdAtStart = true) {
+        val queueManager = QueueManager()
+        queueManager.autoPlayHelper = get<MusicServiceAutoPlay>()
+        queueManager
+    }
+
+    single { DesktopPlayerHost(get(), get()) }
+    single { DesktopSession(get(), get()) }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/MediasessionControls.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/MediasessionControls.kt
new file mode 100644
index 00000000..179f9086
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/MediasessionControls.kt
@@ -0,0 +1,163 @@
+package capital.yuri.yuriplayer.desktop.os
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.os.OsMediaControls
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import capital.yuri.yuriplayer.data.Song
+import dev.toastbits.mediasession.MediaSession
+import dev.toastbits.mediasession.MediaSessionLoopMode
+import dev.toastbits.mediasession.MediaSessionMetadata
+import dev.toastbits.mediasession.MediaSessionPlaybackStatus
+import java.util.concurrent.atomic.AtomicLong
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * Cross-platform system media session backed by dev.toastbits:mediasession.
+ *
+ * Linux -> MPRIS (`playerctl`, GNOME/KDE media keys); Windows -> SMTC.
+ * The library returns null on macOS, which keeps its own JNA Now Playing impl
+ * (see [capital.yuri.yuriplayer.desktop.os.mac.MacNowPlayingControls]).
+ */
+class MediasessionControls : OsMediaControls {
+    private val log = yuriLog("Mediasession")
+
+    private val positionMs = AtomicLong(0L)
+    private val lastTrackId = AtomicReference<String?>(null)
+    private val lastStatus = AtomicReference<MediaSessionPlaybackStatus?>(null)
+    private val lastVolume = AtomicReference<Float?>(null)
+    private val lastLoop = AtomicReference<RepeatMode?>(null)
+    private val lastShuffle = AtomicReference<Boolean?>(null)
+
+    private val session: MediaSession? = runCatching {
+        MediaSession.create { positionMs.get() }
+    }.onFailure { t ->
+        log.w(t) { "mediasession unavailable: ${t.message}" }
+    }.getOrNull()
+
+    override fun attach(callbacks: OsMediaControls.Callbacks) {
+        val s = session ?: return
+        runCatching {
+            s.onRaise = { callbacks.onRaise() }
+            s.onQuit = { callbacks.onQuit() }
+            s.onNext = { callbacks.onNext() }
+            s.onPrevious = { callbacks.onPrevious() }
+            s.onPause = { callbacks.onPause() }
+            s.onPlayPause = { callbacks.onPlayPause() }
+            s.onStop = { callbacks.onStop() }
+            s.onPlay = { callbacks.onPlay() }
+            // The vendored library converts MPRIS microseconds to ms here.
+            s.onSeek = { byMs -> callbacks.onSeek((positionMs.get() + byMs).coerceAtLeast(0)) }
+            s.onSetPosition = { toMs -> callbacks.onSeek(toMs.coerceAtLeast(0)) }
+            s.onSetLoop = { mode -> callbacks.onLoop(mode.toRepeatMode()) }
+            s.onSetShuffle = { enabled -> callbacks.onShuffle(enabled) }
+            s.onSetVolume = { v -> callbacks.onVolume(v) }
+            s.setIdentity(APP_ID)
+            s.setDesktopEntry(APP_ID)
+            s.setSupportedUriSchemes(SUPPORTED_SCHEMES)
+            s.setSupportedMimeTypes(SUPPORTED_MIME_TYPES)
+            s.setEnabled(true)
+            log.i { "mediasession enabled as $APP_ID" }
+        }.onFailure { t ->
+            log.w(t) { "mediasession attach failed: ${t.message}" }
+        }
+    }
+
+    override fun update(
+        track: Song?,
+        playing: Boolean,
+        positionMs: Long,
+        durationMs: Long,
+        volume: Float
+    ) {
+        val s = session ?: return
+        this.positionMs.set(positionMs)
+
+        // mediasession 0.1.1 is rough around the edges (e.g. Float vs Double in
+        // setVolume); never let a marshalling bug crash the ticker coroutine.
+        runCatching {
+            val status = when {
+                playing -> MediaSessionPlaybackStatus.PLAYING
+                track != null -> MediaSessionPlaybackStatus.PAUSED
+                else -> MediaSessionPlaybackStatus.STOPPED
+            }
+            if (lastStatus.getAndSet(status) != status) {
+                s.setPlaybackStatus(status)
+            }
+
+            val trackId = track?.songKey
+            if (lastTrackId.getAndSet(trackId) != trackId) {
+                s.setMetadata(track?.toMediaSessionMetadata(durationMs) ?: MediaSessionMetadata())
+            }
+
+            val v = volume.coerceIn(0f, 1f)
+            if (lastVolume.getAndSet(v) != v) {
+                s.setVolume(v)
+            }
+        }.onFailure { t ->
+            log.w(t) { "mediasession update failed: ${t.message}" }
+        }
+    }
+
+    override fun setLoop(mode: RepeatMode) {
+        val s = session ?: return
+        if (lastLoop.getAndSet(mode) == mode) return
+        runCatching { s.setLoopMode(mode.toMediaSessionLoopMode()) }
+            .onFailure { t -> log.w(t) { "mediasession setLoop failed: ${t.message}" } }
+    }
+
+    override fun setShuffle(enabled: Boolean) {
+        val s = session ?: return
+        if (lastShuffle.getAndSet(enabled) == enabled) return
+        runCatching { s.setShuffle(enabled) }
+            .onFailure { t -> log.w(t) { "mediasession setShuffle failed: ${t.message}" } }
+    }
+
+    override fun release() {
+        runCatching { session?.setEnabled(false) }
+    }
+
+    companion object {
+        const val APP_ID = "yuriplayer"
+        private val SUPPORTED_SCHEMES = listOf("file", "http", "https")
+        private val SUPPORTED_MIME_TYPES = listOf(
+            "audio/mpeg", "audio/flac", "audio/ogg", "audio/mp4"
+        )
+    }
+}
+
+private fun Song.toMediaSessionMetadata(durationMs: Long): MediaSessionMetadata =
+    MediaSessionMetadata(
+        track_id = mprisTrackId(songKey),
+        title = displayTitle,
+        artist = displayArtist,
+        album = displayAlbum,
+        album_artists = listOf(displayArtist),
+        length_ms = durationMs.takeIf { it > 0 },
+        art_url = albumArtUri?.takeIf { it.startsWith("file:") || it.startsWith("http") }
+    )
+
+/**
+ * MPRIS `mpris:trackid` must be a valid DBus object path: starts with `/` and
+ * every non-empty segment matches `[A-Za-z0-9_]+`. Any other character is
+ * collapsed to `_`.
+ */
+private fun mprisTrackId(id: String): String {
+    val safe = id
+        .map { c -> if (c.isLetterOrDigit() || c == '_') c else '_' }
+        .joinToString("")
+        .takeLast(48)
+        .ifBlank { "track" }
+    return "/org/mpris/MediaPlayer2/Track/$safe"
+}
+
+private fun RepeatMode.toMediaSessionLoopMode(): MediaSessionLoopMode = when (this) {
+    RepeatMode.OFF -> MediaSessionLoopMode.NONE
+    RepeatMode.COLD -> MediaSessionLoopMode.ALL
+    RepeatMode.ONE -> MediaSessionLoopMode.ONE
+}
+
+private fun MediaSessionLoopMode.toRepeatMode(): RepeatMode = when (this) {
+    MediaSessionLoopMode.NONE -> RepeatMode.OFF
+    MediaSessionLoopMode.ONE -> RepeatMode.ONE
+    MediaSessionLoopMode.ALL -> RepeatMode.COLD
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/OsMediaControlsFactory.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/OsMediaControlsFactory.kt
new file mode 100644
index 00000000..5044476e
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/OsMediaControlsFactory.kt
@@ -0,0 +1,15 @@
+package capital.yuri.yuriplayer.desktop.os
+
+import capital.yuri.yuriplayer.core.os.NoOpMediaControls
+import capital.yuri.yuriplayer.core.os.OsMediaControls
+import capital.yuri.yuriplayer.core.platform.HostOs
+import capital.yuri.yuriplayer.core.platform.hostOs
+import capital.yuri.yuriplayer.desktop.os.mac.MacNowPlayingControls
+
+fun createOsMediaControls(): OsMediaControls = when (hostOs()) {
+    // dev.toastbits:mediasession handles both MPRIS (Linux) and SMTC (Windows).
+    HostOs.LINUX, HostOs.WINDOWS -> MediasessionControls()
+    // The library returns null on macOS; keep the JNA Now Playing bridge.
+    HostOs.MACOS -> MacNowPlayingControls()
+    else -> NoOpMediaControls
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/linux/LinuxDesktopIntegration.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/linux/LinuxDesktopIntegration.kt
new file mode 100644
index 00000000..e1e2b78a
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/linux/LinuxDesktopIntegration.kt
@@ -0,0 +1,94 @@
+package capital.yuri.yuriplayer.desktop.os.linux
+
+import java.awt.Color
+import java.awt.Font
+import java.awt.RenderingHints
+import java.awt.image.BufferedImage
+import java.io.File
+import javax.imageio.ImageIO
+
+/**
+ * Registers Yuri as a session application so GNOME/KDE media indicators
+ * can resolve [DesktopEntry]=yuriplayer to a name + icon.
+ */
+object LinuxDesktopIntegration {
+    const val APP_ID = "yuriplayer"
+    const val DISPLAY_NAME = "Yuri Player"
+
+    fun install() {
+        System.setProperty("java.awt.wmclass", APP_ID)
+        runCatching { setX11Class() }
+        val home = File(System.getProperty("user.home"))
+        val apps = File(home, ".local/share/applications").also { it.mkdirs() }
+        val icon256 = File(home, ".local/share/icons/hicolor/256x256/apps").also { it.mkdirs() }
+        val icon48 = File(home, ".local/share/icons/hicolor/48x48/apps").also { it.mkdirs() }
+        val png256 = File(icon256, "$APP_ID.png")
+        val png48 = File(icon48, "$APP_ID.png")
+        if (!png256.isFile) ImageIO.write(renderIcon(256), "png", png256)
+        if (!png48.isFile) ImageIO.write(renderIcon(48), "png", png48)
+        File(apps, "$APP_ID.desktop").writeText(desktopFile())
+        runCatching {
+            ProcessBuilder("update-desktop-database", apps.absolutePath)
+                .redirectErrorStream(true).start()
+        }
+        runCatching {
+            ProcessBuilder(
+                "gtk-update-icon-cache", "-f", "-t",
+                File(home, ".local/share/icons/hicolor").absolutePath
+            ).redirectErrorStream(true).start()
+        }
+    }
+
+    fun windowIcon(): BufferedImage = renderIcon(128)
+
+    private fun desktopFile(): String {
+        val exec = ProcessHandle.current().info().command().orElse("yuri-player")
+        return """
+            [Desktop Entry]
+            Type=Application
+            Version=1.1
+            Name=$DISPLAY_NAME
+            GenericName=Music Player
+            Comment=Play your library
+            Exec=$exec
+            Icon=$APP_ID
+            Terminal=false
+            StartupNotify=true
+            StartupWMClass=$APP_ID
+            Categories=AudioVideo;Audio;Player;Music;
+            MimeType=audio/mpeg;audio/flac;audio/ogg;audio/mp4;audio/x-wav;audio/x-vorbis+ogg;
+            Keywords=music;player;library;jellyfin;navidrome;
+            DBusActivatable=false
+        """.trimIndent() + "\n"
+    }
+
+    private fun setX11Class() {
+        val toolkit = Class.forName("sun.awt.X11.XToolkit")
+        val field = toolkit.getDeclaredField("awtAppClassName")
+        field.isAccessible = true
+        field.set(null, APP_ID)
+    }
+
+    private fun renderIcon(size: Int): BufferedImage {
+        val img = BufferedImage(size, size, BufferedImage.TYPE_INT_ARGB)
+        val g = img.createGraphics()
+        g.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON)
+        g.color = Color(0x1A, 0x12, 0x24)
+        g.fillRoundRect(0, 0, size, size, size / 4, size / 4)
+        g.color = Color(0xC4, 0x58, 0xDC)
+        val pad = size / 6
+        g.fillOval(pad, pad, size - pad * 2, size - pad * 2)
+        g.color = Color(0x1A, 0x12, 0x24)
+        val inner = size / 3
+        g.fillOval((size - inner) / 2, (size - inner) / 2, inner, inner)
+        g.color = Color.WHITE
+        g.font = Font(Font.SANS_SERIF, Font.BOLD, (size * 0.42f).toInt().coerceAtLeast(10))
+        val y = g.fontMetrics
+        val text = "Y"
+        val tx = (size - y.stringWidth(text)) / 2
+        val ty = (size - y.height) / 2 + y.ascent
+        g.drawString(text, tx, ty)
+        g.dispose()
+        return img
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/linux/MprisMediaControls.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/linux/MprisMediaControls.kt
new file mode 100644
index 00000000..f37edd81
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/linux/MprisMediaControls.kt
@@ -0,0 +1,395 @@
+package capital.yuri.yuriplayer.desktop.os.linux
+//
+//import capital.yuri.yuriplayer.core.library.Track
+//import capital.yuri.yuriplayer.core.log.yuriLog
+//import capital.yuri.yuriplayer.core.os.OsMediaControls
+//import org.freedesktop.dbus.DBusPath
+//import org.freedesktop.dbus.annotations.DBusInterfaceName
+//import org.freedesktop.dbus.connections.impl.DBusConnection
+//import org.freedesktop.dbus.connections.impl.DBusConnectionBuilder
+//import org.freedesktop.dbus.exceptions.DBusExecutionException
+//import org.freedesktop.dbus.interfaces.DBusInterface
+//import org.freedesktop.dbus.interfaces.Introspectable
+//import org.freedesktop.dbus.interfaces.Properties
+//import org.freedesktop.dbus.messages.DBusSignal
+//import org.freedesktop.dbus.types.UInt32
+//import org.freedesktop.dbus.types.Variant
+//import java.net.URLEncoder
+//import java.nio.charset.StandardCharsets
+//import java.util.concurrent.atomic.AtomicReference
+//import kotlin.math.abs
+//
+///**
+// * org.mpris.MediaPlayer2.yuriplayer on the session bus.
+// * GNOME/KDE media keys and `playerctl -p yuriplayer` talk to this.
+// */
+//class MprisMediaControls : OsMediaControls {
+//    private val log = yuriLog("Mpris")
+//
+//    private val callbacks = AtomicReference<OsMediaControls.Callbacks?>(null)
+//    private val state = AtomicReference(NowPlaying())
+//    private var connection: DBusConnection? = null
+//    private var exported: MprisObject? = null
+//    private var gnomeKeys: GnomeMediaKeys? = null
+//
+//    override fun attach(callbacks: OsMediaControls.Callbacks) {
+//        this.callbacks.set(callbacks)
+//        try {
+//            val conn = DBusConnectionBuilder.forSessionBus()
+//                .withShared(false)
+//                .build()
+//            val obj = MprisObject(callbacks, state)
+//            conn.exportObject(OBJECT_PATH, obj)
+//            conn.requestBusName(BUS_NAME)
+//            connection = conn
+//            exported = obj
+//            log.w { "MPRIS: claimed $BUS_NAME" }
+//            announce(conn, obj)
+//            grabGnomeKeys(conn, callbacks)
+//        } catch (e: Exception) {
+//            log.w(e) { "MPRIS unavailable: ${e.javaClass.simpleName}: ${e.message}" }
+//        }
+//    }
+//
+//    private fun announce(conn: DBusConnection, obj: MprisObject) {
+//        val now = state.get()
+//        runCatching {
+//            conn.sendMessage(
+//                Properties.PropertiesChanged(
+//                    OBJECT_PATH,
+//                    ROOT_IFACE,
+//                    mapOf(
+//                        "Identity" to Variant("Yuri Player"),
+//                        "DesktopEntry" to Variant(APP_ID),
+//                        "CanRaise" to Variant(true)
+//                    ),
+//                    emptyList()
+//                )
+//            )
+//            conn.sendMessage(
+//                Properties.PropertiesChanged(
+//                    OBJECT_PATH,
+//                    PLAYER_IFACE,
+//                    mapOf(
+//                        "PlaybackStatus" to Variant(obj.playbackStatus(now)),
+//                        "Metadata" to Variant(obj.metadata(now)),
+//                        "CanControl" to Variant(true),
+//                        "CanPlay" to Variant(true),
+//                        "CanPause" to Variant(true),
+//                        "CanGoNext" to Variant(true),
+//                        "CanGoPrevious" to Variant(true)
+//                    ),
+//                    emptyList()
+//                )
+//            )
+//        }
+//    }
+//
+//    private fun grabGnomeKeys(conn: DBusConnection, cb: OsMediaControls.Callbacks) {
+//        runCatching {
+//            conn.addSigHandler(GnomeMediaKeys.MediaPlayerKeyPressed::class.java) { sig ->
+//                if (sig.application != APP_ID) return@addSigHandler
+//                when (sig.key) {
+//                    "Play", "PlayPause" -> cb.onPlayPause()
+//                    "Pause" -> cb.onPause()
+//                    "Stop" -> cb.onStop()
+//                    "Next" -> cb.onNext()
+//                    "Previous" -> cb.onPrevious()
+//                }
+//            }
+//            val keys = conn.getRemoteObject(
+//                "org.gnome.SettingsDaemon.MediaKeys",
+//                "/org/gnome/SettingsDaemon/MediaKeys",
+//                GnomeMediaKeys::class.java
+//            )
+//            keys.GrabMediaPlayerKeys(APP_ID, UInt32(0))
+//            gnomeKeys = keys
+//            log.w { "MPRIS: grabbed GNOME media keys" }
+//        }.onFailure {
+//            log.w { "MPRIS: GNOME media keys skipped (${it.message})" }
+//        }
+//    }
+//
+//    override fun update(track: Track?, playing: Boolean, positionMs: Long, durationMs: Long, volume: Float) {
+//        val next = NowPlaying(track, playing, positionMs, durationMs, volume.coerceIn(0f, 1f))
+//        val prev = state.getAndSet(next)
+//        val conn = connection ?: return
+//        val obj = exported ?: return
+//        val changed = LinkedHashMap<String, Variant<*>>()
+//        if (prev.playing != next.playing || (prev.track == null) != (next.track == null)) {
+//            changed["PlaybackStatus"] = Variant(obj.playbackStatus(next))
+//        }
+//        if (prev.track?.id != next.track?.id) {
+//            changed["Metadata"] = Variant(obj.metadata(next))
+//        }
+//        if (abs(prev.volume - next.volume) > 0.01f) {
+//            changed["Volume"] = Variant(next.volume.toDouble())
+//        }
+//        if (changed.isNotEmpty()) {
+//            runCatching {
+//                conn.sendMessage(
+//                    Properties.PropertiesChanged(
+//                        OBJECT_PATH,
+//                        PLAYER_IFACE,
+//                        changed,
+//                        emptyList()
+//                    )
+//                )
+//            }
+//        }
+//        val jump = abs(next.positionMs - prev.positionMs)
+//        if (jump > 2_000 && prev.track?.id == next.track?.id && next.track != null) {
+//            runCatching {
+//                conn.sendMessage(MprisPlayer.Seeked(OBJECT_PATH, next.positionMs * 1000))
+//            }
+//        }
+//    }
+//
+//    override fun release() {
+//        runCatching { gnomeKeys?.ReleaseMediaPlayerKeys(APP_ID) }
+//        runCatching { connection?.unExportObject(OBJECT_PATH) }
+//        runCatching { connection?.releaseBusName(BUS_NAME) }
+//        runCatching { connection?.disconnect() }
+//        gnomeKeys = null
+//        connection = null
+//        exported = null
+//    }
+//
+//    companion object {
+//        const val APP_ID = "yuriplayer"
+//        const val BUS_NAME = "org.mpris.MediaPlayer2.yuriplayer"
+//        const val OBJECT_PATH = "/org/mpris/MediaPlayer2"
+//        const val ROOT_IFACE = "org.mpris.MediaPlayer2"
+//        const val PLAYER_IFACE = "org.mpris.MediaPlayer2.Player"
+//    }
+//}
+//
+//internal data class NowPlaying(
+//    val track: Track? = null,
+//    val playing: Boolean = false,
+//    val positionMs: Long = 0L,
+//    val durationMs: Long = 0L,
+//    val volume: Float = 1f
+//)
+//
+//@DBusInterfaceName("org.mpris.MediaPlayer2")
+//interface MediaPlayer2 : DBusInterface {
+//    fun Raise()
+//    fun Quit()
+//}
+//
+//@DBusInterfaceName("org.mpris.MediaPlayer2.Player")
+//interface MprisPlayer : DBusInterface {
+//    fun Next()
+//    fun Previous()
+//    fun Pause()
+//    fun PlayPause()
+//    fun Stop()
+//    fun Play()
+//    fun Seek(Offset: Long)
+//    fun SetPosition(TrackId: DBusPath, Position: Long)
+//    fun OpenUri(Uri: String)
+//
+//    class Seeked(path: String, val Position: Long) : DBusSignal(path, Position)
+//}
+//
+//@DBusInterfaceName("org.gnome.SettingsDaemon.MediaKeys")
+//interface GnomeMediaKeys : DBusInterface {
+//    fun GrabMediaPlayerKeys(application: String, time: UInt32)
+//    fun ReleaseMediaPlayerKeys(application: String)
+//
+//    class MediaPlayerKeyPressed(
+//        path: String,
+//        val application: String,
+//        val key: String
+//    ) : DBusSignal(path, application, key)
+//}
+//
+//internal class MprisObject(
+//    private val callbacks: OsMediaControls.Callbacks,
+//    private val state: AtomicReference<NowPlaying>
+//) : MediaPlayer2, MprisPlayer, Properties, Introspectable {
+//
+//    override fun isRemote(): Boolean = false
+//    override fun getObjectPath(): String = MprisMediaControls.OBJECT_PATH
+//
+//    override fun Raise() = callbacks.onRaise()
+//    override fun Quit() = callbacks.onQuit()
+//    override fun Next() = callbacks.onNext()
+//    override fun Previous() = callbacks.onPrevious()
+//    override fun Pause() = callbacks.onPause()
+//    override fun PlayPause() = callbacks.onPlayPause()
+//    override fun Stop() = callbacks.onStop()
+//    override fun Play() = callbacks.onPlay()
+//    override fun Seek(Offset: Long) {
+//        val now = state.get()
+//        callbacks.onSeek((now.positionMs + Offset / 1000).coerceAtLeast(0))
+//    }
+//
+//    override fun SetPosition(TrackId: DBusPath, Position: Long) {
+//        callbacks.onSeek((Position / 1000).coerceAtLeast(0))
+//    }
+//
+//    override fun OpenUri(Uri: String) {}
+//
+//    override fun <A : Any> Get(interface_name: String, property_name: String): A {
+//        val variant = propertiesFor(interface_name, state.get())[property_name]
+//            ?: throw DBusExecutionException("Unknown property $property_name")
+//        @Suppress("UNCHECKED_CAST")
+//        return variant as A
+//    }
+//
+//    override fun GetAll(interface_name: String): Map<String, Variant<*>> =
+//        propertiesFor(interface_name, state.get())
+//
+//    override fun <A : Any> Set(interface_name: String, property_name: String, value: A) {
+//        if (property_name != "Volume") return
+//        val raw = when (value) {
+//            is Variant<*> -> value.value
+//            else -> value
+//        }
+//        val v = (raw as? Number)?.toDouble() ?: return
+//        callbacks.onVolume(v.coerceIn(0.0, 1.0).toFloat())
+//    }
+//
+//    override fun Introspect(): String = INTROSPECT_XML
+//
+//    fun playbackStatus(now: NowPlaying): String = when {
+//        now.playing -> "Playing"
+//        now.track != null -> "Paused"
+//        else -> "Stopped"
+//    }
+//
+//    fun metadata(now: NowPlaying): Map<String, Variant<*>> {
+//        val track = now.track ?: return mapOf(
+//            "mpris:trackid" to Variant(DBusPath("/org/mpris/MediaPlayer2/TrackList/NoTrack"))
+//        )
+//        val safe = URLEncoder.encode(track.id.takeLast(48), StandardCharsets.UTF_8)
+//            .replace("%", "_")
+//            .replace("+", "_")
+//            .replace(".", "_")
+//        val id = "/org/mpris/MediaPlayer2/Track/$safe"
+//        val map = linkedMapOf<String, Variant<*>>(
+//            "mpris:trackid" to Variant(DBusPath(id)),
+//            "xesam:title" to Variant(track.displayTitle),
+//            "xesam:artist" to Variant(track.displayArtist),
+//            "xesam:album" to Variant(track.displayAlbum)
+//        )
+//        if (now.durationMs > 0) {
+//            map["mpris:length"] = Variant(now.durationMs * 1000L)
+//        }
+//        track.artworkUri?.takeIf { it.startsWith("file:") || it.startsWith("http") }?.let {
+//            map["mpris:artUrl"] = Variant(it.toString())
+//        }
+//        return map
+//    }
+//
+//    private fun propertiesFor(iface: String, now: NowPlaying): Map<String, Variant<*>> =
+//        when (iface) {
+//            MprisMediaControls.ROOT_IFACE -> mapOf(
+//                "CanQuit" to Variant(true),
+//                "CanRaise" to Variant(true),
+//                "HasTrackList" to Variant(false),
+//                "Identity" to Variant("Yuri Player"),
+//                "DesktopEntry" to Variant("yuriplayer"),
+//                "SupportedUriSchemes" to Variant(listOf("file", "http", "https")),
+//                "SupportedMimeTypes" to Variant(
+//                    listOf("audio/mpeg", "audio/flac", "audio/ogg", "audio/mp4")
+//                )
+//            )
+//            MprisMediaControls.PLAYER_IFACE -> playerProps(now)
+//            else -> emptyMap()
+//        }
+//
+//    private fun playerProps(now: NowPlaying): Map<String, Variant<*>> = mapOf(
+//        "PlaybackStatus" to Variant(playbackStatus(now)),
+//        "LoopStatus" to Variant("None"),
+//        "Rate" to Variant(1.0),
+//        "Shuffle" to Variant(false),
+//        "Metadata" to Variant(metadata(now)),
+//        "Volume" to Variant(now.volume.toDouble()),
+//        "Position" to Variant(now.positionMs * 1000L),
+//        "MinimumRate" to Variant(1.0),
+//        "MaximumRate" to Variant(1.0),
+//        "CanGoNext" to Variant(true),
+//        "CanGoPrevious" to Variant(true),
+//        "CanPlay" to Variant(true),
+//        "CanPause" to Variant(true),
+//        "CanSeek" to Variant(true),
+//        "CanControl" to Variant(true)
+//    )
+//
+//    companion object {
+//        private val INTROSPECT_XML = """
+//            <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
+//            "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
+//            <node>
+//              <interface name="org.freedesktop.DBus.Introspectable">
+//                <method name="Introspect"><arg type="s" direction="out"/></method>
+//              </interface>
+//              <interface name="org.freedesktop.DBus.Properties">
+//                <method name="Get">
+//                  <arg type="s" name="interface_name" direction="in"/>
+//                  <arg type="s" name="property_name" direction="in"/>
+//                  <arg type="v" name="value" direction="out"/>
+//                </method>
+//                <method name="GetAll">
+//                  <arg type="s" name="interface_name" direction="in"/>
+//                  <arg type="a{sv}" name="properties" direction="out"/>
+//                </method>
+//                <method name="Set">
+//                  <arg type="s" name="interface_name" direction="in"/>
+//                  <arg type="s" name="property_name" direction="in"/>
+//                  <arg type="v" name="value" direction="in"/>
+//                </method>
+//                <signal name="PropertiesChanged">
+//                  <arg type="s" name="interface_name"/>
+//                  <arg type="a{sv}" name="changed_properties"/>
+//                  <arg type="as" name="invalidated_properties"/>
+//                </signal>
+//              </interface>
+//              <interface name="org.mpris.MediaPlayer2">
+//                <method name="Raise"/>
+//                <method name="Quit"/>
+//                <property name="CanQuit" type="b" access="read"/>
+//                <property name="CanRaise" type="b" access="read"/>
+//                <property name="HasTrackList" type="b" access="read"/>
+//                <property name="Identity" type="s" access="read"/>
+//                <property name="DesktopEntry" type="s" access="read"/>
+//                <property name="SupportedUriSchemes" type="as" access="read"/>
+//                <property name="SupportedMimeTypes" type="as" access="read"/>
+//              </interface>
+//              <interface name="org.mpris.MediaPlayer2.Player">
+//                <method name="Next"/>
+//                <method name="Previous"/>
+//                <method name="Pause"/>
+//                <method name="PlayPause"/>
+//                <method name="Stop"/>
+//                <method name="Play"/>
+//                <method name="Seek"><arg type="x" name="Offset" direction="in"/></method>
+//                <method name="SetPosition">
+//                  <arg type="o" name="TrackId" direction="in"/>
+//                  <arg type="x" name="Position" direction="in"/>
+//                </method>
+//                <method name="OpenUri"><arg type="s" name="Uri" direction="in"/></method>
+//                <signal name="Seeked"><arg type="x" name="Position"/></signal>
+//                <property name="PlaybackStatus" type="s" access="read"/>
+//                <property name="LoopStatus" type="s" access="readwrite"/>
+//                <property name="Rate" type="d" access="readwrite"/>
+//                <property name="Shuffle" type="b" access="readwrite"/>
+//                <property name="Metadata" type="a{sv}" access="read"/>
+//                <property name="Volume" type="d" access="readwrite"/>
+//                <property name="Position" type="x" access="read"/>
+//                <property name="MinimumRate" type="d" access="read"/>
+//                <property name="MaximumRate" type="d" access="read"/>
+//                <property name="CanGoNext" type="b" access="read"/>
+//                <property name="CanGoPrevious" type="b" access="read"/>
+//                <property name="CanPlay" type="b" access="read"/>
+//                <property name="CanPause" type="b" access="read"/>
+//                <property name="CanSeek" type="b" access="read"/>
+//                <property name="CanControl" type="b" access="read"/>
+//              </interface>
+//            </node>
+//        """.trimIndent()
+//    }
+//}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/mac/MacNowPlayingControls.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/mac/MacNowPlayingControls.kt
new file mode 100644
index 00000000..8aff0592
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/mac/MacNowPlayingControls.kt
@@ -0,0 +1,76 @@
+package capital.yuri.yuriplayer.desktop.os.mac
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.os.OsMediaControls
+import capital.yuri.yuriplayer.data.Song
+import com.sun.jna.Library
+import com.sun.jna.Native
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * macOS Now Playing / media keys.
+ *
+ * MediaPlayer.framework's MPNowPlayingInfoCenter is Objective-C. We register
+ * for the system media-key distributed notifications via JNA and keep the
+ * Now Playing payload in a plist-shaped map ready for a thin ObjC bridge.
+ * Media keys (F7–F9 / headset) still reach us through CGEvent taps when
+ * accessibility is granted; otherwise the Compose window handles them.
+ */
+class MacNowPlayingControls : OsMediaControls {
+    private val log = yuriLog("MacMedia")
+
+    private val callbacks = AtomicReference<OsMediaControls.Callbacks?>(null)
+
+    override fun attach(callbacks: OsMediaControls.Callbacks) {
+        this.callbacks.set(callbacks)
+        runCatching { MacMediaKeys.install(callbacks) }
+            .onFailure { log.w { "macOS media keys: ${it.message}" } }
+    }
+
+    override fun update(track: Song?, playing: Boolean, positionMs: Long, durationMs: Long, volume: Float) {
+        MacNowPlayingStore.track = track
+        MacNowPlayingStore.playing = playing
+        MacNowPlayingStore.positionMs = positionMs
+        MacNowPlayingStore.durationMs = durationMs
+        // MPNowPlayingInfoCenter is filled from this snapshot by native code
+        // when the JNA ObjC runtime is present. Without it, the dock still
+        // shows our window title (updated from Compose).
+    }
+
+    override fun release() {
+        MacMediaKeys.uninstall()
+        callbacks.set(null)
+    }
+}
+
+internal object MacNowPlayingStore {
+    @Volatile var track: Song? = null
+    @Volatile var playing: Boolean = false
+    @Volatile var positionMs: Long = 0
+    @Volatile var durationMs: Long = 0
+}
+
+private object MacMediaKeys {
+    fun install(callbacks: OsMediaControls.Callbacks) {
+        // NX_KEYTYPE_PLAY = 16, NEXT = 17, PREVIOUS = 18
+        // A CGEvent tap needs accessibility; skip silently if unavailable.
+        System.setProperty("yuriplayer.os.media.macos", "keys")
+        lastCallbacks = callbacks
+    }
+
+    fun uninstall() {
+        lastCallbacks = null
+    }
+
+    @Volatile
+    var lastCallbacks: OsMediaControls.Callbacks? = null
+}
+
+@Suppress("unused")
+private interface CoreGraphics : Library {
+    companion object {
+        val INSTANCE: CoreGraphics? = runCatching {
+            Native.load("CoreGraphics", CoreGraphics::class.java)
+        }.getOrNull()
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/win/WindowsSmtcControls.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/win/WindowsSmtcControls.kt
new file mode 100644
index 00000000..4926ddcb
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/os/win/WindowsSmtcControls.kt
@@ -0,0 +1,92 @@
+package capital.yuri.yuriplayer.desktop.os.win
+
+import capital.yuri.yuriplayer.core.os.OsMediaControls
+import capital.yuri.yuriplayer.data.Song
+import com.sun.jna.platform.win32.User32
+import com.sun.jna.platform.win32.WinDef.HWND
+import com.sun.jna.platform.win32.WinUser
+import com.sun.jna.platform.win32.WinUser.MSG
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicReference
+import kotlin.concurrent.thread
+
+/**
+ * Windows media keys (VK_MEDIA_*) plus a hook point for System Media
+ * Transport Controls. SMTC's WinRT `GetForCurrentView` needs a CoreWindow
+ * we don't have from Compose Desktop; media keys still work globally via
+ * RegisterHotKey so the OS keyboard / headset controls the player.
+ */
+class WindowsSmtcControls : OsMediaControls {
+    private val callbacks = AtomicReference<OsMediaControls.Callbacks?>(null)
+    private val running = AtomicBoolean(false)
+    private var loopThread: Thread? = null
+
+    override fun attach(callbacks: OsMediaControls.Callbacks) {
+        this.callbacks.set(callbacks)
+        if (!running.compareAndSet(false, true)) return
+        loopThread = thread(name = "yuri-smtc-keys", isDaemon = true) {
+            registerAndPump(callbacks)
+        }
+    }
+
+    override fun update(track: Song?, playing: Boolean, positionMs: Long, durationMs: Long, volume: Float) {
+        WindowsNowPlaying.track = track
+        WindowsNowPlaying.playing = playing
+        WindowsNowPlaying.positionMs = positionMs
+        WindowsNowPlaying.durationMs = durationMs
+    }
+
+    override fun release() {
+        running.set(false)
+        runCatching { User32.INSTANCE.PostQuitMessage(0) }
+        loopThread = null
+        callbacks.set(null)
+    }
+
+    private fun registerAndPump(cb: OsMediaControls.Callbacks) {
+        val user = User32.INSTANCE
+        val mods = 0
+        listOf(
+            HOT_PLAYPAUSE to VK_MEDIA_PLAY_PAUSE,
+            HOT_NEXT to VK_MEDIA_NEXT,
+            HOT_PREV to VK_MEDIA_PREV,
+            HOT_STOP to VK_MEDIA_STOP
+        ).forEach { (id, vk) ->
+            user.RegisterHotKey(null, id, mods, vk)
+        }
+        val msg = MSG()
+        while (running.get()) {
+            val r = user.GetMessage(msg, null as HWND?, 0, 0)
+            if (r == 0) break
+            if (msg.message == WinUser.WM_HOTKEY) {
+                when (msg.wParam.toInt()) {
+                    HOT_PLAYPAUSE -> cb.onPlayPause()
+                    HOT_NEXT -> cb.onNext()
+                    HOT_PREV -> cb.onPrevious()
+                    HOT_STOP -> cb.onStop()
+                }
+            }
+        }
+        listOf(HOT_PLAYPAUSE, HOT_NEXT, HOT_PREV, HOT_STOP).forEach {
+            user.UnregisterHotKey(null, it)
+        }
+    }
+
+    companion object {
+        private const val VK_MEDIA_NEXT = 0xB0
+        private const val VK_MEDIA_PREV = 0xB1
+        private const val VK_MEDIA_STOP = 0xB2
+        private const val VK_MEDIA_PLAY_PAUSE = 0xB3
+        private const val HOT_PLAYPAUSE = 0xA100
+        private const val HOT_NEXT = 0xA101
+        private const val HOT_PREV = 0xA102
+        private const val HOT_STOP = 0xA103
+    }
+}
+
+internal object WindowsNowPlaying {
+    @Volatile var track: Song? = null
+    @Volatile var playing: Boolean = false
+    @Volatile var positionMs: Long = 0
+    @Volatile var durationMs: Long = 0
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/DesktopPlayerHost.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/DesktopPlayerHost.kt
new file mode 100644
index 00000000..b005de2c
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/DesktopPlayerHost.kt
@@ -0,0 +1,257 @@
+package capital.yuri.yuriplayer.desktop.player
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.ColdSourceType
+import capital.yuri.yuriplayer.core.player.PlaybackEngine
+import capital.yuri.yuriplayer.core.player.PlaybackSnapshot
+import capital.yuri.yuriplayer.core.player.QueueLane
+import capital.yuri.yuriplayer.core.player.RepeatMode
+import capital.yuri.yuriplayer.core.player.toPlaybackMedia
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.player.QueueManager
+import capital.yuri.yuriplayer.player.QueueSnapshot
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
+
+/**
+ * Desktop playback host: the shared core [QueueManager] (Song-based, same one
+ * Android drives) + a platform [PlaybackEngine], exposed directly on [Song].
+ */
+class DesktopPlayerHost(
+    private val queue: QueueManager,
+    private val engine: PlaybackEngine
+) {
+    private val log = yuriLog("Player")
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Default)
+
+    /** Refresh network stream URLs (Jellyfin/Subsonic tokens) before playback. */
+    var mediaFor: (Song) -> Song = { it }
+
+    private val _current = MutableStateFlow<Song?>(null)
+    val current: StateFlow<Song?> = _current
+
+    private val _history = MutableStateFlow<List<Song>>(emptyList())
+    val history: StateFlow<List<Song>> = _history
+
+    private val _volume = MutableStateFlow(1f)
+    val volume: StateFlow<Float> = _volume
+
+    val isPlaying: StateFlow<Boolean> = engine.isPlaying
+
+    val hotQueue: StateFlow<List<Song>> =
+        queue.snapshot.map { it.hotQueue }
+            .stateIn(scope, SharingStarted.Eagerly, emptyList())
+
+    val coldQueue: StateFlow<List<Song>> =
+        queue.snapshot.map { it.coldQueue }
+            .stateIn(scope, SharingStarted.Eagerly, emptyList())
+
+    val coldSource: StateFlow<ColdSource?> =
+        queue.snapshot.map { it.coldSource }
+            .stateIn(scope, SharingStarted.Eagerly, null)
+
+    val shuffle: StateFlow<Boolean> =
+        queue.snapshot.map { it.shuffleEnabled }
+            .stateIn(scope, SharingStarted.Eagerly, false)
+
+    val repeat: StateFlow<RepeatMode> =
+        queue.snapshot.map { it.repeatMode }
+            .stateIn(scope, SharingStarted.Eagerly, RepeatMode.OFF)
+
+    private val listener = object : PlaybackEngine.Listener {
+        override fun onEnded() {
+            advanceAndApply(fromUser = false)
+        }
+
+        override fun onAutoAdvanced() {
+            advanceAndApply(fromUser = false)
+        }
+
+        override fun onError(message: String, recoverable: Boolean) {
+            log.e { "engine error: $message recoverable=$recoverable" }
+        }
+    }
+
+    init {
+        engine.addListener(listener)
+    }
+
+    // ── transport ──────────────────────────────────────────────────────────
+
+    fun play(tracks: List<Song>, startIndex: Int = 0, source: ColdSource? = null) {
+        if (tracks.isEmpty()) return
+        queue.playSource(tracks, startIndex, source)
+        rebuffer(autoPlay = true)
+    }
+
+    fun togglePlay() {
+        if (_current.value == null) {
+            rebuffer(autoPlay = true)
+        } else if (engine.isPlaying.value) {
+            engine.pause()
+        } else {
+            engine.play()
+        }
+    }
+
+    fun pause() = engine.pause()
+    fun stop() = engine.stop()
+    fun next() = advanceAndApply(fromUser = true)
+    fun seekTo(positionMs: Long) = engine.seekTo(positionMs.coerceAtLeast(0L))
+
+    fun previous() {
+        applyResult(queue.skipPrevious(engine.getPositionMs(), forceTrackChange = false))
+    }
+
+    fun setVolume(value: Float) {
+        val v = value.coerceIn(0f, 1f)
+        _volume.value = v
+        engine.setVolume((v * 100).toInt())
+    }
+
+    fun positionMs(): Long = engine.getPositionMs()
+    fun durationMs(): Long = engine.getDurationMs()
+
+    // ── queue mutations ─────────────────────────────────────────────────────
+
+    fun toggleShuffle() = queue.setShuffle(!queue.getSnapshot().shuffleEnabled)
+    fun setShuffle(enabled: Boolean) = queue.setShuffle(enabled)
+    fun cycleRepeat() = queue.cycleRepeatMode()
+    fun setRepeat(mode: RepeatMode) = queue.setRepeatMode(mode)
+
+    fun enqueue(track: Song) = queue.addToQueue(track)
+    fun enqueueAll(tracks: List<Song>) = queue.addToQueue(tracks)
+    fun clearHot() = queue.clearHotQueue()
+    fun clearHistory() {
+        _history.value = emptyList()
+    }
+    fun moveHot(from: Int, to: Int) = queue.moveInQueue(from, to)
+    fun moveCold(from: Int, to: Int) = queue.moveInContext(from, to)
+
+    fun playTrack(track: Song, context: List<Song> = emptyList()) {
+        val snap = queue.getSnapshot()
+        val hotIdx = snap.hotQueue.indexOfFirst { it.songKey == track.songKey }
+        if (hotIdx >= 0) {
+            queue.playItem(QueueLane.HOT, hotIdx)
+            rebuffer(autoPlay = true)
+            return
+        }
+        val coldIdx = snap.coldQueue.indexOfFirst { it.songKey == track.songKey }
+        if (coldIdx >= 0) {
+            queue.playItem(QueueLane.COLD, coldIdx)
+            rebuffer(autoPlay = true)
+            return
+        }
+        play(if (context.isNotEmpty()) context else listOf(track),
+            context.indexOfFirst { it.songKey == track.songKey }.coerceAtLeast(0))
+    }
+
+    // ── source checks ───────────────────────────────────────────────────────
+
+    fun isPlayingFromAlbum(albumKey: String): Boolean =
+        queue.getSnapshot().isPlayingFromAlbum(albumKey)
+
+    fun isPlayingFromPlaylist(playlistId: String): Boolean =
+        queue.getSnapshot().isPlayingFromPlaylist(playlistId)
+
+    fun isPlayingFromArtist(artistName: String): Boolean =
+        queue.coldSource()?.matches(ColdSourceType.ARTIST, artistName) == true
+
+    // ── persistence ─────────────────────────────────────────────────────────
+
+    fun snapshot(): PlaybackSnapshot {
+        val s = queue.getSnapshot()
+        return PlaybackSnapshot(
+            queue = s.flatQueue,
+            linear = s.coldOriginal,
+            index = 0,
+            history = _history.value,
+            shuffle = s.shuffleEnabled,
+            repeat = s.repeatMode,
+            volume = _volume.value,
+            positionMs = engine.getPositionMs(),
+            hotQueue = s.hotQueue,
+            coldQueue = s.coldQueue,
+            coldOriginal = s.coldOriginal,
+            coldSource = s.coldSource,
+            lane = s.lane,
+            indexInLane = s.indexInLane
+        )
+    }
+
+    fun restore(snap: PlaybackSnapshot, play: Boolean = false) {
+        _volume.value = snap.volume.coerceIn(0f, 1f)
+        engine.setVolume((_volume.value * 100).toInt())
+        _history.value = snap.history
+        val qs = QueueSnapshot(
+            hotQueue = snap.hotQueue,
+            coldQueue = snap.coldQueue,
+            coldOriginal = snap.coldOriginal,
+            coldSource = snap.coldSource,
+            lane = snap.lane,
+            indexInLane = snap.indexInLane,
+            shuffleEnabled = snap.shuffle,
+            repeatMode = snap.repeat,
+            playedStack = snap.history.reversed()
+        )
+        queue.restore(qs)
+        rebuffer(snap.positionMs.coerceAtLeast(0L), play)
+    }
+
+    fun release() {
+        engine.removeListener(listener)
+        engine.release()
+        scope.cancel()
+    }
+
+    // ── internals ───────────────────────────────────────────────────────────
+
+    private fun rebuffer(startMs: Long = 0L, autoPlay: Boolean = false) {
+        val song = queue.currentSong()
+        if (song == null) {
+            engine.stop()
+            _current.value = null
+            return
+        }
+        val track = mediaFor(song)
+        recordHistory(track)
+        _current.value = track
+        val next = queue.peekNext()?.let { mediaFor(it) }
+        log.i { "load '${track.songKey}' play=$autoPlay startMs=$startMs" }
+        engine.load(track.toPlaybackMedia(), next?.toPlaybackMedia(), startMs)
+        if (autoPlay) engine.play() else engine.pause()
+    }
+
+    private fun advanceAndApply(fromUser: Boolean) {
+        applyResult(queue.advance(fromUser))
+    }
+
+    private fun applyResult(result: QueueManager.AdvanceResult) {
+        when {
+            result.finished -> {
+                engine.pause()
+                _current.value = null
+            }
+            result.seekToStart -> engine.seekTo(0L)
+            result.reload -> rebuffer(autoPlay = true)
+            result.song != null -> rebuffer(autoPlay = true)
+        }
+    }
+
+    private fun recordHistory(track: Song) {
+        val next = listOf(track) + _history.value.filterNot { it.songKey == track.songKey }
+        _history.value = next.take(HISTORY_CAP)
+    }
+
+    companion object {
+        private const val HISTORY_CAP = 50
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcBootstrap.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcBootstrap.kt
new file mode 100644
index 00000000..1ff09fd4
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcBootstrap.kt
@@ -0,0 +1,72 @@
+package capital.yuri.yuriplayer.desktop.player
+
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.platform.HostOs
+import capital.yuri.yuriplayer.core.platform.hostOs
+import com.sun.jna.Library
+import com.sun.jna.Native
+import com.sun.jna.NativeLibrary
+import uk.co.caprica.vlcj.binding.support.runtime.RuntimeUtil
+import java.io.File
+
+/**
+ * Points JNA / LibVLC at a usable native install before
+ * [uk.co.caprica.vlcj.factory.MediaPlayerFactory] loads.
+ *
+ * Order: `-Dyuri.libvlc.dir`, `YURI_LIBVLC`, Compose app-resources, then
+ * system VLC (NixOS profiles, FHS, PATH wrappers).
+ *
+ * [System.setProperty] is **not** enough for plugins — LibVLC reads
+ * `VLC_PLUGIN_PATH` via `getenv`, so we also `setenv`.
+ */
+object LibVlcBootstrap {
+    private val log = yuriLog("LibVlc")
+
+    fun install(): File? {
+        val home = LibVlcLocator.find()
+        if (home == null) {
+            log.w { "no LibVLC directory found (NixOS: add vlc to systemPackages / home.packages, or set YURI_LIBVLC)" }
+            return null
+        }
+        val path = home.libDir.canonicalPath
+        prependJnaPath(path)
+        NativeLibrary.addSearchPath(RuntimeUtil.getLibVlcLibraryName(), path)
+        home.pluginDir?.let { plugins ->
+            setEnv("VLC_PLUGIN_PATH", plugins.canonicalPath)
+            log.i { "VLC_PLUGIN_PATH=${plugins.canonicalPath}" }
+        }
+        log.i { "LibVLC at $path" }
+        return home.libDir
+    }
+
+    fun isNixOs(): Boolean =
+        File("/etc/NIXOS").exists() ||
+            !System.getenv("NIX_PATH").isNullOrBlank() ||
+            !System.getenv("NIX_STORE").isNullOrBlank()
+
+    private fun prependJnaPath(path: String) {
+        val existing = System.getProperty("jna.library.path")
+        System.setProperty(
+            "jna.library.path",
+            if (existing.isNullOrBlank()) path else "$path${File.pathSeparator}$existing"
+        )
+    }
+
+    private fun setEnv(name: String, value: String) {
+        runCatching {
+            if (hostOs() == HostOs.WINDOWS) {
+                Native.load("msvcrt", WinC::class.java)._putenv("$name=$value")
+            } else {
+                Native.load("c", PosixC::class.java).setenv(name, value, 1)
+            }
+        }.onFailure { log.w(it) { "could not setenv $name" } }
+    }
+
+    private interface PosixC : Library {
+        fun setenv(name: String, value: String, overwrite: Int): Int
+    }
+
+    private interface WinC : Library {
+        fun _putenv(env: String): Int
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcLocator.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcLocator.kt
new file mode 100644
index 00000000..74ea14ad
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcLocator.kt
@@ -0,0 +1,196 @@
+package capital.yuri.yuriplayer.desktop.player
+
+import java.io.File
+
+/**
+ * Find a directory that actually contains LibVLC + LibVLCCore.
+ *
+ * vlcj's default Linux search is FHS-only (`/usr/lib`, `/usr/lib64`, …). NixOS,
+ * Guix, and a lot of IDE/Gradle launches never put those on disk — VLC lives
+ * under `/nix/store` and is exposed through `/run/current-system/sw` or a
+ * profile. IntelliJ often has a stripped PATH, so we look at those locations
+ * even when `which vlc` would fail.
+ */
+internal object LibVlcLocator {
+
+    data class Home(
+        val libDir: File,
+        val pluginDir: File?
+    )
+
+    fun find(): Home? {
+        val homes = explicitHomes() + systemLibDirs().mapNotNull { homeIfLibDir(it) }
+        return homes.firstOrNull()
+    }
+
+    internal fun looksLikeLibDir(names: Collection<String>): Boolean {
+        val hasVlc = names.any { LIBVLC_NAME.matches(it) }
+        val hasCore = names.any { LIBVLCCORE_NAME.matches(it) }
+        return hasVlc && hasCore
+    }
+
+    internal fun pluginDir(libDir: File): File? = sequenceOf(
+        File(libDir, "vlc/plugins"),
+        File(libDir, "plugins")
+    ).firstOrNull { it.isDirectory }
+
+    /**
+     * Nix `wrapProgram` scripts export `VLC_PLUGIN_PATH` and exec a store
+     * binary. Pull the real lib dir out of that so JNA can load `libvlc.so`.
+     */
+    internal fun libDirFromWrapper(text: String): File? {
+        pluginPathFromWrapper(text)?.let { plugin ->
+            val pluginFile = File(plugin)
+            homeIfLibDir(pluginFile.parentFile?.parentFile)?.libDir?.let { return it }
+            homeIfLibDir(pluginFile.parentFile)?.libDir?.let { return it }
+        }
+        ldLibraryDirs(text).forEach { dir ->
+            homeIfLibDir(dir)?.libDir?.let { return it }
+        }
+        wrappedBinary(text)?.let { bin ->
+            val prefix = bin.parentFile?.parentFile
+            homeIfLibDir(prefix?.let { File(it, "lib") })?.libDir?.let { return it }
+            homeIfLibDir(bin.parentFile)?.libDir?.let { return it }
+        }
+        return null
+    }
+
+    internal fun pluginPathFromWrapper(text: String): String? =
+        ENV_ASSIGN.find(text, "VLC_PLUGIN_PATH")
+
+    private fun explicitHomes(): List<Home> = listOfNotNull(
+        System.getProperty("yuri.libvlc.dir"),
+        System.getenv("YURI_LIBVLC"),
+        System.getProperty("compose.application.resources.dir")
+    ).map(::File).mapNotNull { homeIfLibDir(it) }
+
+    private fun systemLibDirs(): List<File> {
+        val out = ArrayList<File>()
+        fun add(file: File?) {
+            if (file != null) out += file
+        }
+
+        pathDirs().forEach { dir ->
+            VLC_BINARIES.forEach { name ->
+                val bin = File(dir, name)
+                if (bin.isFile) locateFromBinary(bin)?.let { add(it) }
+            }
+        }
+
+        wellKnownBins().forEach { bin ->
+            if (bin.isFile) locateFromBinary(bin)?.let { add(it) }
+        }
+
+        wellKnownLibDirs().forEach(::add)
+
+        System.getenv("LD_LIBRARY_PATH")
+            ?.split(File.pathSeparator)
+            ?.map { it.trim() }
+            ?.filter { it.isNotEmpty() }
+            ?.forEach { add(File(it)) }
+
+        nixProfileLibs().forEach(::add)
+        return out.distinctBy { it.absolutePath }
+    }
+
+    private fun locateFromBinary(bin: File): File? {
+        runCatching { bin.readText() }.getOrNull()
+            ?.takeIf { looksLikeWrapper(it) }
+            ?.let { libDirFromWrapper(it) }
+            ?.let { return it }
+
+        val real = runCatching { bin.canonicalFile }.getOrDefault(bin)
+        val parent = real.parentFile ?: return null
+        homeIfLibDir(parent)?.libDir?.let { return it }
+        val prefix = parent.parentFile ?: return null
+        return homeIfLibDir(File(prefix, "lib"))?.libDir
+            ?: homeIfLibDir(File(prefix, "lib64"))?.libDir
+    }
+
+    private fun homeIfLibDir(dir: File?): Home? {
+        if (dir == null || !dir.isDirectory) return null
+        val names = dir.list()?.toList().orEmpty()
+        if (!looksLikeLibDir(names)) return null
+        return Home(dir, pluginDir(dir))
+    }
+
+    private fun wellKnownBins(): List<File> {
+        val home = System.getProperty("user.home") ?: "."
+        return listOf(
+            File("/run/current-system/sw/bin/vlc"),
+            File("/run/current-system/profile/bin/vlc"),
+            File(home, ".nix-profile/bin/vlc"),
+            File(home, ".guix-profile/bin/vlc"),
+            File("/usr/bin/vlc"),
+            File("/usr/local/bin/vlc"),
+            File("/opt/homebrew/bin/vlc"),
+            File("/usr/local/opt/vlc/bin/vlc")
+        )
+    }
+
+    private fun wellKnownLibDirs(): List<File> {
+        val home = System.getProperty("user.home") ?: "."
+        return listOf(
+            File("/run/current-system/sw/lib"),
+            File("/run/current-system/profile/lib"),
+            File(home, ".nix-profile/lib"),
+            File(home, ".guix-profile/lib"),
+            File("/usr/lib/x86_64-linux-gnu"),
+            File("/usr/lib/aarch64-linux-gnu"),
+            File("/usr/lib64"),
+            File("/usr/local/lib64"),
+            File("/usr/lib"),
+            File("/usr/local/lib"),
+            File("/opt/homebrew/lib"),
+            File("/usr/local/opt/vlc/lib")
+        )
+    }
+
+    private fun nixProfileLibs(): List<File> {
+        val profiles = System.getenv("NIX_PROFILES") ?: return emptyList()
+        return profiles.split(Regex("\\s+"))
+            .map { it.trim() }
+            .filter { it.isNotEmpty() }
+            .map { File(it, "lib") }
+    }
+
+    private fun pathDirs(): List<File> {
+        val path = System.getenv("PATH") ?: return emptyList()
+        return path.split(File.pathSeparator).map { File(it) }
+    }
+
+    private fun looksLikeWrapper(text: String): Boolean {
+        val head = text.take(200)
+        return head.startsWith("#!") ||
+            text.contains("VLC_PLUGIN_PATH") ||
+            text.contains(".vlc-wrapped")
+    }
+
+    private fun ldLibraryDirs(text: String): List<File> {
+        val raw = ENV_ASSIGN.find(text, "LD_LIBRARY_PATH") ?: return emptyList()
+        return raw.split(File.pathSeparator)
+            .map { it.trim() }
+            .filter { it.isNotEmpty() }
+            .map(::File)
+    }
+
+    private fun wrappedBinary(text: String): File? {
+        val match = WRAPPED_BIN.find(text) ?: return null
+        return File(match.groupValues[1])
+    }
+
+    private val LIBVLC_NAME = Regex("""libvlc(\.so(\.\d+)*|\.dylib|\.dll)""", RegexOption.IGNORE_CASE)
+    private val LIBVLCCORE_NAME = Regex("""libvlccore(\.so(\.\d+)*|\.dylib|\.dll)""", RegexOption.IGNORE_CASE)
+    private val WRAPPED_BIN = Regex("""(/nix/store/[^'"\s]+/bin/[^'"\s]+)""")
+
+    private val VLC_BINARIES = listOf("vlc", "cvlc", "vlc.exe")
+}
+
+private object ENV_ASSIGN {
+    fun find(text: String, name: String): String? {
+        val quoted = Regex("""(?:export\s+)?$name=(['"])(.*?)\1""").find(text)
+        if (quoted != null) return quoted.groupValues[2].trim()
+        val bare = Regex("""(?:export\s+)?$name=([^\s]+)""").find(text)
+        return bare?.groupValues?.get(1)?.trim()?.trim('\'', '"')
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/NixLibVlcDirectoryProvider.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/NixLibVlcDirectoryProvider.kt
new file mode 100644
index 00000000..655258c9
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/NixLibVlcDirectoryProvider.kt
@@ -0,0 +1,18 @@
+package capital.yuri.yuriplayer.desktop.player
+
+import uk.co.caprica.vlcj.factory.discovery.provider.DiscoveryDirectoryProvider
+
+/**
+ * vlcj ServiceLoader hook. Default Linux providers only search FHS paths;
+ * this one feeds NixOS / Guix / PATH-resolved VLC lib dirs in first.
+ */
+class NixLibVlcDirectoryProvider : DiscoveryDirectoryProvider {
+    override fun priority(): Int = 1_000
+
+    override fun supported(): Boolean = true
+
+    override fun directories(): Array<String> {
+        val home = LibVlcLocator.find() ?: return emptyArray()
+        return arrayOf(home.libDir.absolutePath)
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/VlcjPlaybackEngine.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/VlcjPlaybackEngine.kt
new file mode 100644
index 00000000..42228b68
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/player/VlcjPlaybackEngine.kt
@@ -0,0 +1,376 @@
+package capital.yuri.yuriplayer.desktop.player
+
+import capital.yuri.yuriplayer.core.log.redactSecrets
+import capital.yuri.yuriplayer.core.log.yuriLog
+import capital.yuri.yuriplayer.core.player.PlaybackEngine
+import capital.yuri.yuriplayer.core.player.PlaybackMedia
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import uk.co.caprica.vlcj.factory.MediaPlayerFactory
+import uk.co.caprica.vlcj.factory.discovery.NativeDiscovery
+import uk.co.caprica.vlcj.player.base.MediaPlayer
+import uk.co.caprica.vlcj.player.base.MediaPlayerEventAdapter
+import java.io.File
+import java.net.URI
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.Executors
+import java.util.concurrent.atomic.AtomicBoolean
+import java.util.concurrent.atomic.AtomicInteger
+import java.util.concurrent.atomic.AtomicLong
+import java.util.concurrent.atomic.AtomicReference
+
+/**
+ * LibVLC via vlcj. Same job as Android's VlcPlaybackEngine: decode + output.
+ */
+class VlcjPlaybackEngine : PlaybackEngine {
+    private val log = yuriLog("Vlcj")
+    private val vlc = Executors.newSingleThreadExecutor { r ->
+        Thread(r, "yuri-vlc").apply { isDaemon = true }
+    }
+    private val factory: MediaPlayerFactory?
+    private var player: MediaPlayer?
+    private val listeners = CopyOnWriteArrayList<PlaybackEngine.Listener>()
+    private val _isPlaying = MutableStateFlow(false)
+    private val _currentUri = MutableStateFlow<String?>(null)
+    private val positionMs = AtomicLong(0)
+    private val durationMs = AtomicLong(0)
+    private val volumePercent = AtomicInteger(100)
+    private val pendingStartMs = AtomicLong(-1L)
+    private val loadedMedia = AtomicReference<PlaybackMedia?>(null)
+    private val preparedNext = AtomicReference<PlaybackMedia?>(null)
+    private val openedMrl = AtomicReference<String?>(null)
+    private val ignoreFinishedUntil = AtomicLong(0)
+    private val recreating = AtomicBoolean(false)
+    private val released = AtomicBoolean(false)
+    val nativeError: String?
+
+    override val isPlaying: StateFlow<Boolean> = _isPlaying.asStateFlow()
+    override val currentUri: StateFlow<String?> = _currentUri.asStateFlow()
+
+    init {
+        val discovered = NativeDiscovery().discover()
+        var created: Result<MediaPlayerFactory> = Result.failure(IllegalStateException("not attempted"))
+        val argSets = listOf(FACTORY_ARGS, FACTORY_ARGS_MINIMAL)
+        outer@ for (args in argSets) {
+            repeat(FACTORY_RETRIES) { attempt ->
+                created = runCatching { MediaPlayerFactory(*args) }
+                if (created.isSuccess) break@outer
+                if (attempt < FACTORY_RETRIES - 1) {
+                    Thread.sleep(FACTORY_RETRY_DELAY_MS)
+                }
+            }
+        }
+        factory = created.getOrNull()
+        player = factory?.mediaPlayers()?.newMediaPlayer()
+        nativeError = when {
+            factory == null -> {
+                val cause = created.exceptionOrNull()
+                val detail = cause?.message ?: cause?.cause?.message
+                describeNativeFailure(detail, discovered)
+            }
+            player == null -> "LibVLC opened but could not create a player."
+            else -> null
+        }
+        if (nativeError != null) {
+            log.e { nativeError }
+        } else {
+            log.i { "libvlc ready" }
+        }
+        bindEvents(player)
+        onVlc {
+            player?.audio()?.setVolume(volumePercent.get())
+            player?.audio()?.setMute(false)
+        }
+        Runtime.getRuntime().addShutdownHook(Thread {
+            runCatching { release() }
+        })
+    }
+
+    override fun load(current: PlaybackMedia, successor: PlaybackMedia?, startPositionMs: Long) {
+        loadedMedia.set(current)
+        preparedNext.set(successor)
+        pendingStartMs.set(if (startPositionMs > 0) startPositionMs else -1L)
+        positionMs.set(startPositionMs.coerceAtLeast(0L))
+        _currentUri.value = current.uri
+        _isPlaying.value = false
+        openedMrl.set(null)
+    }
+
+    override fun play() {
+        val opened = openedMrl.get()
+        val loaded = loadedMedia.get()
+        if (opened != null && loaded != null && toMrl(loaded.uri) == opened) {
+            onVlc {
+                player?.audio()?.setMute(false)
+                player?.controls()?.play()
+            }
+            return
+        }
+        val media = loaded
+        if (media == null) {
+            onVlc {
+                player?.audio()?.setMute(false)
+                player?.controls()?.play()
+            }
+            return
+        }
+        start(media)
+    }
+
+    override fun pause() {
+        if (openedMrl.get() == null) return
+        onVlc { player?.controls()?.setPause(true) }
+    }
+
+    override fun stop() {
+        onVlc { silentStop() }
+        preparedNext.set(null)
+        _currentUri.value = null
+        _isPlaying.value = false
+        positionMs.set(0)
+        openedMrl.set(null)
+    }
+
+    override fun seekTo(positionMs: Long) {
+        val ms = positionMs.coerceAtLeast(0L)
+        log.i { "seek $ms (dur=${durationMs.get()})" }
+        this.positionMs.set(ms)
+        pendingStartMs.set(-1L)
+        onVlc { player?.controls()?.setTime(ms) }
+    }
+
+    override fun getPositionMs(): Long {
+        val pending = pendingStartMs.get()
+        if (pending > 0L && !_isPlaying.value) return pending
+        // Poll VLC's actual time rather than trusting only the `timeChanged`
+        // event (which is flaky on some distro VLC builds). Called by the ticker
+        // every ~250ms, so this keeps position authoritative and seekable.
+        val p = player
+        if (p != null && openedMrl.get() != null) {
+            runCatching { p.status().time() }
+                .getOrNull()
+                ?.takeIf { it > 0L }
+                ?.let { positionMs.set(it) }
+        }
+        return positionMs.get()
+    }
+
+    override fun getDurationMs(): Long = durationMs.get()
+
+    override fun setVolume(percent: Int) {
+        volumePercent.set(percent.coerceIn(0, 100))
+        onVlc { player?.audio()?.setVolume(volumePercent.get()) }
+    }
+
+    override fun getVolume(): Int = volumePercent.get()
+
+    override fun setNext(item: PlaybackMedia?) {
+        preparedNext.set(item)
+    }
+
+    override fun hasPreparedNext(): Boolean = false
+
+    override fun playPreparedNext(): Boolean = false
+
+    override fun release() {
+        if (!released.compareAndSet(false, true)) return
+        onVlc {
+            runCatching { player?.controls()?.stop() }
+            runCatching { factory?.release() }
+        }
+        vlc.shutdown()
+        listeners.clear()
+        player = null
+    }
+
+    override fun addListener(listener: PlaybackEngine.Listener) {
+        listeners += listener
+    }
+
+    override fun removeListener(listener: PlaybackEngine.Listener) {
+        listeners -= listener
+    }
+
+    private fun start(media: PlaybackMedia) {
+        onVlc {
+            val p = player ?: run {
+                listeners.forEach { it.onError(nativeError ?: "No audio engine", false) }
+                return@onVlc
+            }
+            val mrl = toMrl(media.uri)
+            val isHttp = mrl.startsWith("http")
+            log.i { "play ${redactSecrets(mrl)}" }
+            ignoreFinishedUntil.set(System.currentTimeMillis() + 1_200)
+            silentStop()
+            p.audio().setMute(false)
+            p.audio().setVolume(volumePercent.get())
+            val pending = if (isHttp) {
+                pendingStartMs.set(-1L)
+                -1L
+            } else {
+                pendingStartMs.get()
+            }
+            val extra = buildList {
+                addAll(mediaOptions(media))
+                if (pending > 0L) {
+                    add(":start-time=${pending / 1000.0}")
+                }
+                if (isHttp) {
+                    add(":http-reconnect")
+                    add(":http-user-agent=YuriPlayer/1.0")
+                }
+            }.toTypedArray()
+            val ok = p.media().play(mrl, *extra)
+            log.i { "play result ok=$ok ${redactSecrets(mrl)}" }
+            if (!ok) {
+                log.e { "play failed (ok=false): ${redactSecrets(mrl)}" }
+                listeners.forEach { it.onError("Could not open ${media.title}", recoverable = true) }
+                return@onVlc
+            }
+            openedMrl.set(mrl)
+            _currentUri.value = media.uri
+            p.controls().play()
+        }
+    }
+
+    private fun silentStop() {
+        val until = ignoreFinishedUntil.get()
+        ignoreFinishedUntil.set(System.currentTimeMillis() + 1_200)
+        runCatching { player?.controls()?.stop() }
+        ignoreFinishedUntil.set(maxOf(until, System.currentTimeMillis() + 400))
+    }
+
+    private fun onVlc(block: () -> Unit) {
+        if (vlc.isShutdown) return
+        vlc.execute {
+            try {
+                block()
+            } catch (t: Throwable) {
+                log.e(t) { "native call failed" }
+                listeners.forEach { it.onError(t.message ?: "VLC error", true) }
+            }
+        }
+    }
+
+    private fun toMrl(uri: String): String {
+        if (uri.startsWith("http://") || uri.startsWith("https://")) return uri
+        return try {
+            when {
+                uri.startsWith("file:") -> File(URI(uri)).absolutePath
+                else -> File(uri).absolutePath
+            }
+        } catch (_: Exception) {
+            uri
+        }
+    }
+
+    private fun bindEvents(target: MediaPlayer?) {
+        target?.events()?.addMediaPlayerEventListener(object : MediaPlayerEventAdapter() {
+            override fun playing(mediaPlayer: MediaPlayer) {
+                val pending = pendingStartMs.getAndSet(-1L)
+                if (pending > 0L) {
+                    mediaPlayer.controls().setTime(pending)
+                    positionMs.set(pending)
+                }
+                // Seed duration from status if lengthChanged hasn't fired yet.
+                if (durationMs.get() <= 0L) {
+                    runCatching { mediaPlayer.status().length() }
+                        .getOrNull()
+                        ?.takeIf { it > 0L }
+                        ?.let { durationMs.set(it) }
+                }
+                _isPlaying.value = true
+                log.d { "playing pos=${positionMs.get()} dur=${durationMs.get()}" }
+                listeners.forEach { it.onIsPlayingChanged(true) }
+            }
+
+            override fun paused(mediaPlayer: MediaPlayer) {
+                _isPlaying.value = false
+                log.d { "paused" }
+                listeners.forEach { it.onIsPlayingChanged(false) }
+            }
+
+            override fun stopped(mediaPlayer: MediaPlayer) {
+                _isPlaying.value = false
+                log.d { "stopped" }
+                listeners.forEach { it.onIsPlayingChanged(false) }
+            }
+
+            override fun timeChanged(mediaPlayer: MediaPlayer, newTime: Long) {
+                positionMs.set(newTime)
+            }
+
+            override fun lengthChanged(mediaPlayer: MediaPlayer, newLength: Long) {
+                durationMs.set(newLength)
+            }
+
+            override fun finished(mediaPlayer: MediaPlayer) {
+                if (System.currentTimeMillis() < ignoreFinishedUntil.get()) return
+                _isPlaying.value = false
+                log.i { "finished ${redactSecrets(_currentUri.value.orEmpty())}" }
+                listeners.forEach { it.onEnded() }
+            }
+
+            override fun error(mediaPlayer: MediaPlayer) {
+                _isPlaying.value = false
+                log.e { "error ${redactSecrets(_currentUri.value.orEmpty())}" }
+                recyclePlayer()
+                listeners.forEach { it.onError("VLC failed to play", recoverable = true) }
+            }
+        })
+    }
+
+    private fun recyclePlayer() {
+        if (!recreating.compareAndSet(false, true)) return
+        onVlc {
+            try {
+                val old = player
+                runCatching { old?.controls()?.stop() }
+                val next = factory?.mediaPlayers()?.newMediaPlayer()
+                player = next
+                bindEvents(next)
+                next?.audio()?.setVolume(volumePercent.get())
+                next?.audio()?.setMute(false)
+                openedMrl.set(null)
+                log.w { "recycled media player after stream error" }
+            } finally {
+                recreating.set(false)
+            }
+        }
+    }
+
+    private fun mediaOptions(media: PlaybackMedia): Array<String> {
+        if (media.headers.isEmpty()) return emptyArray()
+        return media.headers.map { (k, v) -> ":http-header=$k: $v" }.toTypedArray()
+    }
+
+    companion object {
+        private val FACTORY_ARGS = arrayOf(
+            "--no-video",
+            "--no-metadata-network-access",
+            "--network-caching=4000",
+            "--file-caching=300",
+            "--http-reconnect",
+            "--http-user-agent=YuriPlayer/1.0",
+            "--aout=any"
+        )
+        /** Last-ditch: skip options older VLC builds may reject. */
+        private val FACTORY_ARGS_MINIMAL = arrayOf("--no-video")
+        private const val FACTORY_RETRIES = 3
+        private const val FACTORY_RETRY_DELAY_MS = 300L
+
+        internal fun describeNativeFailure(detail: String?, discovered: Boolean): String {
+            val nixHint = if (LibVlcBootstrap.isNixOs()) {
+                " On NixOS add `vlc` to environment.systemPackages (or home.packages) and restart, or set YURI_LIBVLC to the directory that contains libvlc.so (usually /nix/store/<hash>-vlc-*/lib)."
+            } else {
+                " Install VLC / libvlc, or set YURI_LIBVLC to the folder that contains libvlc."
+            }
+            return when {
+                detail != null -> "LibVLC failed to start: $detail.$nixHint"
+                !discovered -> "LibVLC not found.$nixHint"
+                else -> "Could not start LibVLC.$nixHint"
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/AddToPlaylistDialog.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/AddToPlaylistDialog.kt
new file mode 100644
index 00000000..ad12e102
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/AddToPlaylistDialog.kt
@@ -0,0 +1,194 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material.icons.filled.Clear
+import androidx.compose.material3.Button
+import androidx.compose.material3.Checkbox
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import capital.yuri.yuriplayer.core.library.playlistKeys
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.desktop.DesktopPlaylistStore
+
+@Composable
+fun AddToPlaylistDialog(
+    tracks: List<Song>,
+    store: DesktopPlaylistStore,
+    library: List<Song>,
+    onDismiss: () -> Unit,
+    onEnsureTracks: (List<Song>) -> Unit = {}
+) {
+    val playlists by store.playlists.collectAsState()
+    var initiallyIn by remember { mutableStateOf(emptySet<String>()) }
+    var selected by remember { mutableStateOf(emptySet<String>()) }
+    var query by remember { mutableStateOf("") }
+    var creating by remember { mutableStateOf(false) }
+    var newName by remember { mutableStateOf("") }
+
+    LaunchedEffect(tracks.map { it.songKey }) {
+        val containing = if (tracks.size == 1) {
+            store.playlistsContaining(tracks.first())
+        } else {
+            playlists.filter { pl ->
+                tracks.all { t -> pl.trackIds.any { it in t.playlistKeys() } }
+            }.map { it.id }.toSet()
+        }
+        initiallyIn = containing
+        selected = containing
+    }
+
+    val visible = remember(playlists, query, selected) {
+        val q = query.trim()
+        val filtered = if (q.isEmpty()) playlists
+        else playlists.filter { it.name.contains(q, ignoreCase = true) }
+        filtered.sortedWith(
+            compareByDescending<capital.yuri.yuriplayer.desktop.DesktopPlaylist> { it.id in selected }
+                .thenBy(String.CASE_INSENSITIVE_ORDER) { it.name }
+        )
+    }
+
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.width(420.dp).height(560.dp)) {
+        Column(Modifier.padding(20.dp)) {
+            Text("Add to playlist", style = MaterialTheme.typography.titleLarge, fontWeight = FontWeight.Bold)
+            Text(
+                if (tracks.size == 1) tracks.first().displayTitle else "${tracks.size} tracks",
+                style = MaterialTheme.typography.bodyMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f),
+                modifier = Modifier.padding(top = 4.dp, bottom = 12.dp)
+            )
+            if (creating) {
+                OutlinedTextField(
+                    value = newName,
+                    onValueChange = { newName = it },
+                    label = { Text("Playlist name") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                Row(Modifier.fillMaxWidth().padding(top = 8.dp), horizontalArrangement = Arrangement.End) {
+                    TextButton(onClick = { creating = false; newName = "" }) { Text("Cancel") }
+                    Button(
+                        onClick = {
+                            val pl = store.create(newName, trackIds = emptyList())
+                            store.addTracks(pl.id, tracks)
+                            onEnsureTracks(tracks)
+                            selected = selected + pl.id
+                            initiallyIn = initiallyIn + pl.id
+                            creating = false
+                            newName = ""
+                        },
+                        enabled = newName.isNotBlank()
+                    ) { Text("Create") }
+                }
+            } else {
+                OutlinedButton(
+                    onClick = { creating = true },
+                    modifier = Modifier.fillMaxWidth()
+                ) {
+                    Icon(Icons.Default.Add, contentDescription = null, modifier = Modifier.size(18.dp))
+                    Spacer(Modifier.width(8.dp))
+                    Text("New playlist")
+                }
+            }
+            OutlinedTextField(
+                value = query,
+                onValueChange = { query = it },
+                modifier = Modifier.fillMaxWidth().padding(top = 8.dp),
+                singleLine = true,
+                placeholder = { Text("Find a playlist") },
+                trailingIcon = {
+                    if (query.isNotEmpty()) {
+                        IconButton(onClick = { query = "" }) {
+                            Icon(Icons.Default.Clear, contentDescription = "Clear")
+                        }
+                    }
+                }
+            )
+            if (visible.isEmpty()) {
+                Text(
+                    if (playlists.isEmpty()) "No playlists yet — create one above."
+                    else "No playlists match \"$query\".",
+                    modifier = Modifier.padding(vertical = 24.dp),
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+            } else {
+                LazyColumn(Modifier.weight(1f).padding(top = 8.dp)) {
+                    items(visible, key = { it.id }) { pl ->
+                        val checked = pl.id in selected
+                        Row(
+                            Modifier
+                                .fillMaxWidth()
+                                .clickable {
+                                    selected = if (checked) selected - pl.id else selected + pl.id
+                                }
+                                .padding(vertical = 10.dp),
+                            verticalAlignment = Alignment.CenterVertically
+                        ) {
+                            CoverArt(model = pl.artworkUri(library), size = 40.dp, corner = 4.dp)
+                            Spacer(Modifier.width(12.dp))
+                            Column(Modifier.weight(1f)) {
+                                Text(pl.name, fontWeight = FontWeight.Medium, maxLines = 1)
+                                Text(
+                                    "${pl.trackIds.size} songs",
+                                    style = MaterialTheme.typography.bodySmall,
+                                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                                )
+                            }
+                            Checkbox(checked = checked, onCheckedChange = {
+                                selected = if (checked) selected - pl.id else selected + pl.id
+                            })
+                        }
+                    }
+                }
+            }
+            Row(Modifier.fillMaxWidth().padding(top = 8.dp), horizontalArrangement = Arrangement.End) {
+                TextButton(onClick = onDismiss) { Text("Cancel") }
+                Button(
+                    enabled = selected != initiallyIn,
+                    onClick = {
+                        val added = selected - initiallyIn
+                        val removed = initiallyIn - selected
+                        for (pl in playlists) {
+                            when (pl.id) {
+                                in added -> store.addTracks(pl.id, tracks)
+                                in removed -> store.removeTracks(pl.id, tracks)
+                            }
+                        }
+                        if (added.isNotEmpty()) onEnsureTracks(tracks)
+                        onDismiss()
+                    }
+                ) { Text("Save") }
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/ArtistBannerPicker.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/ArtistBannerPicker.kt
new file mode 100644
index 00000000..0ce87e73
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/ArtistBannerPicker.kt
@@ -0,0 +1,161 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.border
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.aspectRatio
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.grid.GridCells
+import androidx.compose.foundation.lazy.grid.GridItemSpan
+import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
+import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.draw.clipToBounds
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import capital.yuri.yuriplayer.core.artist.ArtistImageCandidate
+import capital.yuri.yuriplayer.core.artist.ArtistInfoClient
+
+@Composable
+fun ArtistBannerPicker(
+    artistName: String,
+    client: ArtistInfoClient,
+    onDismiss: () -> Unit,
+    onPicked: (ArtistImageCandidate) -> Unit
+) {
+    var loading by remember { mutableStateOf(true) }
+    var candidates by remember { mutableStateOf<List<ArtistImageCandidate>>(emptyList()) }
+    var error by remember { mutableStateOf<String?>(null) }
+
+    LaunchedEffect(artistName) {
+        loading = true
+        error = null
+        candidates = runCatching { client.bannerCandidates(artistName) }
+            .onFailure { error = it.message }
+            .getOrDefault(emptyList())
+        loading = false
+    }
+
+    val sections = remember(candidates) {
+        candidates.groupBy { sourceLabel(it.sourceId) }.toList()
+    }
+
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.width(640.dp).heightIn(max = 560.dp)) {
+        Column(Modifier.padding(20.dp)) {
+            Text("Choose a header", style = MaterialTheme.typography.titleLarge)
+            Text(
+                artistName,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                modifier = Modifier.padding(top = 4.dp, bottom = 12.dp)
+            )
+            when {
+                loading -> Box(
+                    Modifier.fillMaxWidth().height(180.dp),
+                    contentAlignment = Alignment.Center
+                ) { CircularProgressIndicator() }
+                error != null -> Text(error!!, color = MaterialTheme.colorScheme.error)
+                candidates.isEmpty() -> Text(
+                    "Couldn't find headers for $artistName",
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+                else -> LazyVerticalGrid(
+                    columns = GridCells.Fixed(3),
+                    modifier = Modifier.heightIn(max = 420.dp).fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(10.dp),
+                    verticalArrangement = Arrangement.spacedBy(12.dp),
+                    contentPadding = PaddingValues(bottom = 8.dp)
+                ) {
+                    sections.forEach { (title, items) ->
+                        item(span = { GridItemSpan(3) }, key = "h-$title") {
+                            Text(
+                                title,
+                                style = MaterialTheme.typography.labelLarge,
+                                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f),
+                                modifier = Modifier.padding(top = 4.dp)
+                            )
+                        }
+                        items(items, key = { it.url }) { c ->
+                            BannerTile(c) { onPicked(c) }
+                        }
+                    }
+                }
+            }
+            TextButton(onClick = onDismiss, modifier = Modifier.align(Alignment.End)) {
+                Text("Cancel")
+            }
+        }
+    }
+}
+
+@Composable
+private fun BannerTile(
+    candidate: ArtistImageCandidate,
+    onClick: () -> Unit
+) {
+    val shape = RoundedCornerShape(10.dp)
+    Column {
+        Box(
+            Modifier
+                .fillMaxWidth()
+                .aspectRatio(1f)
+                .clip(shape)
+                .clipToBounds()
+                .border(1.dp, MaterialTheme.colorScheme.outline.copy(alpha = 0.35f), shape)
+                .background(MaterialTheme.colorScheme.surfaceVariant)
+                .clickable(onClick = onClick)
+        ) {
+            CoverArt(
+                model = candidate.url,
+                modifier = Modifier.fillMaxSize(),
+                square = false,
+                corner = 0.dp,
+                contentScale = ContentScale.Crop
+            )
+        }
+        Text(
+            candidate.label,
+            style = MaterialTheme.typography.labelSmall,
+            maxLines = 1,
+            overflow = TextOverflow.Ellipsis,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+            modifier = Modifier.padding(top = 4.dp)
+        )
+    }
+}
+
+private fun sourceLabel(id: String) = when (id.lowercase()) {
+    "wikipedia" -> "Wikipedia"
+    "theaudiodb", "audiodb" -> "TheAudioDB"
+    "deezer" -> "Deezer"
+    "musicbrainz" -> "MusicBrainz"
+    "wikidata" -> "Wikidata"
+    "jellyfin" -> "Jellyfin"
+    "navidrome", "subsonic" -> "Navidrome"
+    else -> id.replaceFirstChar { it.uppercase() }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopExplore.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopExplore.kt
new file mode 100644
index 00000000..15eeffd0
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopExplore.kt
@@ -0,0 +1,403 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Search
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.layout.ContentScale
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.list.TrackRow
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.AlbumPageModel
+import capital.yuri.yuriplayer.components.model.albums
+import capital.yuri.yuriplayer.components.model.toRow
+import capital.yuri.yuriplayer.core.library.LocalLibraryScanner
+import capital.yuri.yuriplayer.core.library.matchesQuery
+import capital.yuri.yuriplayer.core.library.matchesSearch
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.desktop.DesktopPlaylist
+import capital.yuri.yuriplayer.desktop.DesktopSession
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.withContext
+
+private const val SEARCH_DEBOUNCE_MS = 280L
+private const val SONG_HIT_LIMIT = 80
+private const val ALBUM_HIT_LIMIT = 12
+private const val ARTIST_HIT_LIMIT = 12
+
+@Composable
+fun DesktopExplore(
+    session: DesktopSession,
+    query: String,
+    tracks: List<Song>,
+    albums: List<AlbumPageModel>,
+    playlists: List<DesktopPlaylist>,
+    onOpenAlbum: (AlbumPageModel) -> Unit,
+    onOpenPlaylist: (DesktopPlaylist) -> Unit,
+    onOpenArtist: (String) -> Unit,
+    onPlaySongs: (List<Song>, Int) -> Unit,
+    likedIds: Set<String> = emptySet(),
+    onToggleLike: (String) -> Unit = {},
+    songMenu: (Song) -> List<out MenuEntry> = { emptyList() }
+) {
+    val remotes by session.sources.remotes.collectAsState()
+    val enabled = remember(remotes) { remotes.filter { it.enabled } }
+    val allKeys = remember(enabled) {
+        buildSet {
+            add(LocalLibraryScanner.SOURCE_LOCAL)
+            enabled.forEach { add(it.id) }
+        }
+    }
+    var selectedKeys by remember { mutableStateOf(emptySet<String>()) }
+    val effective = if (selectedKeys.isEmpty()) allKeys else selectedKeys
+
+    var songHits by remember { mutableStateOf<List<Song>>(emptyList()) }
+    var albumHits by remember { mutableStateOf<List<AlbumPageModel>>(emptyList()) }
+    var artistHits by remember { mutableStateOf<List<ArtistHit>>(emptyList()) }
+    var playlistHits by remember { mutableStateOf<List<DesktopPlaylist>>(emptyList()) }
+    var busy by remember { mutableStateOf(false) }
+
+    // Cache the artist→tracks grouping across keystrokes (it only changes when
+    // the library changes, not when the query changes).
+    val tracksByArtist = remember(tracks) { tracks.groupBy { it.displayArtist.lowercase() } }
+
+    LaunchedEffect(query, selectedKeys, tracks, albums, playlists, enabled) {
+        val q = query.trim()
+        if (q.isEmpty()) {
+            songHits = emptyList()
+            albumHits = emptyList()
+            artistHits = emptyList()
+            playlistHits = emptyList()
+            busy = false
+            return@LaunchedEffect
+        }
+        busy = true
+        delay(SEARCH_DEBOUNCE_MS)
+        if (query.trim() != q) return@LaunchedEffect
+
+        val includeLocal = selectedKeys.isEmpty() || LocalLibraryScanner.SOURCE_LOCAL in selectedKeys
+        val remoteIds = if (selectedKeys.isEmpty()) null else selectedKeys - LocalLibraryScanner.SOURCE_LOCAL
+
+        val indexed = tracks.filter { track ->
+            val sid = track.sourceId ?: LocalLibraryScanner.SOURCE_LOCAL
+            sid in effective
+        }
+
+        // Compute the full matching set once. The previous code re-ran
+        // matchesQuery() inside the album loop (O(albums × tracks)), which was
+        // the source of the lag; now it runs once per track.
+        val matching = withContext(Dispatchers.Default) {
+            indexed.filter { it.matchesQuery(q) }
+        }
+        if (query.trim() != q) return@LaunchedEffect
+
+        val matchingAlbumTitles = matching.mapTo(HashSet()) { it.displayAlbum.lowercase() }
+
+        fun applyHits(songs: List<Song>) {
+            val unique = songs.distinctBy { it.songKey }.take(SONG_HIT_LIMIT)
+            songHits = unique
+            val uniqueIds = unique.mapTo(HashSet()) { it.songKey }
+
+            albumHits = albums.filter { album ->
+                album.title.matchesSearch(q) ||
+                    album.artist.matchesSearch(q) ||
+                    album.tracks.any { row -> row.id in uniqueIds } ||
+                    album.title.lowercase() in matchingAlbumTitles
+            }.take(ALBUM_HIT_LIMIT).ifEmpty { unique.albums().take(ALBUM_HIT_LIMIT) }
+
+            artistHits = indexed
+                .map { it.displayArtist }
+                .distinct()
+                .filter { it.matchesSearch(q) }
+                .take(ARTIST_HIT_LIMIT)
+                .mapNotNull { name ->
+                    val ofArtist = tracksByArtist[name.lowercase()].orEmpty()
+                    if (ofArtist.isEmpty()) null
+                    else ArtistHit(
+                        name = name,
+                        artworkUri = ofArtist.firstNotNullOfOrNull { it.albumArtUri },
+                        trackCount = ofArtist.size,
+                        albumCount = ofArtist.map { it.displayAlbum }.distinct().size
+                    )
+                }
+
+            playlistHits = if (includeLocal) {
+                playlists.filter { it.name.matchesSearch(q) }.take(12)
+            } else {
+                emptyList()
+            }
+            busy = false
+        }
+
+        applyHits(matching)
+
+        val remoteMatches = if (remoteIds == null || remoteIds.isNotEmpty()) {
+            runCatching {
+                withContext(Dispatchers.IO) { session.searchRemotes(q, remoteIds) }
+            }.getOrDefault(emptyList())
+        } else {
+            emptyList()
+        }
+        if (query.trim() != q) return@LaunchedEffect
+        applyHits(matching + remoteMatches)
+    }
+
+    Column(Modifier.fillMaxSize()) {
+        Text(
+            "Filters",
+            style = MaterialTheme.typography.titleSmall,
+            fontWeight = FontWeight.SemiBold,
+            modifier = Modifier.padding(start = 20.dp, top = 12.dp, end = 20.dp, bottom = 4.dp)
+        )
+        LazyRow(
+            modifier = Modifier.fillMaxWidth(),
+            contentPadding = PaddingValues(horizontal = 20.dp, vertical = 4.dp),
+            horizontalArrangement = Arrangement.spacedBy(8.dp)
+        ) {
+            item {
+                FilterChip(
+                    selected = selectedKeys.isEmpty(),
+                    onClick = { selectedKeys = emptySet() },
+                    label = { Text("All", maxLines = 1) }
+                )
+            }
+            item {
+                FilterChip(
+                    selected = selectedKeys.isEmpty() || LocalLibraryScanner.SOURCE_LOCAL in selectedKeys,
+                    onClick = {
+                        selectedKeys = toggleKey(
+                            LocalLibraryScanner.SOURCE_LOCAL, allKeys, selectedKeys
+                        )
+                    },
+                    label = { Text("On this device", maxLines = 1) }
+                )
+            }
+            items(enabled, key = { it.id }) { remote ->
+                FilterChip(
+                    selected = selectedKeys.isEmpty() || remote.id in selectedKeys,
+                    onClick = { selectedKeys = toggleKey(remote.id, allKeys, selectedKeys) },
+                    label = { Text(remote.name.ifBlank { remote.kind.name }, maxLines = 1) }
+                )
+            }
+        }
+
+        val status = when {
+            busy -> "Searching…"
+            query.trim().isEmpty() -> "Type to search songs, albums, artists, and playlists"
+            else -> buildList {
+                if (artistHits.isNotEmpty()) add("${artistHits.size} artists")
+                if (albumHits.isNotEmpty()) add("${albumHits.size} albums")
+                if (playlistHits.isNotEmpty()) add("${playlistHits.size} playlists")
+                add("${songHits.size} songs")
+            }.joinToString(" · ")
+        }
+        Row(
+            Modifier.padding(horizontal = 20.dp, vertical = 6.dp),
+            verticalAlignment = Alignment.CenterVertically
+        ) {
+            if (busy) {
+                CircularProgressIndicator(Modifier.size(14.dp), strokeWidth = 2.dp)
+                Spacer(Modifier.width(8.dp))
+            }
+            Text(
+                status,
+                style = MaterialTheme.typography.labelMedium,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+            )
+        }
+
+        when {
+            query.trim().isEmpty() -> {
+                Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+                    Column(horizontalAlignment = Alignment.CenterHorizontally) {
+                        Icon(
+                            Icons.Default.Search,
+                            contentDescription = null,
+                            modifier = Modifier.size(48.dp),
+                            tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.25f)
+                        )
+                        Spacer(Modifier.height(12.dp))
+                        Text(
+                            "Explore every library",
+                            style = MaterialTheme.typography.titleMedium,
+                            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                        )
+                        Text(
+                            "Artists, albums, songs, and playlists · local + Jellyfin + Subsonic",
+                            style = MaterialTheme.typography.bodySmall,
+                            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.4f),
+                            modifier = Modifier.padding(top = 6.dp)
+                        )
+                    }
+                }
+            }
+            !busy && songHits.isEmpty() && albumHits.isEmpty() &&
+                artistHits.isEmpty() && playlistHits.isEmpty() -> {
+                Text(
+                    if (tracks.isEmpty()) {
+                        "Nothing indexed yet — scan a folder from the globe menu or Settings → Library."
+                    } else {
+                        "No matches for \"${query.trim()}\"."
+                    },
+                    modifier = Modifier.padding(20.dp),
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                )
+            }
+            else -> {
+                LazyColumn(Modifier.fillMaxSize()) {
+                    if (artistHits.isNotEmpty()) {
+                        item { ExploreSection("Artists") }
+                        items(artistHits, key = { "ar-${it.name}" }) { artist ->
+                            Row(
+                                Modifier
+                                    .fillMaxWidth()
+                                    .clickable { onOpenArtist(artist.name) }
+                                    .padding(horizontal = 20.dp, vertical = 10.dp),
+                                verticalAlignment = Alignment.CenterVertically
+                            ) {
+                                CoverArt(
+                                    model = artist.artworkUri,
+                                    size = 48.dp,
+                                    corner = 24.dp,
+                                    contentScale = ContentScale.Crop
+                                )
+                                Spacer(Modifier.width(12.dp))
+                                Column {
+                                    Text(artist.name, fontWeight = FontWeight.Medium, maxLines = 1)
+                                    Text(
+                                        "${artist.trackCount} tracks · ${artist.albumCount} albums",
+                                        style = MaterialTheme.typography.bodySmall,
+                                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                                    )
+                                }
+                            }
+                        }
+                    }
+                    if (albumHits.isNotEmpty()) {
+                        item { ExploreSection("Albums") }
+                        items(albumHits, key = { "al-${it.id}" }) { album ->
+                            Row(
+                                Modifier
+                                    .fillMaxWidth()
+                                    .clickable { onOpenAlbum(album) }
+                                    .padding(horizontal = 20.dp, vertical = 10.dp),
+                                verticalAlignment = Alignment.CenterVertically
+                            ) {
+                                CoverArt(model = album.artworkUri, size = 48.dp, corner = 6.dp)
+                                Spacer(Modifier.width(12.dp))
+                                Column {
+                                    Text(album.title, fontWeight = FontWeight.Medium, maxLines = 1)
+                                    Text(
+                                        album.artist,
+                                        style = MaterialTheme.typography.bodySmall,
+                                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                                        maxLines = 1,
+                                        overflow = TextOverflow.Ellipsis
+                                    )
+                                }
+                            }
+                        }
+                    }
+                    if (playlistHits.isNotEmpty()) {
+                        item { ExploreSection("Playlists") }
+                        items(playlistHits, key = { "pl-${it.id}" }) { pl ->
+                            Row(
+                                Modifier
+                                    .fillMaxWidth()
+                                    .clickable { onOpenPlaylist(pl) }
+                                    .padding(horizontal = 20.dp, vertical = 10.dp),
+                                verticalAlignment = Alignment.CenterVertically
+                            ) {
+                                CoverArt(
+                                    model = pl.artworkUri(tracks),
+                                    size = 48.dp,
+                                    corner = 6.dp
+                                )
+                                Spacer(Modifier.width(12.dp))
+                                Column {
+                                    Text(pl.name, fontWeight = FontWeight.Medium, maxLines = 1)
+                                    Text(
+                                        pl.description ?: "Playlist",
+                                        style = MaterialTheme.typography.bodySmall,
+                                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                                        maxLines = 1
+                                    )
+                                }
+                            }
+                        }
+                    }
+                    if (songHits.isNotEmpty()) {
+                        item { ExploreSection("Songs") }
+                        itemsIndexed(songHits, key = { _, t -> t.songKey }) { index, track ->
+                            TrackRow(
+                                track = track.toRow(),
+                                onClick = { onPlaySongs(songHits, index) },
+                                liked = track.songKey in likedIds,
+                                onToggleLike = { onToggleLike(track.songKey) },
+                                contextItems = songMenu(track)
+                            )
+                        }
+                    }
+                    item { Spacer(Modifier.height(24.dp)) }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+private fun ExploreSection(title: String) {
+    Text(
+        title,
+        style = MaterialTheme.typography.titleSmall,
+        fontWeight = FontWeight.SemiBold,
+        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f),
+        modifier = Modifier.padding(horizontal = 20.dp, vertical = 10.dp)
+    )
+}
+
+private data class ArtistHit(
+    val name: String,
+    val artworkUri: String?,
+    val trackCount: Int,
+    val albumCount: Int
+)
+
+private fun toggleKey(key: String, allKeys: Set<String>, selected: Set<String>): Set<String> {
+    val effective = if (selected.isEmpty()) allKeys else selected
+    val next = if (key in effective) effective - key else effective + key
+    return if (next.isEmpty() || next.containsAll(allKeys)) emptySet() else next
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopFiles.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopFiles.kt
new file mode 100644
index 00000000..1b09cbda
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopFiles.kt
@@ -0,0 +1,126 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import java.awt.Dialog
+import java.awt.FileDialog
+import java.awt.Frame
+import java.awt.KeyboardFocusManager
+import java.awt.Window
+import java.io.File
+import java.io.IOException
+import java.net.URI
+import javax.swing.SwingUtilities
+
+object DesktopFiles {
+    private val imageExt = setOf("jpg", "jpeg", "png", "webp", "gif", "bmp")
+
+    fun pickImage(title: String = "Choose image"): File? =
+        pickImages(title, multiple = false).firstOrNull()
+
+    fun pickImages(title: String = "Choose images", multiple: Boolean = true): List<File> {
+        val picked = if (isLinux()) linuxNativePicker(title, multiple) else null
+        val files = picked ?: awtPicker(title, multiple)
+        return files.filter { it.isFile && it.extension.lowercase() in imageExt }
+    }
+
+    fun downloadImage(url: String): File? = runCatching {
+        val out = File.createTempFile("yuri-img-", ".img")
+        URI(url).toURL().openStream().use { input ->
+            out.outputStream().use { input.copyTo(it) }
+        }
+        out.takeIf { it.length() > 32 }
+    }.getOrNull()
+
+    private fun isLinux(): Boolean {
+        val os = System.getProperty("os.name").orEmpty().lowercase()
+        return os.contains("linux") || os.contains("bsd")
+    }
+
+    /**
+     * System portal pickers (zenity / kdialog). Returning empty means the user
+     * cancelled; null means no native tool was available.
+     */
+    private fun linuxNativePicker(title: String, multiple: Boolean): List<File>? {
+        val desktop = System.getenv("XDG_CURRENT_DESKTOP").orEmpty().lowercase()
+        val kdeFirst = "kde" in desktop || "plasma" in desktop
+        val tools = if (kdeFirst) listOf(::kdialogCmd, ::zenityCmd) else listOf(::zenityCmd, ::kdialogCmd)
+        for (tool in tools) {
+            val cmd = tool(title, multiple)
+            val result = runPicker(cmd) ?: continue
+            return result
+        }
+        return null
+    }
+
+    private fun zenityCmd(title: String, multiple: Boolean): List<String> = buildList {
+        add("zenity")
+        add("--file-selection")
+        add("--title=$title")
+        add("--file-filter=Images | *.jpg *.jpeg *.png *.webp *.gif *.bmp *.JPG *.JPEG *.PNG *.WEBP")
+        if (multiple) {
+            add("--multiple")
+            add("--separator=\n")
+        }
+    }
+
+    private fun kdialogCmd(title: String, multiple: Boolean): List<String> = buildList {
+        add("kdialog")
+        add("--title")
+        add(title)
+        if (multiple) add("--multiple")
+        add("--getopenfilename")
+        add(System.getProperty("user.home") ?: ".")
+        add("Images (*.jpg *.jpeg *.png *.webp *.gif *.bmp)")
+    }
+
+    private fun runPicker(cmd: List<String>): List<File>? {
+        val process = try {
+            ProcessBuilder(cmd)
+                .redirectError(ProcessBuilder.Redirect.DISCARD)
+                .start()
+        } catch (_: IOException) {
+            return null
+        }
+        val text = process.inputStream.bufferedReader().readText().trim()
+        val code = process.waitFor()
+        if (code != 0 || text.isEmpty()) return emptyList()
+        return text.split('\n', '\u0000')
+            .flatMap { line -> if (':' in line && !line.startsWith('/')) line.split(':') else listOf(line) }
+            .map { it.trim().removeSurrounding("\"") }
+            .filter { it.isNotEmpty() }
+            .map { File(it) }
+    }
+
+    private fun awtPicker(title: String, multiple: Boolean): List<File> {
+        var result: Array<File>? = null
+        val task = Runnable {
+            val owner = ownerFrame()
+            val dialog = if (owner != null) {
+                FileDialog(owner, title, FileDialog.LOAD)
+            } else {
+                FileDialog(null as Frame?, title, FileDialog.LOAD)
+            }
+            dialog.isMultipleMode = multiple
+            dialog.file = "*.jpg;*.jpeg;*.png;*.webp;*.gif;*.bmp"
+            dialog.modalityType = Dialog.ModalityType.APPLICATION_MODAL
+            dialog.isAlwaysOnTop = true
+            dialog.isVisible = true
+            result = dialog.files
+            dialog.dispose()
+        }
+        if (SwingUtilities.isEventDispatchThread()) task.run()
+        else SwingUtilities.invokeAndWait(task)
+        return result?.toList().orEmpty()
+    }
+
+    private fun ownerFrame(): Frame? {
+        val focus = KeyboardFocusManager.getCurrentKeyboardFocusManager()
+        fun Window.toFrame(): Frame? = when (this) {
+            is Frame -> this
+            is Dialog -> owner as? Frame
+            else -> null
+        }
+        focus.activeWindow?.toFrame()?.let { return it }
+        focus.focusedWindow?.toFrame()?.let { return it }
+        return Frame.getFrames().firstOrNull { it.isShowing }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopProviders.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopProviders.kt
new file mode 100644
index 00000000..9420d5f9
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopProviders.kt
@@ -0,0 +1,408 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Cloud
+import androidx.compose.material.icons.filled.Dns
+import androidx.compose.material.icons.filled.Folder
+import androidx.compose.material.icons.filled.Storage
+import androidx.compose.material.icons.filled.Visibility
+import androidx.compose.material.icons.filled.VisibilityOff
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.text.input.PasswordVisualTransformation
+import androidx.compose.ui.text.input.VisualTransformation
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.settings.SettingsGroup
+import capital.yuri.yuriplayer.components.settings.SettingsNavRow
+import capital.yuri.yuriplayer.components.settings.SettingsNote
+import capital.yuri.yuriplayer.components.settings.SettingsSectionTitle
+import capital.yuri.yuriplayer.components.settings.SettingsSwitchRow
+import capital.yuri.yuriplayer.components.settings.SettingsTopBar
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import capital.yuri.yuriplayer.core.source.RemoteAccount
+import capital.yuri.yuriplayer.core.source.SourceKind
+import capital.yuri.yuriplayer.desktop.DesktopSession
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+
+private sealed class ProviderPage {
+    data object List : ProviderPage()
+    data class Editor(val existing: RemoteAccount?, val kind: SourceKind) : ProviderPage()
+}
+
+@Composable
+fun DesktopProvidersPane(
+    session: DesktopSession,
+    onOpenLocal: () -> Unit
+) {
+    var page by remember { mutableStateOf<ProviderPage>(ProviderPage.List) }
+    when (val p = page) {
+        ProviderPage.List -> ProvidersList(
+            session = session,
+            onOpenLocal = onOpenLocal,
+            onOpen = { page = ProviderPage.Editor(it, it.kind) },
+            onAdd = { page = ProviderPage.Editor(null, it) }
+        )
+        is ProviderPage.Editor -> ProviderEditor(
+            session = session,
+            existing = p.existing,
+            kind = p.kind,
+            onBack = { page = ProviderPage.List }
+        )
+    }
+}
+
+@Composable
+private fun ProvidersList(
+    session: DesktopSession,
+    onOpenLocal: () -> Unit,
+    onOpen: (RemoteAccount) -> Unit,
+    onAdd: (SourceKind) -> Unit
+) {
+    val remotes by session.sources.remotes.collectAsState()
+    val scanMessage by session.scanMessage.collectAsState()
+    val scope = rememberCoroutineScope()
+    var listStatus by remember { mutableStateOf<String?>(null) }
+    var testingId by remember { mutableStateOf<String?>(null) }
+
+    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState())) {
+        SettingsNote("Local library and remote servers YuriPlayer can play from.")
+        if (scanMessage.isNotBlank()) {
+            Text(
+                scanMessage,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.primary,
+                modifier = Modifier.padding(vertical = 4.dp)
+            )
+        }
+        Spacer(Modifier.height(8.dp))
+
+        SettingsSectionTitle("On this device")
+        SettingsGroup {
+            SettingsNavRow(
+                title = "Local files",
+                subtitle = "Default music folders plus any you add",
+                icon = Icons.Default.Folder,
+                trailing = "Configure",
+                onClick = onOpenLocal
+            )
+        }
+
+        SettingsSectionTitle("Servers")
+        if (remotes.isEmpty()) {
+            SettingsGroup {
+                SettingsNavRow(
+                    title = "No servers yet",
+                    subtitle = "Add Jellyfin or Subsonic / OpenSubsonic",
+                    icon = Icons.Default.Storage,
+                    onClick = { onAdd(SourceKind.JELLYFIN) }
+                )
+            }
+        } else {
+            SettingsGroup {
+                remotes.forEach { row ->
+                    Column {
+                        SettingsNavRow(
+                            title = row.name.ifBlank { kindLabel(row.kind) },
+                            subtitle = buildString {
+                                append(kindLabel(row.kind))
+                                if (!row.enabled) append(" · off")
+                                append(" · ")
+                                append(row.baseUrl.removePrefix("https://").removePrefix("http://"))
+                            },
+                            icon = iconFor(row.kind),
+                            trailing = if (row.enabled) "On" else "Off",
+                            onClick = { onOpen(row) }
+                        )
+                        Row(
+                            Modifier.fillMaxWidth().padding(start = 54.dp, end = 16.dp, bottom = 8.dp),
+                            horizontalArrangement = Arrangement.End
+                        ) {
+                            TextButton(
+                                enabled = testingId != row.id,
+                                onClick = {
+                                    testingId = row.id
+                                    listStatus = null
+                                    scope.launch {
+                                        val result = withContext(Dispatchers.IO) {
+                                            session.testConnection(
+                                                row.kind,
+                                                row.baseUrl,
+                                                row.username,
+                                                row.secret
+                                            )
+                                        }
+                                        listStatus = result.getOrElse { "Failed: ${it.message ?: it}" }
+                                        testingId = null
+                                    }
+                                }
+                            ) {
+                                Text(if (testingId == row.id) "Testing…" else "Test connection")
+                            }
+                        }
+                    }
+                }
+            }
+        }
+
+        if (listStatus != null) {
+            Text(
+                listStatus!!,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.primary,
+                modifier = Modifier.padding(vertical = 8.dp)
+            )
+        }
+
+        SettingsSectionTitle("Add")
+        SettingsGroup {
+            SettingsNavRow(
+                title = "Jellyfin",
+                subtitle = "Self-hosted media server",
+                icon = Icons.Default.Dns,
+                onClick = { onAdd(SourceKind.JELLYFIN) }
+            )
+            SettingsNavRow(
+                title = "Subsonic / OpenSubsonic",
+                subtitle = "Navidrome, Gonic, Official, …",
+                icon = Icons.Default.Cloud,
+                onClick = { onAdd(SourceKind.SUBSONIC) }
+            )
+        }
+        Spacer(Modifier.height(24.dp))
+    }
+}
+
+@Composable
+private fun ProviderEditor(
+    session: DesktopSession,
+    existing: RemoteAccount?,
+    kind: SourceKind,
+    onBack: () -> Unit
+) {
+    val scope = rememberCoroutineScope()
+    var label by remember { mutableStateOf(existing?.name.orEmpty().ifBlank {
+        if (kind == SourceKind.JELLYFIN) "Jellyfin" else "Subsonic"
+    }) }
+    var url by remember { mutableStateOf(existing?.baseUrl.orEmpty()) }
+    var username by remember { mutableStateOf(existing?.username.orEmpty()) }
+    var password by remember { mutableStateOf(existing?.secret.orEmpty()) }
+    var showPassword by remember { mutableStateOf(false) }
+    var enabled by remember { mutableStateOf(existing?.enabled ?: true) }
+    var status by remember { mutableStateOf<String?>(null) }
+    var testing by remember { mutableStateOf(false) }
+    var saving by remember { mutableStateOf(false) }
+    var confirmDelete by remember { mutableStateOf(false) }
+
+    fun runTest() {
+        if (testing) return
+        scope.launch {
+            testing = true
+            status = null
+            val result = withContext(Dispatchers.IO) {
+                session.testConnection(kind, url, username, password)
+            }
+            status = result.getOrElse { "Failed: ${it.message ?: it}" }
+            testing = false
+        }
+    }
+
+    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState())) {
+        SettingsTopBar(
+            title = if (existing == null) "Add provider" else "Edit provider",
+            onBack = onBack
+        )
+        Text(
+            kindLabel(kind),
+            style = MaterialTheme.typography.labelLarge,
+            color = MaterialTheme.colorScheme.primary
+        )
+        Spacer(Modifier.height(8.dp))
+
+        SettingsSectionTitle("Identity")
+        SettingsGroup {
+            Column(Modifier.padding(16.dp)) {
+                OutlinedTextField(
+                    value = label,
+                    onValueChange = { label = it },
+                    label = { Text("Label") },
+                    placeholder = { Text("Home server") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                Spacer(Modifier.height(4.dp))
+                Text(
+                    "Shown in the providers list and library filters.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+                )
+            }
+        }
+
+        SettingsSectionTitle("Connection")
+        SettingsGroup {
+            Column(Modifier.padding(16.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
+                OutlinedTextField(
+                    value = url,
+                    onValueChange = { url = it },
+                    label = { Text("Server URL") },
+                    placeholder = { Text("https://music.example.com") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                OutlinedTextField(
+                    value = username,
+                    onValueChange = { username = it },
+                    label = { Text("Username") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth()
+                )
+                OutlinedTextField(
+                    value = password,
+                    onValueChange = { password = it },
+                    label = { Text("Password") },
+                    singleLine = true,
+                    visualTransformation = if (showPassword) {
+                        VisualTransformation.None
+                    } else {
+                        PasswordVisualTransformation()
+                    },
+                    keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
+                    trailingIcon = {
+                        IconButton(onClick = { showPassword = !showPassword }) {
+                            Icon(
+                                if (showPassword) Icons.Default.VisibilityOff else Icons.Default.Visibility,
+                                contentDescription = if (showPassword) "Hide password" else "Show password"
+                            )
+                        }
+                    },
+                    modifier = Modifier.fillMaxWidth()
+                )
+                OutlinedButton(
+                    onClick = { runTest() },
+                    enabled = !testing && url.isNotBlank() && username.isNotBlank()
+                ) {
+                    Text(if (testing) "Testing…" else "Test connection")
+                }
+            }
+        }
+
+        SettingsSectionTitle("Options")
+        SettingsGroup {
+            SettingsSwitchRow(
+                title = "Enabled",
+                subtitle = "Include this provider when browsing and playing",
+                checked = enabled,
+                onCheckedChange = { enabled = it }
+            )
+        }
+
+        if (status != null) {
+            Text(
+                status!!,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.primary,
+                modifier = Modifier.padding(vertical = 8.dp)
+            )
+        }
+
+        SettingsSectionTitle("Actions")
+        SettingsGroup {
+            SettingsNavRow(
+                title = if (testing) "Testing…" else "Test connection",
+                subtitle = "Authenticate against the server",
+                onClick = { runTest() }
+            )
+            SettingsNavRow(
+                title = if (saving) "Saving…" else "Save",
+                subtitle = "Write label and credentials",
+                onClick = {
+                    if (saving) return@SettingsNavRow
+                    saving = true
+                    status = null
+                    session.saveRemote(
+                        existingId = existing?.id,
+                        kind = kind,
+                        name = label,
+                        baseUrl = url,
+                        username = username,
+                        password = password,
+                        enabled = enabled
+                    ) { ok, message ->
+                        saving = false
+                        if (ok) onBack() else status = message
+                    }
+                }
+            )
+            if (existing != null) {
+                SettingsNavRow(
+                    title = "Delete provider",
+                    subtitle = "Remove this server from YuriPlayer",
+                    onClick = { confirmDelete = true }
+                )
+            }
+        }
+        Spacer(Modifier.height(24.dp))
+    }
+
+    if (confirmDelete && existing != null) {
+        InWindowPanel(onDismiss = { confirmDelete = false }, modifier = Modifier.padding(24.dp)) {
+            Column(Modifier.padding(24.dp).fillMaxWidth()) {
+                Text("Delete provider?", style = MaterialTheme.typography.titleLarge)
+                Text(
+                    "“${label.ifBlank { kindLabel(kind) }}” will be removed. Local files are unaffected.",
+                    style = MaterialTheme.typography.bodyMedium,
+                    modifier = Modifier.padding(top = 8.dp)
+                )
+                Row(Modifier.fillMaxWidth().padding(top = 16.dp), horizontalArrangement = Arrangement.End) {
+                    TextButton(onClick = { confirmDelete = false }) { Text("Cancel") }
+                    TextButton(
+                        onClick = {
+                            session.removeRemote(existing.id)
+                            confirmDelete = false
+                            onBack()
+                        }
+                    ) { Text("Delete") }
+                }
+            }
+        }
+    }
+}
+
+private fun kindLabel(kind: SourceKind): String = when (kind) {
+    SourceKind.JELLYFIN -> "Jellyfin"
+    SourceKind.SUBSONIC -> "Subsonic / OpenSubsonic"
+    SourceKind.LOCAL -> "Local"
+}
+
+private fun iconFor(kind: SourceKind) = when (kind) {
+    SourceKind.JELLYFIN -> Icons.Default.Dns
+    SourceKind.SUBSONIC -> Icons.Default.Cloud
+    SourceKind.LOCAL -> Icons.Default.Folder
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopScanMenu.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopScanMenu.kt
new file mode 100644
index 00000000..032f03e7
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopScanMenu.kt
@@ -0,0 +1,155 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.size
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.TravelExplore
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.material3.DropdownMenu
+import androidx.compose.material3.DropdownMenuItem
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.desktop.DesktopScanStatus
+import capital.yuri.yuriplayer.desktop.DesktopSession
+
+@Composable
+fun DesktopScanMenu(session: DesktopSession) {
+    val scanning by session.isScanning.collectAsState()
+    val message by session.scanMessage.collectAsState()
+    val sources by session.scanSources.collectAsState()
+    var expanded by remember { mutableStateOf(false) }
+    val muted = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+
+    Box {
+        IconButton(onClick = { expanded = true }) {
+            if (scanning) {
+                CircularProgressIndicator(
+                    modifier = Modifier.size(20.dp),
+                    strokeWidth = 2.dp,
+                    color = muted
+                )
+            } else {
+                Icon(
+                    Icons.Default.TravelExplore,
+                    contentDescription = "Library scan",
+                    tint = muted
+                )
+            }
+        }
+        DropdownMenu(
+            expanded = expanded,
+            onDismissRequest = { expanded = false }
+        ) {
+            DropdownMenuItem(
+                text = {
+                    Text(
+                        message,
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.primary
+                    )
+                },
+                onClick = { },
+                enabled = false
+            )
+            HorizontalDivider()
+            DropdownMenuItem(
+                text = { Text("Partial scan all") },
+                onClick = {
+                    expanded = false
+                    session.requestScan(force = false)
+                }
+            )
+            DropdownMenuItem(
+                text = { Text("Full scan all") },
+                onClick = {
+                    expanded = false
+                    session.requestScan(force = true)
+                }
+            )
+            DropdownMenuItem(
+                text = { Text("Full scan local only") },
+                onClick = {
+                    expanded = false
+                    session.requestScan(force = true, sourceId = DesktopSession.LOCAL_SCAN_ID)
+                }
+            )
+            DropdownMenuItem(
+                text = { Text("Pause all") },
+                enabled = scanning,
+                onClick = {
+                    expanded = false
+                    session.pauseScan(null)
+                }
+            )
+            DropdownMenuItem(
+                text = { Text("Stop all") },
+                enabled = scanning,
+                onClick = {
+                    expanded = false
+                    session.stopScan(null)
+                }
+            )
+            if (sources.isNotEmpty()) {
+                HorizontalDivider()
+                sources.forEach { row ->
+                    val statusLabel = when (row.status) {
+                        DesktopScanStatus.RUNNING -> "running"
+                        DesktopScanStatus.PAUSED -> "paused"
+                        DesktopScanStatus.STOPPED -> "stopped"
+                        DesktopScanStatus.DONE ->
+                            if (row.count > 0) "done (${row.count})" else "done"
+                        DesktopScanStatus.ERROR -> row.detail.ifBlank { "error" }
+                        DesktopScanStatus.IDLE -> "idle"
+                    }
+                    val busy = row.status == DesktopScanStatus.RUNNING || scanning
+                    DropdownMenuItem(
+                        text = { Text("${row.name} · $statusLabel") },
+                        onClick = { },
+                        enabled = false
+                    )
+                    DropdownMenuItem(
+                        text = { Text("  Partial scan") },
+                        onClick = {
+                            expanded = false
+                            session.requestScan(force = false, sourceId = row.id)
+                        }
+                    )
+                    DropdownMenuItem(
+                        text = { Text("  Full scan") },
+                        onClick = {
+                            expanded = false
+                            session.requestScan(force = true, sourceId = row.id)
+                        }
+                    )
+                    DropdownMenuItem(
+                        text = { Text("  Pause") },
+                        enabled = busy,
+                        onClick = {
+                            expanded = false
+                            session.pauseScan(row.id)
+                        }
+                    )
+                    DropdownMenuItem(
+                        text = { Text("  Stop") },
+                        enabled = busy,
+                        onClick = {
+                            expanded = false
+                            session.stopScan(row.id)
+                        }
+                    )
+                }
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopSettings.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopSettings.kt
new file mode 100644
index 00000000..c70e14be
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/DesktopSettings.kt
@@ -0,0 +1,172 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.heightIn
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.widthIn
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Folder
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.dialog.InWindowDialog
+import capital.yuri.yuriplayer.components.settings.SettingsCategory
+import capital.yuri.yuriplayer.components.settings.SettingsShell
+import capital.yuri.yuriplayer.components.theme.AccentPicker
+import capital.yuri.yuriplayer.components.theme.ThemeModePicker
+import capital.yuri.yuriplayer.core.platform.appDirectories
+import capital.yuri.yuriplayer.desktop.DesktopSession
+import javax.swing.JFileChooser
+
+@Composable
+fun DesktopSettingsDialog(
+    session: DesktopSession,
+    onDismiss: () -> Unit
+) {
+    var category by remember { mutableStateOf(SettingsCategory.Appearance) }
+    InWindowDialog(onDismiss = onDismiss) {
+        SettingsShell(
+            selected = category,
+            onSelect = { category = it },
+            onClose = onDismiss,
+            modifier = Modifier
+                .widthIn(min = 720.dp, max = 1080.dp)
+                .heightIn(min = 480.dp, max = 720.dp)
+                .fillMaxWidth(0.86f)
+                .height(640.dp),
+            categories = listOf(
+                SettingsCategory.Appearance,
+                SettingsCategory.Playback,
+                SettingsCategory.Library,
+                SettingsCategory.Providers,
+                SettingsCategory.About
+            )
+        ) {
+            when (category) {
+                SettingsCategory.Appearance -> AppearancePane(session)
+                SettingsCategory.Playback -> PlaybackPane()
+                SettingsCategory.Library -> LibraryPane(session)
+                SettingsCategory.Providers -> DesktopProvidersPane(
+                    session = session,
+                    onOpenLocal = { category = SettingsCategory.Library }
+                )
+                SettingsCategory.About -> AboutPane()
+            }
+        }
+    }
+}
+
+@Composable
+private fun AppearancePane(session: DesktopSession) {
+    val choice by session.theme.choice.collectAsState()
+    Column {
+        Text(
+            "Dark, light, or follow the system. Accent is the Material 3 primary. " +
+                "Cover art still tints now playing and the play button.",
+            style = MaterialTheme.typography.bodyMedium,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f)
+        )
+        Spacer(Modifier.height(16.dp))
+        Text("Theme", style = MaterialTheme.typography.titleSmall)
+        Spacer(Modifier.height(8.dp))
+        ThemeModePicker(mode = choice.mode, onMode = session.theme::setMode)
+        Spacer(Modifier.height(20.dp))
+        AccentPicker(selectedId = choice.accentId, onSelect = session.theme::setAccent)
+        Spacer(Modifier.height(20.dp))
+        Text(
+            "Jewel, macOS, and Windows families are next — they won’t depend on Material 3.",
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f)
+        )
+    }
+}
+
+@Composable
+private fun PlaybackPane() {
+    Column {
+        Text("Audio engine", style = MaterialTheme.typography.titleMedium)
+        Spacer(Modifier.height(8.dp))
+        Text(
+            "Desktop uses LibVLC (vlcj). Same family as the default Android engine. " +
+                "Media3 is phone-only.",
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.75f)
+        )
+        Spacer(Modifier.height(12.dp))
+        Text(
+            "LibVLC — bundled on Windows/macOS, system VLC on Linux. " +
+                "NixOS: add vlc to systemPackages (or set YURI_LIBVLC to the lib dir).",
+            color = MaterialTheme.colorScheme.onSurface
+        )
+    }
+}
+
+@Composable
+private fun LibraryPane(session: DesktopSession) {
+    val folders by session.sources.extraFolders.collectAsState()
+    val status by session.scanMessage.collectAsState()
+    val defaults = remember { appDirectories().defaultMusicRoots }
+    Column(Modifier.fillMaxSize().verticalScroll(rememberScrollState())) {
+        Text(status, style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.primary)
+        Spacer(Modifier.height(16.dp))
+        Text("Local folders", style = MaterialTheme.typography.titleMedium)
+        Text(
+            "Default music folders are scanned automatically. Jellyfin and Subsonic live under Providers.",
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+        )
+        defaults.forEach { path ->
+            Text(path, modifier = Modifier.padding(top = 4.dp), color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f))
+        }
+        folders.forEach { path ->
+            Row(Modifier.fillMaxWidth(), verticalAlignment = Alignment.CenterVertically) {
+                Text(path, modifier = Modifier.weight(1f))
+                TextButton(onClick = { session.removeFolder(path) }) { Text("Remove") }
+            }
+        }
+        Spacer(Modifier.height(8.dp))
+        OutlinedButton(onClick = {
+            pickDirectory()?.let { session.addFolder(it) }
+        }) {
+            Icon(Icons.Default.Folder, contentDescription = null)
+            Text("  Add folder")
+        }
+        Spacer(Modifier.height(16.dp))
+        OutlinedButton(onClick = { session.rescan() }) { Text("Rescan libraries") }
+    }
+}
+
+private fun pickDirectory(): String? {
+    val chooser = JFileChooser()
+    chooser.fileSelectionMode = JFileChooser.DIRECTORIES_ONLY
+    chooser.dialogTitle = "Add music folder"
+    chooser.isAcceptAllFileFilterUsed = false
+    return if (chooser.showOpenDialog(null) == JFileChooser.APPROVE_OPTION) {
+        chooser.selectedFile?.absolutePath
+    } else null
+}
+
+@Composable
+private fun AboutPane() {
+    Column(Modifier.fillMaxSize().padding(top = 8.dp)) {
+        Text("Yuri Player", style = MaterialTheme.typography.headlineSmall)
+        Text("Desktop · Compose Multiplatform", color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f))
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/ImageCropDialog.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/ImageCropDialog.kt
new file mode 100644
index 00000000..e756055b
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/ImageCropDialog.kt
@@ -0,0 +1,243 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.Canvas
+import androidx.compose.foundation.background
+import androidx.compose.foundation.gestures.detectDragGestures
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.draw.clipToBounds
+import androidx.compose.ui.geometry.Offset
+import androidx.compose.ui.geometry.Size
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.graphics.drawscope.Stroke
+import androidx.compose.ui.graphics.toComposeImageBitmap
+import androidx.compose.ui.input.pointer.PointerEventType
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.layout.onSizeChanged
+import androidx.compose.ui.unit.IntOffset
+import androidx.compose.ui.unit.IntSize
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import java.awt.RenderingHints
+import java.awt.image.BufferedImage
+import java.io.File
+import javax.imageio.ImageIO
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+/**
+ * Pan/zoom crop for any aspect. `aspect` is width / height (1 = square cover,
+ * 3 = Twitter-style header). Source is scaled to cover the frame.
+ */
+@Composable
+fun ImageCropDialog(
+    source: File,
+    title: String = "Crop",
+    aspect: Float = 1f,
+    onCancel: () -> Unit,
+    onCropped: (File) -> Unit
+) {
+    val image = remember(source) { runCatching { ImageIO.read(source) }.getOrNull() }
+    if (image == null) {
+        onCancel()
+        return
+    }
+    val bitmap = remember(image) { image.toComposeImageBitmap() }
+    var zoom by remember { mutableFloatStateOf(1f) }
+    var pan by remember { mutableStateOf(Offset.Zero) }
+    var stage by remember { mutableStateOf(Size.Zero) }
+    val wide = aspect >= 1.4f
+    val panel = if (wide) Modifier.size(760.dp, 520.dp) else Modifier.size(560.dp, 640.dp)
+
+    InWindowPanel(onDismiss = onCancel, modifier = panel) {
+        Column(Modifier.fillMaxSize().padding(16.dp)) {
+            Text(title, style = MaterialTheme.typography.titleLarge)
+            Text(
+                "Scroll to zoom · drag to pan",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                modifier = Modifier.padding(bottom = 12.dp)
+            )
+            Box(
+                Modifier
+                    .fillMaxWidth()
+                    .weight(1f)
+                    .clip(RoundedCornerShape(8.dp))
+                    .clipToBounds()
+                    .background(Color.Black)
+                    .onSizeChanged { stage = Size(it.width.toFloat(), it.height.toFloat()) }
+                    .pointerInput(image) {
+                        awaitPointerEventScope {
+                            while (true) {
+                                val event = awaitPointerEvent()
+                                if (event.type == PointerEventType.Scroll) {
+                                    val dy = event.changes.firstOrNull()?.scrollDelta?.y ?: 0f
+                                    zoom = (zoom * (1f - dy * 0.08f)).coerceIn(1f, 8f)
+                                }
+                            }
+                        }
+                    }
+                    .pointerInput(image) {
+                        detectDragGestures { change, drag ->
+                            change.consume()
+                            pan += drag
+                        }
+                    },
+                contentAlignment = Alignment.Center
+            ) {
+                Canvas(Modifier.fillMaxSize().clipToBounds()) {
+                    val layout = cropLayout(size, image.width, image.height, aspect, zoom, pan)
+                    drawImage(
+                        image = bitmap,
+                        dstOffset = IntOffset(layout.drawLeft.roundToInt(), layout.drawTop.roundToInt()),
+                        dstSize = IntSize(
+                            layout.drawW.roundToInt().coerceAtLeast(1),
+                            layout.drawH.roundToInt().coerceAtLeast(1)
+                        )
+                    )
+                    val dim = Color.Black.copy(alpha = 0.5f)
+                    drawRect(dim, size = Size(size.width, layout.frameTop))
+                    drawRect(
+                        dim,
+                        topLeft = Offset(0f, layout.frameTop + layout.frameH),
+                        size = Size(size.width, size.height - layout.frameTop - layout.frameH)
+                    )
+                    drawRect(
+                        dim,
+                        topLeft = Offset(0f, layout.frameTop),
+                        size = Size(layout.frameLeft, layout.frameH)
+                    )
+                    drawRect(
+                        dim,
+                        topLeft = Offset(layout.frameLeft + layout.frameW, layout.frameTop),
+                        size = Size(size.width - layout.frameLeft - layout.frameW, layout.frameH)
+                    )
+                    val grid = Color.White.copy(alpha = 0.28f)
+                    for (i in 1..2) {
+                        val x = layout.frameLeft + layout.frameW * i / 3f
+                        val y = layout.frameTop + layout.frameH * i / 3f
+                        drawLine(grid, Offset(x, layout.frameTop), Offset(x, layout.frameTop + layout.frameH), 1f)
+                        drawLine(grid, Offset(layout.frameLeft, y), Offset(layout.frameLeft + layout.frameW, y), 1f)
+                    }
+                    drawRect(
+                        Color.White,
+                        topLeft = Offset(layout.frameLeft, layout.frameTop),
+                        size = Size(layout.frameW, layout.frameH),
+                        style = Stroke(width = 2.dp.toPx())
+                    )
+                }
+            }
+            Row(Modifier.fillMaxWidth().padding(top = 12.dp), verticalAlignment = Alignment.CenterVertically) {
+                TextButton(onClick = onCancel) { Text("Cancel") }
+                Spacer(Modifier.weight(1f))
+                TextButton(
+                    onClick = {
+                        val canvas = if (stage.width > 1f && stage.height > 1f) {
+                            stage
+                        } else {
+                            Size(760f, 400f)
+                        }
+                        val out = cropToAspect(image, aspect, zoom, pan, canvas)
+                        if (out != null) onCropped(out) else onCancel()
+                    }
+                ) { Text("Use photo") }
+            }
+        }
+    }
+}
+
+private data class CropLayout(
+    val frameLeft: Float,
+    val frameTop: Float,
+    val frameW: Float,
+    val frameH: Float,
+    val drawLeft: Float,
+    val drawTop: Float,
+    val drawW: Float,
+    val drawH: Float,
+    val cover: Float,
+    val panX: Float,
+    val panY: Float
+)
+
+private fun cropLayout(
+    canvas: Size,
+    imgWpx: Int,
+    imgHpx: Int,
+    aspect: Float,
+    zoom: Float,
+    pan: Offset
+): CropLayout {
+    val maxW = canvas.width * 0.9f
+    val maxH = canvas.height * 0.88f
+    val ratio = aspect.coerceAtLeast(0.2f)
+    val (frameW, frameH) = if (maxW / maxH > ratio) {
+        maxH * ratio to maxH
+    } else {
+        maxW to maxW / ratio
+    }
+    val frameLeft = (canvas.width - frameW) / 2f
+    val frameTop = (canvas.height - frameH) / 2f
+    val imgW = imgWpx.toFloat()
+    val imgH = imgHpx.toFloat()
+    val cover = max(frameW / imgW, frameH / imgH) * zoom.coerceAtLeast(1f)
+    val drawW = imgW * cover
+    val drawH = imgH * cover
+    val maxPanX = max(0f, (drawW - frameW) / 2f)
+    val maxPanY = max(0f, (drawH - frameH) / 2f)
+    val px = pan.x.coerceIn(-maxPanX, maxPanX)
+    val py = pan.y.coerceIn(-maxPanY, maxPanY)
+    val drawLeft = frameLeft + (frameW - drawW) / 2f + px
+    val drawTop = frameTop + (frameH - drawH) / 2f + py
+    return CropLayout(frameLeft, frameTop, frameW, frameH, drawLeft, drawTop, drawW, drawH, cover, px, py)
+}
+
+internal fun cropToAspect(
+    src: BufferedImage,
+    aspect: Float,
+    zoom: Float,
+    pan: Offset,
+    canvas: Size,
+    longEdge: Int = 1536
+): File? {
+    if (canvas.width <= 1f || canvas.height <= 1f) return null
+    val layout = cropLayout(canvas, src.width, src.height, aspect.coerceAtLeast(0.2f), zoom, pan)
+    val left = (layout.drawW - layout.frameW) / 2f - layout.panX
+    val top = (layout.drawH - layout.frameH) / 2f - layout.panY
+    val srcX = (left / layout.cover).toInt().coerceIn(0, src.width - 1)
+    val srcY = (top / layout.cover).toInt().coerceIn(0, src.height - 1)
+    val srcW = (layout.frameW / layout.cover).toInt().coerceAtLeast(1).coerceAtMost(src.width - srcX)
+    val srcH = (layout.frameH / layout.cover).toInt().coerceAtLeast(1).coerceAtMost(src.height - srcY)
+    val cropped = src.getSubimage(srcX, srcY, srcW, srcH)
+    val ratio = aspect.coerceAtLeast(0.2f)
+    val outW = if (ratio >= 1f) longEdge else (longEdge * ratio).roundToInt().coerceAtLeast(1)
+    val outH = if (ratio >= 1f) (longEdge / ratio).roundToInt().coerceAtLeast(1) else longEdge
+    val dest = BufferedImage(outW, outH, BufferedImage.TYPE_INT_RGB)
+    val g = dest.createGraphics()
+    g.setRenderingHint(RenderingHints.KEY_INTERPOLATION, RenderingHints.VALUE_INTERPOLATION_BILINEAR)
+    g.drawImage(cropped, 0, 0, outW, outH, null)
+    g.dispose()
+    val out = File.createTempFile("yuri-crop-", ".jpg")
+    ImageIO.write(dest, "jpg", out)
+    return out
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/MetadataEditDialog.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/MetadataEditDialog.kt
new file mode 100644
index 00000000..dd0ef1af
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/MetadataEditDialog.kt
@@ -0,0 +1,226 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import capital.yuri.yuriplayer.components.model.AlbumPageModel
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.desktop.TagWriter
+import java.io.File
+
+@Composable
+fun EditSongDialog(
+    track: Song,
+    onDismiss: () -> Unit,
+    onSaved: (Song) -> Unit
+) {
+    val file = track.path?.let { File(it) }
+    val writable = file != null && file.isFile && file.canWrite()
+    var title by remember(track.songKey) { mutableStateOf(track.title.orEmpty()) }
+    var artist by remember(track.songKey) { mutableStateOf(track.artist.orEmpty()) }
+    var genre by remember(track.songKey) { mutableStateOf(track.genre.orEmpty()) }
+    var coverFile by remember { mutableStateOf<File?>(null) }
+    var cropSource by remember { mutableStateOf<File?>(null) }
+    var error by remember { mutableStateOf<String?>(null) }
+
+    cropSource?.let { src ->
+        ImageCropDialog(
+            source = src,
+            title = "Crop cover",
+            onCancel = { cropSource = null },
+            onCropped = {
+                coverFile = it
+                cropSource = null
+            }
+        )
+    }
+
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.size(480.dp, 520.dp)) {
+        Surface {
+            Column(Modifier.padding(20.dp)) {
+                Text("Edit song", style = MaterialTheme.typography.titleLarge)
+                if (!writable) {
+                    Text(
+                        "This file isn’t writable (remote or read-only).",
+                        color = MaterialTheme.colorScheme.error,
+                        style = MaterialTheme.typography.bodySmall,
+                        modifier = Modifier.padding(top = 8.dp)
+                    )
+                }
+                CoverArt(
+                    model = coverFile?.toURI()?.toString() ?: track.albumArtUri,
+                    size = 96.dp,
+                    corner = 8.dp,
+                    modifier = Modifier.padding(vertical = 12.dp)
+                )
+                TextButton(
+                    onClick = { cropSource = DesktopFiles.pickImage() },
+                    enabled = writable
+                ) { Text("Change cover") }
+                OutlinedTextField(title, { title = it }, label = { Text("Title") }, modifier = Modifier.fillMaxWidth())
+                Spacer(Modifier.height(8.dp))
+                OutlinedTextField(artist, { artist = it }, label = { Text("Artist") }, modifier = Modifier.fillMaxWidth())
+                Spacer(Modifier.height(8.dp))
+                OutlinedTextField(genre, { genre = it }, label = { Text("Genre") }, modifier = Modifier.fillMaxWidth())
+                error?.let {
+                    Text(it, color = MaterialTheme.colorScheme.error, modifier = Modifier.padding(top = 8.dp))
+                }
+                Spacer(Modifier.weight(1f))
+                Row {
+                    TextButton(onClick = onDismiss) { Text("Cancel") }
+                    Spacer(Modifier.weight(1f))
+                    TextButton(
+                        enabled = writable,
+                        onClick = {
+                            val f = file ?: return@TextButton
+                            val result = TagWriter.write(
+                                f,
+                                TagWriter.SongEdit(
+                                    title = title.ifBlank { null },
+                                    artist = artist.ifBlank { null },
+                                    genre = genre.ifBlank { null }
+                                ),
+                                coverJpeg = coverFile?.readBytes()
+                            )
+                            result.fold(
+                                onSuccess = {
+                                    onSaved(
+                                        track.copy(
+                                            title = title.ifBlank { track.title },
+                                            artist = artist.ifBlank { track.artist },
+                                            genre = genre.ifBlank { track.genre },
+                                            albumArtUri = coverFile?.toURI()?.toString() ?: track.albumArtUri
+                                        )
+                                    )
+                                    onDismiss()
+                                },
+                                onFailure = { error = it.message ?: "Couldn’t save tags" }
+                            )
+                        }
+                    ) { Text("Save") }
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun EditAlbumDialog(
+    album: AlbumPageModel,
+    tracks: List<Song>,
+    onDismiss: () -> Unit,
+    onSaved: (List<Song>) -> Unit
+) {
+    val writable = tracks.mapNotNull { it.path?.let { p -> File(p) } }.any { it.isFile && it.canWrite() }
+    var title by remember(album.id) { mutableStateOf(album.title) }
+    var artist by remember(album.id) { mutableStateOf(album.artist) }
+    var year by remember(album.id) { mutableStateOf(album.year?.toString().orEmpty()) }
+    var genre by remember(album.id) { mutableStateOf(tracks.firstOrNull()?.genre.orEmpty()) }
+    var coverFile by remember { mutableStateOf<File?>(null) }
+    var cropSource by remember { mutableStateOf<File?>(null) }
+    var error by remember { mutableStateOf<String?>(null) }
+
+    cropSource?.let { src ->
+        ImageCropDialog(
+            source = src,
+            onCancel = { cropSource = null },
+            onCropped = {
+                coverFile = it
+                cropSource = null
+            }
+        )
+    }
+
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.size(480.dp, 560.dp)) {
+        Surface {
+            Column(Modifier.padding(20.dp)) {
+                Text("Edit album", style = MaterialTheme.typography.titleLarge)
+                CoverArt(
+                    model = coverFile?.toURI()?.toString() ?: album.artworkUri,
+                    size = 96.dp,
+                    corner = 8.dp,
+                    modifier = Modifier.padding(vertical = 12.dp)
+                )
+                TextButton(
+                    onClick = { cropSource = DesktopFiles.pickImage() },
+                    enabled = writable
+                ) { Text("Change cover") }
+                OutlinedTextField(title, { title = it }, label = { Text("Album") }, modifier = Modifier.fillMaxWidth())
+                Spacer(Modifier.height(8.dp))
+                OutlinedTextField(artist, { artist = it }, label = { Text("Album artist") }, modifier = Modifier.fillMaxWidth())
+                Spacer(Modifier.height(8.dp))
+                OutlinedTextField(year, { year = it }, label = { Text("Year") }, modifier = Modifier.fillMaxWidth())
+                Spacer(Modifier.height(8.dp))
+                OutlinedTextField(genre, { genre = it }, label = { Text("Genre") }, modifier = Modifier.fillMaxWidth())
+                error?.let {
+                    Text(it, color = MaterialTheme.colorScheme.error, modifier = Modifier.padding(top = 8.dp))
+                }
+                Spacer(Modifier.weight(1f))
+                Row {
+                    TextButton(onClick = onDismiss) { Text("Cancel") }
+                    Spacer(Modifier.width(8.dp))
+                    TextButton(
+                        enabled = writable,
+                        onClick = {
+                            val coverBytes = coverFile?.readBytes()
+                            val yearInt = year.toIntOrNull()
+                            val updated = ArrayList<Song>()
+                            var failed = 0
+                            tracks.forEach { t ->
+                                val f = t.path?.let { File(it) }
+                                if (f == null || !f.canWrite()) {
+                                    failed++
+                                    updated += t
+                                    return@forEach
+                                }
+                                val result = TagWriter.write(
+                                    f,
+                                    TagWriter.SongEdit(
+                                        album = title.ifBlank { null },
+                                        albumArtist = artist.ifBlank { null },
+                                        year = yearInt,
+                                        genre = genre.ifBlank { null }
+                                    ),
+                                    coverJpeg = coverBytes
+                                )
+                                if (result.isFailure) failed++
+                                updated += t.copy(
+                                    album = title.ifBlank { t.album },
+                                    albumArtist = artist.ifBlank { t.albumArtist },
+                                    year = yearInt ?: t.year,
+                                    genre = genre.ifBlank { t.genre },
+                                    albumArtUri = coverFile?.toURI()?.toString() ?: t.albumArtUri
+                                )
+                            }
+                            if (failed == tracks.size) {
+                                error = "Couldn’t write tags on these files"
+                            } else {
+                                onSaved(updated)
+                                onDismiss()
+                            }
+                        }
+                    ) { Text("Save") }
+                }
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/PlaylistPage.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/PlaylistPage.kt
new file mode 100644
index 00000000..490d47fd
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/PlaylistPage.kt
@@ -0,0 +1,431 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.gestures.detectDragGesturesAfterLongPress
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.filled.Add
+import androidx.compose.material.icons.filled.Edit
+import androidx.compose.material.icons.filled.Lock
+import androidx.compose.material.icons.filled.Pause
+import androidx.compose.material.icons.filled.PlayArrow
+import androidx.compose.material3.Checkbox
+import androidx.compose.material3.FilledIconButton
+import androidx.compose.material3.Icon
+import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedTextField
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.input.pointer.pointerInput
+import androidx.compose.ui.platform.LocalDensity
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import kotlin.math.roundToInt
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import capital.yuri.yuriplayer.components.list.LikeHeart
+import capital.yuri.yuriplayer.components.list.TrackRow
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.model.toRow
+import capital.yuri.yuriplayer.core.library.matchesQuery
+import capital.yuri.yuriplayer.core.library.playlistKeys
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.desktop.DesktopCover
+import capital.yuri.yuriplayer.desktop.DesktopPlaylist
+import capital.yuri.yuriplayer.desktop.DesktopPlaylistStore
+import java.io.File
+
+@Composable
+fun PlaylistPage(
+    playlist: DesktopPlaylist,
+    tracks: List<Song>,
+    library: List<Song>,
+    currentId: String?,
+    playing: Boolean = false,
+    store: DesktopPlaylistStore,
+    onBack: () -> Unit,
+    onPlay: (List<Song>, Int) -> Unit,
+    onEditTrack: (Song) -> Unit,
+    likedIds: Set<String> = emptySet(),
+    onToggleLike: (String) -> Unit = {},
+    playlistLiked: Boolean = false,
+    onTogglePlaylistLike: () -> Unit = {},
+    songMenu: (Song) -> List<out MenuEntry> = { emptyList() }
+) {
+    var name by remember(playlist.id, playlist.updatedAtMs) { mutableStateOf(playlist.name) }
+    var description by remember(playlist.id, playlist.updatedAtMs) {
+        mutableStateOf(playlist.description.orEmpty())
+    }
+    var editing by remember { mutableStateOf(false) }
+    var showCovers by remember { mutableStateOf(false) }
+    var showAdd by remember { mutableStateOf(false) }
+    var cropSource by remember { mutableStateOf<File?>(null) }
+    var cropSecret by remember { mutableStateOf(false) }
+    val art = playlist.artworkUri(tracks)
+
+    cropSource?.let { src ->
+        ImageCropDialog(
+            source = src,
+            title = if (cropSecret) "Crop secret cover" else "Crop cover",
+            onCancel = { cropSource = null },
+            onCropped = { cropped ->
+                store.addCover(playlist.id, cropped, isSecret = cropSecret, makeActive = !cropSecret)
+                cropSource = null
+            }
+        )
+    }
+
+    Column(Modifier.fillMaxSize().padding(24.dp)) {
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            IconButton(onClick = onBack) {
+                Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "Back")
+            }
+            Spacer(Modifier.weight(1f))
+            IconButton(onClick = { editing = !editing }) {
+                Icon(Icons.Default.Edit, contentDescription = "Edit playlist")
+            }
+        }
+        Row(Modifier.fillMaxWidth().padding(top = 8.dp)) {
+            Box(
+                Modifier
+                    .size(220.dp)
+                    .clip(RoundedCornerShape(12.dp))
+                    .clickable { showCovers = true }
+            ) {
+                CoverArt(model = art, modifier = Modifier.fillMaxSize(), corner = 12.dp)
+            }
+            Column(Modifier.weight(1f).padding(start = 24.dp)) {
+                if (editing) {
+                    OutlinedTextField(
+                        value = name,
+                        onValueChange = { name = it },
+                        label = { Text("Name") },
+                        singleLine = true,
+                        modifier = Modifier.fillMaxWidth()
+                    )
+                    OutlinedTextField(
+                        value = description,
+                        onValueChange = { description = it },
+                        label = { Text("Description") },
+                        modifier = Modifier.fillMaxWidth().padding(top = 8.dp)
+                    )
+                    Row(Modifier.padding(top = 8.dp)) {
+                        TextButton(onClick = {
+                            store.rename(playlist.id, name, description)
+                            editing = false
+                        }) { Text("Save") }
+                        TextButton(onClick = {
+                            name = playlist.name
+                            description = playlist.description.orEmpty()
+                            editing = false
+                        }) { Text("Cancel") }
+                    }
+                } else {
+                    Text(playlist.name, style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold)
+                    if (!playlist.description.isNullOrBlank()) {
+                        Text(
+                            playlist.description,
+                            style = MaterialTheme.typography.bodyMedium,
+                            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f),
+                            modifier = Modifier.padding(top = 6.dp)
+                        )
+                    }
+                    Text(
+                        "${tracks.size} songs",
+                        style = MaterialTheme.typography.bodySmall,
+                        color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.5f),
+                        modifier = Modifier.padding(top = 8.dp)
+                    )
+                }
+                Row(
+                    Modifier.padding(top = 16.dp),
+                    verticalAlignment = Alignment.CenterVertically
+                ) {
+                    FilledIconButton(
+                        onClick = { if (tracks.isNotEmpty()) onPlay(tracks, 0) }
+                    ) {
+                        Icon(
+                            if (playing) Icons.Default.Pause else Icons.Default.PlayArrow,
+                            contentDescription = if (playing) "Pause" else "Play"
+                        )
+                    }
+                    LikeHeart(liked = playlistLiked, onToggle = onTogglePlaylistLike)
+                    TextButton(onClick = { showAdd = true }) { Text("Add songs") }
+                }
+            }
+        }
+        Spacer(Modifier.height(16.dp))
+        val density = LocalDensity.current
+        val rowPx = with(density) { 64.dp.toPx() }
+        LazyColumn(Modifier.weight(1f)) {
+            itemsIndexed(tracks, key = { i, t -> "${t.songKey}#$i" }) { index, track ->
+                TrackRow(
+                    track = track.toRow(highlighted = track.songKey == currentId),
+                    onClick = { onPlay(tracks, index) },
+                    onLongClick = { onEditTrack(track) },
+                    showCover = true,
+                    showAlbum = true,
+                    liked = track.songKey in likedIds,
+                    onToggleLike = { onToggleLike(track.songKey) },
+                    contextItems = songMenu(track),
+                    modifier = Modifier.pointerInput(tracks, playlist.id) {
+                        var from: Int? = null
+                        var dy = 0f
+                        detectDragGesturesAfterLongPress(
+                            onDragStart = {
+                                from = index
+                                dy = 0f
+                            },
+                            onDrag = { change, drag ->
+                                change.consume()
+                                dy += drag.y
+                            },
+                            onDragEnd = {
+                                val start = from ?: return@detectDragGesturesAfterLongPress
+                                val to = (start + (dy / rowPx).roundToInt())
+                                    .coerceIn(0, tracks.lastIndex)
+                                if (start != to) store.moveTrack(playlist.id, start, to)
+                                from = null
+                            },
+                            onDragCancel = { from = null }
+                        )
+                    }
+                )
+            }
+        }
+    }
+
+    if (showAdd) {
+        AddSongsDialog(
+            library = library,
+            existing = (playlist.trackIds + playlist.tracks(library).flatMap { it.playlistKeys() }).toSet(),
+            onDismiss = { showAdd = false },
+            onAdd = { added ->
+                store.addTracks(playlist.id, added)
+                showAdd = false
+            }
+        )
+    }
+
+    if (showCovers) {
+        CoverManagerDialog(
+            playlist = playlist,
+            store = store,
+            onDismiss = { showCovers = false },
+            onPick = { secret ->
+                val file = DesktopFiles.pickImage(if (secret) "Secret cover" else "Playlist cover")
+                if (file != null) {
+                    cropSecret = secret
+                    cropSource = file
+                    showCovers = false
+                }
+            }
+        )
+    }
+}
+
+@Composable
+private fun AddSongsDialog(
+    library: List<Song>,
+    existing: Set<String>,
+    onDismiss: () -> Unit,
+    onAdd: (List<Song>) -> Unit
+) {
+    var query by remember { mutableStateOf("") }
+    val hits = remember(query, library) {
+        val q = query.trim()
+        if (q.isEmpty()) library.take(40)
+        else library.filter { it.matchesQuery(q) }.take(40)
+    }
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.size(520.dp, 560.dp)) {
+        Surface {
+            Column(Modifier.padding(16.dp)) {
+                OutlinedTextField(
+                    value = query,
+                    onValueChange = { query = it },
+                    label = { Text("Search library") },
+                    modifier = Modifier.fillMaxWidth(),
+                    singleLine = true
+                )
+                LazyColumn(Modifier.weight(1f).padding(top = 8.dp)) {
+                    itemsIndexed(hits, key = { _, t -> t.songKey }) { _, track ->
+                        val inPl = track.playlistKeys().any { it in existing }
+                        TrackRow(
+                            track = track.toRow(),
+                            onClick = { if (!inPl) onAdd(listOf(track)) },
+                            showCover = true,
+                            showAlbum = true
+                        )
+                    }
+                }
+                TextButton(onClick = onDismiss, modifier = Modifier.align(Alignment.End)) { Text("Done") }
+            }
+        }
+    }
+}
+
+@Composable
+private fun CoverManagerDialog(
+    playlist: DesktopPlaylist,
+    store: DesktopPlaylistStore,
+    onDismiss: () -> Unit,
+    onPick: (secret: Boolean) -> Unit
+) {
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.size(560.dp, 420.dp)) {
+        Surface {
+            Column(Modifier.fillMaxSize().padding(20.dp)) {
+                Text("Covers", style = MaterialTheme.typography.titleLarge, fontWeight = FontWeight.Bold)
+                Text(
+                    "Secret covers stay off the public slot after you quit.",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                    modifier = Modifier.padding(bottom = 12.dp)
+                )
+                LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                    itemsIndexed(playlist.covers) { _, cover ->
+                        CoverSlotCard(
+                            cover = cover,
+                            active = cover.id == playlist.activeCoverId,
+                            onActivate = { store.setActiveCover(playlist.id, cover.id) },
+                            onSecret = { store.setCoverSecret(playlist.id, cover.id, !cover.isSecret) },
+                            onDelete = { store.removeCover(playlist.id, cover.id) }
+                        )
+                    }
+                    item {
+                        AddCoverChip("Public") { onPick(false) }
+                    }
+                    item {
+                        AddCoverChip("Secret") { onPick(true) }
+                    }
+                }
+                Spacer(Modifier.weight(1f))
+                TextButton(onClick = onDismiss, modifier = Modifier.align(Alignment.End)) { Text("Done") }
+            }
+        }
+    }
+}
+
+@Composable
+private fun CoverSlotCard(
+    cover: DesktopCover,
+    active: Boolean,
+    onActivate: () -> Unit,
+    onSecret: () -> Unit,
+    onDelete: () -> Unit
+) {
+    Column(horizontalAlignment = Alignment.CenterHorizontally, modifier = Modifier.width(120.dp)) {
+        Box(
+            Modifier
+                .size(112.dp)
+                .clip(RoundedCornerShape(10.dp))
+                .clickable(onClick = onActivate)
+        ) {
+            CoverArt(
+                model = File(cover.path).toURI().toString(),
+                modifier = Modifier.fillMaxSize(),
+                corner = 10.dp
+            )
+            if (cover.isSecret) {
+                Icon(
+                    Icons.Default.Lock,
+                    contentDescription = "Secret",
+                    tint = MaterialTheme.colorScheme.onSurface,
+                    modifier = Modifier
+                        .align(Alignment.TopEnd)
+                        .padding(6.dp)
+                        .size(18.dp)
+                )
+            }
+            if (active) {
+                Box(
+                    Modifier
+                        .matchParentSize()
+                        .background(MaterialTheme.colorScheme.primary.copy(alpha = 0.18f))
+                )
+            }
+        }
+        Row(verticalAlignment = Alignment.CenterVertically) {
+            Checkbox(checked = cover.isSecret, onCheckedChange = { onSecret() })
+            Text("Secret", style = MaterialTheme.typography.labelSmall)
+        }
+        TextButton(onClick = onDelete) { Text("Remove") }
+    }
+}
+
+@Composable
+private fun AddCoverChip(label: String, onClick: () -> Unit) {
+    Column(
+        Modifier
+            .size(112.dp)
+            .clip(RoundedCornerShape(10.dp))
+            .background(MaterialTheme.colorScheme.surfaceVariant)
+            .clickable(onClick = onClick),
+        verticalArrangement = Arrangement.Center,
+        horizontalAlignment = Alignment.CenterHorizontally
+    ) {
+        Icon(Icons.Default.Add, contentDescription = null)
+        Text(label, style = MaterialTheme.typography.labelMedium)
+    }
+}
+
+@Composable
+fun NewPlaylistDialog(
+    onDismiss: () -> Unit,
+    onCreate: (name: String, description: String?) -> Unit
+) {
+    var name by remember { mutableStateOf("") }
+    var description by remember { mutableStateOf("") }
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.size(420.dp, 280.dp)) {
+        Surface {
+            Column(Modifier.padding(20.dp)) {
+                Text("New playlist", style = MaterialTheme.typography.titleLarge, fontWeight = FontWeight.Bold)
+                OutlinedTextField(
+                    value = name,
+                    onValueChange = { name = it },
+                    label = { Text("Name") },
+                    singleLine = true,
+                    modifier = Modifier.fillMaxWidth().padding(top = 12.dp)
+                )
+                OutlinedTextField(
+                    value = description,
+                    onValueChange = { description = it },
+                    label = { Text("Description") },
+                    modifier = Modifier.fillMaxWidth().padding(top = 8.dp)
+                )
+                Row(Modifier.fillMaxWidth().padding(top = 16.dp), horizontalArrangement = Arrangement.End) {
+                    TextButton(onClick = onDismiss) { Text("Cancel") }
+                    TextButton(
+                        onClick = { onCreate(name, description.takeIf { it.isNotBlank() }) },
+                        enabled = name.isNotBlank()
+                    ) { Text("Create") }
+                }
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/SourcesPickerDialog.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/SourcesPickerDialog.kt
new file mode 100644
index 00000000..7151d899
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/SourcesPickerDialog.kt
@@ -0,0 +1,146 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Check
+import androidx.compose.material.icons.filled.Cloud
+import androidx.compose.material.icons.filled.Lock
+import androidx.compose.material.icons.filled.SdStorage
+import androidx.compose.material3.HorizontalDivider
+import androidx.compose.material3.Icon
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.dialog.InWindowPanel
+import capital.yuri.yuriplayer.core.source.RemoteAccount
+import capital.yuri.yuriplayer.core.source.SourceKind
+import capital.yuri.yuriplayer.core.library.LocalLibraryScanner
+import capital.yuri.yuriplayer.data.Song
+
+data class SourceChoice(
+    val track: Song,
+    val label: String,
+    val typeLabel: String,
+    val writable: Boolean,
+    val preferred: Boolean
+)
+
+fun sourceChoices(
+    sources: List<Song>,
+    remotes: List<RemoteAccount>,
+    preferredId: String?
+): List<SourceChoice> {
+    val byId = remotes.associateBy { it.id }
+    return sources.map { t ->
+        val remote = t.sourceId?.let { byId[it] }
+        val local = t.sourceId == LocalLibraryScanner.SOURCE_LOCAL || t.contentUri.startsWith("file:")
+        val writable = local
+        val typeLabel = when {
+            local -> "Local"
+            remote?.kind == SourceKind.JELLYFIN -> "Jellyfin"
+            remote?.kind == SourceKind.SUBSONIC -> "Navidrome"
+            t.songKey.startsWith("jellyfin:") -> "Jellyfin"
+            t.songKey.startsWith("subsonic:") || t.songKey.startsWith("navidrome:") -> "Subsonic"
+            else -> "Source"
+        }
+        val label = when {
+            local -> "On this device"
+            remote != null && remote.name.isNotBlank() -> remote.name
+            else -> typeLabel
+        }
+        SourceChoice(
+            track = t,
+            label = label,
+            typeLabel = typeLabel,
+            writable = writable,
+            preferred = preferredId != null && (t.songKey == preferredId || t.sourceId == preferredId)
+        )
+    }
+}
+
+@Composable
+fun SourcesPickerDialog(
+    title: String,
+    choices: List<SourceChoice>,
+    onDismiss: () -> Unit,
+    onPick: (Song) -> Unit
+) {
+    InWindowPanel(onDismiss = onDismiss, modifier = Modifier.width(420.dp).height(480.dp)) {
+        Column(Modifier.fillMaxSize().padding(20.dp)) {
+            Text("Sources", style = MaterialTheme.typography.titleLarge, fontWeight = FontWeight.Bold)
+            Text(
+                title,
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                modifier = Modifier.padding(top = 4.dp)
+            )
+            Text(
+                "Tap a source to prefer it for playback.",
+                style = MaterialTheme.typography.bodySmall,
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.45f),
+                modifier = Modifier.padding(top = 4.dp, bottom = 8.dp)
+            )
+            HorizontalDivider()
+            LazyColumn(Modifier.weight(1f).padding(top = 8.dp)) {
+                items(choices, key = { it.track.songKey }) { c ->
+                    Row(
+                        Modifier
+                            .fillMaxWidth()
+                            .clickable { onPick(c.track) }
+                            .padding(vertical = 12.dp),
+                        verticalAlignment = Alignment.CenterVertically
+                    ) {
+                        Icon(
+                            imageVector = when {
+                                !c.writable -> Icons.Default.Lock
+                                c.writable && c.typeLabel == "Local" -> Icons.Default.SdStorage
+                                else -> Icons.Default.Cloud
+                            },
+                            contentDescription = null,
+                            modifier = Modifier.size(22.dp),
+                            tint = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f)
+                        )
+                        Spacer(Modifier.width(14.dp))
+                        Column(Modifier.weight(1f)) {
+                            Text(
+                                c.label,
+                                fontWeight = if (c.preferred) FontWeight.SemiBold else FontWeight.Normal
+                            )
+                            Text(
+                                "${c.typeLabel} · ${if (c.writable) "Writable" else "Read-only"}",
+                                style = MaterialTheme.typography.bodySmall,
+                                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+                            )
+                        }
+                        if (c.preferred) {
+                            Icon(
+                                Icons.Default.Check,
+                                contentDescription = "Preferred",
+                                tint = MaterialTheme.colorScheme.primary
+                            )
+                        }
+                    }
+                }
+            }
+            TextButton(onClick = onDismiss, modifier = Modifier.align(Alignment.End)) {
+                Text("Done")
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/YuriDesktopApp.kt b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/YuriDesktopApp.kt
new file mode 100644
index 00000000..f7faea24
--- /dev/null
+++ b/desktop/src/main/kotlin/capital/yuri/yuriplayer/desktop/ui/YuriDesktopApp.kt
@@ -0,0 +1,1345 @@
+package capital.yuri.yuriplayer.desktop.ui
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.PaddingValues
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.layout.width
+import androidx.compose.foundation.lazy.LazyRow
+import androidx.compose.foundation.lazy.grid.GridCells
+import androidx.compose.foundation.lazy.grid.LazyVerticalGrid
+import androidx.compose.foundation.lazy.grid.items
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.FilterChip
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.collectAsState
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableIntStateOf
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.rememberCoroutineScope
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.text.style.TextOverflow
+import androidx.compose.ui.unit.dp
+import capital.yuri.yuriplayer.components.album.AlbumPage
+import capital.yuri.yuriplayer.components.art.CoverArt
+import capital.yuri.yuriplayer.components.artist.ArtistPage
+import capital.yuri.yuriplayer.components.layout.DesktopBentoLayout
+import capital.yuri.yuriplayer.components.layout.DesktopNav
+import capital.yuri.yuriplayer.components.layout.LibraryFilter
+import capital.yuri.yuriplayer.components.layout.LibraryRailItem
+import capital.yuri.yuriplayer.components.list.AlbumCard
+import capital.yuri.yuriplayer.components.list.ContextAction
+import capital.yuri.yuriplayer.components.list.ContextMenuAnchor
+import capital.yuri.yuriplayer.components.menu.ContextMenuScope
+import capital.yuri.yuriplayer.components.menu.MenuEntry
+import capital.yuri.yuriplayer.components.menu.buildContextMenu
+import capital.yuri.yuriplayer.components.model.AlbumPageModel
+import capital.yuri.yuriplayer.components.model.TrackRowModel
+import capital.yuri.yuriplayer.components.model.albums
+import capital.yuri.yuriplayer.components.model.artistPage
+import capital.yuri.yuriplayer.components.model.toCover
+import capital.yuri.yuriplayer.components.model.toRow
+import capital.yuri.yuriplayer.components.player.BottomPlayerBar
+import capital.yuri.yuriplayer.components.player.NowPlayingSidebar
+import capital.yuri.yuriplayer.components.theme.PlayerChromeTheme
+import capital.yuri.yuriplayer.components.theme.YuriTheme
+import capital.yuri.yuriplayer.components.theme.playerColorsFromPixels
+import capital.yuri.yuriplayer.core.artist.ArtistProfile
+import capital.yuri.yuriplayer.core.library.albumPageIdentity
+import capital.yuri.yuriplayer.core.library.catalogKey
+import capital.yuri.yuriplayer.core.library.pickPreferred
+import capital.yuri.yuriplayer.core.library.sourceRank
+import capital.yuri.yuriplayer.core.player.ColdSource
+import capital.yuri.yuriplayer.core.player.ColdSourceType
+import capital.yuri.yuriplayer.data.Song
+import capital.yuri.yuriplayer.desktop.DesktopCollection
+import capital.yuri.yuriplayer.desktop.DesktopSession
+import kotlinx.coroutines.launch
+
+private sealed class Route {
+    data object Home : Route()
+    data object Search : Route()
+    data class Album(val album: AlbumPageModel) : Route()
+    data class Playlist(val id: String) : Route()
+    data class Artist(val name: String) : Route()
+    data object MyStuff : Route()
+}
+
+@Composable
+fun YuriDesktopApp(session: DesktopSession) {
+    val coverPixels by session.coverPixels.collectAsState()
+    val playerColors = remember(coverPixels) {
+        coverPixels?.let { playerColorsFromPixels(it) }
+    }
+    val themeChoice by session.theme.choice.collectAsState()
+    YuriTheme(choice = themeChoice) {
+        val tracks by session.tracks.collectAsState()
+        val current by session.player.current.collectAsState()
+        val playing by session.player.isPlaying.collectAsState()
+        val history by session.player.history.collectAsState()
+        val status by session.scanMessage.collectAsState()
+        val position by session.positionMs.collectAsState()
+        val duration by session.durationMs.collectAsState()
+        val engineMessage by session.engineMessage.collectAsState()
+        val online by session.network.isOnline.collectAsState()
+        val shuffle by session.player.shuffle.collectAsState()
+        val repeat by session.player.repeat.collectAsState()
+        val volume by session.player.volume.collectAsState()
+        val liked by session.collection.liked.collectAsState()
+        val pins by session.collection.pinned.collectAsState()
+        val saved by session.collection.saved.collectAsState()
+        val hotQueue by session.player.hotQueue.collectAsState()
+        val coldQueue by session.player.coldQueue.collectAsState()
+        val coldSource by session.player.coldSource.collectAsState()
+        val playlists by session.playlists.playlists.collectAsState()
+        val remotes by session.sources.remotes.collectAsState()
+        val leftFrac by session.layout.leftFraction.collectAsState()
+        val rightFrac by session.layout.rightFraction.collectAsState()
+        var prefRev by remember { mutableIntStateOf(0) }
+        val albums = remember(tracks, prefRev) { tracks.albums(session.sourcePrefs.snapshot()) }
+        var stack by remember { mutableStateOf(listOf<Route>(Route.Home)) }
+        var forward by remember { mutableStateOf(listOf<Route>()) }
+        var query by remember { mutableStateOf("") }
+        var libraryFilter by remember { mutableStateOf(LibraryFilter.Playlists) }
+        var showSettings by remember { mutableStateOf(false) }
+        var showNewPlaylist by remember { mutableStateOf(false) }
+        var showSidebar by remember { mutableStateOf(true) }
+        var editSong by remember { mutableStateOf<Song?>(null) }
+        var editAlbum by remember { mutableStateOf<AlbumPageModel?>(null) }
+        var addToPlaylist by remember { mutableStateOf<List<Song>?>(null) }
+        var sourcesFor by remember { mutableStateOf<List<Song>?>(null) }
+        val route = stack.last()
+        val nav = if (route is Route.Search) DesktopNav.Search else DesktopNav.Home
+        val scope = rememberCoroutineScope()
+
+        fun push(next: Route) {
+            stack = stack + next
+            forward = emptyList()
+        }
+
+        fun goBack() {
+            if (stack.size > 1) {
+                forward = listOf(stack.last()) + forward
+                stack = stack.dropLast(1)
+            }
+        }
+
+        fun goForward() {
+            val n = forward.firstOrNull() ?: return
+            forward = forward.drop(1)
+            stack = stack + n
+        }
+
+        fun openAlbum(album: AlbumPageModel) = push(Route.Album(album))
+        fun openArtist(name: String) = push(Route.Artist(name))
+
+        fun playlistAddAlternate(songs: List<Song>): ContextMenuScope.() -> Unit = {
+            val candidates = playlists
+                .filter { pl ->
+                    songs.any { t -> pl.orderedEntries().none { e -> e.matches(t) } }
+                }
+                .sortedBy { it.name.lowercase() }
+            if (candidates.isEmpty()) {
+                item("Already in every playlist", enabled = false) {}
+            } else {
+                candidates.forEach { pl ->
+                    item(pl.name) {
+                        session.ensureTracks(songs)
+                        session.playlists.addTracks(pl.id, songs)
+                    }
+                }
+            }
+        }
+
+        fun songMenu(
+            track: Song,
+            onAlbumPage: Boolean = false,
+            playlistId: String? = null
+        ): List<MenuEntry> = buildContextMenu {
+            item("Add to playlist", alternate = playlistAddAlternate(listOf(track))) {
+                addToPlaylist = listOf(track)
+            }
+            item("Add to queue") { session.player.enqueue(track) }
+            item("Sources") {
+                val ids = HashSet<String>()
+                ids += track.songKey
+                ids += track.catalogKey()
+                val row = albums.asSequence()
+                    .mapNotNull { a -> a.tracks.firstOrNull { track.songKey in it.sourceIds || it.id == track.songKey } }
+                    .firstOrNull()
+                if (row != null) ids += row.sourceIds
+                val want = ids
+                sourcesFor = tracks.asSequence()
+                    .filter { it.songKey in want || it.catalogKey() in want }
+                    .distinctBy { it.songKey }
+                    .take(16)
+                    .toList()
+                    .ifEmpty { listOf(track) }
+            }
+            submenu("Go to") {
+                if (!onAlbumPage) {
+                    item("Album") {
+                        albums.firstOrNull { a ->
+                            a.tracks.any { track.songKey in it.sourceIds || it.id == track.songKey }
+                        }?.let(::openAlbum)
+                    }
+                }
+                item("Artist") { openArtist(track.displayArtist) }
+            }
+            if (playlistId != null) {
+                divider()
+                item("Remove from this playlist", destructive = true) {
+                    session.playlists.removeTracks(playlistId, listOf(track))
+                }
+            }
+        }
+
+        fun menuForQueueRow(row: TrackRowModel, pool: List<Song>): List<MenuEntry> {
+            val track = pool.firstOrNull { it.songKey == row.id } ?: Song(
+                id = 0L,
+                contentUri = "",
+                title = row.title,
+                artist = row.artist,
+                album = row.album,
+                durationMs = row.durationMs,
+                albumArtUri = row.artworkUri
+            )
+            return songMenu(track)
+        }
+
+        fun pinTracks(item: LibraryRailItem): List<Song> = when {
+            item.id == "liked" -> tracks.filter { it.songKey in liked }
+            item.id.startsWith("playlist:") -> {
+                val id = item.id.removePrefix("playlist:")
+                playlists.firstOrNull { it.id == id }?.tracks(tracks).orEmpty()
+            }
+            item.id.startsWith("artist:") || item.circular ->
+                tracks.filter {
+                    it.displayArtist.equals(item.title, true) || it.albumArtist.equals(item.title, true)
+                }
+            else -> {
+                val album = albums.firstOrNull { it.id == item.id }
+                album?.tracks?.mapNotNull { row ->
+                    val group = tracks.filter { it.songKey in row.sourceIds }
+                    pickPreferred(group, session.sourcePrefs.get(albumPageIdentity(group.firstOrNull() ?: return@mapNotNull null)))
+                }.orEmpty()
+                    .ifEmpty { tracks.filter { it.songKey == item.id }.takeIf { it.isNotEmpty() } ?: emptyList() }
+            }
+        }
+
+        val recency = remember(history) {
+            history.mapIndexed { i, t -> t.songKey to i }.toMap()
+        }
+        fun albumRecency(album: AlbumPageModel): Int =
+            album.tracks.minOfOrNull { recency[it.id] ?: Int.MAX_VALUE } ?: Int.MAX_VALUE
+
+        val libraryItems = remember(albums, tracks, libraryFilter, pins, saved, history, liked, playlists) {
+            val likedAlbums = albums.filter { album -> album.tracks.any { it.id in liked } }
+            val likedArtists = tracks.filter { it.songKey in liked }.map { it.displayArtist }.distinct()
+            val pinItems = pins.map { pin ->
+                when (pin.kind) {
+                    DesktopCollection.Kind.ALBUM -> {
+                        val album = albums.firstOrNull { it.id == pin.id }
+                            ?: albums.firstOrNull { it.title.equals(pin.title, true) }
+                        LibraryRailItem(
+                            pin.id, pin.title, pin.subtitle,
+                            album?.artworkUri, pinned = true
+                        )
+                    }
+                    DesktopCollection.Kind.ARTIST -> LibraryRailItem(
+                        pin.id, pin.title, pin.subtitle,
+                        tracks.firstOrNull { it.displayArtist.equals(pin.title, true) }?.albumArtUri,
+                        circular = true, pinned = true
+                    )
+                    DesktopCollection.Kind.SONG -> {
+                        val t = tracks.firstOrNull { it.songKey == pin.id }
+                        LibraryRailItem(
+                            pin.id, pin.title, pin.subtitle,
+                            t?.albumArtUri, pinned = true
+                        )
+                    }
+                    DesktopCollection.Kind.PLAYLIST -> {
+                        val pl = playlists.firstOrNull { it.id == pin.id }
+                        LibraryRailItem(
+                            "playlist:${pin.id}", pin.title, pin.subtitle,
+                            pl?.artworkUri(tracks), pinned = true
+                        )
+                    }
+                }
+            }
+            val likedRow = if (liked.isNotEmpty()) {
+                listOf(
+                    LibraryRailItem(
+                        id = "liked",
+                        title = "My Stuff",
+                        subtitle = "${liked.size} songs",
+                        artworkUri = null,
+                        heart = true
+                    )
+                )
+            } else emptyList()
+            val rest = when (libraryFilter) {
+                LibraryFilter.Artists -> {
+                    val names = (
+                        pins.filter { it.kind == DesktopCollection.Kind.ARTIST }.map { it.title } +
+                            saved.filter { it.kind == DesktopCollection.Kind.ARTIST }.map { it.title } +
+                            likedArtists
+                        ).distinct()
+                    names.map { name ->
+                        LibraryRailItem(
+                            "artist:$name",
+                            name,
+                            "Artist",
+                            tracks.firstOrNull { it.displayArtist.equals(name, true) }?.albumArtUri,
+                            circular = true
+                        )
+                    }
+                }
+                LibraryFilter.Albums -> {
+                    val pinnedAlbums = (
+                        pins.filter { it.kind == DesktopCollection.Kind.ALBUM } +
+                            saved.filter { it.kind == DesktopCollection.Kind.ALBUM }
+                        )
+                        .mapNotNull { pin ->
+                            albums.firstOrNull { it.id == pin.id }
+                                ?: albums.firstOrNull { it.title.equals(pin.title, true) }
+                        }
+                    (pinnedAlbums + likedAlbums).distinctBy { it.id }
+                        .map { LibraryRailItem(it.id, it.title, it.artist, it.artworkUri) }
+                }
+                LibraryFilter.Playlists -> listOf(
+                    LibraryRailItem("new-playlist", "New playlist", "Create", null)
+                ) + playlists.sortedByDescending { it.updatedAtMs }.map { pl ->
+                    LibraryRailItem(
+                        "playlist:${pl.id}",
+                        pl.name,
+                        "${pl.trackIds.size} songs",
+                        pl.artworkUri(tracks)
+                    )
+                }
+                LibraryFilter.Recents -> {
+                    val stuffAlbumIds = (
+                        pins.filter { it.kind == DesktopCollection.Kind.ALBUM }.map { it.id } +
+                            likedAlbums.map { it.id }
+                        ).toSet()
+                    buildList {
+                        history.forEach { t ->
+                            val album = albums.firstOrNull { a -> a.tracks.any { it.id == t.songKey } }
+                            if (album != null && (album.id in stuffAlbumIds || album.tracks.any { it.id in liked })) {
+                                add(LibraryRailItem(album.id, album.title, "Album · ${album.artist}", album.artworkUri))
+                            }
+                        }
+                    }.distinctBy { it.id }
+                }
+            }
+            val pinIds = pinItems.map { it.id }.toSet()
+            likedRow + pinItems + rest.filter { it.id !in pinIds && it.id !in likedRow.map { r -> r.id }.toSet() }
+        }
+        val selectedLibraryId = (route as? Route.Album)?.album?.id
+
+        DesktopBentoLayout(
+            nav = nav,
+            searchQuery = query,
+            onSearchQuery = {
+                query = it
+                if (it.isNotBlank() && route !is Route.Search) push(Route.Search)
+            },
+            onHome = { stack = listOf(Route.Home); forward = emptyList(); query = "" },
+            onBack = ::goBack,
+            onForward = ::goForward,
+            canBack = stack.size > 1,
+            canForward = forward.isNotEmpty(),
+            onSettings = { showSettings = true },
+            scanMenu = { DesktopScanMenu(session) },
+            libraryFilter = libraryFilter,
+            onLibraryFilter = { libraryFilter = it },
+            libraryItems = libraryItems,
+            selectedLibraryId = selectedLibraryId,
+            onLibraryItem = { item ->
+                when {
+                    item.id == "new-playlist" -> showNewPlaylist = true
+                    item.id == "liked" -> push(Route.MyStuff)
+                    item.id.startsWith("playlist:") -> {
+                        push(Route.Playlist(item.id.removePrefix("playlist:")))
+                    }
+                    item.id.startsWith("artist:") -> {
+                        openArtist(item.id.removePrefix("artist:").ifBlank { item.title })
+                    }
+                    item.circular -> openArtist(item.title)
+                    else -> albums.firstOrNull { it.id == item.id }?.let { openAlbum(it) }
+                }
+            },
+            libraryMenu = { item ->
+                if (item.id == "new-playlist") {
+                    emptyList()
+                } else {
+                    val playable = pinTracks(item)
+                    buildList {
+                        if (playable.isNotEmpty()) {
+                            add(ContextAction("Play") { session.player.play(playable, 0) })
+                            add(ContextAction("Add to queue") { session.player.enqueueAll(playable) })
+                        }
+                        if (playable.isNotEmpty()) {
+                            add(
+                                ContextAction(
+                                    label = "Add to playlist",
+                                    alternate = buildContextMenu(playlistAddAlternate(playable)),
+                                    onClick = { addToPlaylist = playable }
+                                )
+                            )
+                        }
+                        if (item.pinned) {
+                            val kind = when {
+                                item.id.startsWith("playlist:") -> DesktopCollection.Kind.PLAYLIST
+                                item.circular || item.id.startsWith("artist:") -> DesktopCollection.Kind.ARTIST
+                                albums.any { it.id == item.id } -> DesktopCollection.Kind.ALBUM
+                                else -> DesktopCollection.Kind.SONG
+                            }
+                            val rawId = item.id.removePrefix("playlist:").removePrefix("artist:")
+                            add(
+                                ContextAction("Unpin", destructive = true) {
+                                    session.collection.unpin(kind, rawId)
+                                }
+                            )
+                        }
+                    }
+                }
+            },
+            showSidebar = showSidebar,
+            leftFraction = leftFrac,
+            rightFraction = rightFrac,
+            offline = !online,
+            onLeftFraction = { f, persist -> session.layout.setLeft(f, persist) },
+            onRightFraction = { f, persist -> session.layout.setRight(f, persist) },
+            bottomBar = {
+                PlayerChromeTheme(playerColors, useArtBackground = true) {
+                    BottomPlayerBar(
+                        track = current?.toCover(),
+                        playing = playing,
+                        positionMs = position,
+                        durationMs = duration,
+                        onPrev = session.player::previous,
+                        onToggle = session.player::togglePlay,
+                        onNext = session.player::next,
+                        onSeek = { ms ->
+                            session.player.seekTo(ms)
+                            session.persistPlayback()
+                        },
+                        accent = playerColors?.accent ?: MaterialTheme.colorScheme.primary,
+                        shuffle = shuffle,
+                        repeat = repeat,
+                        onToggleShuffle = session.player::toggleShuffle,
+                        onCycleRepeat = session.player::cycleRepeat,
+                        volume = volume,
+                        onVolume = session.player::setVolume,
+                        liked = current?.songKey in liked,
+                        onToggleLike = {
+                            val t = current ?: return@BottomPlayerBar
+                            session.collection.toggleLike(t.songKey)
+                        },
+                        queueVisible = showSidebar,
+                        onToggleQueue = { showSidebar = !showSidebar },
+                        songMenu = current?.let { songMenu(it) }.orEmpty()
+                    )
+                }
+            },
+            sidebar = {
+                PlayerChromeTheme(playerColors, useArtBackground = true) {
+                    val curId = current?.songKey
+                    val hotIdx = hotQueue.indexOfFirst { it.songKey == curId }
+                    val coldIdx = coldQueue.indexOfFirst { it.songKey == curId }
+                    val hotUp = if (hotIdx >= 0) hotQueue.drop(hotIdx + 1) else hotQueue
+                    val coldUp = if (coldIdx >= 0) coldQueue.drop(coldIdx + 1) else coldQueue
+                    val coldLabel = coldSource?.title?.takeIf { it.isNotBlank() }
+                        ?: coldUp.firstOrNull()?.displayAlbum?.takeIf { it.isNotBlank() && it != "Unknown Album" }
+                        ?: "Up next"
+                    NowPlayingSidebar(
+                        track = current?.toCover(),
+                        hot = hotUp.map { it.toRow() },
+                        cold = coldUp.map { it.toRow() },
+                        coldLabel = coldLabel,
+                        history = history.map { it.toRow() },
+                        onPlayHot = { i -> hotUp.getOrNull(i)?.let { session.player.playTrack(it) } },
+                        onPlayCold = { i -> coldUp.getOrNull(i)?.let { session.player.playTrack(it) } },
+                        onHistoryTrack = { row ->
+                            val t = history.firstOrNull { it.songKey == row.id } ?: return@NowPlayingSidebar
+                            session.player.playTrack(t, tracks.ifEmpty { listOf(t) })
+                        },
+                        onClearHot = session.player::clearHot,
+                        onClearHistory = session.player::clearHistory,
+                        onMoveHot = { from, to ->
+                            val skip = if (hotIdx >= 0) hotIdx + 1 else 0
+                            session.player.moveHot(from + skip, to + skip)
+                        },
+                        onMoveCold = { from, to ->
+                            val skip = if (coldIdx >= 0) coldIdx + 1 else 0
+                            session.player.moveCold(from + skip, to + skip)
+                        },
+                        likedIds = liked,
+                        onToggleTrackLike = session.collection::toggleLike,
+                        songMenu = { row ->
+                            menuForQueueRow(row, hotQueue + coldQueue + history + tracks)
+                        },
+                        nowPlayingMenu = current?.let { songMenu(it) }.orEmpty()
+                    )
+                }
+            }
+        ) {
+            when (val r = route) {
+                Route.Home -> HomeFeed(
+                    albums = albums,
+                    playlists = playlists,
+                    tracks = tracks,
+                    recents = history,
+                    pins = pins,
+                    liked = liked,
+                    status = engineMessage ?: status,
+                    onOpenAlbum = ::openAlbum,
+                    onOpenPlaylist = { push(Route.Playlist(it.id)) },
+                    onOpenArtist = ::openArtist,
+                    onPlayTracks = { list, i -> session.player.play(list, i) },
+                    onEnqueue = { session.player.enqueueAll(it) },
+                    onUnpin = { kind, id -> session.collection.unpin(kind, id) },
+                    onAddToPlaylist = { addToPlaylist = it },
+                    playlistQuickAdd = { songs -> buildContextMenu(playlistAddAlternate(songs)) }
+                )
+                Route.Search -> DesktopExplore(
+                    session = session,
+                    query = query,
+                    tracks = tracks,
+                    albums = albums,
+                    playlists = playlists,
+                    onOpenAlbum = ::openAlbum,
+                    onOpenPlaylist = { push(Route.Playlist(it.id)) },
+                    onOpenArtist = ::openArtist,
+                    onPlaySongs = { list, i -> session.player.play(list, i) },
+                    likedIds = liked,
+                    onToggleLike = session.collection::toggleLike,
+                    songMenu = { songMenu(it) }
+                )
+                Route.MyStuff -> MyStuffPage(
+                    tracks = tracks,
+                    albums = albums,
+                    playlists = playlists,
+                    pins = pins,
+                    liked = liked,
+                    onOpenAlbum = ::openAlbum,
+                    onOpenPlaylist = { push(Route.Playlist(it.id)) },
+                    onOpenArtist = ::openArtist,
+                    onPlayTracks = { list, i -> session.player.play(list, i) }
+                )
+                is Route.Album -> {
+                    val live = albums.firstOrNull { it.id == r.album.id } ?: r.album
+                    fun resolveRow(row: TrackRowModel): Song? {
+                        val group = tracks.filter { it.songKey in row.sourceIds.ifEmpty { listOf(row.id) } }
+                        if (group.isEmpty()) return tracks.firstOrNull { it.songKey == row.id }
+                        val identity = albumPageIdentity(group.first())
+                        return pickPreferred(group, session.sourcePrefs.get(identity))
+                    }
+                    val albumTracks = live.tracks.mapNotNull(::resolveRow)
+                    AlbumPage(
+                        album = live.copy(
+                            tracks = live.tracks.map {
+                                it.copy(highlighted = current?.songKey == it.id || current?.songKey in it.sourceIds)
+                            }
+                        ),
+                        playing = playing && session.player.isPlayingFromAlbum(live.id),
+                        onBack = ::goBack,
+                        onPlay = {
+                            if (albumTracks.isNotEmpty()) session.player.play(albumTracks, 0, ColdSource(ColdSourceType.ALBUM, live.id, live.title))
+                        },
+                        onTrack = { i ->
+                            if (i in albumTracks.indices) session.player.play(albumTracks, i, ColdSource(ColdSourceType.ALBUM, live.id, live.title))
+                        },
+                        onEdit = { editAlbum = live },
+                        onEditTrack = { i ->
+                            albumTracks.getOrNull(i)?.let { editSong = it }
+                        },
+                        onArtist = ::openArtist,
+                        liked = session.collection.isSaved(DesktopCollection.Kind.ALBUM, live.id),
+                        onToggleLike = {
+                            session.collection.toggleSaved(
+                                DesktopCollection.Pin(
+                                    DesktopCollection.Kind.ALBUM,
+                                    live.id,
+                                    live.title,
+                                    live.artist
+                                )
+                            )
+                        },
+                        likedTrackIds = liked,
+                        onToggleTrackLike = session.collection::toggleLike,
+                        songMenu = { row ->
+                            tracks.firstOrNull { it.songKey == row.id }?.let { songMenu(it, onAlbumPage = true) }.orEmpty()
+                        },
+                        onSources = { row ->
+                            val ids = row.sourceIds.ifEmpty { listOf(row.id) }.toHashSet()
+                            sourcesFor = tracks.filter { it.songKey in ids }
+                                .ifEmpty { tracks.filter { it.catalogKey() == row.id } }
+                                .ifEmpty { listOfNotNull(tracks.firstOrNull { it.songKey == row.id }) }
+                        }
+                    )
+                }
+                is Route.Artist -> {
+                    var profile by remember(r.name) { mutableStateOf<ArtistProfile?>(null) }
+                    var pickBanner by remember { mutableStateOf(false) }
+                    var cropBanner by remember { mutableStateOf<java.io.File?>(null) }
+                    LaunchedEffect(r.name) {
+                        profile = runCatching { session.artists.resolve(r.name) }.getOrNull()
+                    }
+                    val model = remember(r.name, tracks, liked, history, profile) {
+                        val base = tracks.artistPage(r.name, liked, history)
+                        base.copy(
+                            about = profile?.bio ?: base.about,
+                            artworkUri = profile?.imageUri ?: base.artworkUri,
+                            bannerUri = when {
+                                profile?.bannerCleared == true -> ""
+                                !profile?.bannerUri.isNullOrBlank() -> profile!!.bannerUri
+                                else -> null
+                            },
+                            genres = profile?.genres.orEmpty()
+                        )
+                    }
+                    val artistTracks = remember(r.name, tracks) {
+                        tracks.filter {
+                            it.displayArtist.equals(r.name, true) ||
+                                it.albumArtist.equals(r.name, true)
+                        }
+                    }
+                    ArtistPage(
+                        artist = model,
+                        playing = playing && session.player.isPlayingFromArtist(r.name),
+                        onPlay = {
+                            if (artistTracks.isNotEmpty()) session.player.play(artistTracks, 0, ColdSource(ColdSourceType.ARTIST, r.name, r.name))
+                        },
+                        onShuffle = {
+                            if (artistTracks.isNotEmpty()) {
+                                if (!shuffle) session.player.toggleShuffle()
+                                session.player.play(artistTracks, 0, ColdSource(ColdSourceType.ARTIST, r.name, r.name))
+                            }
+                        },
+                        onTrack = { i ->
+                            val popularIds = model.popular.map { it.id }
+                            val list = popularIds.mapNotNull { id -> artistTracks.firstOrNull { it.songKey == id } }
+                                .ifEmpty { artistTracks }
+                            if (i in list.indices) session.player.play(list, i, ColdSource(ColdSourceType.ARTIST, r.name, r.name))
+                        },
+                        onOpenAlbum = ::openAlbum,
+                        onChangeHeader = {
+                            DesktopFiles.pickImage("Choose header")?.let { cropBanner = it }
+                        },
+                        onFetchHeader = { pickBanner = true },
+                        onClearHeader = {
+                            profile = session.artists.clearBanner(r.name)
+                        },
+                        liked = session.collection.isSaved(DesktopCollection.Kind.ARTIST, r.name),
+                        onToggleLike = {
+                            session.collection.toggleSaved(
+                                DesktopCollection.Pin(
+                                    DesktopCollection.Kind.ARTIST,
+                                    r.name,
+                                    r.name,
+                                    "Artist"
+                                )
+                            )
+                        },
+                        likedTrackIds = liked,
+                        onToggleTrackLike = session.collection::toggleLike,
+                        songMenu = { row ->
+                            tracks.firstOrNull { it.songKey == row.id }?.let { songMenu(it) }.orEmpty()
+                        }
+                    )
+                    if (pickBanner) {
+                        ArtistBannerPicker(
+                            artistName = r.name,
+                            client = session.artists,
+                            onDismiss = { pickBanner = false },
+                            onPicked = { candidate ->
+                                scope.launch {
+                                    runCatching {
+                                        profile = session.artists.applyBannerUrl(r.name, candidate.url)
+                                    }
+                                    pickBanner = false
+                                }
+                            }
+                        )
+                    }
+                    if (cropBanner != null) {
+                        ImageCropDialog(
+                            source = cropBanner!!,
+                            title = "Crop banner",
+                            aspect = 3f,
+                            onCancel = { cropBanner = null },
+                            onCropped = { cropped ->
+                                runCatching {
+                                    profile = session.artists.applyLocalBanner(r.name, cropped)
+                                }
+                                cropBanner = null
+                            }
+                        )
+                    }
+                }
+                is Route.Playlist -> {
+                    val pl = playlists.firstOrNull { it.id == r.id }
+                    if (pl == null) {
+                        Text("Playlist gone.", modifier = Modifier.padding(24.dp))
+                    } else {
+                        LaunchedEffect(pl.id, pl.snapshots.map { it.songKey }) {
+                            session.ensureTracks(pl.snapshots)
+                        }
+                        PlaylistPage(
+                            playlist = pl,
+                            tracks = pl.tracks(tracks),
+                            library = tracks,
+                            currentId = current?.songKey,
+                            playing = playing && session.player.isPlayingFromPlaylist(pl.id),
+                            store = session.playlists,
+                            onBack = ::goBack,
+                            onPlay = { list, i -> session.player.play(list, i, ColdSource(ColdSourceType.PLAYLIST, pl.id, pl.name)) },
+                            onEditTrack = { editSong = it },
+                            likedIds = liked,
+                            onToggleLike = session.collection::toggleLike,
+                            playlistLiked = session.collection.isSaved(DesktopCollection.Kind.PLAYLIST, pl.id),
+                            onTogglePlaylistLike = {
+                                session.collection.toggleSaved(
+                                    DesktopCollection.Pin(
+                                        DesktopCollection.Kind.PLAYLIST,
+                                        pl.id,
+                                        pl.name,
+                                        "Playlist"
+                                    )
+                                )
+                            },
+                            songMenu = { songMenu(it, playlistId = pl.id) }
+                        )
+                    }
+                }
+            }
+        }
+        if (showSettings) {
+            DesktopSettingsDialog(
+                session = session,
+                onDismiss = { showSettings = false }
+            )
+        }
+        if (showNewPlaylist) {
+            NewPlaylistDialog(
+                onDismiss = { showNewPlaylist = false },
+                onCreate = { name, description ->
+                    val created = session.playlists.create(name, description)
+                    showNewPlaylist = false
+                    push(Route.Playlist(created.id))
+                }
+            )
+        }
+        editSong?.let { song ->
+            EditSongDialog(
+                track = song,
+                onDismiss = { editSong = null },
+                onSaved = { session.replaceTracks(listOf(it)) }
+            )
+        }
+        editAlbum?.let { album ->
+            val albumTracks = tracks.filter { t -> album.tracks.any { it.id == t.songKey } }
+            EditAlbumDialog(
+                album = album,
+                tracks = albumTracks,
+                onDismiss = { editAlbum = null },
+                onSaved = { session.replaceTracks(it) }
+            )
+        }
+        addToPlaylist?.let { songs ->
+            AddToPlaylistDialog(
+                tracks = songs,
+                store = session.playlists,
+                library = tracks,
+                onDismiss = { addToPlaylist = null },
+                onEnsureTracks = { session.ensureTracks(it) }
+            )
+        }
+        sourcesFor?.let { group ->
+            val preferredId = group.firstOrNull()?.let { session.sourcePrefs.get(albumPageIdentity(it)) }
+                ?: group.minByOrNull { it.sourceRank() }?.songKey
+            SourcesPickerDialog(
+                title = group.first().displayTitle,
+                choices = sourceChoices(group, remotes, preferredId),
+                onDismiss = { sourcesFor = null },
+                onPick = { picked ->
+                    session.sourcePrefs.set(albumPageIdentity(picked), picked.songKey)
+                    prefRev++
+                    sourcesFor = null
+                }
+            )
+        }
+    }
+}
+
+@Composable
+private fun MyStuffPage(
+    tracks: List<Song>,
+    albums: List<AlbumPageModel>,
+    playlists: List<capital.yuri.yuriplayer.desktop.DesktopPlaylist>,
+    pins: List<DesktopCollection.Pin>,
+    liked: Set<String>,
+    onOpenAlbum: (AlbumPageModel) -> Unit,
+    onOpenPlaylist: (capital.yuri.yuriplayer.desktop.DesktopPlaylist) -> Unit,
+    onOpenArtist: (String) -> Unit,
+    onPlayTracks: (List<Song>, Int) -> Unit
+) {
+    val likedTracks = remember(liked, tracks) { tracks.filter { it.songKey in liked } }
+    val pinnedAlbumIds = remember(pins) {
+        pins.filter { it.kind == DesktopCollection.Kind.ALBUM }.map { it.id }.toSet()
+    }
+    val pinnedAlbumTitles = remember(pins) {
+        pins.filter { it.kind == DesktopCollection.Kind.ALBUM }.map { it.title.lowercase() }.toSet()
+    }
+    val pinnedAlbums = remember(albums, pinnedAlbumIds, pinnedAlbumTitles) {
+        albums.filter { it.id in pinnedAlbumIds || it.title.lowercase() in pinnedAlbumTitles }
+    }
+    val pinnedArtists = remember(pins, tracks) {
+        pins.filter { it.kind == DesktopCollection.Kind.ARTIST }.map { p ->
+            p.title to tracks.firstOrNull {
+                it.displayArtist.equals(p.title, true) || it.albumArtist.equals(p.title, true)
+            }?.albumArtUri
+        }
+    }
+    val pinnedPlaylists = remember(pins, playlists) {
+        val ids = pins.filter { it.kind == DesktopCollection.Kind.PLAYLIST }.map { it.id }.toSet()
+        playlists.filter { it.id in ids }
+    }
+
+    Column(
+        Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 24.dp, vertical = 16.dp)
+    ) {
+        Text(
+            "My Stuff",
+            style = MaterialTheme.typography.headlineMedium,
+            fontWeight = FontWeight.Bold,
+            color = MaterialTheme.colorScheme.onBackground
+        )
+        Spacer(Modifier.height(16.dp))
+
+        if (likedTracks.isNotEmpty()) {
+            SectionHeader("Liked songs")
+            Column {
+                likedTracks.forEach { track ->
+                    Row(
+                        Modifier
+                            .fillMaxWidth()
+                            .clip(RoundedCornerShape(10.dp))
+                            .clickable { onPlayTracks(likedTracks, likedTracks.indexOf(track)) }
+                            .padding(8.dp),
+                        verticalAlignment = Alignment.CenterVertically
+                    ) {
+                        CoverArt(model = track.albumArtUri, size = 44.dp, corner = 6.dp)
+                        Spacer(Modifier.width(12.dp))
+                        Column(Modifier.weight(1f)) {
+                            Text(
+                                track.displayTitle,
+                                fontWeight = FontWeight.Medium,
+                                maxLines = 1,
+                                overflow = TextOverflow.Ellipsis
+                            )
+                            Text(
+                                track.displayArtist,
+                                style = MaterialTheme.typography.bodySmall,
+                                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+                                maxLines = 1,
+                                overflow = TextOverflow.Ellipsis
+                            )
+                        }
+                    }
+                }
+            }
+        }
+
+        if (pinnedAlbums.isNotEmpty()) {
+            Spacer(Modifier.height(20.dp))
+            SectionHeader("Albums")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(pinnedAlbums, key = { it.id }) { album ->
+                    AlbumCard(album = album, onClick = { onOpenAlbum(album) })
+                }
+            }
+        }
+
+        if (pinnedArtists.isNotEmpty()) {
+            Spacer(Modifier.height(20.dp))
+            SectionHeader("Artists")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(pinnedArtists, key = { it.first }) { (name, cover) ->
+                    Column(
+                        Modifier.width(140.dp).clickable { onOpenArtist(name) },
+                        horizontalAlignment = Alignment.CenterHorizontally
+                    ) {
+                        CoverArt(
+                            model = cover,
+                            size = 128.dp,
+                            corner = 64.dp,
+                            contentScale = androidx.compose.ui.layout.ContentScale.Crop
+                        )
+                        Text(
+                            name,
+                            modifier = Modifier.padding(top = 8.dp),
+                            maxLines = 1,
+                            overflow = TextOverflow.Ellipsis,
+                            fontWeight = FontWeight.Medium
+                        )
+                    }
+                }
+            }
+        }
+
+        if (pinnedPlaylists.isNotEmpty()) {
+            Spacer(Modifier.height(20.dp))
+            SectionHeader("Playlists")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(pinnedPlaylists, key = { it.id }) { pl ->
+                    AlbumCard(
+                        album = AlbumPageModel(
+                            id = pl.id,
+                            title = pl.name,
+                            artist = pl.description ?: "Playlist",
+                            artworkUri = pl.artworkUri(tracks),
+                            tracks = emptyList()
+                        ),
+                        onClick = { onOpenPlaylist(pl) }
+                    )
+                }
+            }
+        }
+
+        if (likedTracks.isEmpty() && pinnedAlbums.isEmpty() && pinnedArtists.isEmpty() && pinnedPlaylists.isEmpty()) {
+            Spacer(Modifier.height(12.dp))
+            Text(
+                "Nothing here yet — like songs or pin albums, artists, and playlists.",
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f)
+            )
+        }
+    }
+}
+
+@Composable
+private fun HomeFeed(
+    albums: List<AlbumPageModel>,
+    playlists: List<capital.yuri.yuriplayer.desktop.DesktopPlaylist>,
+    tracks: List<Song>,
+    recents: List<Song>,
+    pins: List<DesktopCollection.Pin>,
+    liked: Set<String>,
+    status: String,
+    onOpenAlbum: (AlbumPageModel) -> Unit,
+    onOpenPlaylist: (capital.yuri.yuriplayer.desktop.DesktopPlaylist) -> Unit,
+    onOpenArtist: (String) -> Unit,
+    onPlayTracks: (List<Song>, Int) -> Unit,
+    onEnqueue: (List<Song>) -> Unit = {},
+    onUnpin: (DesktopCollection.Kind, String) -> Unit = { _, _ -> },
+    onAddToPlaylist: (List<Song>) -> Unit = {},
+    playlistQuickAdd: (List<Song>) -> List<MenuEntry> = { emptyList() }
+) {
+    val recentAlbums = remember(recents, albums) {
+        recents.mapNotNull { t ->
+            albums.firstOrNull { a -> a.tracks.any { it.id == t.songKey } }
+        }.distinctBy { it.id }
+    }
+    val likedTracks = remember(liked, tracks) { tracks.filter { it.songKey in liked } }
+    val shortcuts = remember(pins, liked, likedTracks, albums, playlists, tracks) {
+        buildHomeShortcuts(
+            pins, liked, likedTracks, albums, playlists, tracks,
+            onOpenAlbum, onOpenPlaylist, onOpenArtist, onPlayTracks,
+            onEnqueue, onUnpin, onAddToPlaylist, playlistQuickAdd
+        )
+    }
+    val greeting = remember {
+        val h = java.time.LocalTime.now().hour
+        when {
+            h < 12 -> "Good morning"
+            h < 18 -> "Good afternoon"
+            else -> "Good evening"
+        }
+    }
+    val stuffAlbums = remember(pins, liked, albums) {
+        val pinnedAlbumIds = pins.filter { it.kind == DesktopCollection.Kind.ALBUM }.map { it.id }.toSet()
+        val pinnedTitles = pins.filter { it.kind == DesktopCollection.Kind.ALBUM }
+            .map { it.title.lowercase() }.toSet()
+        albums.filter { album ->
+            album.id in pinnedAlbumIds ||
+                album.title.lowercase() in pinnedTitles ||
+                album.tracks.any { it.id in liked }
+        }
+    }
+    val stuffArtists = remember(pins, liked, albums, tracks) {
+        val pinned = pins.filter { it.kind == DesktopCollection.Kind.ARTIST }.map { it.title }
+        val fromAlbums = stuffAlbums.map { it.artist }
+        val fromLiked = tracks.filter { it.songKey in liked }.map { it.displayArtist }
+        (pinned + fromAlbums + fromLiked).map { it.trim() }.filter { it.isNotEmpty() }.distinct()
+    }
+
+    Column(
+        Modifier
+            .fillMaxSize()
+            .verticalScroll(rememberScrollState())
+            .padding(horizontal = 24.dp, vertical = 16.dp)
+    ) {
+        Text(
+            greeting,
+            style = MaterialTheme.typography.headlineMedium,
+            fontWeight = FontWeight.Bold,
+            color = MaterialTheme.colorScheme.onBackground
+        )
+        Spacer(Modifier.height(12.dp))
+        Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
+            FilterChip(selected = true, onClick = {}, label = { Text("All") })
+            FilterChip(selected = false, onClick = {}, label = { Text("Music") })
+        }
+        if (shortcuts.isNotEmpty()) {
+            Spacer(Modifier.height(16.dp))
+            shortcuts.chunked(4).forEach { row ->
+                Row(
+                    Modifier.fillMaxWidth().padding(bottom = 8.dp),
+                    horizontalArrangement = Arrangement.spacedBy(8.dp)
+                ) {
+                    row.forEach { pin ->
+                        SpotifyPinCard(pin = pin, modifier = Modifier.weight(1f))
+                    }
+                    repeat(4 - row.size) { Spacer(Modifier.weight(1f)) }
+                }
+            }
+        }
+        Spacer(Modifier.height(20.dp))
+        if (recents.isNotEmpty()) {
+            SectionHeader("Jump back in")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(recents.take(12), key = { it.songKey }) { track ->
+                    AlbumCard(
+                        album = AlbumPageModel(
+                            id = track.songKey,
+                            title = track.displayTitle,
+                            artist = track.displayArtist,
+                            artworkUri = track.albumArtUri,
+                            tracks = emptyList()
+                        ),
+                        onClick = { onPlayTracks(listOf(track) + tracks, 0) }
+                    )
+                }
+            }
+            Spacer(Modifier.height(24.dp))
+        }
+        if (playlists.isNotEmpty()) {
+            SectionHeader("Your playlists")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(playlists.take(12), key = { it.id }) { pl ->
+                    AlbumCard(
+                        album = AlbumPageModel(
+                            id = pl.id,
+                            title = pl.name,
+                            artist = pl.description ?: "Playlist",
+                            artworkUri = pl.artworkUri(tracks),
+                            tracks = emptyList()
+                        ),
+                        onClick = { onOpenPlaylist(pl) }
+                    )
+                }
+            }
+            Spacer(Modifier.height(24.dp))
+        }
+        if (recentAlbums.isNotEmpty()) {
+            SectionHeader("Recently played")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(recentAlbums.take(12), key = { it.id }) { album ->
+                    AlbumCard(album = album, onClick = { onOpenAlbum(album) })
+                }
+            }
+            Spacer(Modifier.height(24.dp))
+        }
+        if (stuffAlbums.isNotEmpty()) {
+            val mixAlbums = remember(stuffAlbums) { stuffAlbums.shuffled().take(12) }
+            SectionHeader("Albums from My Stuff")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(mixAlbums, key = { it.id }) { album ->
+                    AlbumCard(album = album, onClick = { onOpenAlbum(album) })
+                }
+            }
+            Spacer(Modifier.height(24.dp))
+        }
+        if (stuffArtists.isNotEmpty()) {
+            SectionHeader("Artists from My Stuff")
+            LazyRow(horizontalArrangement = Arrangement.spacedBy(12.dp)) {
+                items(stuffArtists.take(12), key = { it }) { name ->
+                    val cover = albums.firstOrNull { it.artist == name }?.artworkUri
+                    Column(
+                        Modifier.width(140.dp).clickable { onOpenArtist(name) },
+                        horizontalAlignment = Alignment.CenterHorizontally
+                    ) {
+                        CoverArt(
+                            model = cover,
+                            size = 128.dp,
+                            corner = 64.dp,
+                            contentScale = androidx.compose.ui.layout.ContentScale.Crop
+                        )
+                        Text(
+                            name,
+                            modifier = Modifier.padding(top = 8.dp),
+                            maxLines = 1,
+                            overflow = TextOverflow.Ellipsis,
+                            fontWeight = FontWeight.Medium
+                        )
+                    }
+                }
+            }
+            Spacer(Modifier.height(24.dp))
+        }
+        if (shortcuts.isEmpty() && stuffAlbums.isEmpty() && playlists.isEmpty() && recents.isEmpty()) {
+            Text(
+                "Pin albums, artists, or playlists from My Stuff and they’ll show up here.",
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f),
+                modifier = Modifier.padding(top = 24.dp)
+            )
+        }
+        if (albums.isEmpty() && playlists.isEmpty() && recents.isEmpty() && tracks.isEmpty()) {
+            Text(
+                status.ifBlank { "Nothing in the library yet." },
+                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
+            )
+        }
+    }
+}
+
+private data class SpotifyPin(
+    val id: String,
+    val title: String,
+    val artworkUri: String?,
+    val circular: Boolean = false,
+    val onClick: () -> Unit,
+    val menu: List<out MenuEntry> = emptyList()
+)
+
+private fun buildHomeShortcuts(
+    pins: List<DesktopCollection.Pin>,
+    liked: Set<String>,
+    likedTracks: List<Song>,
+    albums: List<AlbumPageModel>,
+    playlists: List<capital.yuri.yuriplayer.desktop.DesktopPlaylist>,
+    tracks: List<Song>,
+    onOpenAlbum: (AlbumPageModel) -> Unit,
+    onOpenPlaylist: (capital.yuri.yuriplayer.desktop.DesktopPlaylist) -> Unit,
+    onOpenArtist: (String) -> Unit,
+    onPlayTracks: (List<Song>, Int) -> Unit,
+    onEnqueue: (List<Song>) -> Unit,
+    onUnpin: (DesktopCollection.Kind, String) -> Unit,
+    onAddToPlaylist: (List<Song>) -> Unit,
+    playlistQuickAdd: (List<Song>) -> List<MenuEntry>
+): List<SpotifyPin> {
+    val out = ArrayList<SpotifyPin>(8)
+    fun add(pin: SpotifyPin) {
+        if (out.size >= 8) return
+        if (out.any { it.id == pin.id }) return
+        out += pin
+    }
+    fun menu(
+        kind: DesktopCollection.Kind?,
+        id: String,
+        playable: List<Song>,
+        play: () -> Unit
+    ) = buildList {
+        if (playable.isNotEmpty() || kind == null) {
+            add(ContextAction("Play", onClick = play))
+        }
+        if (playable.isNotEmpty()) {
+            add(ContextAction("Add to queue") { onEnqueue(playable) })
+        }
+        if (playable.isNotEmpty()) {
+            add(
+                ContextAction(
+                    label = "Add to playlist",
+                    alternate = playlistQuickAdd(playable),
+                    onClick = { onAddToPlaylist(playable) }
+                )
+            )
+        }
+        if (kind != null) {
+            add(ContextAction("Unpin", destructive = true) { onUnpin(kind, id) })
+        }
+    }
+    if (liked.isNotEmpty()) {
+        add(
+            SpotifyPin(
+                id = "liked",
+                title = "My Stuff",
+                artworkUri = likedTracks.firstOrNull()?.albumArtUri,
+                onClick = { onPlayTracks(likedTracks, 0) },
+                menu = menu(null, "liked", likedTracks) { onPlayTracks(likedTracks, 0) }
+            )
+        )
+    }
+    for (pin in pins) {
+        when (pin.kind) {
+            DesktopCollection.Kind.ALBUM -> {
+                val album = albums.firstOrNull { it.id == pin.id }
+                    ?: albums.firstOrNull { it.title.equals(pin.title, true) }
+                val playable = album?.tracks?.mapNotNull { row -> tracks.firstOrNull { it.songKey == row.id } }.orEmpty()
+                add(
+                    SpotifyPin(
+                        pin.id, pin.title, album?.artworkUri,
+                        onClick = { album?.let(onOpenAlbum) },
+                        menu = menu(DesktopCollection.Kind.ALBUM, pin.id, playable) {
+                            if (playable.isNotEmpty()) onPlayTracks(playable, 0)
+                            else album?.let(onOpenAlbum)
+                        }
+                    )
+                )
+            }
+            DesktopCollection.Kind.ARTIST -> {
+                val playable = tracks.filter {
+                    it.displayArtist.equals(pin.title, true) || it.albumArtist.equals(pin.title, true)
+                }
+                add(
+                    SpotifyPin(
+                        pin.id,
+                        pin.title,
+                        tracks.firstOrNull { it.displayArtist.equals(pin.title, true) }?.albumArtUri,
+                        circular = true,
+                        onClick = { onOpenArtist(pin.title) },
+                        menu = menu(DesktopCollection.Kind.ARTIST, pin.id, playable) { onOpenArtist(pin.title) }
+                    )
+                )
+            }
+            DesktopCollection.Kind.SONG -> {
+                val t = tracks.firstOrNull { it.songKey == pin.id }
+                val playable = listOfNotNull(t)
+                add(
+                    SpotifyPin(
+                        pin.id, pin.title, t?.albumArtUri,
+                        onClick = { t?.let { onPlayTracks(listOf(it), 0) } },
+                        menu = menu(DesktopCollection.Kind.SONG, pin.id, playable) {
+                            t?.let { onPlayTracks(listOf(it), 0) }
+                        }
+                    )
+                )
+            }
+            DesktopCollection.Kind.PLAYLIST -> {
+                val pl = playlists.firstOrNull { it.id == pin.id }
+                val playable = pl?.tracks(tracks).orEmpty()
+                add(
+                    SpotifyPin(
+                        pin.id, pin.title, pl?.artworkUri(tracks),
+                        onClick = { pl?.let(onOpenPlaylist) },
+                        menu = menu(DesktopCollection.Kind.PLAYLIST, pin.id, playable) {
+                            if (playable.isNotEmpty()) onPlayTracks(playable, 0)
+                            else pl?.let(onOpenPlaylist)
+                        }
+                    )
+                )
+            }
+        }
+    }
+    return out
+}
+
+@Composable
+private fun SpotifyPinCard(pin: SpotifyPin, modifier: Modifier = Modifier) {
+    ContextMenuAnchor(items = pin.menu, modifier = modifier) {
+        Surface(
+            modifier = Modifier
+                .fillMaxWidth()
+                .height(72.dp)
+                .clip(RoundedCornerShape(6.dp))
+                .clickable(onClick = pin.onClick),
+            color = MaterialTheme.colorScheme.surfaceVariant.copy(alpha = 0.55f),
+            shape = RoundedCornerShape(6.dp),
+            tonalElevation = 2.dp
+        ) {
+            Row(verticalAlignment = Alignment.CenterVertically) {
+                CoverArt(
+                    model = pin.artworkUri,
+                    size = 72.dp,
+                    corner = if (pin.circular) 36.dp else 0.dp,
+                    contentScale = if (pin.circular) {
+                        androidx.compose.ui.layout.ContentScale.Crop
+                    } else {
+                        androidx.compose.ui.layout.ContentScale.Fit
+                    }
+                )
+                Text(
+                    pin.title,
+                    modifier = Modifier.padding(horizontal = 12.dp),
+                    maxLines = 2,
+                    overflow = TextOverflow.Ellipsis,
+                    fontWeight = FontWeight.SemiBold,
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurface
+                )
+            }
+        }
+    }
+}
+
+@Composable
+private fun SectionHeader(title: String) {
+    Row(
+        Modifier.fillMaxWidth().padding(bottom = 8.dp),
+        verticalAlignment = Alignment.CenterVertically
+    ) {
+        Text(title, style = MaterialTheme.typography.titleLarge, fontWeight = FontWeight.Bold)
+        Spacer(Modifier.weight(1f))
+        TextButton(onClick = {}) { Text("Show all") }
+    }
+}
+
+@Composable
+private fun LibraryGrid(
+    albums: List<AlbumPageModel>,
+    status: String,
+    emptyHint: String,
+    onOpen: (AlbumPageModel) -> Unit
+) {
+    Column(Modifier.fillMaxSize().padding(horizontal = 20.dp, vertical = 16.dp)) {
+        Text("Search", style = MaterialTheme.typography.headlineSmall, fontWeight = FontWeight.Bold)
+        Text(
+            status,
+            style = MaterialTheme.typography.bodySmall,
+            color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.55f),
+            modifier = Modifier.padding(bottom = 12.dp, top = 4.dp)
+        )
+        if (albums.isEmpty()) {
+            Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+                Text(emptyHint, color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f))
+            }
+        } else {
+            LazyVerticalGrid(
+                columns = GridCells.Adaptive(180.dp),
+                contentPadding = PaddingValues(bottom = 24.dp),
+                horizontalArrangement = Arrangement.spacedBy(16.dp),
+                verticalArrangement = Arrangement.spacedBy(16.dp)
+            ) {
+                items(albums, key = { it.id }) { album ->
+                    AlbumCard(album = album, onClick = { onOpen(album) })
+                }
+            }
+        }
+    }
+}
diff --git a/desktop/src/main/resources/META-INF/services/uk.co.caprica.vlcj.factory.discovery.provider.DiscoveryDirectoryProvider b/desktop/src/main/resources/META-INF/services/uk.co.caprica.vlcj.factory.discovery.provider.DiscoveryDirectoryProvider
new file mode 100644
index 00000000..f132458f
--- /dev/null
+++ b/desktop/src/main/resources/META-INF/services/uk.co.caprica.vlcj.factory.discovery.provider.DiscoveryDirectoryProvider
@@ -0,0 +1 @@
+capital.yuri.yuriplayer.desktop.player.NixLibVlcDirectoryProvider
diff --git a/desktop/src/main/resources/logback.xml b/desktop/src/main/resources/logback.xml
new file mode 100644
index 00000000..915178f1
--- /dev/null
+++ b/desktop/src/main/resources/logback.xml
@@ -0,0 +1,31 @@
+<configuration>
+    <property name="LOG_DIR" value="${LOG_DIR:-${user.home}/.cache/yuriplayer}"/>
+
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} %-5level %logger{28} — %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+        <file>${LOG_DIR}/yuriplayer.log</file>
+        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
+            <fileNamePattern>${LOG_DIR}/yuriplayer.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
+            <maxFileSize>8MB</maxFileSize>
+            <maxHistory>7</maxHistory>
+            <totalSizeCap>40MB</totalSizeCap>
+        </rollingPolicy>
+        <encoder>
+            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %logger — %msg%n</pattern>
+        </encoder>
+    </appender>
+
+    <logger name="YuriPlayer" level="DEBUG"/>
+    <logger name="uk.co.caprica.vlcj" level="WARN"/>
+    <logger name="org.freedesktop.dbus" level="WARN"/>
+
+    <root level="INFO">
+        <appender-ref ref="CONSOLE"/>
+        <appender-ref ref="FILE"/>
+    </root>
+</configuration>
diff --git a/desktop/src/test/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcLocatorTest.kt b/desktop/src/test/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcLocatorTest.kt
new file mode 100644
index 00000000..8bd6e998
--- /dev/null
+++ b/desktop/src/test/kotlin/capital/yuri/yuriplayer/desktop/player/LibVlcLocatorTest.kt
@@ -0,0 +1,69 @@
+package capital.yuri.yuriplayer.desktop.player
+
+import java.io.File
+import kotlin.io.path.createTempDirectory
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertFalse
+import kotlin.test.assertTrue
+
+class LibVlcLocatorTest {
+
+    @Test
+    fun recognizesNixAndFhsLibraryNames() {
+        assertTrue(
+            LibVlcLocator.looksLikeLibDir(listOf("libvlc.so.5", "libvlccore.so.9", "vlc"))
+        )
+        assertTrue(
+            LibVlcLocator.looksLikeLibDir(listOf("libvlc.dll", "libvlccore.dll", "plugins"))
+        )
+        assertTrue(
+            LibVlcLocator.looksLikeLibDir(listOf("libvlc.dylib", "libvlccore.dylib"))
+        )
+        assertFalse(LibVlcLocator.looksLikeLibDir(listOf("libvlc.so.5")))
+    }
+
+    @Test
+    fun parsesNixWrapProgramScript() {
+        val text = """
+            #! /nix/store/aaaa-bash-5.2/bin/bash -e
+            export PATH='/nix/store/bbbb-coreutils/bin'
+            export VLC_PLUGIN_PATH='/nix/store/cccc-vlc-3.0.21/lib/vlc/plugins'
+            export LD_LIBRARY_PATH='/nix/store/cccc-vlc-3.0.21/lib:/nix/store/dddd-lib/lib'
+            exec -a "$0" /nix/store/cccc-vlc-3.0.21/bin/.vlc-wrapped "$@"
+        """.trimIndent()
+        val plugin = LibVlcLocator.pluginPathFromWrapper(text)
+        assertEquals("/nix/store/cccc-vlc-3.0.21/lib/vlc/plugins", plugin)
+    }
+
+    @Test
+    fun libDirFromWrapperResolvesExistingLayout() {
+        val root = createTempDirectory("vlc-nix").toFile()
+        try {
+            val lib = File(root, "lib").apply { mkdirs() }
+            File(lib, "libvlc.so.5").writeText("")
+            File(lib, "libvlccore.so.9").writeText("")
+            File(lib, "vlc/plugins").mkdirs()
+            val text = """
+                #! /nix/store/aaaa-bash/bin/bash -e
+                export VLC_PLUGIN_PATH='${File(lib, "vlc/plugins").absolutePath}'
+                export LD_LIBRARY_PATH='${lib.absolutePath}'
+                exec -a "${'$'}0" ${File(root, "bin/.vlc-wrapped").absolutePath}
+            """.trimIndent()
+            val found = LibVlcLocator.libDirFromWrapper(text)
+            assertEquals(lib.canonicalFile, found?.canonicalFile)
+        } finally {
+            root.deleteRecursively()
+        }
+    }
+
+    @Test
+    fun describeNativeFailureMentionsOverride() {
+        val msg = VlcjPlaybackEngine.describeNativeFailure(
+            "Failed to properly initialise the native library",
+            discovered = false
+        )
+        assertTrue(msg.contains("YURI_LIBVLC"))
+        assertTrue(msg.contains("Failed to properly initialise the native library"))
+    }
+}
diff --git a/gradle.properties b/gradle.properties
index 962a7968..d2248db6 100644
--- a/gradle.properties
+++ b/gradle.properties
@@ -10,7 +10,7 @@ org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
 # When configured, Gradle will run in incubating parallel mode.
 # This option should only be used with decoupled projects. For more details, visit
 # https://developer.android.com/r/tools/gradle-multi-project-decoupled-projects
-# org.gradle.parallel=true
+org.gradle.parallel=true
 # When enabled, the Configuration Cache allows Gradle to skip the configuration
 # phase entirely if nothing that affects the build configuration (such as build scripts)
 # has changed. Additionally, Gradle applies performance optimizations to task execution.
@@ -21,3 +21,6 @@ kotlin.code.style=official
 # AGP 9 built-in Kotlin + KSP: Room generates into kotlin source sets.
 # See https://developer.android.com/r/tools/built-in-kotlin
 android.disallowKotlinSourceSets=false
+
+# Enabled parallel sync for Gradle 9.4+
+org.gradle.tooling.parallel=true
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index ed1bb926..2efd31a7 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -1,21 +1,22 @@
 [versions]
-agp = "9.3.1"
-coreKtx = "1.19.0"
+agp = "9.3.2"
+coreKtx = "1.18.0"
 junit = "4.13.2"
 junitVersion = "1.3.0"
 espressoCore = "3.7.0"
 appcompat = "1.8.0"
 material = "1.13.0"
-lifecycleRuntimeKtx = "2.11.0"
+lifecycleRuntimeKtx = "2.10.0"
 activityCompose = "1.13.0"
 kotlin = "2.3.21"
-composeBom = "2026.08.00"
+composeBom = "2026.06.00"
 media3 = "1.11.0"
 media = "1.7.1"
 koin = "4.2.2"
 coroutines = "1.11.0"
 palette = "1.0.0"
 room = "2.8.4"
+sqlite = "2.6.2"
 ksp = "2.3.11"
 serialization = "1.11.0"
 jaudiotagger = "2.2.7"
@@ -26,6 +27,15 @@ jellyfinSdk = "1.8.11"
 aboutLibraries = "14.2.1"
 libvlc = "3.6.2"
 robolectric = "4.16"
+composeMultiplatform = "1.8.2"
+composeIconsExtended = "1.7.3"
+vlcj = "4.10.1"
+dbusJava = "5.1.1"
+junixsocket = "2.10.1"
+jna = "5.17.0"
+slf4j = "2.0.17"
+logback = "1.5.18"
+lyricist = "1.6.1"
 
 [libraries]
 androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
@@ -58,35 +68,60 @@ androidx-media3-common = { group = "androidx.media3", name = "media3-common", ve
 
 libvlc-all = { group = "org.videolan.android", name = "libvlc-all", version.ref = "libvlc" }
 
+koin-core = { group = "io.insert-koin", name = "koin-core", version.ref = "koin" }
 koin-android = { group = "io.insert-koin", name = "koin-android", version.ref = "koin" }
 koin-androidx-compose = { group = "io.insert-koin", name = "koin-androidx-compose", version.ref = "koin" }
 
+aboutlibraries-core = { group = "com.mikepenz", name = "aboutlibraries-core", version.ref = "aboutLibraries" }
+
+jellyfin-core = { group = "org.jellyfin.sdk", name = "jellyfin-core", version.ref = "jellyfinSdk" }
+
+coil-compose = { group = "io.coil-kt.coil3", name = "coil-compose", version.ref = "coil" }
+coil-network-ktor3 = { group = "io.coil-kt.coil3", name = "coil-network-ktor3", version.ref = "coil" }
+coil-gif = { group = "io.coil-kt.coil3", name = "coil-gif", version.ref = "coil" }
+
+jetbrains-compose-runtime = { group = "org.jetbrains.compose.runtime", name = "runtime", version.ref = "composeMultiplatform" }
+jetbrains-compose-foundation = { group = "org.jetbrains.compose.foundation", name = "foundation", version.ref = "composeMultiplatform" }
+jetbrains-compose-ui = { group = "org.jetbrains.compose.ui", name = "ui", version.ref = "composeMultiplatform" }
+jetbrains-compose-material3 = { group = "org.jetbrains.compose.material3", name = "material3", version.ref = "composeMultiplatform" }
+jetbrains-compose-material-icons-extended = { group = "org.jetbrains.compose.material", name = "material-icons-extended", version.ref = "composeIconsExtended" }
+
 kotlinx-coroutines-android = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-android", version.ref = "coroutines" }
+kotlinx-coroutines-core = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-core", version.ref = "coroutines" }
+kotlinx-coroutines-swing = { group = "org.jetbrains.kotlinx", name = "kotlinx-coroutines-swing", version.ref = "coroutines" }
 kotlinx-serialization-json = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "serialization" }
 
 androidx-room-runtime = { group = "androidx.room", name = "room-runtime", version.ref = "room" }
 androidx-room-ktx = { group = "androidx.room", name = "room-ktx", version.ref = "room" }
 androidx-room-compiler = { group = "androidx.room", name = "room-compiler", version.ref = "room" }
+androidx-sqlite-bundled = { group = "androidx.sqlite", name = "sqlite-bundled", version.ref = "sqlite" }
 
 jaudiotagger = { group = "com.github.goxr3plus", name = "jaudiotagger", version.ref = "jaudiotagger" }
 
+vlcj = { group = "uk.co.caprica", name = "vlcj", version.ref = "vlcj" }
+dbus-java-core = { group = "com.github.hypfvieh", name = "dbus-java-core", version.ref = "dbusJava" }
+dbus-java-transport-native-unix = { group = "com.github.hypfvieh", name = "dbus-java-transport-native-unixsocket", version.ref = "dbusJava" }
+junixsocket-core = { group = "com.kohlschutter.junixsocket", name = "junixsocket-core", version.ref = "junixsocket" }
+jna = { group = "net.java.dev.jna", name = "jna", version.ref = "jna" }
+jna-platform = { group = "net.java.dev.jna", name = "jna-platform", version.ref = "jna" }
+slf4j-api = { group = "org.slf4j", name = "slf4j-api", version.ref = "slf4j" }
+logback-classic = { group = "ch.qos.logback", name = "logback-classic", version.ref = "logback" }
+
+ktor-client-core = { group = "io.ktor", name = "ktor-client-core", version.ref = "ktor" }
 ktor-client-cio = { group = "io.ktor", name = "ktor-client-cio", version.ref = "ktor" }
 ktor-client-content-negotiation = { group = "io.ktor", name = "ktor-client-content-negotiation", version.ref = "ktor" }
 ktor-client-logging = { group = "io.ktor", name = "ktor-client-logging", version.ref = "ktor" }
 ktor-serialization-kotlinx-json = { group = "io.ktor", name = "ktor-serialization-kotlinx-json", version.ref = "ktor" }
 
-coil-compose = { group = "io.coil-kt.coil3", name = "coil-compose", version.ref = "coil" }
-coil-network-ktor3 = { group = "io.coil-kt.coil3", name = "coil-network-ktor3", version.ref = "coil" }
-coil-gif = { group = "io.coil-kt.coil3", name = "coil-gif", version.ref = "coil" }
-
-jellyfin-core = { group = "org.jellyfin.sdk", name = "jellyfin-core", version.ref = "jellyfinSdk" }
-
-aboutlibraries-core = { group = "com.mikepenz", name = "aboutlibraries-core", version.ref = "aboutLibraries" }
-
 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }
+android-kmp-library = { id = "com.android.kotlin.multiplatform.library", version.ref = "agp" }
+kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
+kotlin-jvm = { id = "org.jetbrains.kotlin.jvm", version.ref = "kotlin" }
 kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
 kotlin-serialization = { id = "org.jetbrains.kotlin.plugin.serialization", version.ref = "kotlin" }
+compose-multiplatform = { id = "org.jetbrains.compose", version.ref = "composeMultiplatform" }
 ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
+androidx-room = { id = "androidx.room", version.ref = "room" }
 aboutlibraries = { id = "com.mikepenz.aboutlibraries.plugin", version.ref = "aboutLibraries" }
 aboutlibraries-android = { id = "com.mikepenz.aboutlibraries.plugin.android", version.ref = "aboutLibraries" }
diff --git a/mediasession/build.gradle.kts b/mediasession/build.gradle.kts
new file mode 100644
index 00000000..70ba2174
--- /dev/null
+++ b/mediasession/build.gradle.kts
@@ -0,0 +1,25 @@
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+}
+
+// Vendored fork of dev.toastbits:mediasession (0.1.1). Kept as a local
+// subproject so we can fix upstream bugs (Float/Double volume marshalling,
+// microsecond seek offsets, missing onSetVolume callback) without waiting
+// on upstream releases.
+kotlin {
+    jvm {
+        compilerOptions {
+            jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+        }
+    }
+
+    sourceSets {
+        jvmMain.dependencies {
+            implementation(libs.dbus.java.core)
+            implementation(libs.dbus.java.transport.native.unix)
+            implementation(libs.junixsocket.core)
+            implementation(libs.jna)
+            implementation(libs.jna.platform)
+        }
+    }
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSession.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSession.kt
new file mode 100644
index 00000000..5a1682e7
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSession.kt
@@ -0,0 +1,31 @@
+package dev.toastbits.mediasession
+
+interface MediaSession: MediaSessionProperties {
+    val enabled: Boolean
+    fun setEnabled(enabled: Boolean)
+
+    var onRaise: (() -> Unit)?
+    var onQuit: (() -> Unit)?
+    var onNext: (() -> Unit)?
+    var onPrevious: (() -> Unit)?
+    var onPause: (() -> Unit)?
+    var onPlayPause: (() -> Unit)?
+    var onStop: (() -> Unit)?
+    var onPlay: (() -> Unit)?
+    var onSeek: ((by_ms: Long) -> Unit)?
+    var onSetPosition: ((to_ms: Long) -> Unit)?
+    var onOpenUri: ((uri: String) -> Unit)?
+    var onSetRate: ((rate: Float) -> Unit)?
+    var onSetLoop: ((loop_mode: MediaSessionLoopMode) -> Unit)?
+    var onSetShuffle: ((shuffle_mode: Boolean) -> Unit)?
+    var onSetVolume: ((volume: Float) -> Unit)?
+
+    fun getPositionMs(): Long = 0
+    fun onPositionChanged()
+
+    companion object {
+        fun create(getPositionMs: (() -> Long)? = null): MediaSession? = createMediaSession(getPositionMs)
+    }
+}
+
+expect fun createMediaSession(getPositionMs: (() -> Long)? = null): MediaSession?
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionLoopMode.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionLoopMode.kt
new file mode 100644
index 00000000..ab6b90ab
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionLoopMode.kt
@@ -0,0 +1,5 @@
+package dev.toastbits.mediasession
+
+enum class MediaSessionLoopMode {
+    NONE, ONE, ALL
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionMetadata.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionMetadata.kt
new file mode 100644
index 00000000..65c19eb2
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionMetadata.kt
@@ -0,0 +1,28 @@
+package dev.toastbits.mediasession
+
+data class MediaSessionMetadata(
+    val track_id: String? = null,
+    val length_ms: Long? = null,
+    val art_url: String? = null,
+    val album: String? = null,
+    val album_artists: List<String>? = null,
+    val artist: String? = null,
+    val lyrics: String? = null,
+    val audio_bpm: Int? = null,
+    val auto_rating: Float? = null,
+    val comment: List<String>? = null,
+    val composer: List<String>? = null,
+    val content_created: String? = null,
+    val disc_number: Int? = null,
+    val first_used: String? = null,
+    val genres: List<String>? = null,
+    val last_used: String? = null,
+    val lyricist: List<String>? = null,
+    val title: String? = null,
+    val track_number: Int? = null,
+    val url: String? = null,
+    val use_count: Int? = null,
+    val user_rating: Float? = null,
+
+    val custom_metadata: Map<String, String> = emptyMap()
+)
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionPlaybackStatus.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionPlaybackStatus.kt
new file mode 100644
index 00000000..8667bf2b
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionPlaybackStatus.kt
@@ -0,0 +1,5 @@
+package dev.toastbits.mediasession
+
+enum class MediaSessionPlaybackStatus {
+    PLAYING, PAUSED, STOPPED
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionProperties.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionProperties.kt
new file mode 100644
index 00000000..6b811cb3
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/MediaSessionProperties.kt
@@ -0,0 +1,29 @@
+package dev.toastbits.mediasession
+
+interface MediaSessionProperties {
+    val identity: String
+    val desktop_entry: String?
+    val supported_uri_schemes: List<String>
+    val supported_mime_types: List<String>
+    val loop_mode: MediaSessionLoopMode
+    val shuffle: Boolean
+    val volume: Float
+    val rate: Float
+    val playback_status: MediaSessionPlaybackStatus
+    val maximum_rate: Float
+    val minimum_rate: Float
+    val metadata: MediaSessionMetadata
+
+    fun setIdentity(identity: String)
+    fun setDesktopEntry(desktop_entry: String?)
+    fun setSupportedUriSchemes(supported_uri_schemes: List<String>)
+    fun setSupportedMimeTypes(supported_mime_types: List<String>)
+    fun setLoopMode(loop_mode: MediaSessionLoopMode)
+    fun setShuffle(shuffle: Boolean)
+    fun setVolume(volume: Float)
+    fun setRate(rate: Float)
+    fun setPlaybackStatus(status: MediaSessionPlaybackStatus)
+    fun setMaximumRate(maximum_rate: Float)
+    fun setMinimumRate(minimum_rate: Float)
+    fun setMetadata(metadata: MediaSessionMetadata)
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/DBusVariant.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/DBusVariant.kt
new file mode 100644
index 00000000..006dca8d
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/DBusVariant.kt
@@ -0,0 +1,9 @@
+package dev.toastbits.mediasession.mpris
+
+expect class DBusVariant<T>
+
+expect val <T> DBusVariant<T>.value: T
+
+expect fun <T> createDBusVariant(value: T, signature: String): DBusVariant<T>
+expect inline fun <reified T> createDBusVariant(value: T): DBusVariant<T>
+expect inline fun <reified T: Any> createDBusVariant(value: Array<T>): DBusVariant<Array<DBusVariant<T>>>
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisConstants.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisConstants.kt
new file mode 100644
index 00000000..361cb09d
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisConstants.kt
@@ -0,0 +1,14 @@
+package dev.toastbits.mediasession.mpris
+
+object MprisConstants {
+    val OBJECT_PATH: String = "/org/mpris/MediaPlayer2"
+
+    enum class Interface(val iface: String) {
+        GENERAL("org.mpris.MediaPlayer2"),
+        PLAYER("org.mpris.MediaPlayer2.Player"),
+        DBUS_PROPERTIES("org.freedesktop.DBus.Properties")
+    }
+
+    fun getBusName(identity: String): String =
+        "org.mpris.MediaPlayer2.$identity"
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSession.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSession.kt
new file mode 100644
index 00000000..119cb541
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSession.kt
@@ -0,0 +1,73 @@
+@file:Suppress("UNCHECKED_CAST")
+package dev.toastbits.mediasession.mpris
+
+import dev.toastbits.mediasession.MediaSessionProperties
+import dev.toastbits.mediasession.MediaSessionLoopMode
+import dev.toastbits.mediasession.MediaSessionMetadata
+import dev.toastbits.mediasession.MediaSessionPlaybackStatus
+
+abstract class MprisMediaSession: MediaSessionProperties {
+    abstract val properties: MprisProperties
+
+    override val identity: String
+        get() = (properties.getProperty(MprisProperty.Identity) as DBusVariant<String>).value
+    override val desktop_entry: String?
+        get() = (properties.getProperty(MprisProperty.DesktopEntry) as DBusVariant<String?>).value
+    override val supported_uri_schemes: List<String>
+        get() = (properties.getProperty(MprisProperty.SupportedUriSchemes) as DBusVariant<List<String>>).value
+    override val supported_mime_types: List<String>
+        get() = (properties.getProperty(MprisProperty.SupportedMimeTypes) as DBusVariant<List<String>>).value
+    override val loop_mode: MediaSessionLoopMode
+        get() = (properties.getProperty(MprisProperty.LoopStatus) as DBusVariant<String?>).value?.fromMprisLoopMode() ?: MediaSessionLoopMode.NONE
+    override val shuffle: Boolean
+        get() = (properties.getProperty(MprisProperty.Shuffle) as DBusVariant<Boolean?>).value ?: false
+    override val volume: Float
+        get() = (properties.getProperty(MprisProperty.Volume) as DBusVariant<Double>).value.toFloat()
+    override val rate: Float
+        get() = (properties.getProperty(MprisProperty.Rate) as DBusVariant<Float>).value
+    override val metadata: MediaSessionMetadata
+        get() = (properties.getProperty(MprisProperty.Metadata) as DBusVariant<Map<String, DBusVariant<*>>>?)?.value?.fromMprisPlayerMetadata(identity) ?: MediaSessionMetadata()
+    override val playback_status: MediaSessionPlaybackStatus
+        get() = (properties.getProperty(MprisProperty.PlaybackStatus) as DBusVariant<String>).value.fromMprisPlaybackStatus()
+    override val maximum_rate: Float
+        get() = (properties.getProperty(MprisProperty.MaximumRate) as DBusVariant<Float>).value
+    override val minimum_rate: Float
+        get() = (properties.getProperty(MprisProperty.MinimumRate) as DBusVariant<Float>).value
+
+    override fun setIdentity(identity: String) = properties.setProperty(MprisProperty.Identity, createDBusVariant(identity))
+    override fun setDesktopEntry(desktop_entry: String?) = properties.setProperty(MprisProperty.DesktopEntry, createDBusVariant(desktop_entry))
+    override fun setSupportedUriSchemes(supported_uri_schemes: List<String>) = properties.setProperty(MprisProperty.SupportedUriSchemes, createDBusVariant(supported_uri_schemes.toTypedArray()))
+    override fun setSupportedMimeTypes(supported_mime_types: List<String>) = properties.setProperty(MprisProperty.SupportedMimeTypes, createDBusVariant(supported_mime_types.toTypedArray()))
+    override fun setLoopMode(loop_mode: MediaSessionLoopMode) = properties.setProperty(MprisProperty.LoopStatus, createDBusVariant(loop_mode.toMprisLoopMode()))
+    override fun setShuffle(shuffle: Boolean) = properties.setProperty(MprisProperty.Shuffle, createDBusVariant(shuffle))
+    override fun setVolume(volume: Float) = properties.setProperty(MprisProperty.Volume, createDBusVariant(volume.toDouble()))
+    override fun setRate(rate: Float) = properties.setProperty(MprisProperty.Rate, createDBusVariant(rate))
+    override fun setPlaybackStatus(status: MediaSessionPlaybackStatus) = properties.setProperty(MprisProperty.PlaybackStatus, createDBusVariant(status.toMprisPlaybackStatus()))
+    override fun setMaximumRate(maximum_rate: Float) = properties.setProperty(MprisProperty.MaximumRate, createDBusVariant(maximum_rate))
+    override fun setMinimumRate(minimum_rate: Float) = properties.setProperty(MprisProperty.MinimumRate, createDBusVariant(minimum_rate))
+
+    override fun setMetadata(metadata: MediaSessionMetadata) =
+        properties.setProperty(
+            MprisProperty.Metadata,
+            createDBusVariant(
+                metadata
+                    .toMprisPlayerMetadata(identity)
+                    .entries
+                    .associate {
+                        val value = it.value
+
+                        try {
+                            if (value is List<*>) {
+                                return@associate it.key to createDBusVariant((value as List<String>).toTypedArray())
+                            }
+
+                            return@associate it.key to createDBusVariant(value)
+                        }
+                        catch (e: Throwable) {
+                            throw RuntimeException("Could not convert metadata key '${it.key}' with value '$value'", e)
+                        }
+                    },
+                "a{sv}"
+            )
+        )
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionLoopMode.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionLoopMode.kt
new file mode 100644
index 00000000..216191e7
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionLoopMode.kt
@@ -0,0 +1,18 @@
+package dev.toastbits.mediasession.mpris
+
+import dev.toastbits.mediasession.MediaSessionLoopMode
+
+fun MediaSessionLoopMode.toMprisLoopMode(): String =
+    when (this) {
+        MediaSessionLoopMode.NONE -> "None"
+        MediaSessionLoopMode.ONE -> "Track"
+        MediaSessionLoopMode.ALL -> "Playlist"
+    }
+
+fun String.fromMprisLoopMode(): MediaSessionLoopMode =
+    when (this) {
+        "None" -> MediaSessionLoopMode.NONE
+        "Track" -> MediaSessionLoopMode.ONE
+        "Playlist" -> MediaSessionLoopMode.ALL
+        else -> throw NotImplementedError("Unknown loop status '$this'")
+    }
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionMetadata.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionMetadata.kt
new file mode 100644
index 00000000..798b7015
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionMetadata.kt
@@ -0,0 +1,102 @@
+package dev.toastbits.mediasession.mpris
+
+import dev.toastbits.mediasession.MediaSessionMetadata
+import kotlin.text.Regex
+
+@Suppress("UNCHECKED_CAST")
+fun MediaSessionMetadata.toMprisPlayerMetadata(identity: String): Map<String, Any> {
+    val track_id_error: String? = track_id?.let { getTrackIdError(it) }
+    check(track_id_error == null) {
+        "Track ID '$track_id' is not a valid DBus object path. $track_id_error. (See https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path)"
+    }
+
+    return mutableMapOf(
+        "mpris:trackid" to track_id,
+        "mpris:length" to length_ms?.times(1000L),
+        "mpris:artUrl" to art_url,
+        "xesam:album" to album,
+        "xesam:albumArtist" to album_artists,
+        "xesam:artist" to artist,
+        "xesam:asText" to lyrics,
+        "xesam:audioBPM" to audio_bpm,
+        "xesam:autoRating" to auto_rating,
+        "xesam:comment" to comment,
+        "xesam:composer" to composer,
+        "xesam:contentCreated" to content_created,
+        "xesam:discNumber" to disc_number,
+        "xesam:firstUsed" to first_used,
+        "xesam:genre" to genres,
+        "xesam:lastUsed" to last_used,
+        "xesam:lyricist" to lyricist,
+        "xesam:title" to title,
+        "xesam:trackNumber" to track_number,
+        "xesam:url" to url,
+        "xesam:useCount" to use_count,
+        "xesam:userRating" to user_rating
+    )
+    .also { map ->
+        for ((key, value) in custom_metadata) {
+            map["$identity:$key"] = value
+        }
+    }
+    .filter { it.value != null } as Map<String, Any>
+}
+
+@Suppress("UNCHECKED_CAST")
+fun Map<String, DBusVariant<*>>.fromMprisPlayerMetadata(identity: String): MediaSessionMetadata {
+    val default: MediaSessionMetadata = MediaSessionMetadata()
+    val custom_prefix: String = identity + ":"
+
+    return MediaSessionMetadata(
+        track_id = (get("mpris:trackid")?.value ?: default.track_id) as String?,
+        length_ms = (get("mpris:length")?.value as Long?)?.div(1000L) ?: default.length_ms,
+        art_url = (get("mpris:artUrl")?.value ?: default.art_url) as String?,
+        album = (get("xesam:album")?.value ?: default.album) as String?,
+        album_artists = (get("xesam:albumArtist")?.value as Array<DBusVariant<*>>?)?.toStringList() ?: default.album_artists,
+        artist = (get("xesam:artist")?.value ?: default.artist) as String?,
+        lyrics = (get("xesam:asText")?.value ?: default.lyrics) as String?,
+        audio_bpm = (get("xesam:audioBPM")?.value ?: default.audio_bpm) as Int?,
+        auto_rating = (get("xesam:autoRating")?.value ?: default.auto_rating) as Float?,
+        comment = (get("xesam:comment")?.value as Array<DBusVariant<*>>?)?.toStringList() ?: default.comment,
+        composer = (get("xesam:composer")?.value as Array<DBusVariant<*>>?)?.toStringList() ?: default.composer,
+        content_created = (get("xesam:contentCreated")?.value ?: default.content_created) as String?,
+        disc_number = (get("xesam:discNumber")?.value ?: default.disc_number) as Int?,
+        first_used = (get("xesam:firstUsed")?.value ?: default.first_used) as String?,
+        genres = (get("xesam:genre")?.value as Array<DBusVariant<*>>?)?.toStringList() ?: default.genres,
+        last_used = (get("xesam:lastUsed")?.value ?: default.last_used) as String?,
+        lyricist = (get("xesam:lyricist")?.value as Array<DBusVariant<*>>?)?.toStringList() ?: default.lyricist,
+        title = (get("xesam:title")?.value ?: default.title) as String?,
+        track_number = (get("xesam:trackNumber")?.value ?: default.track_number) as Int?,
+        url = (get("xesam:url")?.value ?: default.url) as String?,
+        use_count = (get("xesam:useCount")?.value ?: default.use_count) as Int?,
+        user_rating = (get("xesam:userRating")?.value ?: default.user_rating) as Float?,
+        custom_metadata = mapNotNull { entry ->
+            if (!entry.key.startsWith(custom_prefix)) {
+                return@mapNotNull null
+            }
+
+            val value: String = (entry.value.value as String?) ?: return@mapNotNull null
+            return@mapNotNull entry.key.drop(custom_prefix.length) to value
+        }.toMap()
+    )
+}
+
+fun Array<DBusVariant<*>>.toStringList(): List<String> =
+    map { it.value as String }
+
+fun getTrackIdError(id: String): String? {
+    if (!id.startsWith("/")) {
+        return "ID doesn't begin with '/'"
+    }
+
+    val parts: List<String> = id.split('/').filter { it.isNotEmpty() }
+    val part_regex: Regex = Regex("^[A-Za-z0-9_]+\$")
+
+    for ((index, part) in parts.withIndex()) {
+        if (!part_regex.matches(part)) {
+            return "Part ${index + 1} '$part' contains illegal character(s)"
+        }
+    }
+
+    return null
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionPlaybackStatus.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionPlaybackStatus.kt
new file mode 100644
index 00000000..75b468e0
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisMediaSessionPlaybackStatus.kt
@@ -0,0 +1,18 @@
+package dev.toastbits.mediasession.mpris
+
+import dev.toastbits.mediasession.MediaSessionPlaybackStatus
+
+fun MediaSessionPlaybackStatus.toMprisPlaybackStatus(): String =
+    when (this) {
+        MediaSessionPlaybackStatus.PLAYING -> "Playing"
+        MediaSessionPlaybackStatus.PAUSED -> "Paused"
+        MediaSessionPlaybackStatus.STOPPED -> "Stopped"
+    }
+
+fun String.fromMprisPlaybackStatus(): MediaSessionPlaybackStatus =
+    when (this) {
+        "Playing" -> MediaSessionPlaybackStatus.PLAYING
+        "Paused" -> MediaSessionPlaybackStatus.PAUSED
+        "Stopped" -> MediaSessionPlaybackStatus.STOPPED
+        else -> throw NotImplementedError("Unknown playback status '$this'")
+    }
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisProperties.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisProperties.kt
new file mode 100644
index 00000000..f94def4b
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisProperties.kt
@@ -0,0 +1,67 @@
+package dev.toastbits.mediasession.mpris
+
+import dev.toastbits.mediasession.MediaSession
+import dev.toastbits.mediasession.MediaSessionMetadata
+
+abstract class MprisProperties {
+    protected abstract val session: MediaSession
+    protected abstract fun emitPropertyChange(property: MprisProperty, value: DBusVariant<*>?)
+
+    var metadata: MediaSessionMetadata = MediaSessionMetadata()
+        private set
+
+    private val properties: MutableMap<MprisProperty, DBusVariant<*>?> =
+        mutableMapOf(
+            MprisProperty.HasTrackList to createDBusVariant(false),
+            MprisProperty.Identity to createDBusVariant("mediasessionkt"),
+            MprisProperty.DesktopEntry to null,
+            MprisProperty.SupportedUriSchemes to createDBusVariant(emptyArray<String>()),
+            MprisProperty.SupportedMimeTypes to createDBusVariant(emptyArray<String>()),
+            MprisProperty.PlaybackStatus to createDBusVariant("Stopped"),
+            MprisProperty.LoopStatus to createDBusVariant("None"),
+            MprisProperty.Rate to createDBusVariant(1.0),
+            MprisProperty.Shuffle to createDBusVariant(false),
+            MprisProperty.Metadata to createDBusVariant(emptyMap<String, DBusVariant<*>>(), "a{sv}"),
+            MprisProperty.Volume to createDBusVariant(1.0),
+            MprisProperty.MaximumRate to createDBusVariant(1.0),
+            MprisProperty.MinimumRate to createDBusVariant(1.0),
+        )
+
+    fun getProperty(property: MprisProperty): DBusVariant<*>? =
+        when (property) {
+            MprisProperty.Position -> createDBusVariant(session.getPositionMs() * 1000)
+            MprisProperty.CanRaise -> createDBusVariant(session.onRaise != null)
+            MprisProperty.CanQuit -> createDBusVariant(session.onQuit != null)
+            MprisProperty.CanGoNext -> createDBusVariant(session.onNext != null)
+            MprisProperty.CanGoPrevious -> createDBusVariant(session.onPrevious != null)
+            MprisProperty.CanPlay -> createDBusVariant(session.onPlay != null)
+            MprisProperty.CanPause -> createDBusVariant(session.onPause != null)
+            MprisProperty.CanSeek -> createDBusVariant(session.onSeek != null)
+            MprisProperty.CanControl -> createDBusVariant(true)
+            else -> {
+                if (!properties.contains(property)) {
+                    throw NotImplementedError(property.toString())
+                }
+
+                properties[property]
+            }
+        }
+
+    inline fun forEachProperty(action: (MprisProperty, DBusVariant<*>) -> Unit) {
+        for (property in MprisProperty.entries) {
+            val value: DBusVariant<*> = getProperty(property) ?: continue
+            action(property, value)
+        }
+    }
+
+    fun setProperty(property: MprisProperty, value: DBusVariant<*>?) {
+        onPropertySet(property, value)
+        emitPropertyChange(property, value)
+    }
+
+    protected fun onPropertySet(property: MprisProperty, value: DBusVariant<*>?) {
+        if (properties.contains(property)) {
+            properties[property] = value
+        }
+    }
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisProperty.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisProperty.kt
new file mode 100644
index 00000000..c278911b
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/mpris/MprisProperty.kt
@@ -0,0 +1,39 @@
+package dev.toastbits.mediasession.mpris
+
+enum class MprisProperty {
+    CanRaise,
+    CanQuit,
+    CanGoNext,
+    CanGoPrevious,
+    CanPlay,
+    CanPause,
+    CanSeek,
+    CanControl,
+
+    HasTrackList,
+    Identity,
+    DesktopEntry,
+    SupportedUriSchemes,
+    SupportedMimeTypes,
+    PlaybackStatus,
+    LoopStatus,
+    Rate,
+    Shuffle,
+    Metadata,
+    Volume,
+    Position,
+    MaximumRate,
+    MinimumRate;
+
+    fun getInterface(): MprisConstants.Interface =
+        when (this) {
+            CanQuit,
+            CanRaise,
+            HasTrackList,
+            Identity,
+            DesktopEntry,
+            SupportedUriSchemes,
+            SupportedMimeTypes -> MprisConstants.Interface.GENERAL
+            else -> MprisConstants.Interface.PLAYER
+        }
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/smtc/SMTCAdapter.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/smtc/SMTCAdapter.kt
new file mode 100644
index 00000000..f0cccc56
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/smtc/SMTCAdapter.kt
@@ -0,0 +1,84 @@
+package dev.toastbits.mediasession.smtc
+
+import dev.toastbits.mediasession.MediaSessionLoopMode
+
+interface SMTCAdapter {
+    fun init(): Int
+
+    var onPause: (() -> Unit)?
+    var onStop: (() -> Unit)?
+    var onPlay: (() -> Unit)?
+    var onNext: (() -> Unit)?
+    var onPrevious: (() -> Unit)?
+    var onSetPosition: ((to_ms: Long) -> Unit)?
+    var onSetRate: ((rate: Float) -> Unit)?
+    var onSetLoop: ((loop_mode: Int) -> Unit)?
+    var onSetShuffle: ((shuffle_mode: Boolean) -> Unit)?
+
+    fun revokeCallbacks()
+
+    fun getEnabled(): Boolean
+    fun setEnabled(enabled: Boolean)
+
+    fun getNextEnabled(): Boolean
+    fun setNextEnabled(enabled: Boolean)
+
+    fun getPreviousEnabled(): Boolean
+    fun setPreviousEnabled(enabled: Boolean)
+
+    fun getPlayEnabled(): Boolean
+    fun setPlayEnabled(enabled: Boolean)
+
+    fun getPauseEnabled(): Boolean
+    fun setPauseEnabled(enabled: Boolean)
+
+    fun getStopEnabled(): Boolean
+    fun setStopEnabled(enabled: Boolean)
+
+    fun getRate(): Double
+    fun setRate(rate: Double)
+
+    fun getShuffle(): Boolean
+    fun setShuffle(shuffle: Boolean)
+
+    fun getLoop(): Int
+    fun setLoop(loop: Int)
+
+    fun getPlaybackState(): Int
+    fun setPlaybackState(state: Int)
+
+    fun setTimelineProperties(start: Long, end: Long, seek_start: Long, seek_end: Long)
+    fun setPosition(position: Long)
+
+    fun update()
+    fun reset()
+
+    fun getMediaType(): Int
+    fun setMediaType(type: Int)
+
+    fun thumbnailLoaded(): Boolean
+    fun setThumbnail(path: String, update_when_loaded: Boolean)
+
+    fun getMusicTitle(): String
+    fun setMusicTitle(title: String)
+
+    fun getMusicArtist(): String
+    fun setMusicArtist(artist: String)
+
+    fun getMusicAlbumTitle(): String
+    fun setMusicAlbumTitle(title: String)
+
+    fun getMusicAlbumArtist(): String
+    fun setMusicAlbumArtist(artist: String)
+
+    fun getMusicGenresSize(): Int
+    fun getMusicGenreAt(index: Int): String
+    fun addMusicGenre(genre: String)
+    fun clearMusicGenres()
+
+    fun getMusicAlbumTrackCount(): Int
+    fun setMusicAlbumTrackCount(count: Int)
+
+    fun getMusicTrack(): Int
+    fun setMusicTrack(track: Int)
+}
diff --git a/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/smtc/SMTCMediaSession.kt b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/smtc/SMTCMediaSession.kt
new file mode 100644
index 00000000..4f7acc13
--- /dev/null
+++ b/mediasession/src/commonMain/kotlin/dev/toastbits/mediasession/smtc/SMTCMediaSession.kt
@@ -0,0 +1,246 @@
+package dev.toastbits.mediasession.smtc
+
+import dev.toastbits.mediasession.MediaSessionProperties
+import dev.toastbits.mediasession.MediaSession
+import dev.toastbits.mediasession.MediaSessionLoopMode
+import dev.toastbits.mediasession.MediaSessionMetadata
+import dev.toastbits.mediasession.MediaSessionPlaybackStatus
+
+open class SMTCMediaSession(private val smtc: SMTCAdapter): MediaSessionProperties, MediaSession {
+    private var session_enabled: Boolean = false
+    private var _art_url: String? = null
+
+    override val enabled: Boolean
+        get() = session_enabled
+
+    init {
+        val result: Int = 
+            try {
+                smtc.init()
+            }
+            catch (e: Throwable) {
+                throw RuntimeException("Failed to initialise smtc", e)
+            }
+        
+        if (result != 0) {
+            throw RuntimeException("Failed to initialise smtc ($result), is Windows.Media.Playback.MediaPlayer available?")
+        }
+    }
+
+    override fun setEnabled(enabled: Boolean) {
+        if (enabled == session_enabled) {
+            return
+        }
+
+        smtc.setEnabled(enabled)
+        session_enabled = enabled
+
+        if (enabled) {
+            update()
+        }
+    }
+
+    override var onRaise: (() -> Unit)? = null
+    override var onQuit: (() -> Unit)? = null
+
+    override var onNext: (() -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onNext = value
+            smtc.setNextEnabled(value != null)
+        }
+    override var onPrevious: (() -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onPrevious = value
+            smtc.setPreviousEnabled(value != null)
+        }
+
+    override var onPause: (() -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onPause = value
+        }
+    override var onStop: (() -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onStop = value
+        }
+    override var onPlay: (() -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onPlay = value
+        }
+    override var onSetPosition: ((to_ms: Long) -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onSetPosition = value
+        }
+    override var onSetRate: ((rate: Float) -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onSetRate = value
+        }
+    override var onSetLoop: ((loop_mode: MediaSessionLoopMode) -> Unit)? = null
+        set(value) {
+            field = value
+
+            if (value == null) {
+                smtc.onSetLoop = null
+            }
+            else {
+                smtc.onSetLoop = { loop_mode ->
+                    value.invoke(loop_mode.toLoopMode())
+                }
+            }
+        }
+    override var onSetShuffle: ((shuffle_mode: Boolean) -> Unit)? = null
+        set(value) {
+            field = value
+            smtc.onSetShuffle = value
+        }
+    
+    override var onPlayPause: (() -> Unit)? = null
+    override var onSeek: ((by_ms: Long) -> Unit)? = null
+    override var onOpenUri: ((uri: String) -> Unit)? = null
+    override var onSetVolume: ((volume: Float) -> Unit)? = null
+
+    override fun onPositionChanged() {
+        smtc.setPosition(getPositionMs())
+    }
+
+    override val identity: String
+        get() = ""
+    override val desktop_entry: String?
+        get() = null
+    override val supported_uri_schemes: List<String>
+        get() = emptyList()
+    override val supported_mime_types: List<String>
+        get() = emptyList()
+    override val loop_mode: MediaSessionLoopMode
+        get() = smtc.getLoop().toLoopMode()
+    override val shuffle: Boolean
+        get() = smtc.getShuffle()
+    override val volume: Float
+        get() = 0f
+    override val rate: Float
+        get() = smtc.getRate().toFloat()
+    override val metadata: MediaSessionMetadata
+        get() = MediaSessionMetadata(
+            track_id = null,
+            length_ms = null,
+            art_url = _art_url,
+            album = smtc.getMusicAlbumTitle(),
+            album_artists = listOfNotNull(smtc.getMusicAlbumArtist()),
+            artist = smtc.getMusicArtist(),
+            lyrics = null,
+            audio_bpm = null,
+            auto_rating = null,
+            comment = null,
+            composer = null,
+            content_created = null,
+            disc_number = null,
+            first_used = null,
+            genres = (0 until smtc.getMusicGenresSize()).mapNotNull { i -> smtc.getMusicGenreAt(i) },
+            last_used = null,
+            lyricist = null,
+            title = smtc.getMusicTitle(),
+            track_number = smtc.getMusicTrack().toInt(),
+            url = null,
+            use_count = null,
+            user_rating = null
+        )
+    override val playback_status: MediaSessionPlaybackStatus
+        get() =
+            when (smtc.getPlaybackState()) {
+                0 -> MediaSessionPlaybackStatus.STOPPED
+                1 -> MediaSessionPlaybackStatus.PAUSED
+                2 -> MediaSessionPlaybackStatus.STOPPED
+                3 -> MediaSessionPlaybackStatus.PLAYING
+                4 -> MediaSessionPlaybackStatus.PAUSED
+                else -> MediaSessionPlaybackStatus.STOPPED
+            }
+    override val maximum_rate: Float
+        get() = 1f
+    override val minimum_rate: Float
+        get() = 0f
+
+    override fun setIdentity(identity: String) {}
+
+    override fun setDesktopEntry(desktop_entry: String?) {}
+
+    override fun setSupportedUriSchemes(supported_uri_schemes: List<String>) {}
+
+    override fun setSupportedMimeTypes(supported_mime_types: List<String>) {}
+
+    override fun setLoopMode(loop_mode: MediaSessionLoopMode) {
+        smtc.setLoop(loop_mode.toInt())
+        update()
+    }
+    override fun setShuffle(shuffle: Boolean) {
+        smtc.setShuffle(shuffle)
+        update()
+    }
+    override fun setVolume(volume: Float) {
+        // TODO
+    }
+    override fun setRate(rate: Float) {
+        smtc.setRate(rate.toDouble())
+        update()
+    }
+    override fun setPlaybackStatus(status: MediaSessionPlaybackStatus) {
+        smtc.setPlaybackState(
+            when (status) {
+                MediaSessionPlaybackStatus.PLAYING -> 3
+                MediaSessionPlaybackStatus.PAUSED -> 1
+                MediaSessionPlaybackStatus.STOPPED -> 2
+            }
+        )
+        update()
+    }
+    override fun setMaximumRate(maximum_rate: Float) {}
+    override fun setMinimumRate(minimum_rate: Float) {}
+
+    override fun setMetadata(metadata: MediaSessionMetadata) {
+        smtc.setMusicTitle(metadata.title ?: "")
+        smtc.setMusicArtist(metadata.artist ?: "")
+        smtc.setMusicAlbumTitle(metadata.album ?: "")
+        smtc.setMusicAlbumArtist(metadata.album_artists?.firstOrNull() ?: "")
+        smtc.setMusicTrack(metadata.track_number ?: 0)
+
+        smtc.setThumbnail((metadata.art_url ?: "").replace("/", "\\"), true)
+        _art_url = metadata.art_url
+
+        smtc.clearMusicGenres()
+        for (genre in metadata.genres ?: emptyList()) {
+            smtc.addMusicGenre(genre)
+        }
+
+        val length: Long = metadata.length_ms ?: 0
+        smtc.setTimelineProperties(0, length, 0, length)
+
+        update()
+    }
+
+    private fun update() {
+        if (enabled) {
+            smtc.update()
+        }
+    }
+}
+
+private fun Int.toLoopMode(): MediaSessionLoopMode =
+    when (this) {
+        0 -> MediaSessionLoopMode.NONE
+        1 -> MediaSessionLoopMode.ONE
+        2 -> MediaSessionLoopMode.ALL
+        else -> throw NotImplementedError(this.toString())
+    }
+
+
+private fun MediaSessionLoopMode.toInt(): Int =
+    when (this) {
+        MediaSessionLoopMode.NONE -> 0
+        MediaSessionLoopMode.ONE -> 1
+        MediaSessionLoopMode.ALL -> 2
+    }
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/MediaSession.jvm.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/MediaSession.jvm.kt
new file mode 100644
index 00000000..25044d6e
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/MediaSession.jvm.kt
@@ -0,0 +1,23 @@
+package dev.toastbits.mediasession
+
+import dev.toastbits.mediasession.linux.LinuxMediaSession
+import dev.toastbits.mediasession.smtc.SMTCMediaSession
+import dev.toastbits.mediasession.smtc.JniSMTCAdapter
+
+actual fun createMediaSession(getPositionMs: (() -> Long)?): MediaSession? {
+    val os: String = System.getProperty("os.name").lowercase()
+
+    if (os.startsWith("windows")) {
+        return object : SMTCMediaSession(JniSMTCAdapter()) {
+            override fun getPositionMs(): Long = getPositionMs?.invoke() ?: super.getPositionMs()
+        }
+    }
+
+    if (os.contains("linux")) {
+        return object : LinuxMediaSession() {
+            override fun getPositionMs(): Long = getPositionMs?.invoke() ?: super.getPositionMs()
+        }
+    }
+
+    return null
+}
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/LinuxMediaSession.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/LinuxMediaSession.kt
new file mode 100644
index 00000000..dddbc338
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/LinuxMediaSession.kt
@@ -0,0 +1,61 @@
+package dev.toastbits.mediasession.linux
+
+import dev.toastbits.mediasession.*
+import dev.toastbits.mediasession.mpris.MprisMediaSession
+import dev.toastbits.mediasession.mpris.MprisProperties
+import org.freedesktop.dbus.connections.impl.DBusConnection
+import org.freedesktop.dbus.connections.impl.DBusConnectionBuilder
+
+@Suppress("UNCHECKED_CAST")
+open class LinuxMediaSession: MprisMediaSession(), MediaSession, MediaSessionProperties {
+    private var session_enabled: Boolean = false
+    private val connection: DBusConnection = DBusConnectionBuilder.forSessionBus().build()
+
+    private val session_interface: SessionInterface = SessionInterface(this, connection)
+    override val properties: MprisProperties = session_interface
+
+    override val enabled: Boolean
+        get() = session_enabled
+
+    override fun setEnabled(enabled: Boolean) {
+        if (enabled == session_enabled) {
+            return
+        }
+
+        if (enabled) {
+            connection.requestBusName("org.mpris.MediaPlayer2.$identity")
+            connection.exportObject(session_interface.getObjectPath(), session_interface)
+            session_enabled = true
+        }
+        else {
+            connection.unExportObject(session_interface.getObjectPath())
+            connection.releaseBusName("org.mpris.MediaPlayer2.$identity")
+            session_enabled = false
+        }
+    }
+
+    override var onRaise: (() -> Unit)? = null
+    override var onQuit: (() -> Unit)? = null
+    override var onNext: (() -> Unit)? = null
+    override var onPrevious: (() -> Unit)? = null
+    override var onPause: (() -> Unit)? = null
+    override var onPlayPause: (() -> Unit)? = null
+    override var onStop: (() -> Unit)? = null
+    override var onPlay: (() -> Unit)? = null
+    override var onSeek: ((by_ms: Long) -> Unit)? = null
+    override var onSetPosition: ((to_ms: Long) -> Unit)? = null
+    override var onOpenUri: ((uri: String) -> Unit)? = null
+    override var onSetRate: ((rate: Float) -> Unit)? = null
+    override var onSetLoop: ((loop_mode: MediaSessionLoopMode) -> Unit)? = null
+    override var onSetShuffle: ((shuffle_mode: Boolean) -> Unit)? = null
+    override var onSetVolume: ((volume: Float) -> Unit)? = null
+
+    override fun onPositionChanged() {
+        connection.sendMessage(
+            PlayerInterface.Seeked(
+                session_interface.getObjectPath(),
+                getPositionMs()
+            )
+        )
+    }
+}
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/MediaInterface.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/MediaInterface.kt
new file mode 100644
index 00000000..e08a9e7b
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/MediaInterface.kt
@@ -0,0 +1,10 @@
+package dev.toastbits.mediasession
+
+import org.freedesktop.dbus.annotations.DBusInterfaceName
+import org.freedesktop.dbus.interfaces.DBusInterface
+
+@DBusInterfaceName("org.mpris.MediaPlayer2")
+internal interface MediaInterface: DBusInterface {
+    fun Raise()
+    fun Quit()
+}
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/MediaSessionLinux.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/MediaSessionLinux.kt
new file mode 100644
index 00000000..6e9c12c3
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/MediaSessionLinux.kt
@@ -0,0 +1,61 @@
+package dev.toastbits.mediasession.linux
+
+import dev.toastbits.mediasession.*
+import dev.toastbits.mediasession.mpris.MprisMediaSession
+import dev.toastbits.mediasession.mpris.MprisProperties
+import org.freedesktop.dbus.connections.impl.DBusConnection
+import org.freedesktop.dbus.connections.impl.DBusConnectionBuilder
+
+@Suppress("UNCHECKED_CAST")
+open class MediaSessionLinux: MprisMediaSession(), MediaSession, MediaSessionProperties {
+    private var session_enabled: Boolean = false
+    private val connection: DBusConnection = DBusConnectionBuilder.forSessionBus().build()
+
+    private val session_interface: SessionInterface = SessionInterface(this, connection)
+    override val properties: MprisProperties = session_interface
+
+    override val enabled: Boolean
+        get() = session_enabled
+
+    override fun setEnabled(enabled: Boolean) {
+        if (enabled == session_enabled) {
+            return
+        }
+
+        if (enabled) {
+            connection.requestBusName("org.mpris.MediaPlayer2.$identity")
+            connection.exportObject(session_interface.getObjectPath(), session_interface)
+            session_enabled = true
+        }
+        else {
+            connection.unExportObject(session_interface.getObjectPath())
+            connection.releaseBusName("org.mpris.MediaPlayer2.$identity")
+            session_enabled = false
+        }
+    }
+
+    override var onRaise: (() -> Unit)? = null
+    override var onQuit: (() -> Unit)? = null
+    override var onNext: (() -> Unit)? = null
+    override var onPrevious: (() -> Unit)? = null
+    override var onPause: (() -> Unit)? = null
+    override var onPlayPause: (() -> Unit)? = null
+    override var onStop: (() -> Unit)? = null
+    override var onPlay: (() -> Unit)? = null
+    override var onSeek: ((by_ms: Long) -> Unit)? = null
+    override var onSetPosition: ((to_ms: Long) -> Unit)? = null
+    override var onOpenUri: ((uri: String) -> Unit)? = null
+    override var onSetRate: ((rate: Float) -> Unit)? = null
+    override var onSetLoop: ((loop_mode: MediaSessionLoopMode) -> Unit)? = null
+    override var onSetShuffle: ((shuffle_mode: Boolean) -> Unit)? = null
+    override var onSetVolume: ((volume: Float) -> Unit)? = null
+
+    override fun onPositionChanged() {
+        connection.sendMessage(
+            PlayerInterface.Seeked(
+                session_interface.getObjectPath(),
+                getPositionMs()
+            )
+        )
+    }
+}
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/PlayerInterface.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/PlayerInterface.kt
new file mode 100644
index 00000000..de17c803
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/PlayerInterface.kt
@@ -0,0 +1,36 @@
+package dev.toastbits.mediasession
+
+import org.freedesktop.dbus.annotations.DBusInterfaceName
+import org.freedesktop.dbus.annotations.DBusProperty
+import org.freedesktop.dbus.annotations.DBusProperty.Access
+import org.freedesktop.dbus.interfaces.DBusInterface
+import org.freedesktop.dbus.DBusPath
+import org.freedesktop.dbus.messages.DBusSignal
+
+@DBusInterfaceName("org.mpris.MediaPlayer2.Player")
+@DBusProperty(name = "Metadata", type = Map::class, access = Access.READ)
+@DBusProperty(name = "PlaybackStatus", type = String::class, access = Access.READ)
+@DBusProperty(name = "LoopStatus", type = String::class)
+@DBusProperty(name = "Volume", type = Double::class)
+@DBusProperty(name = "Shuffle", type = Boolean::class)
+@DBusProperty(name = "Position", type = Long::class, access = Access.READ)
+@DBusProperty(name = "Rate", type = Double::class)
+@DBusProperty(name = "MinimumRate", type = Double::class)
+@DBusProperty(name = "MaximumRate", type = Double::class)
+@DBusProperty(name = "CanControl", type = Boolean::class, access = Access.READ)
+@DBusProperty(name = "CanPlay", type = Boolean::class, access = Access.READ)
+@DBusProperty(name = "CanPause", type = Boolean::class, access = Access.READ)
+@DBusProperty(name = "CanSeek", type = Boolean::class, access = Access.READ)
+internal interface PlayerInterface: DBusInterface {
+    fun Next()
+    fun Previous()
+    fun Pause()
+    fun PlayPause()
+    fun Stop()
+    fun Play()
+    fun Seek(by_us: Long)
+    fun SetPosition(arg0: DBusPath, to_us: Long)
+    fun OpenUri(uri: String)
+
+    class Seeked(path: String, position_ms: Long): DBusSignal(path, position_ms * 1000)
+}
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/SessionInterface.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/SessionInterface.kt
new file mode 100644
index 00000000..d985cfe9
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/linux/SessionInterface.kt
@@ -0,0 +1,101 @@
+package dev.toastbits.mediasession
+
+import dev.toastbits.mediasession.mpris.DBusVariant
+import dev.toastbits.mediasession.mpris.MprisConstants
+import dev.toastbits.mediasession.mpris.MprisProperties
+import org.freedesktop.dbus.DBusPath
+import org.freedesktop.dbus.connections.impl.DBusConnection
+import org.freedesktop.dbus.interfaces.Properties
+import org.freedesktop.dbus.types.Variant
+import dev.toastbits.mediasession.mpris.MprisProperty
+import dev.toastbits.mediasession.mpris.fromMprisLoopMode
+
+internal class SessionInterface(
+    override val session: MediaSession,
+    private val connection: DBusConnection
+): MprisProperties(), MediaInterface, PlayerInterface, Properties {
+    override fun emitPropertyChange(property: MprisProperty, value: DBusVariant<*>?) {
+        connection.sendMessage(
+            Properties.PropertiesChanged(
+                objectPath,
+                property.getInterface().iface,
+                mapOf(
+                    property.name to value
+                ),
+                emptyList()
+            )
+        )
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    override fun <A> Get(interface_name: String, property_name: String): A? {
+        val property: MprisProperty =
+            MprisProperty.entries.firstOrNull { it.name == property_name } ?: return null
+        return getProperty(property) as A?
+    }
+
+    override fun <A> Set(interface_name: String, property_name: String, value: A) {
+        when (property_name) {
+            "LoopStatus" -> {
+                session.onSetLoop?.invoke((value as String).fromMprisLoopMode())
+            }
+            "Shuffle" -> {
+                session.onSetShuffle?.invoke(value as Boolean)
+            }
+            "Rate" -> {
+                session.onSetRate?.invoke((value as Double).toFloat())
+            }
+            "Volume" -> {
+                session.onSetVolume?.invoke((value as Double).toFloat())
+            }
+        }
+
+        val property: MprisProperty =
+            MprisProperty.entries.firstOrNull { it.name == property_name } ?: return
+        onPropertySet(property, Variant(value))
+    }
+
+    override fun GetAll(interface_name: String): Map<String, Variant<*>> =
+        buildMap {
+            forEachProperty { key, value ->
+                put(key.name, value)
+            }
+        }
+
+    override fun Raise() {
+        session.onRaise?.invoke()
+    }
+    override fun Quit() {
+        session.onQuit?.invoke()
+    }
+    override fun Next() {
+        session.onNext?.invoke()
+    }
+    override fun Previous() {
+        session.onPrevious?.invoke()
+    }
+    override fun Pause() {
+        session.onPause?.invoke()
+    }
+    override fun PlayPause() {
+        session.onPlayPause?.invoke()
+    }
+    override fun Stop() {
+        session.onStop?.invoke()
+    }
+    override fun Play() {
+        session.onPlay?.invoke()
+    }
+    override fun Seek(by_us: Long) {
+        session.onSeek?.invoke(by_us / 1000)
+    }
+    override fun SetPosition(arg0: DBusPath, to_us: Long) {
+        session.onSetPosition?.invoke(to_us / 1000)
+    }
+    override fun OpenUri(uri: String) {
+        session.onOpenUri?.invoke(uri)
+    }
+
+    override fun getObjectPath(): String =
+        MprisConstants.OBJECT_PATH
+}
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/mpris/DBusVariant.jvm.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/mpris/DBusVariant.jvm.kt
new file mode 100644
index 00000000..b3477f7b
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/mpris/DBusVariant.jvm.kt
@@ -0,0 +1,19 @@
+package dev.toastbits.mediasession.mpris
+
+import org.freedesktop.dbus.types.Variant
+
+actual typealias DBusVariant<T> = Variant<T>
+
+actual val <T> DBusVariant<T>.value: T get() = this.value
+
+actual fun <T> createDBusVariant(
+    value: T,
+    signature: String
+): DBusVariant<T> =
+    Variant(value, signature)
+
+actual inline fun <reified T> createDBusVariant(value: T): DBusVariant<T> =
+    Variant(value)
+
+actual inline fun <reified T : Any> createDBusVariant(value: Array<T>): DBusVariant<Array<DBusVariant<T>>> =
+    Variant(Array(value.size) { Variant(value[it]) })
diff --git a/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/smtc/JniSMTCAdapter.kt b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/smtc/JniSMTCAdapter.kt
new file mode 100644
index 00000000..7266a4a4
--- /dev/null
+++ b/mediasession/src/jvmMain/kotlin/dev/toastbits/mediasession/smtc/JniSMTCAdapter.kt
@@ -0,0 +1,218 @@
+package dev.toastbits.mediasession.smtc
+
+import com.sun.jna.Native
+import com.sun.jna.Library
+import com.sun.jna.win32.W32APIOptions
+import com.sun.jna.Pointer
+import com.sun.jna.Callback
+import dev.toastbits.mediasession.MediaSessionLoopMode
+
+class JniSMTCAdapter: SMTCAdapter {
+    private lateinit var libsmtc: SMTCAdapterLibrary
+
+    private var onPauseCallback: Callback? = null
+    private var onStopCallback: Callback? = null
+    private var onPlayCallback: Callback? = null
+    private var onNextCallback: Callback? = null
+    private var onPreviousCallback: Callback? = null
+    private var onSetPositionCallback: Callback? = null
+    private var onSetRateCallback: Callback? = null
+    private var onSetLoopCallback: Callback? = null
+    private var onSetShuffleCallback: Callback? = null
+
+    override fun init(): Int {
+        libsmtc = 
+            Native.loadLibrary(
+                "libSMTCAdapter.dll",
+                SMTCAdapterLibrary::class.java,
+                W32APIOptions.DEFAULT_OPTIONS
+            )
+
+        val result: Int = libsmtc.init()
+        if (result != 0) {
+            return result
+        }
+
+        libsmtc.setMediaType(0)
+        return 0
+    }
+
+    override var onPause: (() -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { Callback1(it) }
+            libsmtc.setOnPause(callback)
+            onPauseCallback = callback
+        }
+    override var onStop: (() -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { Callback1(it) }
+            libsmtc.setOnStop(callback)
+            onStopCallback = callback
+        }
+    override var onPlay: (() -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { Callback1(it) }
+            libsmtc.setOnPlay(callback)
+            onPlayCallback = callback
+        }
+    override var onNext: (() -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { Callback1(it) }
+            libsmtc.setOnNext(callback)
+            onNextCallback = callback
+        }
+    override var onPrevious: (() -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { Callback1(it) }
+            libsmtc.setOnPrevious(callback)
+            onPreviousCallback = callback
+        }
+    override var onSetPosition: ((to_ms: Long) -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { CallbackSeek(it) }
+            libsmtc.setOnSeek(callback)
+            onSetPositionCallback = callback
+        }
+    override var onSetRate: ((rate: Float) -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { CallbackRate(it) }
+            libsmtc.setOnRateChanged(callback)
+            onSetRateCallback = callback
+        }
+    override var onSetLoop: ((loop_mode: Int) -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { CallbackLoop(it) }
+            libsmtc.setOnLoopChanged(callback)
+            onSetLoopCallback = callback
+        }
+    override var onSetShuffle: ((shuffle_mode: Boolean) -> Unit)? = null
+        set(value) {
+            field = value
+            
+            val callback = value?.let { CallbackShuffle(it) }
+            libsmtc.setOnShuffleChanged(callback)
+            onSetShuffleCallback = callback
+        }
+
+    override fun revokeCallbacks() = libsmtc.revokeCallbacks()
+
+    override fun getEnabled(): Boolean = libsmtc.getEnabled()
+    override fun setEnabled(enabled: Boolean) = libsmtc.setEnabled(enabled)
+
+    override fun getNextEnabled(): Boolean = libsmtc.getNextEnabled()
+    override fun setNextEnabled(enabled: Boolean) {
+        libsmtc.setNextEnabled(enabled)
+    }
+
+    override fun getPreviousEnabled(): Boolean = libsmtc.getPreviousEnabled()
+    override fun setPreviousEnabled(enabled: Boolean) = libsmtc.setPreviousEnabled(enabled)
+
+    override fun getPlayEnabled(): Boolean = libsmtc.getPlayEnabled()
+    override fun setPlayEnabled(enabled: Boolean) = libsmtc.setPlayEnabled(enabled)
+
+    override fun getPauseEnabled(): Boolean = libsmtc.getPauseEnabled()
+    override fun setPauseEnabled(enabled: Boolean) = libsmtc.setPauseEnabled(enabled)
+
+    override fun getStopEnabled(): Boolean = libsmtc.getStopEnabled()
+    override fun setStopEnabled(enabled: Boolean) = libsmtc.setStopEnabled(enabled)
+
+    override fun getRate(): Double = libsmtc.getRate()
+    override fun setRate(rate: Double) = libsmtc.setRate(rate)
+
+    override fun getShuffle(): Boolean = libsmtc.getShuffle()
+    override fun setShuffle(shuffle: Boolean) = libsmtc.setShuffle(shuffle)
+
+    override fun getLoop(): Int = libsmtc.getLoop()
+    override fun setLoop(loop: Int) = libsmtc.setLoop(loop)
+
+    override fun getPlaybackState(): Int = libsmtc.getPlaybackState()
+    override fun setPlaybackState(state: Int) = libsmtc.setPlaybackState(state)
+
+    override fun setTimelineProperties(start: Long, end: Long, seek_start: Long, seek_end: Long) = libsmtc.setTimelineProperties(start, end, seek_start, seek_end)
+    override fun setPosition(position: Long) = libsmtc.setPosition(position)
+
+    override fun update() = libsmtc.update()
+    override fun reset() = libsmtc.reset()
+
+    override fun getMediaType(): Int = libsmtc.getMediaType()
+    override fun setMediaType(type: Int) = libsmtc.setMediaType(type)
+
+    override fun thumbnailLoaded(): Boolean = libsmtc.thumbnailLoaded()
+    override fun setThumbnail(path: String, update_when_loaded: Boolean) = libsmtc.setThumbnail(path, update_when_loaded)
+
+    override fun getMusicTitle(): String = libsmtc.getMusicTitle()
+    override fun setMusicTitle(title: String) = libsmtc.setMusicTitle(title)
+
+    override fun getMusicArtist(): String = libsmtc.getMusicArtist()
+    override fun setMusicArtist(artist: String) = libsmtc.setMusicArtist(artist)
+
+    override fun getMusicAlbumTitle(): String = libsmtc.getMusicAlbumTitle()
+    override fun setMusicAlbumTitle(title: String) = libsmtc.setMusicAlbumTitle(title)
+
+    override fun getMusicAlbumArtist(): String = libsmtc.getMusicAlbumArtist()
+    override fun setMusicAlbumArtist(artist: String) = libsmtc.setMusicAlbumArtist(artist)
+
+    override fun getMusicGenresSize(): Int = libsmtc.getMusicGenresSize()
+    override fun getMusicGenreAt(index: Int): String = libsmtc.getMusicGenreAt(index)
+    override fun addMusicGenre(genre: String) = libsmtc.addMusicGenre(genre)
+    override fun clearMusicGenres() = libsmtc.clearMusicGenres()
+
+    override fun getMusicAlbumTrackCount(): Int = libsmtc.getMusicAlbumTrackCount()
+    override fun setMusicAlbumTrackCount(count: Int) = libsmtc.setMusicAlbumTrackCount(count)
+
+    override fun getMusicTrack(): Int = libsmtc.getMusicTrack()
+    override fun setMusicTrack(track: Int) = libsmtc.setMusicTrack(track)
+}
+
+private interface SMTCAdapterLibrary: SMTCAdapter, Library {
+    fun setOnPause(callback: Callback1?)
+    fun setOnStop(callback: Callback1?)
+    fun setOnPlay(callback: Callback1?)
+    fun setOnNext(callback: Callback1?)
+    fun setOnPrevious(callback: Callback1?)
+    fun setOnSeek(callback: CallbackSeek?)
+    fun setOnRateChanged(callback: CallbackRate?)
+    fun setOnLoopChanged(callback: CallbackLoop?)
+    fun setOnShuffleChanged(callback: CallbackShuffle?)
+}
+
+@Suppress("UNUSED_PARAMETER")
+private class Callback1(val callback: () -> Unit): Callback {
+    fun callback(data: Int?) { callback.invoke() }
+}
+
+@Suppress("UNUSED_PARAMETER")
+private class CallbackSeek(val callback: (Long) -> Unit): Callback {
+    fun callback(value: Long, data: Int?) { callback.invoke(value) }
+}
+
+@Suppress("UNUSED_PARAMETER")
+private class CallbackRate(val callback: (Float) -> Unit): Callback {
+    fun callback(value: Float, data: Int?) { callback.invoke(value) }
+}
+
+@Suppress("UNUSED_PARAMETER")
+private class CallbackLoop(val callback: (Int) -> Unit): Callback {
+    fun callback(value: Int, data: Int?) { callback.invoke(value) }
+}
+
+@Suppress("UNUSED_PARAMETER")
+private class CallbackShuffle(val callback: (Boolean) -> Unit): Callback {
+    fun callback(value: Boolean, data: Int?) { callback.invoke(value) }
+}
diff --git a/mediasession/src/jvmMain/resources/win32-x86-64/libSMTCAdapter.dll b/mediasession/src/jvmMain/resources/win32-x86-64/libSMTCAdapter.dll
new file mode 100755
index 00000000..6755de60
Binary files /dev/null and b/mediasession/src/jvmMain/resources/win32-x86-64/libSMTCAdapter.dll differ
diff --git a/mediasession/src/jvmMain/resources/win32-x86/libSMTCAdapter.dll b/mediasession/src/jvmMain/resources/win32-x86/libSMTCAdapter.dll
new file mode 100755
index 00000000..6755de60
Binary files /dev/null and b/mediasession/src/jvmMain/resources/win32-x86/libSMTCAdapter.dll differ
diff --git a/settings.gradle.kts b/settings.gradle.kts
index 0977e3b5..a9419b78 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -19,9 +19,18 @@ dependencyResolutionManagement {
     repositories {
         google()
         mavenCentral()
-        maven { url = uri("https://jitpack.io") }
+        maven {
+            url = uri("https://jitpack.io")
+            content {
+                includeGroup("com.github.goxr3plus")
+            }
+        }
     }
 }
 
 rootProject.name = "Yuri Player"
+include(":core")
+include(":components")
 include(":app")
+include(":desktop")
+include(":mediasession")