chore(nix): refresh lock + npmDepsHash for v1.48.1

CHANGELOG [1.48.1]: add missing blank line between the Opus seek-crash entry
and the next heading, and add "By @Psychotoxical" attribution (no PR number)
to the six entries that were committed directly to the hotfix branch (playback
freeze, macOS headphone restart, Discord cover art, minimize-to-tray, and the
two Windows media-controls fixes from issue #1102).

WHATS_NEW [1.48.1]: rewrite the section to reflect the full user-visible 1.48.1
changelog per the What's New rules — themed Fixed groups (Playback and audio;
Offline, Now Playing, and Navidrome; Themes and integrations; Other), ordered
by user impact, without author/PR/issue references.

.github/workflows/frontend-tests.yml

@@ -56,6 +56,7 @@ jobs:
           node-version: 'lts/*'
           cache: 'npm'
       - run: npm ci
+      - run: npm run prebuild:release-notes
       - name: tsc
         run: npx tsc --noEmit
 
@@ -71,6 +72,7 @@ jobs:
       - name: install jq
         run: sudo apt-get update && sudo apt-get install -y jq
       - run: npm ci
+      - run: npm run prebuild:release-notes
       - name: vitest run --coverage
         run: npx vitest run --coverage
       - name: hot-path file coverage gate

.github/workflows/reusable-channel-publish.yml

@@ -176,18 +176,32 @@ jobs:
       - name: extract changelog
         id: changelog
         run: |
+          set -euo pipefail
           VERSION="${{ steps.get-version.outputs.version }}"
-          BODY=$(awk "/^## \[$VERSION\]/{found=1; next} found && /^## \[/{exit} found{print}" CHANGELOG.md)
-          if [ -z "$BODY" ]; then
-            BASE_VERSION="$(node -e 'const v=process.argv[1]; const m=v.match(/^(\d+\.\d+\.\d+)/); if(m){process.stdout.write(m[1]);}' "$VERSION")"
-            if [ -n "$BASE_VERSION" ] && [ "$BASE_VERSION" != "$VERSION" ]; then
-              BODY=$(awk "/^## \[$BASE_VERSION\]/{found=1; next} found && /^## \[/{exit} found{print}" CHANGELOG.md)
-            fi
+          BODY=""
+          if node scripts/extract-release-section.mjs CHANGELOG.md "$VERSION" --allow-empty > /tmp/changelog-body.md; then
+            BODY="$(cat /tmp/changelog-body.md)"
           fi
           EOF_MARKER=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
           echo "body<<$EOF_MARKER" >> "$GITHUB_OUTPUT"
           echo "$BODY" >> "$GITHUB_OUTPUT"
           echo "$EOF_MARKER" >> "$GITHUB_OUTPUT"
+      - name: extract what's new for release asset
+        id: whats-new
+        run: |
+          set -euo pipefail
+          VERSION="${{ steps.get-version.outputs.version }}"
+          CHANNEL="${{ inputs.channel }}"
+          if ! node scripts/extract-release-section.mjs WHATS_NEW.md "$VERSION" > /tmp/whats-new.md; then
+            if [ "$CHANNEL" = "release" ]; then
+              echo "::error::WHATS_NEW.md has no section for version $VERSION (required for stable release)"
+              exit 1
+            fi
+            echo "::warning::WHATS_NEW.md has no section for $VERSION — skipping whats-new.md asset"
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "skip=false" >> "$GITHUB_OUTPUT"
       - name: create or update release
         id: create-release
         uses: actions/github-script@v9
@@ -237,6 +251,14 @@ jobs:
               prerelease,
             });
             return data.id;
+      - name: upload whats-new.md release asset
+        if: steps.whats-new.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          RELEASE_TAG="${{ steps.tag.outputs.value }}"
+          gh release upload "$RELEASE_TAG" /tmp/whats-new.md --clobber
 
   build-macos-windows:
     if: ${{ inputs.build_platform_artifacts }}

.gitignore

@@ -37,6 +37,9 @@ src-tauri/lcov.info
 # Frontend test coverage
 coverage/
 
+# Generated at build/test/dev time (scripts/generate-release-notes-bundle.mjs)
+src/generated/
+
 # Documentation
 CLAUDE.md
 

CHANGELOG.md

@@ -9,6 +9,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 >
 
 
+## [1.48.1] - 2026-06-15
+
+## Fixed
+
+### Playback freeze on track changes
+
+**By [@Psychotoxical](https://github.com/Psychotoxical)**
+
+* Changing tracks — skipping, or the automatic advance at the end of a song — could freeze the interface for several seconds while audio kept playing (the progress bar and lyrics stopped updating). The queue header recomputed its duration totals on every track change instead of only when the queue itself changes; it now recomputes only on queue changes, so track changes stay instant.
+* This also resolves output-device changes not being applied on Windows: the same freeze was blocking playback from following the newly selected device.
+
+### Paused or stopped playback restarting on headphone disconnect (macOS)
+
+**By [@Psychotoxical](https://github.com/Psychotoxical)**
+
+* On macOS, pausing or stopping playback and then disconnecting headphones (or otherwise switching the audio output device) could make playback restart on the newly selected device. Playback now reliably stays paused or stopped across a device change.
+
+### Crash when seeking Opus/Ogg files
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1100](https://github.com/Psychotoxical/psysonic/pull/1100)**
+
+* Scrubbing the seekbar on an Opus/Ogg file — and then pressing Stop — crashed the whole app (a 1.48 regression from the Symphonia 0.6 migration). The Ogg demuxer recorded its seek bounds only when the source was seekable during the format probe, but probing hid seekability, so the first seek panicked on the audio thread (`Option::unwrap()` on `None`) and took the process down at the audio backend boundary.
+* Local and in-memory Opus/Ogg sources now stay seekable through the probe, so seeking works correctly. As a safety net, any decoder panic during a seek is contained instead of crashing the app; for Opus/Ogg streamed over HTTP, seeking is a no-op for now rather than a crash.
+
+### Discord Rich Presence cover art missing with two server addresses
+
+**By [@Psychotoxical](https://github.com/Psychotoxical)**
+
+* When a server profile had both a local and a public address, Discord Rich Presence showed the placeholder icon instead of the album cover. The cover URL used the local address, which Discord's servers can't reach; it now uses the public address (the same one used for share links).
+
+### "Minimize to Tray" ignored on the macOS close button
+
+**By [@Psychotoxical](https://github.com/Psychotoxical)**
+
+* On macOS, closing the window with the red close button always quit the app, even with "Minimize to Tray" enabled. The close button now respects the setting — with it on, the window hides to the tray instead of quitting, the same as the tray icon's "Hide".
+
+### Library sync stalling for many seconds on large Navidrome collections
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1105](https://github.com/Psychotoxical/psysonic/pull/1105)**
+
+* On large libraries (reported with ~200,000 tracks on Navidrome), background library sync could lock up database writes for minutes at a time — playback history, ratings and other saves piled up waiting behind it.
+* Root cause: the track id-remap step ran a database lookup that couldn't use its indexes and scanned the entire track table once per incoming track, so the cost grew with the square of the library size. The lookup now uses the proper indexes, bringing it back to a fast, near-instant operation.
+
+### Album cover missing in Windows media controls
+
+**By [@Psychotoxical](https://github.com/Psychotoxical)**
+
+* On Windows, the system media controls (the Quick Settings media tile, the lock screen and third-party media flyouts) showed the track title and artist but no album cover. Windows could not decode the cached WebP cover art for its thumbnail, even with the Store WebP extension installed. The cover is now converted to PNG before it is handed to the media controls, so the artwork shows again. macOS and Linux are unaffected.
+
+### Windows media controls showed "Unknown application"
+
+**By [@Psychotoxical](https://github.com/Psychotoxical)**
+
+* On Windows, the system media controls (the Quick Settings media tile, the lock screen and third-party media flyouts) labelled playback as "Unknown application" with no icon. The app now registers an explicit application identity at startup so Windows shows "Psysonic" and its icon as the playback source.
+
+
+
 ## [1.48.0]
 
 ## Added
@@ -21,6 +78,142 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+### Fullscreen player — rebuilt for much lower CPU/RAM
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1001](https://github.com/Psychotoxical/psysonic/pull/1001)**
+
+* The previous fullscreen player was a heavy CPU and memory consumer — constant repaints from animated/blurred backgrounds and effects kept the GPU and a CPU core busy the whole time it was open. It has been **completely replaced** by a static, low-overhead screen: only the seekbar, elapsed time, and clock update live; everything else stays still.
+* Features: sharp high-res background, large album cover, true waveform seekbar, up-next queue popover, scrolling synced lyrics, clickable rating stars, and an on-screen clock.
+* The artist photo now always shows as the background (album cover as fallback); the old **Appearance → "Fullscreen player"** settings were removed.
+
+
+
+### Queue — Timeline display mode
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1004](https://github.com/Psychotoxical/psysonic/pull/1004), suggested by [@Legislate3030](https://github.com/Legislate3030)**
+
+* New third queue display mode (cycle the header button, or pick it in **Settings → Personalisation → Queue display**). Timeline keeps the current track centered with played history above and upcoming tracks below — both visible at once — so it's easy to follow playback and jump back to earlier songs.
+* The up-next order respects shuffle, and a "History" / "Up next" divider marks the boundary.
+
+
+
+### Offline — unified local playback, library index join, and favorites sync
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1008](https://github.com/Psychotoxical/psysonic/pull/1008)**
+
+* All local audio bytes live under one **`media/`** tree: `cache/` (ephemeral hot-cache), `library/` (user-pinned offline), and `favorites/` (auto-synced stars). Paths use library-index metadata and the URL-derived server index key so two profiles on the same server share one bucket.
+* **`localPlaybackStore`** replaces the split hot-cache / offline metadata stores — one index drives prefetch, promotion, eviction, and `psysonic-local://` playback resolution.
+* **Offline Library** lists pinned and favorites-tier tracks by joining that index with the SQLite library catalog (no duplicate offline album cards). Pin album, playlist, or artist from browse; disk usage shown in the Offline Library header.
+* **Favorites auto-sync** keeps starred tracks on disk in `media/favorites/` with a compact toggle, cross-server reconcile, and cancel-on-unstar so orphaned files are not left behind.
+* **Cached offline pins stay in sync** — manually pinned **albums** and **artist discographies** reconcile after a library index sync (delta/full); **regular playlists** reconcile hourly and when edited in-app. Added tracks download and removed ones are pruned. **Smart playlists** (`psy-smart-…`) are excluded — their contents refresh from server rules automatically.
+* Mixed-server queues play offline with correct per-track server scope; network guards skip Subsonic when local bytes exist.
+* Startup migration from legacy `psysonic-offline/` layout; Settings → Storage uses a single **media directory** picker and a live hot-cache track count.
+
+
+
+### Themes — community Theme Store
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1009](https://github.com/Psychotoxical/psysonic/pull/1009), [#1011](https://github.com/Psychotoxical/psysonic/pull/1011), [#1012](https://github.com/Psychotoxical/psysonic/pull/1012), [#1013](https://github.com/Psychotoxical/psysonic/pull/1013), [#1014](https://github.com/Psychotoxical/psysonic/pull/1014), [#1015](https://github.com/Psychotoxical/psysonic/pull/1015), [#1016](https://github.com/Psychotoxical/psysonic/pull/1016), [#1018](https://github.com/Psychotoxical/psysonic/pull/1018), [#1020](https://github.com/Psychotoxical/psysonic/pull/1020), [#1036](https://github.com/Psychotoxical/psysonic/pull/1036), [#1038](https://github.com/Psychotoxical/psysonic/pull/1038), [#1041](https://github.com/Psychotoxical/psysonic/pull/1041)**
+
+* New **Settings → Themes** tab: pick a theme, set the day/night scheduler, and browse a built-in **Theme Store** to install, update and uninstall community themes — with search, a dark/light filter, and full-size thumbnail previews.
+* The app now bundles six core themes (Catppuccin Mocha & Latte, Kanagawa Wave, Stark HUD, and the colour-blind-safe Vision Dark / Vision Navy); every other palette installs on demand from the [psysonic-themes](https://github.com/Psysonic/psysonic-themes) repo. Installed themes are saved locally and apply instantly at startup, even offline.
+* **Import a theme from a local `.zip`** (manifest.json + theme.css): the package is validated, you confirm its name and author, then it installs like any other community theme.
+* Themes are **free-form** — beyond recolouring, they can add their own styling and animations and react to playback / fullscreen / sidebar / lyrics state. A safety floor (no network, no scripts) is always enforced; store themes are reviewed, and imported themes install at your own risk.
+* The store paginates large catalogues, and refreshing the list no longer jumps back to the top.
+* Each store theme shows its **total downloads** and a **last-changed** date, and can be sorted by most popular, newest or name; the catalogue now has numbered page navigation. These stats refresh once a day.
+* The **Now Playing** page now follows the active theme end to end — light themes render it legibly instead of washed-out, with no per-theme tweaks needed.
+* The sidebar now shows a small notice when one of your installed themes has an update available — click it to jump straight to the Theme Store, or dismiss it until the next update. Themes with an update also show an update control right on their card under **Settings → Themes** to update them in place with one click, and the store refreshes once on startup so new themes and updates show up without hitting refresh.
+* Upgrading from an older build: an active or scheduled theme that has moved to the store and isn't installed falls back to Mocha (dark) / Latte (light).
+
+
+
+### Offline — local-bytes browse when the server is down
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1017](https://github.com/Psychotoxical/psysonic/pull/1017)**
+
+* When the active server is unreachable, browse and detail pages read from **local playback bytes** and the **library index** instead of Subsonic — albums, artists, tracks, cached playlists, and cross-server favorites.
+* Single integration contract: `offlineBrowseContext`, `offlineActionPolicy`, and `resolveAlbum` / `resolveArtist` / `resolvePlaylist` resolvers; context menus and detail toolbars block server mutations offline.
+* Disconnect navigation forks by offline capability (stay on page, stay-reload, or redirect); Home reuses the last cached feed snapshot; DEV offline toggle simulates full disconnect for testing.
+* PlayerBar hides star rating and favorite controls while offline browse is active.
+
+
+
+### Startup — themed loading splash before the app bundle loads
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1030](https://github.com/Psychotoxical/psysonic/pull/1030)**
+
+* Inline splash in `index.html` (progress bar + P logo) shows while the Vite bundle loads in dev and production — no empty or black window on launch.
+* Splash colours follow the persisted theme (built-in palettes, day/night scheduler, and installed community themes); the logo uses each theme's accent gradient instead of a hardcoded white asset.
+* The native window stays hidden until the splash has painted (`visible: false` + deferred `show` from Rust/JS); window-state restore no longer overrides startup visibility.
+
+
+
+### Servers — software and version on each server card
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1045](https://github.com/Psychotoxical/psysonic/pull/1045)**
+
+* Each server card under **Settings → Servers** now shows the server software and version (e.g. `Navidrome 0.62.0`) under the server name. The value comes from the existing connection ping, so no extra request is made; it is hidden for servers that don't report it (plain Subsonic without OpenSubsonic).
+
+
+
+### What's New — remote release notes
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1058](https://github.com/Psychotoxical/psysonic/pull/1058)**
+
+* The **What's New** page shows user-friendly highlights from `WHATS_NEW.md` instead of embedding the full technical changelog in the app bundle.
+* RC and stable builds prefetch `whats-new.md` from the GitHub release on startup and cache it locally; offline users see a thin embedded fallback.
+* **`tauri:dev`** reads markdown straight from the repo for easy editing; shipped bundles embed only the current release-line slice. A **Full changelog** tab on the page shows the technical list for the same version.
+* CI uploads `whats-new.md` on each `next` / `release` tag alongside platform artifacts.
+* Remote download uses the existing Rust `fetch_url_bytes` proxy so GitHub release assets work without browser CORS.
+
+
+
+### Music Network — scrobble to more than just Last.fm
+
+**By [@Psychotoxical](https://github.com/Psychotoxical) and [@cucadmuh](https://github.com/cucadmuh), PR [#1066](https://github.com/Psychotoxical/psysonic/pull/1066)**
+
+* **Settings → Integrations** now hosts a **Music Network** that scrobbles your plays to one or more services at once: **Last.fm**, **Libre.fm**, **Rocksky**, **ListenBrainz** (the public service or any compatible server), **Maloja** (native, Audioscrobbler or ListenBrainz API), **Koito**, and any **custom GNU FM** instance.
+* Choose a **primary** service — your loved tracks, similar artists and listening stats come from it — while scrobbles fan out to every connected service. A master switch turns the whole thing on or off.
+* **Last.fm works exactly as before**, including love, similar artists and the Statistics page; your existing connection is migrated automatically on first launch.
+* *Known limitation:* Rocksky currently rejects scrobbles whose title or artist contains non-standard (non-ASCII) characters — a Rocksky-side issue, not a Psysonic bug.
+
+
+
+### Live — rich now-playing on Navidrome 0.62+
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1080](https://github.com/Psychotoxical/psysonic/pull/1080)**
+
+* On servers that advertise the OpenSubsonic `playbackReport` extension (Navidrome ≥ 0.62), Psysonic reports live transport state and position so **Live** shows who is playing or paused and where in the track — including playback speed when the other client sends it.
+* The position bar glides between refreshes; pause and resume update the server immediately instead of waiting for the audio engine.
+* Play counts are unchanged — still driven by the existing scrobble path. Servers without the extension keep the previous now-playing behaviour.
+
+
+
+### Title bar — selectable window button styles
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1083](https://github.com/Psychotoxical/psysonic/pull/1083), suggested by [@PHLAK](https://github.com/PHLAK)**
+
+* The Linux custom title bar gets a **window button style** picker in **Settings → Appearance → Custom title bar** — choose between dots, dots with icons, flat, pill, outline, and minimal looks.
+* All styles now carry minimize/maximize/close icons for clear, colour-blind-friendly buttons, and an optional toggle hides the minimize button (maximize and close only).
+
+
+
+### Playback speed — Semitones strategy, finer labels, and advanced fine steps
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1084](https://github.com/Psychotoxical/psysonic/pull/1084)**
+
+* New **Semitones** strategy sets varispeed directly in semitones (±12 st, 0.1 step) instead of coarse speed steps; the speed readout now shows two decimals so every slider notch is visible.
+* Each strategy button has a short tooltip; **Advanced** mode adds an optional **Fine adjustment** toggle (0.01× / 0.01 st steps) in **Settings → Audio**.
+
+
+
+### Now Playing — live status dot in "Who is listening?"
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1086](https://github.com/Psychotoxical/psysonic/pull/1086)**
+
+* Each listener in the **Who is listening?** popover now shows a small status dot — playing, paused, or idle — derived from the live playback report, replacing the previous "minutes ago" line. The status is also read out for screen readers and on hover, so it is never conveyed by colour alone.
+
+
 ## Changed
 
 ### Dependencies — npm and Rust refresh
@@ -41,6 +234,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+### Playback — Preload Next Track setting removed
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1007](https://github.com/Psychotoxical/psysonic/pull/1007)**
+
+* The **Preload Next Track** toggle and timing modes under **Settings → Storage → Buffering** are gone — ranged streaming now starts playback without that extra RAM prefetch.
+* Gapless and crossfade still prefetch the next track internally when Hot Cache is off; Hot Cache is unchanged.
+
+
+
+### PsyLab — Performance Probe rename, Tuning tab, and log tools
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1027](https://github.com/Psychotoxical/psysonic/pull/1027)**
+
+* **Ctrl+Shift+D** opens **PsyLab** (formerly Performance Probe). Cover backfill thread tuning moved to a new **Tuning** tab.
+* **Logs** tab: selectable text, toolbar copy/export, and a context-menu **Copy** for the current selection.
+* Runtime log lines are sanitized before they enter the buffer — Subsonic/auth tokens and remote hostnames are redacted or partially masked; LAN and localhost addresses stay readable.
+
+
+
+### PsyLab — Connections tab and Navidrome admin role
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1033](https://github.com/Psychotoxical/psysonic/pull/1033)**
+
+* New **Connections** tab: session/endpoint status, active-server capability readout (OpenSubsonic, AudioMuse detection, provider/strategy, detection trust, resolved call route, and AudioMuse mode), and queue-playback server when it differs from the active profile.
+* Navidrome **admin vs standard user** badge via native login probe — useful when diagnosing plugin/settings visibility.
+
+
+
+### Servers — capability framework with AudioMuse sonic routing (Navidrome ≥ 0.62)
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1033](https://github.com/Psychotoxical/psysonic/pull/1033)**
+
+* New declarative **server-capability framework** (`src/serverCapabilities/`): a catalog picks a feature strategy per server generation, runs only the needed probes, and routes API calls — replacing scattered version checks in the UI and call sites.
+* Navidrome **0.62+**: detect the AudioMuse-AI plugin from `getOpenSubsonicExtensions` when `sonicSimilarity` is advertised — the first reliable signal. Settings shows an **auto-managed status indicator** (no manual toggle); older Navidrome keeps the manual toggle and the legacy `getSimilarSongs` Instant Mix probe.
+* **Path routing**: Instant Mix and Lucky Mix prefer the OpenSubsonic `getSonicSimilarTracks` endpoint when the plugin is present, falling back to legacy `getSimilarSongs`.
+
+
+
+### Settings → Servers — compact server cards
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1054](https://github.com/Psychotoxical/psysonic/pull/1054)**
+
+* Two-line header: custom entry name plus `user@host`, HTTPS lock, and a clickable version info tooltip (hover or tap).
+* Navidrome **0.62+**: green **AudioMuse-AI** inline badge when the plugin is detected; older Navidrome keeps the manual toggle row below the card.
+* **Use** and **Active** share one rightmost slot (green badge vs primary button); card actions are edit → test → use/active. Delete lives in the edit form footer.
+* **TooltipPortal**: `data-tooltip-click` for click-pinned tooltips (touch and explicit open without the 1s hover delay).
+
+
 ## Fixed
 
 ### Servers — complete border on the active server card
@@ -60,6 +301,227 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 
+### Track preview — Symphonia 0.6 format hints and fast stream start
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1006](https://github.com/Psychotoxical/psysonic/pull/1006)**
+
+* Preview resolves container format from HTTP headers, Subsonic `suffix`, and magic-byte sniff so Symphonia 0.6 no longer fails with `.unknown` demuxer errors.
+* Preview opens via ranged HTTP when the server supports byte ranges — audio starts after ~384 KiB buffered instead of waiting for a full-file download; buffered fallback uses the same probe seek-gate as main playback.
+* Player bar cover guard while preview metadata loads; progress ring leaves the loading spinner once the engine emits `audio:preview-start`.
+
+
+
+### Mainstage — hero backdrop stays in sync when skipping albums quickly
+
+**By [@cucadmuh](https://github.com/cucadmuh), reported by Asra on the Psysonic Discord, PR [#1021](https://github.com/Psychotoxical/psysonic/pull/1021)**
+
+* Rapid prev/next clicks on the Mainstage hero no longer leave the blurred cover-art background on the previous album while the foreground cover and metadata already show the next one.
+
+
+
+### Song rails — multi-artist credits link to each artist
+
+**By [@cucadmuh](https://github.com/cucadmuh), reported by zunoz on Discord, PR [#1023](https://github.com/Psychotoxical/psysonic/pull/1023)**
+
+* **Random Picks**, **Discover Songs**, and other song cards now split OpenSubsonic `artists[]` into individually clickable names — the same behaviour as album track rows and the player bar, instead of one link for the whole joined credit string.
+* Album cards and the rest of the app share the same artist-ref helper, including when Subsonic returns a single ref object instead of a one-element array.
+
+
+
+### Fullscreen player — corner clock follows Clock format setting
+
+**By [@cucadmuh](https://github.com/cucadmuh), reported by zunoz on Discord, PR [#1025](https://github.com/Psychotoxical/psysonic/pull/1025)**
+
+* The wall clock in the fullscreen player now honours **Settings → System → Clock format** (24-hour vs 12-hour), matching the queue ETA and sleep-timer preview instead of always showing AM/PM.
+
+
+
+### All Albums — Only compilations filter returns results
+
+**By [@cucadmuh](https://github.com/cucadmuh), reported by zunoz on Discord, PR [#1026](https://github.com/Psychotoxical/psysonic/pull/1026)**
+
+* The **Only compilations** toggle on **All Albums** no longer returns an empty list when compilations are tagged via **Various Artists** as album artist or when genre is combined with other browse filters — local index SQL, track-grouped browse, and client-side detection now agree on the same compilation signals.
+
+
+
+### Artist page — Top Tracks play button
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1031](https://github.com/Psychotoxical/psysonic/pull/1031)**
+
+* Play on **Top Tracks** rows no longer silently does nothing when the artist page has top songs but no albums loaded (e.g. lossless artist view); playback starts from the clicked track and continues into the catalog when albums are available.
+
+
+
+### PsyLab — tab bar no longer collapses on the Logs tab
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1033](https://github.com/Psychotoxical/psysonic/pull/1033)**
+
+* The PsyLab tab row keeps its height when the Logs flex layout fills the modal — tabs were previously squashed to a thin strip.
+
+
+
+### Playback — macOS stutter from background device checks
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1039](https://github.com/Psychotoxical/psysonic/pull/1039)**
+
+* On some macOS setups playback stuttered at a steady ~3-second cadence: a background check that scans every audio output device ran on each poll and briefly contended with playback. It now runs only when a specific output device is pinned; with the system default (the common case) a single lightweight check runs instead.
+
+
+
+### Now Playing — cards no longer blank out on track change
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1042](https://github.com/Psychotoxical/psysonic/pull/1042)**
+
+* The "from this album", "discography" and "most played" sections on the Now Playing page disappeared after a track change once the next track started playing from the local cache, and didn't come back. The page now keeps loading that info whenever the server is reachable, regardless of whether the audio plays from cached or offline bytes.
+
+
+
+### Library DB — named slow-write ops for stall diagnosis
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1043](https://github.com/Psychotoxical/psysonic/pull/1043)**
+
+* Production `library-db` write paths now log stable `module.action` op names instead of the generic `misc`, so the next `[library-db] SLOW write` line on macOS (or elsewhere) identifies the call site — diagnostic step for playback stalls under long write-lock holds ([#1040](https://github.com/Psychotoxical/psysonic/issues/1040)).
+
+
+
+### Now Playing — metadata reads from the local library index first
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1049](https://github.com/Psychotoxical/psysonic/pull/1049)**
+
+* The "from this album", "discography", "most played" and song details on the Now Playing page now come from the local library index when it has them, only falling back to the server when the index can't serve a row. Cards and fields (genre, play count, contributors) stay populated during cached and offline playback, with fewer server requests.
+
+
+
+### Themes — consistent focus borders on inputs and dropdowns
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1052](https://github.com/Psychotoxical/psysonic/pull/1052)**
+
+* Text fields no longer draw a double border when focused — they now show a single clean ring across every theme. The colour-blind-safe themes keep their stronger high-contrast focus ring on every field, including the header search.
+* Dropdown and popover borders now follow the active theme in all themes (a couple of themes previously rendered them with an unthemed colour).
+
+
+
+### Home — Most Played no longer jumps the page when loading more
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), reported by zunoz on Discord, PR [#1053](https://github.com/Psychotoxical/psysonic/pull/1053)**
+
+* Clicking the arrow to load more albums in the **Most Played** rail sometimes snapped the page up to an earlier section. Loading more now keeps the viewport in place.
+
+
+
+### Navidrome Now Playing and scrobble with local playback
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1055](https://github.com/Psychotoxical/psysonic/pull/1055)**
+
+* **Show in Now Playing** and Navidrome play-count scrobbles no longer silently skip when audio plays from hot cache, offline library pins, or favorites-auto bytes.
+* Presence and queue sync target the **playback server** reachability gate, so a queue on server A still reports to Navidrome while browsing server B.
+
+
+
+### Album grids — album artist on compilation cards
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1057](https://github.com/Psychotoxical/psysonic/pull/1057), reported in [#1056](https://github.com/Psychotoxical/psysonic/issues/1056)**
+
+* Random Albums, New Releases, All Albums, and other album grids no longer show a track artist on compilation albums when the tags set a single album artist (e.g. **Underworld** on a various-artists mix); the card matches the album page.
+* Local index browse, live search, and FTS album dedupe prefer `album_artist` over per-track `artist`; Hero, Most Played, and offline pin labels use the same display helper.
+
+
+
+### Local index — multi-genre browse, filters, and counts
+
+**By [@cucadmuh](https://github.com/cucadmuh), reported by HiveMind on the Psysonic Discord, PR [#1059](https://github.com/Psychotoxical/psysonic/pull/1059)**
+
+* Tracks tagged with several genres in one metadata field (e.g. `Noise Metal/Dark Ambient/Experimental Black Metal`) again match **each atomic genre** in Genres browse, All Albums filters, genre detail, and Advanced Search — not only the first segment.
+* New `track_genre` index (OpenSubsonic `genres[]` when present, Navidrome-default split fallback), maintained on sync; one-time blocking startup backfill for existing libraries with progress.
+* Migration v12 repairs databases that recorded legacy schema versions 2–11; TS network fallback uses robust `genreTagsFor` parsing.
+
+
+
+### Dev startup — missing generated release-notes bundle
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1060](https://github.com/Psychotoxical/psysonic/pull/1060)**
+
+* Fresh clones no longer crash Vite on `tauri:dev` when `src/generated/releaseNotesBundle.ts` is missing — `dev` and `tauri:dev` now run `prebuild:release-notes` before launch (file stays gitignored).
+
+
+
+### What's New — release-notes cache file on disk (RC/stable)
+
+**By [@cucadmuh](https://github.com/cucadmuh), PR [#1062](https://github.com/Psychotoxical/psysonic/pull/1062)**
+
+* RC and stable builds now persist the downloaded `whats-new.md` slice under AppData — `plugin-fs` had mkdir but lacked recursive write scope, so the `release-notes/` folder appeared empty and every launch re-fetched from GitHub.
+
+
+
+### Favorites — player-bar star stays synced in track lists
+
+**By [@artplan1](https://github.com/artplan1), PR [#1063](https://github.com/Psychotoxical/psysonic/pull/1063)**
+
+* Liking a song from the **player bar**, fullscreen player, or global shortcuts now updates the star in album tracklists, playlists, Random Mix, and Favorites — the row no longer reverts the instant the server sync completes.
+* List views seed starred state from a one-shot fetch and merge session `starredOverrides`; clearing those overrides on sync success had only patched `currentTrack` and the queue cache, so rows fell back to stale fetched values.
+
+
+
+### Fullscreen player — title cleanup
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1068](https://github.com/Psychotoxical/psysonic/pull/1068)**
+
+* The song title no longer shows a leading track number, and letters with descenders (g, j, p, q, y) are no longer clipped along the bottom edge.
+
+
+
+### Discord Rich Presence — album art and clearer settings
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1068](https://github.com/Psychotoxical/psysonic/pull/1068)**
+
+* Album art shows again when the cover source is "Server (via album info)" — Discord was handed a local file path it cannot fetch and fell back to the app icon; it now receives a reachable image URL.
+* **Settings → Integrations:** added notices clarifying that this is the built-in Discord Rich Presence, and that the official Navidrome Discord RP plugin needs "Show in Now Playing" enabled instead.
+
+
+
+### Internet radio — no more duplicate now-playing on Linux
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), reported by agriffit79, PR [#1069](https://github.com/Psychotoxical/psysonic/pull/1069)**
+
+* On Linux, playing an internet radio station showed the track twice in the desktop "now playing" overlay — once from the app's own media controls and once from a second player the web engine registered for the stream. The extra player is now suppressed, so radio shows a single entry like regular tracks.
+
+
+
+### Windows — idle app no longer blocks system sleep
+
+**By [@cucadmuh](https://github.com/cucadmuh), reported by [@Thraka](https://github.com/Thraka), PR [#1073](https://github.com/Psychotoxical/psysonic/pull/1073)**
+
+* Psysonic no longer keeps the audio output device open while the app is idle — the CPAL stream opens on first playback and closes after **60 seconds** without active audio (pause), or **immediately** on Stop / natural queue end, so Windows `powercfg` no longer reports an in-use audio stream when music is not playing ([#1071](https://github.com/Psychotoxical/psysonic/issues/1071)).
+* Resume after a long pause uses the existing cold path (`audio:output-released` resets the warm-pause flag); post-sleep recovery skips reopening the stream when nothing is playing.
+* **Cold start while paused:** after `getPlayQueue` restores position, the seekbar shows the saved time immediately; the current track is hot-cache prefetched and the engine loads silently (`audio_play` with `startPaused`) at that position so the next Play is a warm `audio_resume` without an audible blip at the start of the track.
+* Rodio `Dropping DeviceSink` warnings on stream release are suppressed unless logging is in debug mode.
+* **Stop keeps the waveform:** stopping no longer wipes the seekbar waveform for the still-shown track — the cached analysis bins are kept and re-hydrated from the database, so the real waveform stays mounted instead of falling back to flat bars.
+
+
+
+### Auto-install script — `curl | sudo bash` works again
+
+**By [@kbennett2000](https://github.com/kbennett2000), PR [#1079](https://github.com/Psychotoxical/psysonic/pull/1079)**
+
+* The Linux auto-installer (`install.sh`) failed before any download because `[INFO]` log lines were captured into the package URL and curl rejected the mangled string; logging now goes to stderr, the reinstall prompt reads from the terminal, and package downloads use `--fail --globoff`.
+
+
+
+### Music Network — self-hosted scrobbling reaches the server
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1085](https://github.com/Psychotoxical/psysonic/pull/1085)**
+
+* Self-hosted scrobble targets that use a pasted token (Koito, Maloja's ListenBrainz and Audioscrobbler compatibility surfaces) silently recorded nothing: the saved server address dropped the API path, so listens were sent to a route that does not exist while the account still showed as connected.
+* The correct API path is now kept when connecting. Reconnect an affected account once so it picks up the corrected address.
+
+
+
+### Internet Radio — station management limited to server admins
+
+**By [@Psychotoxical](https://github.com/Psychotoxical), PR [#1086](https://github.com/Psychotoxical/psysonic/pull/1086)**
+
+* Navidrome 0.62 made creating, editing and deleting radio stations admin-only, so those actions failed for standard accounts. Add, edit and delete controls are now hidden for non-admin Navidrome users; playback and favourites stay available to everyone. Other server types are unaffected.
+
 ## [1.47.0]
 
 > **🙏 Thank you to our amazing Discord community.** This release would not have been possible without your tireless support, quality checks, bug reports and all-round collaboration. Every report, every repro and every bit of feedback shaped what shipped here — thank you. Come join us: [discord.gg/AMnDRErm4u](https://discord.gg/AMnDRErm4u)

PRIVACY.md

@@ -9,13 +9,19 @@ All third-party integrations listed below are **opt-in**. Nothing is sent until
 ### Your Subsonic / Navidrome server
 Your server URL, username, and password are stored locally in the app's data directory. All playback and library requests go directly to your own server. Psysonic has no access to this data.
 
-### Last.fm
-If you connect a Last.fm account in Settings, Psysonic sends:
-- **Scrobbles** — track title, artist, album, and timestamp when a song reaches 50% playback
-- **Now Playing** — the currently playing track (title, artist, album)
-- **Love / Unlove** — when you mark a track as loved or unloved
+### Music Network (scrobble & enrichment services)
+Psysonic can connect to one or more scrobble services in Settings → Integrations. Each service you connect is opt-in and independent; nothing is sent to a service you have not connected. Supported service classes:
 
-All requests go to the [Last.fm API](https://www.last.fm/api). Your Last.fm credentials are stored locally and never leave your device. You can disconnect your account at any time in Settings.
+- **Audioscrobbler / GNU FM services** — Last.fm, Libre.fm, Rocksky (AT Protocol), and any self-hosted GNU FM-compatible instance
+- **ListenBrainz** — the public ListenBrainz.org service, or a self-hosted instance (e.g. Koito) via its ListenBrainz-compatible API
+- **Maloja** — your own self-hosted Maloja server (native API or its ListenBrainz-compatible API)
+
+To each connected service, Psysonic may send:
+- **Scrobbles** — track title, artist, album, and timestamp when a song reaches 50% playback
+- **Now Playing** — the currently playing track (title, artist, album), where the service supports it
+- **Love / Unlove** — when you mark a track as loved, on services that support it
+
+Additionally, the one service you choose as your **primary** is queried to enrich the UI (your loved tracks, similar artists, and listening stats). All requests go directly from your device to the service's own host — the public service's host (e.g. the [Last.fm API](https://www.last.fm/api), [ListenBrainz](https://listenbrainz.org)) or, for self-hosted services, the server URL you entered. Credentials (session keys / API tokens) are stored locally and never leave your device. You can disconnect any service at any time in Settings.
 
 ### LRCLIB (Lyrics)
 When lyrics are fetched from LRCLIB, Psysonic sends the track title, artist, album, and duration to [lrclib.net](https://lrclib.net) as a search query. No account is required. This feature can be disabled in Settings → Lyrics.
@@ -37,7 +43,7 @@ If Discord is running and Rich Presence is not disabled, Psysonic connects to th
 The following data is stored exclusively on your device in the app's local storage directory and is never transmitted:
 
 - Server profiles (URL, username, password)
-- Last.fm session key
+- Scrobble service credentials (session keys / API tokens)
 - Playback preferences, themes, keybindings, and all other settings
 - Synced device manifests
 

README.md

@@ -32,9 +32,6 @@ More translations are added over time.
 
 ---
 
-> [!WARNING]
-> Psysonic is under active development. Bugs and rough edges can happen, and features may change as the project evolves.
-
 ## What is Psysonic?
 
 Psysonic is a desktop music client for self-hosted music libraries. It is designed for people who want the freedom of their own server without giving up the comfort, polish and speed of a modern music app.

RELEASE_PROCESS.md

@@ -49,6 +49,7 @@ Rules:
 
 ### Step B: Promote to RC (`next`)
 
+0. Confirm `WHATS_NEW.md` has a `## [X.Y.Z]` section for the release line about to ship (user-facing copy for the in-app What's New screen; CI uploads it as `whats-new.md` on the release tag).
 1. Run workflow: **Promote main to next**.
 2. Workflow behavior:
    - validates required `main` checks before promotion (default: `ci-ok`, or UI-style `ci-main / ci-ok`; either satisfies the gate)

WHATS_NEW.md

@@ -0,0 +1,132 @@
+# What's New
+
+User-facing release highlights for the in-app **What's New** screen. Maintainers refresh the
+current line before promoting to `next` / `release`. Technical details and PR credits stay in
+`CHANGELOG.md`.
+
+Within each section, order by **user impact** (most noticeable first) — not PR merge order.
+`CHANGELOG.md` keeps strict PR order inside Added / Changed / Fixed.
+
+## [1.48.1]
+
+## Fixed
+
+### Playback and audio
+
+- Changing tracks — skipping, or the automatic advance at the end of a song — no longer freezes the interface for a few seconds: the progress bar and lyrics keep updating, and on **Windows** a change of output device now takes effect right away.
+- Seeking an **Opus/Ogg** track — and then pressing **Stop** — no longer crashes the app.
+- **macOS:** pausing or stopping playback and then unplugging headphones (or switching the output device) no longer makes playback restart — it stays paused or stopped.
+
+### Offline, Now Playing, and Navidrome
+
+- On large **Navidrome** libraries, background library sync no longer locks up database writes for minutes at a time, so play history, ratings, and other saves go through without long delays.
+
+### Themes and integrations
+
+- **Discord** Rich Presence shows the album cover again when a server profile has both a local and a public address.
+
+### Other
+
+- **Windows:** the system media controls (Quick Settings media tile, lock screen, and third-party flyouts) now show the album cover and display **Psysonic** with its icon instead of "Unknown application".
+- **macOS:** closing the window with the red close button now respects **Minimize to Tray** — with it on, the window hides to the tray instead of quitting.
+
+## [1.48.0]
+
+## Highlights
+
+### Offline listening
+
+- When the server is unreachable, browse and detail pages show what you already have locally instead of empty errors — albums, artists, playlists, and cross-server favorites.
+- Starred tracks, pinned albums, and playlists live under one **media** folder; browse them in **Offline Library** and see disk usage at a glance.
+- **Favorites auto-sync** keeps loved songs on disk; pinned albums and playlists refresh when the library index updates.
+
+### Music Network — scrobble beyond Last.fm
+
+- **Settings → Integrations** now hosts a **Music Network**: connect **Last.fm**, **Libre.fm**, **ListenBrainz**, **Maloja**, **Rocksky**, **Koito**, or your own **GNU FM** instance — and scrobble to several at once.
+- Pick a **primary** service for loved tracks, similar artists, and stats; other connections still receive scrobbles. Your existing Last.fm setup migrates automatically.
+- A master switch turns the whole network on or off.
+
+### Theme Store
+
+- Browse and install community themes from **Settings → Themes** — search, dark/light filter, full-size previews, and sort by popularity or date.
+- Six palettes ship with the app; everything else installs on demand and works offline after the first download.
+- **Now Playing** follows every theme cleanly, including light palettes.
+- Import a theme from a local `.zip` when you have a package from a friend or your own design.
+- The sidebar nudges you when an installed theme has an update; one-click update from the theme card.
+
+### Fullscreen player
+
+- Rebuilt for much lower CPU and memory use: a calm, sharp fullscreen view with album art, waveform seekbar, up-next queue, synced lyrics, ratings, and a clock that follows your **Clock format** setting.
+- The song title no longer shows a leading track number, and descenders (g, j, p, q, y) are no longer clipped.
+
+### Live — richer now playing on Navidrome 0.62+
+
+- On servers with OpenSubsonic **playbackReport** (Navidrome ≥ 0.62), **Live** shows who is playing or paused, how far into the track they are, and playback speed when another client sends it — with smooth position updates between refreshes.
+- In **Who is listening?**, each listener shows a small status dot (playing, paused, or idle) instead of a vague “minutes ago” line.
+
+### Queue — Timeline mode
+
+- A third queue layout keeps the current track in the middle with history above and up next below — great for long listening sessions. Cycle the header control or pick it in **Settings → Personalisation → Queue display**.
+
+### Settings → Servers
+
+- Each card shows the server software and version (e.g. **Navidrome 0.62.0**) under the name, with a cleaner two-line layout and compact actions.
+- Navidrome **0.62+** shows a green **AudioMuse-AI** badge when the plugin is detected — no manual toggle on current Navidrome.
+
+### Sidebar — pin Now Playing to the top
+
+- New **Settings → Sidebar** toggle moves **Now Playing** to the top of the sidebar instead of the bottom (off by default).
+
+### Startup
+
+- A themed loading splash appears while the app starts — colours follow your active theme, including community palettes.
+
+## Improved
+
+- Audio decoding runs on **Symphonia 0.6**; streams start sooner and recover from stalls without restarting the player.
+- The **Preload Next Track** toggle under **Settings → Storage → Buffering** is gone — playback no longer waits on that extra RAM prefetch. Gapless, crossfade, and Hot Cache behave as before.
+- New **Semitones** playback-speed strategy (±12 st, 0.1 step) with two-decimal speed readout; optional fine steps in **Settings → Audio → Advanced**.
+
+## Fixed
+
+### Playback and audio
+
+- **Windows:** the app no longer keeps the audio device open while idle, so the system can sleep when music is not playing.
+- **macOS:** steady playback stutter from background device polling is gone on the default output path.
+- After a long pause, the seekbar shows the saved position immediately and the next **Play** resumes without an audible blip at track start.
+- **Stop** keeps the real waveform on the seekbar instead of falling back to flat bars.
+
+### Offline, Now Playing, and Navidrome
+
+- Now Playing cards (**from this album**, discography, most played) stay populated during cached and offline playback instead of blanking out on track change.
+- Navidrome **Show in Now Playing** and play-count scrobbles work when audio plays from hot cache, offline pins, or auto-synced favorites.
+- Mixed-server queues still report to the correct Navidrome server.
+
+### Themes and integrations
+
+- Self-hosted Music Network targets (Koito, Maloja, custom GNU FM with a pasted token) scrobble again — reconnect once if you connected before this fix.
+- Favoriting from the player bar, fullscreen player, or shortcuts updates the star in track lists and playlists immediately.
+- Discord Rich Presence shows album art again when covers come from the server.
+- Focus rings and dropdown borders follow the active theme consistently.
+
+### Browse and library
+
+- Tracks tagged with several genres in one field (e.g. `Metal/Ambient/Experimental`) match **each genre** again in browse, filters, and search.
+- **All Albums → Only compilations** returns results for common tagging patterns.
+- Album grids show the album artist on compilations instead of a random track artist.
+- Song rails (**Random Picks**, **Discover Songs**, etc.) link each name in multi-artist credits separately.
+- **Artist → Top Tracks** play works even when the artist page has no albums loaded yet.
+- **Home → Most Played** no longer jumps the page when you load more albums.
+- **Mainstage** hero backdrop stays in sync when you skip albums quickly.
+
+### Other
+
+- **Linux:** the `curl | bash` auto-installer works again.
+- **Linux:** internet radio no longer appears twice in the desktop now-playing overlay.
+- On Navidrome **0.62+**, add/edit/delete radio stations is shown only to admin accounts; everyone can still play and favourite stations.
+- **Linux custom title bar:** pick window button styles (dots, flat, pill, and more) and optionally hide minimize in **Settings → Appearance**.
+- The active server card under **Settings → Servers** draws a complete border on all sides.
+
+## Under the hood
+
+- Navidrome **0.62+** auto-detects **AudioMuse-AI** and routes Instant Mix / Lucky Mix through the smarter API when the plugin is present — older Navidrome keeps the manual toggle you already know.

flake.lock

@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1779560665,
-        "narHash": "sha256-tpyBcxPpcQb8ukyNF7DoCwfSY3VPsxHoYwj00Cayv5o=",
+        "lastModified": 1781577229,
+        "narHash": "sha256-lrp67w8AulE9Ks53n27I45ADSzbOCn4H+CNW1Ck8B+8=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "64c08a7ca051951c8eae34e3e3cb1e202fe36786",
+        "rev": "567a49d1913ce81ac6e9582e3553dd90a955875f",
         "type": "github"
       },
       "original": {

index.html

@@ -6,9 +6,91 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="description" content="Psysonic – Dein Navidrome Desktop Player" />
     <title>Psysonic</title>
+    <script src="/startup-splash-preflight.js"></script>
+    <style>
+      html, body {
+        margin: 0;
+        min-height: 100%;
+        background: var(--startup-splash-bg, #1e1e2e);
+      }
+      #app-startup-splash {
+        --splash-bg: var(--startup-splash-bg, #1e1e2e);
+        --splash-text: var(--startup-splash-text, #cdd6f4);
+        --splash-muted: var(--startup-splash-muted, #a6adc8);
+        --splash-accent: var(--startup-splash-accent, #cba6f7);
+        --splash-track: var(--startup-splash-track, #313244);
+        --splash-logo-start: var(--startup-splash-logo-start, var(--splash-accent));
+        --splash-logo-end: var(--startup-splash-logo-end, var(--splash-accent));
+        position: fixed;
+        inset: 0;
+        z-index: 2147483646;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 1.75rem;
+        background: var(--splash-bg);
+        color: var(--splash-text);
+        font-family: system-ui, -apple-system, sans-serif;
+        opacity: 1;
+        transition: opacity 0.28s ease;
+      }
+      #app-startup-splash.app-startup-splash--hide {
+        opacity: 0;
+        pointer-events: none;
+      }
+      #app-startup-splash .app-startup-splash__logo {
+        height: 72px;
+        width: auto;
+        opacity: 0.95;
+      }
+      #app-startup-splash .app-startup-splash__label {
+        font-size: 0.8rem;
+        font-weight: 600;
+        letter-spacing: 0.06em;
+        text-transform: uppercase;
+        color: var(--splash-muted);
+      }
+      #app-startup-splash .app-startup-splash__bar {
+        width: min(240px, 72vw);
+        height: 4px;
+        border-radius: 999px;
+        background: var(--splash-track);
+        overflow: hidden;
+      }
+      #app-startup-splash .app-startup-splash__bar-fill {
+        width: 42%;
+        height: 100%;
+        border-radius: inherit;
+        background: var(--splash-accent);
+        animation: app-startup-splash-indeterminate 1.15s ease-in-out infinite;
+      }
+      @keyframes app-startup-splash-indeterminate {
+        0% { transform: translateX(-120%); }
+        100% { transform: translateX(320%); }
+      }
+    </style>
   </head>
   <body>
+    <div id="app-startup-splash" role="status" aria-live="polite" aria-label="Loading Psysonic">
+      <svg class="app-startup-splash__logo" viewBox="0 0 115.549 130.30972" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+        <defs>
+          <linearGradient id="startupSplashLogoGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+            <stop offset="0%" stop-color="var(--splash-logo-start)" />
+            <stop offset="100%" stop-color="var(--splash-logo-end)" />
+          </linearGradient>
+        </defs>
+        <g transform="translate(220.53237,27.789086)">
+          <path fill="url(#startupSplashLogoGrad)" d="m -191.83501,87.581279 v -14.93937 l 1.01946,-0.029 c 1.8496,-0.0526 5.09881,-2.007 6.98453,-4.20123 2.13731,-2.48697 3.28384,-4.43657 4.52545,-7.69521 0.51751,-1.35819 1.078,-2.78694 1.24554,-3.175 0.16755,-0.38805 0.88173,-2.7693 1.58707,-5.29166 0.70533,-2.52236 1.41605,-4.90361 1.57937,-5.29167 0.16441,-0.39067 0.30759,11.85061 0.32081,27.42847 l 0.0239,28.134031 h -8.64306 -8.64305 z m -3.42317,-19.65031 c -0.81559,-0.16111 -1.84746,-0.48272 -2.29306,-0.71468 -1.09242,-0.5687 -2.72853,-2.16884 -2.74064,-2.68038 -0.005,-0.22765 -0.38465,-0.86265 -0.84281,-1.41111 -0.8626,-1.03264 -2.38323,-4.66133 -4.63113,-11.05137 -1.72997,-4.91772 -1.63358,-4.68451 -3.35352,-8.11389 -0.82714,-1.64924 -1.91998,-3.45186 -2.42853,-4.00582 -1.28805,-1.40307 -4.41406,-2.7715 -6.89485,-3.01827 l -2.08965,-0.20785 1.43221,-0.99035 c 1.5468,-1.06957 5.31147,-2.35399 6.9124,-2.35835 1.72563,-0.005 4.25283,0.7809 5.71247,1.77575 1.63175,1.11217 3.92377,3.83335 3.77488,4.48172 -0.0559,0.24344 0.11427,0.44261 0.37817,0.44261 0.53171,0 3.78445,6.24176 3.78445,7.26208 0,0.15195 0.30609,0.92171 0.6802,1.71057 0.37412,0.78887 1.08633,2.44854 1.5827,3.68817 1.00279,2.50434 2.57055,5.33152 2.95544,5.32962 0.85183,-0.004 3.83204,-7.97894 5.40479,-14.46266 1.9193,-7.91232 5.01161,-18.44694 6.10967,-20.81389 2.30114,-4.96024 4.60601,-7.03734 8.12223,-7.31959 1.95377,-0.15683 2.44243,-0.0601 4.01261,0.79453 2.49546,1.35819 3.31044,2.35029 5.40102,6.57479 0.93741,1.89425 3.29625,9.1126 4.36446,13.35583 0.51289,2.03729 1.21262,4.57729 1.55498,5.64444 0.34236,1.06716 0.83543,2.65466 1.09573,3.52778 0.96371,3.23267 3.75139,8.2344 5.51689,9.89856 2.09506,1.9748 4.10606,3.2977 5.85136,3.84922 0.72761,0.22993 1.32292,0.49404 1.32292,0.58692 0,0.0929 -0.71641,0.48577 -1.59202,0.87309 -2.29705,1.01609 -6.48839,1.02714 -8.75823,0.0231 -3.42674,-1.51581 -6.17101,-4.45149 -8.36088,-8.94406 -0.59782,-1.22642 -1.23412,-2.50231 -1.41401,-2.8353 -0.17988,-0.333 -0.47718,-1.20612 -0.66066,-1.94028 -0.74987,-3.00045 -6.42415,-19.25706 -6.99617,-20.04376 -0.79895,-1.09881 -0.87818,-1.08476 -1.55823,0.27628 -1.1693,2.3402 -2.07427,5.18987 -3.61302,11.37709 -3.03871,12.21839 -6.36478,22.38234 -8.0081,24.47148 -0.36655,0.466 -0.66646,0.99153 -0.66646,1.16785 0,0.86017 -2.61454,3.05174 -4.28395,3.59089 -1.94625,0.62857 -2.53141,0.65417 -4.78366,0.20926 z m 49.82815,-13.29265 c -2.77991,-0.70614 -6.29714,-6.05076 -8.15323,-12.38927 -0.30389,-1.03778 -0.47868,-1.96073 -0.38841,-2.051 0.0903,-0.0903 1.5695,-0.22877 3.28719,-0.30779 8.47079,-0.38969 9.78292,-0.63406 14.05919,-2.61837 3.78653,-1.75706 9.09259,-6.79386 10.56941,-10.03304 3.78708,-8.30644 4.33485,-14.20262 2.08448,-22.4376404 -1.15336,-4.22063002 -3.6401,-8.21361 -6.73205,-10.80969 -1.12271,-0.94265 -2.12066,-1.8146 -2.21767,-1.93765 -0.3794,-0.48123 -4.30858,-2.4333296 -6.41876,-3.1889796 -2.16778,-0.77628 -2.64336,-0.79956 -18.71666,-0.91597 l -16.49236,-0.11945 V -0.68605142 10.798429 h -0.8256 c -1.53109,0 -5.09758,2.09614 -6.79456,3.99338 -1.65639,1.85186 -4.54446,7.43871 -5.41264,10.47051 -0.25002,0.87312 -0.58222,1.98437 -0.73823,2.46944 -0.39136,1.2169 -2.0765,7.30176 -3.12634,11.28889 -0.2052,0.7793 -0.33685,-11.27627 -0.35693,-32.6846104 l -0.0318,-33.9193396 1.55319,-0.12371 c 0.85426,-0.068 12.32395,-0.10028 25.4882,-0.0716 20.69377,0.045 24.2694,0.12953 26.40444,0.62402 3.9887,0.92382 7.58472,2.04932 7.58472,2.3739 0,0.16576 0.52886,0.30139 1.17524,0.30139 2.09331,0 10.76432,4.87704 10.22435,5.75072 -0.12186,0.19718 -0.0447,0.24734 0.17328,0.11263 0.60692,-0.3751 4.21691,3.0333 6.9953,6.60467 2.06429,2.6534496 4.63504,8.4775396 5.94174,13.4611396 1.7681,6.7433 1.74625,15.8657704 -0.0549,22.9305504 -2.11084,8.27937 -4.97852,13.41407 -10.75456,19.25647 -2.59968,2.62955 -8.78375,7.02548 -9.88326,7.02548 -0.27557,0 -0.68644,0.1854 -0.91304,0.412 -0.39593,0.39593 -0.78905,0.56749 -4.31522,1.88319 -3.68968,1.37672 -10.83412,2.28545 -13.21446,1.68081 z m 7.57002,-15.26489 c 0,-0.19403 -0.07,-0.35278 -0.15557,-0.35278 -0.0856,0 -0.25368,0.15875 -0.3736,0.35278 -0.11992,0.19403 -0.0499,0.35278 0.15557,0.35278 0.20548,0 0.3736,-0.15875 0.3736,-0.35278 z" />
+        </g>
+      </svg>
+      <div class="app-startup-splash__bar" aria-hidden="true">
+        <div class="app-startup-splash__bar-fill"></div>
+      </div>
+      <span class="app-startup-splash__label">Loading</span>
+    </div>
     <div id="root"></div>
+    <script src="/startup-splash-reveal.js"></script>
     <script type="module" src="/src/main.tsx"></script>
   </body>
 </html>

nix/upstream-sources.json

@@ -1,3 +1,3 @@
 {
-  "npmDepsHash": "sha256-7BvKeTkZzAQoBVm2vw2oZRsRKWN/Du1pn89U1rtc47k="
+  "npmDepsHash": "sha256-T2zrXt3cvqjmeoEOjTPoEiJKuzLv6R5QMuwTeNBSH/8="
 }

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "psysonic",
-  "version": "1.48.0-dev",
+  "version": "1.48.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "psysonic",
-      "version": "1.48.0-dev",
+      "version": "1.48.1",
       "dependencies": {
         "@fontsource-variable/dm-sans": "^5.2.8",
         "@fontsource-variable/figtree": "^5.2.10",
@@ -56,7 +56,7 @@
         "@types/react-dom": "^19.2.3",
         "@vitejs/plugin-react": "^6.0.2",
         "@vitest/coverage-v8": "^4.1.8",
-        "esbuild": "^0.28.0",
+        "esbuild": "^0.28.1",
         "jsdom": "^29.1.1",
         "typescript": "^6.0.3",
         "vite": "^8.0.14",
@@ -394,9 +394,9 @@
       }
     },
     "node_modules/@esbuild/aix-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
-      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.1.tgz",
+      "integrity": "sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==",
       "cpu": [
         "ppc64"
       ],
@@ -411,9 +411,9 @@
       }
     },
     "node_modules/@esbuild/android-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
-      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.1.tgz",
+      "integrity": "sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==",
       "cpu": [
         "arm"
       ],
@@ -428,9 +428,9 @@
       }
     },
     "node_modules/@esbuild/android-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
-      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.1.tgz",
+      "integrity": "sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==",
       "cpu": [
         "arm64"
       ],
@@ -445,9 +445,9 @@
       }
     },
     "node_modules/@esbuild/android-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
-      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.1.tgz",
+      "integrity": "sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==",
       "cpu": [
         "x64"
       ],
@@ -462,9 +462,9 @@
       }
     },
     "node_modules/@esbuild/darwin-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
-      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.1.tgz",
+      "integrity": "sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==",
       "cpu": [
         "arm64"
       ],
@@ -479,9 +479,9 @@
       }
     },
     "node_modules/@esbuild/darwin-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
-      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.1.tgz",
+      "integrity": "sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==",
       "cpu": [
         "x64"
       ],
@@ -496,9 +496,9 @@
       }
     },
     "node_modules/@esbuild/freebsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==",
       "cpu": [
         "arm64"
       ],
@@ -513,9 +513,9 @@
       }
     },
     "node_modules/@esbuild/freebsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
-      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==",
       "cpu": [
         "x64"
       ],
@@ -530,9 +530,9 @@
       }
     },
     "node_modules/@esbuild/linux-arm": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
-      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.1.tgz",
+      "integrity": "sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==",
       "cpu": [
         "arm"
       ],
@@ -547,9 +547,9 @@
       }
     },
     "node_modules/@esbuild/linux-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
-      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.1.tgz",
+      "integrity": "sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==",
       "cpu": [
         "arm64"
       ],
@@ -564,9 +564,9 @@
       }
     },
     "node_modules/@esbuild/linux-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
-      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.1.tgz",
+      "integrity": "sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==",
       "cpu": [
         "ia32"
       ],
@@ -581,9 +581,9 @@
       }
     },
     "node_modules/@esbuild/linux-loong64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
-      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.1.tgz",
+      "integrity": "sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==",
       "cpu": [
         "loong64"
       ],
@@ -598,9 +598,9 @@
       }
     },
     "node_modules/@esbuild/linux-mips64el": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
-      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.1.tgz",
+      "integrity": "sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==",
       "cpu": [
         "mips64el"
       ],
@@ -615,9 +615,9 @@
       }
     },
     "node_modules/@esbuild/linux-ppc64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
-      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.1.tgz",
+      "integrity": "sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==",
       "cpu": [
         "ppc64"
       ],
@@ -632,9 +632,9 @@
       }
     },
     "node_modules/@esbuild/linux-riscv64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
-      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.1.tgz",
+      "integrity": "sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==",
       "cpu": [
         "riscv64"
       ],
@@ -649,9 +649,9 @@
       }
     },
     "node_modules/@esbuild/linux-s390x": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
-      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.1.tgz",
+      "integrity": "sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==",
       "cpu": [
         "s390x"
       ],
@@ -666,9 +666,9 @@
       }
     },
     "node_modules/@esbuild/linux-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
-      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.1.tgz",
+      "integrity": "sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==",
       "cpu": [
         "x64"
       ],
@@ -683,9 +683,9 @@
       }
     },
     "node_modules/@esbuild/netbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==",
       "cpu": [
         "arm64"
       ],
@@ -700,9 +700,9 @@
       }
     },
     "node_modules/@esbuild/netbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==",
       "cpu": [
         "x64"
       ],
@@ -717,9 +717,9 @@
       }
     },
     "node_modules/@esbuild/openbsd-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
-      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.1.tgz",
+      "integrity": "sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==",
       "cpu": [
         "arm64"
       ],
@@ -734,9 +734,9 @@
       }
     },
     "node_modules/@esbuild/openbsd-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
-      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.1.tgz",
+      "integrity": "sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==",
       "cpu": [
         "x64"
       ],
@@ -751,9 +751,9 @@
       }
     },
     "node_modules/@esbuild/openharmony-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
-      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.1.tgz",
+      "integrity": "sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==",
       "cpu": [
         "arm64"
       ],
@@ -768,9 +768,9 @@
       }
     },
     "node_modules/@esbuild/sunos-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
-      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.1.tgz",
+      "integrity": "sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==",
       "cpu": [
         "x64"
       ],
@@ -785,9 +785,9 @@
       }
     },
     "node_modules/@esbuild/win32-arm64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
-      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.1.tgz",
+      "integrity": "sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==",
       "cpu": [
         "arm64"
       ],
@@ -802,9 +802,9 @@
       }
     },
     "node_modules/@esbuild/win32-ia32": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
-      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.1.tgz",
+      "integrity": "sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==",
       "cpu": [
         "ia32"
       ],
@@ -819,9 +819,9 @@
       }
     },
     "node_modules/@esbuild/win32-x64": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
-      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.1.tgz",
+      "integrity": "sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==",
       "cpu": [
         "x64"
       ],
@@ -2366,9 +2366,9 @@
       }
     },
     "node_modules/esbuild": {
-      "version": "0.28.0",
-      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
-      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+      "version": "0.28.1",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.1.tgz",
+      "integrity": "sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==",
       "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
@@ -2379,32 +2379,32 @@
         "node": ">=18"
       },
       "optionalDependencies": {
-        "@esbuild/aix-ppc64": "0.28.0",
-        "@esbuild/android-arm": "0.28.0",
-        "@esbuild/android-arm64": "0.28.0",
-        "@esbuild/android-x64": "0.28.0",
-        "@esbuild/darwin-arm64": "0.28.0",
-        "@esbuild/darwin-x64": "0.28.0",
-        "@esbuild/freebsd-arm64": "0.28.0",
-        "@esbuild/freebsd-x64": "0.28.0",
-        "@esbuild/linux-arm": "0.28.0",
-        "@esbuild/linux-arm64": "0.28.0",
-        "@esbuild/linux-ia32": "0.28.0",
-        "@esbuild/linux-loong64": "0.28.0",
-        "@esbuild/linux-mips64el": "0.28.0",
-        "@esbuild/linux-ppc64": "0.28.0",
-        "@esbuild/linux-riscv64": "0.28.0",
-        "@esbuild/linux-s390x": "0.28.0",
-        "@esbuild/linux-x64": "0.28.0",
-        "@esbuild/netbsd-arm64": "0.28.0",
-        "@esbuild/netbsd-x64": "0.28.0",
-        "@esbuild/openbsd-arm64": "0.28.0",
-        "@esbuild/openbsd-x64": "0.28.0",
-        "@esbuild/openharmony-arm64": "0.28.0",
-        "@esbuild/sunos-x64": "0.28.0",
-        "@esbuild/win32-arm64": "0.28.0",
-        "@esbuild/win32-ia32": "0.28.0",
-        "@esbuild/win32-x64": "0.28.0"
+        "@esbuild/aix-ppc64": "0.28.1",
+        "@esbuild/android-arm": "0.28.1",
+        "@esbuild/android-arm64": "0.28.1",
+        "@esbuild/android-x64": "0.28.1",
+        "@esbuild/darwin-arm64": "0.28.1",
+        "@esbuild/darwin-x64": "0.28.1",
+        "@esbuild/freebsd-arm64": "0.28.1",
+        "@esbuild/freebsd-x64": "0.28.1",
+        "@esbuild/linux-arm": "0.28.1",
+        "@esbuild/linux-arm64": "0.28.1",
+        "@esbuild/linux-ia32": "0.28.1",
+        "@esbuild/linux-loong64": "0.28.1",
+        "@esbuild/linux-mips64el": "0.28.1",
+        "@esbuild/linux-ppc64": "0.28.1",
+        "@esbuild/linux-riscv64": "0.28.1",
+        "@esbuild/linux-s390x": "0.28.1",
+        "@esbuild/linux-x64": "0.28.1",
+        "@esbuild/netbsd-arm64": "0.28.1",
+        "@esbuild/netbsd-x64": "0.28.1",
+        "@esbuild/openbsd-arm64": "0.28.1",
+        "@esbuild/openbsd-x64": "0.28.1",
+        "@esbuild/openharmony-arm64": "0.28.1",
+        "@esbuild/sunos-x64": "0.28.1",
+        "@esbuild/win32-arm64": "0.28.1",
+        "@esbuild/win32-ia32": "0.28.1",
+        "@esbuild/win32-x64": "0.28.1"
       }
     },
     "node_modules/estree-walker": {

package.json

@@ -1,18 +1,19 @@
 {
   "name": "psysonic",
-  "version": "1.48.0-dev",
+  "version": "1.48.1",
   "private": true,
   "scripts": {
     "check:css-imports": "node scripts/check-css-import-graph.mjs",
-    "dev": "vite",
-    "build": "tsc && vite build",
+    "prebuild:release-notes": "node scripts/generate-release-notes-bundle.mjs",
+    "dev": "npm run prebuild:release-notes && vite",
+    "build": "npm run prebuild:release-notes && tsc && vite build",
     "preview": "vite preview",
     "tauri": "tauri",
-    "tauri:dev": "tauri dev",
-    "tauri:build": "tauri build",
-    "test": "vitest run && npm run check:css-imports",
+    "tauri:dev": "npm run prebuild:release-notes && tauri dev",
+    "tauri:build": "npm run prebuild:release-notes && tauri build",
+    "test": "npm run prebuild:release-notes && vitest run && node --test scripts/extract-release-section.test.mjs && npm run check:css-imports",
     "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage && npm run check:css-imports"
+    "test:coverage": "npm run prebuild:release-notes && vitest run --coverage && npm run check:css-imports"
   },
   "dependencies": {
     "@fontsource-variable/dm-sans": "^5.2.8",
@@ -63,7 +64,7 @@
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.2",
     "@vitest/coverage-v8": "^4.1.8",
-    "esbuild": "^0.28.0",
+    "esbuild": "^0.28.1",
     "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
     "vite": "^8.0.14",

public/startup-splash-preflight.js

@@ -0,0 +1,161 @@
+/**
+ * Synchronous startup splash theme (before the Vite bundle loads).
+ * Keep palette ids/hex in sync with `src/config/startupSplashPalettes.ts`.
+ */
+(function startupSplashPreflight() {
+  var THEME_KEY = 'psysonic_theme';
+  var INSTALLED_KEY = 'psysonic_installed_themes';
+  var DEFAULT = {
+    bg: '#1e1e2e',
+    text: '#cdd6f4',
+    muted: '#a6adc8',
+    accent: '#cba6f7',
+    track: '#313244',
+    logoStart: '#cba6f7',
+    logoEnd: '#89b4fa',
+  };
+  var BUILTIN = {
+    mocha: DEFAULT,
+    latte: {
+      bg: '#eff1f5',
+      text: '#4c4f69',
+      muted: '#6c6f85',
+      accent: '#8839ef',
+      track: '#ccd0da',
+      logoStart: '#8839ef',
+      logoEnd: '#1e66f5',
+    },
+    'kanagawa-wave': {
+      bg: '#1F1F28',
+      text: '#DCD7BA',
+      muted: '#727169',
+      accent: '#7E9CD8',
+      track: '#2A2A37',
+      logoStart: '#7E9CD8',
+      logoEnd: '#957FB8',
+    },
+    'stark-hud': {
+      bg: '#0b0f15',
+      text: '#e0f7fa',
+      muted: '#7da5aa',
+      accent: '#00f2ff',
+      track: '#141b24',
+      logoStart: '#00f2ff',
+      logoEnd: '#7df9ff',
+    },
+    'vision-dark': {
+      bg: '#0d0b12',
+      text: '#f2eef8',
+      muted: '#a6a2b8',
+      accent: '#ffd700',
+      track: '#16131e',
+      logoStart: '#ffd700',
+      logoEnd: '#a07af8',
+    },
+    'vision-navy': {
+      bg: '#0a1628',
+      text: '#e8eef8',
+      muted: '#9caac2',
+      accent: '#ffd700',
+      track: '#12213a',
+      logoStart: '#ffd700',
+      logoEnd: '#a07af8',
+    },
+  };
+
+  function readCssVar(css, name) {
+    var match = css.match(new RegExp(name + '\\s*:\\s*([^;]+);'));
+    var value = match && match[1] ? match[1].trim() : '';
+    return value || null;
+  }
+
+  function resolveScheduledTheme(state) {
+    if (!state.enableThemeScheduler) return state.theme;
+    var now = new Date();
+    var nowMins = now.getHours() * 60 + now.getMinutes();
+    var dayParts = state.timeDayStart.split(':').map(Number);
+    var nightParts = state.timeNightStart.split(':').map(Number);
+    var dayMins = dayParts[0] * 60 + dayParts[1];
+    var nightMins = nightParts[0] * 60 + nightParts[1];
+    var isDay = dayMins < nightMins
+      ? nowMins >= dayMins && nowMins < nightMins
+      : nowMins >= dayMins || nowMins < nightMins;
+    return isDay ? state.themeDay : state.themeNight;
+  }
+
+  function readThemeState() {
+    try {
+      var raw = localStorage.getItem(THEME_KEY);
+      if (!raw) return null;
+      var parsed = JSON.parse(raw);
+      var s = parsed && parsed.state;
+      if (!s) return null;
+      return {
+        enableThemeScheduler: !!s.enableThemeScheduler,
+        theme: String(s.theme || 'mocha'),
+        themeDay: String(s.themeDay || 'latte'),
+        themeNight: String(s.themeNight || 'mocha'),
+        timeDayStart: String(s.timeDayStart || '07:00'),
+        timeNightStart: String(s.timeNightStart || '19:00'),
+      };
+    } catch (_err) {
+      return null;
+    }
+  }
+
+  function readInstalledThemes() {
+    try {
+      var raw = localStorage.getItem(INSTALLED_KEY);
+      if (!raw) return [];
+      var parsed = JSON.parse(raw);
+      var themes = parsed && parsed.state && parsed.state.themes;
+      return Array.isArray(themes) ? themes : [];
+    } catch (_err) {
+      return [];
+    }
+  }
+
+  function paletteForTheme(themeId, installedThemes) {
+    if (BUILTIN[themeId]) return BUILTIN[themeId];
+    for (var i = 0; i < installedThemes.length; i += 1) {
+      var theme = installedThemes[i];
+      if (!theme || theme.id !== themeId || !theme.css) continue;
+      var bg = readCssVar(theme.css, '--bg-app');
+      var accent = readCssVar(theme.css, '--accent');
+      if (!bg || !accent) break;
+      var logoStart = readCssVar(theme.css, '--logo-color-start') || accent;
+      var logoEnd = readCssVar(theme.css, '--logo-color-end')
+        || readCssVar(theme.css, '--accent-2')
+        || accent;
+      return {
+        bg: bg,
+        text: readCssVar(theme.css, '--text-primary') || readCssVar(theme.css, '--ctp-text') || DEFAULT.text,
+        muted: readCssVar(theme.css, '--text-muted') || readCssVar(theme.css, '--ctp-subtext0') || DEFAULT.muted,
+        accent: accent,
+        track: readCssVar(theme.css, '--bg-card') || readCssVar(theme.css, '--border-subtle') || DEFAULT.track,
+        logoStart: logoStart,
+        logoEnd: logoEnd,
+      };
+    }
+    return DEFAULT;
+  }
+
+  function applyPalette(themeId, palette) {
+    var root = document.documentElement;
+    root.setAttribute('data-theme', themeId);
+    root.style.setProperty('--startup-splash-bg', palette.bg);
+    root.style.setProperty('--startup-splash-text', palette.text);
+    root.style.setProperty('--startup-splash-muted', palette.muted);
+    root.style.setProperty('--startup-splash-accent', palette.accent);
+    root.style.setProperty('--startup-splash-track', palette.track);
+    root.style.setProperty('--startup-splash-logo-start', palette.logoStart);
+    root.style.setProperty('--startup-splash-logo-end', palette.logoEnd);
+    root.style.background = palette.bg;
+    if (document.body) document.body.style.background = palette.bg;
+  }
+
+  var persisted = readThemeState();
+  var themeId = persisted ? resolveScheduledTheme(persisted) : 'mocha';
+  var palette = paletteForTheme(themeId, readInstalledThemes());
+  applyPalette(themeId, palette);
+})();

public/startup-splash-reveal.js

@@ -0,0 +1,28 @@
+/**
+ * Show the native window after the inline startup splash has painted.
+ * __TAURI_INTERNALS__ may not exist yet when this script first runs.
+ */
+(function startupSplashReveal() {
+  var MAX_ATTEMPTS = 60;
+
+  function tryShowMainWindow() {
+    var internals = window.__TAURI_INTERNALS__;
+    if (!internals || typeof internals.invoke !== 'function') return false;
+    internals.invoke('plugin:window|show', { label: 'main' }).catch(function () {});
+    return true;
+  }
+
+  function reveal(attempt) {
+    if (tryShowMainWindow()) return;
+    if (attempt >= MAX_ATTEMPTS) return;
+    window.setTimeout(function () {
+      reveal(attempt + 1);
+    }, 50);
+  }
+
+  requestAnimationFrame(function () {
+    requestAnimationFrame(function () {
+      reveal(0);
+    });
+  });
+})();

scripts/extract-release-section.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Extract the body of a ## [version] section from a Keep-a-Changelog-style file.
+ * Resolution matches src/utils/releaseNotes/releaseNotesMatch.ts.
+ *
+ * Usage: node scripts/extract-release-section.mjs <file> <version> [--allow-empty]
+ * Stdout: section body (no ## header). Exit 1 if empty unless --allow-empty.
+ */
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+const SEMVER_CORE = /^v?(\d+\.\d+\.\d+)/i;
+
+function versionCore(version) {
+  const m = version.trim().match(SEMVER_CORE);
+  return m ? m[1] : null;
+}
+
+function isPlainTriple(header) {
+  return /^\d+\.\d+\.\d+$/.test(header.trim());
+}
+
+function splitBlocks(raw) {
+  return raw.split(/\n(?=## \[)/).filter((b) => b.startsWith('## ['));
+}
+
+function headerVersion(block) {
+  const m = block.match(/^## \[([^\]]+)\]/);
+  return m ? m[1] : null;
+}
+
+function parseBlock(block) {
+  const lines = block.split('\n');
+  const m = lines[0].match(/## \[([^\]]+)\](?:\s*-\s*(.+))?/);
+  if (!m) return null;
+  return {
+    headerVersion: m[1],
+    date: (m[2] ?? '').trim(),
+    body: lines.slice(1).join('\n').trim(),
+  };
+}
+
+export function findReleaseSection(raw, appVersion) {
+  const blocks = splitBlocks(raw);
+
+  const exact = blocks.find((b) => b.startsWith(`## [${appVersion}]`));
+  if (exact) return parseBlock(exact);
+
+  const appCore = versionCore(appVersion);
+  if (!appCore) return null;
+
+  const candidates = blocks.filter((b) => {
+    const hv = headerVersion(b);
+    return hv !== null && versionCore(hv) === appCore;
+  });
+  if (candidates.length === 0) return null;
+
+  const plain = candidates.find((b) => {
+    const hv = headerVersion(b);
+    return hv !== null && isPlainTriple(hv);
+  });
+  return parseBlock(plain ?? candidates[0]);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const allowEmpty = args.includes('--allow-empty');
+  const positional = args.filter((a) => a !== '--allow-empty');
+  const [file, version] = positional;
+
+  if (!file || !version) {
+    console.error('Usage: node scripts/extract-release-section.mjs <file> <version> [--allow-empty]');
+    process.exit(2);
+  }
+
+  const raw = readFileSync(file, 'utf8');
+  const entry = findReleaseSection(raw, version);
+  const body = entry?.body?.trim() ?? '';
+
+  if (!body) {
+    if (allowEmpty) process.exit(0);
+    console.error(`No release section found in ${file} for version ${version}`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`${body}\n`);
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) main();

scripts/extract-release-section.test.mjs

@@ -0,0 +1,26 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { findReleaseSection } from './extract-release-section.mjs';
+
+const FIXTURE = `
+## [1.48.0] - 2026-06-10
+
+## Highlights
+- One
+
+## [1.47.0]
+- Old
+`;
+
+describe('findReleaseSection', () => {
+  it('matches base line for -rc versions', () => {
+    const entry = findReleaseSection(FIXTURE, '1.48.0-rc.3');
+    assert.equal(entry.headerVersion, '1.48.0');
+    assert.match(entry.body, /Highlights/);
+  });
+
+  it('matches base line for -dev versions', () => {
+    const entry = findReleaseSection(FIXTURE, '1.48.0-dev');
+    assert.equal(entry.headerVersion, '1.48.0');
+  });
+});

scripts/generate-release-notes-bundle.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Build src/generated/releaseNotesBundle.ts for production bundles.
+ * Embeds only the ## [X.Y.Z] slice for package.json version (dev, RC, and stable).
+ * tauri:dev reads live markdown from the repo via Vite ?raw imports instead.
+ */
+
+import { readFileSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findReleaseSection } from './extract-release-section.mjs';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+const version = pkg.version;
+
+const whatsNewPath = join(root, 'WHATS_NEW.md');
+const changelogPath = join(root, 'CHANGELOG.md');
+const whatsNewFull = readFileSync(whatsNewPath, 'utf8');
+const changelogFull = readFileSync(changelogPath, 'utf8');
+
+function sliceForVersion(full, fileLabel) {
+  const entry = findReleaseSection(full, version);
+  if (!entry?.body) {
+    console.warn(`warn: no section in ${fileLabel} for ${version} — embedding empty slice`);
+    return '';
+  }
+  const dateSuffix = entry.date ? ` - ${entry.date}` : '';
+  return `## [${entry.headerVersion}]${dateSuffix}\n\n${entry.body}`;
+}
+
+const whatsNewRaw = sliceForVersion(whatsNewFull, 'WHATS_NEW.md');
+const changelogRaw = sliceForVersion(changelogFull, 'CHANGELOG.md');
+
+const outDir = join(root, 'src/generated');
+mkdirSync(outDir, { recursive: true });
+
+const ts = `/** @generated — run: node scripts/generate-release-notes-bundle.mjs */
+export const WHATS_NEW_RAW: string = ${JSON.stringify(whatsNewRaw)};
+
+export const CHANGELOG_RAW: string = ${JSON.stringify(changelogRaw)};
+`;
+
+writeFileSync(join(outDir, 'releaseNotesBundle.ts'), ts, 'utf8');
+console.log(`wrote src/generated/releaseNotesBundle.ts (sliced for ${version})`);

scripts/install.sh

@@ -14,20 +14,22 @@ YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m' # No Color
 
+# Log helpers write to stderr so functions that return values via stdout
+# (e.g. get_download_url) stay clean when called in command substitution.
 info() {
-    echo -e "${BLUE}[INFO]${NC} $1"
+    echo -e "${BLUE}[INFO]${NC} $1" >&2
 }
 
 success() {
-    echo -e "${GREEN}[SUCCESS]${NC} $1"
+    echo -e "${GREEN}[SUCCESS]${NC} $1" >&2
 }
 
 warn() {
-    echo -e "${YELLOW}[WARN]${NC} $1"
+    echo -e "${YELLOW}[WARN]${NC} $1" >&2
 }
 
 error() {
-    echo -e "${RED}[ERROR]${NC} $1"
+    echo -e "${RED}[ERROR]${NC} $1" >&2
     exit 1
 }
 
@@ -105,7 +107,7 @@ install_package() {
     
     if [ "$OS_TYPE" = "debian" ]; then
         package_file="${package_file}.deb"
-        curl -L -o "$package_file" "$download_url"
+        curl --fail --globoff -L -o "$package_file" "$download_url"
         
         info "Installing package..."
         $PACKAGE_MANAGER install -y "$package_file" || {
@@ -114,7 +116,7 @@ install_package() {
         }
     elif [ "$OS_TYPE" = "rhel" ]; then
         package_file="${package_file}.rpm"
-        curl -L -o "$package_file" "$download_url"
+        curl --fail --globoff -L -o "$package_file" "$download_url"
         
         info "Installing package..."
         $PACKAGE_MANAGER install -y "$package_file"
@@ -128,8 +130,17 @@ install_package() {
 check_installed() {
     if command -v $APP_NAME &> /dev/null || command -v ${APP_NAME^} &> /dev/null; then
         warn "${APP_NAME} appears to be already installed."
-        read -p "Do you want to reinstall? (y/N): " -n 1 -r
-        echo
+        # Under `curl ... | bash`, stdin is the script stream itself, so
+        # read the answer from the controlling terminal instead. Probe by
+        # opening: `[ -r /dev/tty ]` passes on the 0666 device node even
+        # without a controlling terminal; only open() reports the failure.
+        if { : < /dev/tty; } 2>/dev/null; then
+            read -p "Do you want to reinstall? (y/N): " -n 1 -r < /dev/tty
+            echo
+        else
+            warn "No terminal available for prompt; skipping reinstall."
+            exit 0
+        fi
         if [[ ! $REPLY =~ ^[Yy]$ ]]; then
             info "Installation cancelled."
             exit 0

src-tauri/Cargo.lock

@@ -4114,7 +4114,7 @@ dependencies = [
 
 [[package]]
 name = "psysonic"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "biquad",
  "dasp_sample",
@@ -4167,7 +4167,7 @@ dependencies = [
 
 [[package]]
 name = "psysonic-analysis"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "ebur128",
  "futures-util",
@@ -4186,7 +4186,7 @@ dependencies = [
 
 [[package]]
 name = "psysonic-audio"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "biquad",
  "dasp_sample",
@@ -4216,7 +4216,7 @@ dependencies = [
 
 [[package]]
 name = "psysonic-core"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "libc",
  "serde",
@@ -4225,7 +4225,7 @@ dependencies = [
 
 [[package]]
 name = "psysonic-integration"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "discord-rich-presence",
  "futures-util",
@@ -4242,7 +4242,7 @@ dependencies = [
 
 [[package]]
 name = "psysonic-library"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "psysonic-core",
  "psysonic-integration",
@@ -4252,14 +4252,12 @@ dependencies = [
  "serde_json",
  "tauri",
  "tokio",
- "twox-hash",
- "unicode-normalization",
  "wiremock",
 ]
 
 [[package]]
 name = "psysonic-syncfs"
-version = "1.48.0-dev"
+version = "1.48.1"
 dependencies = [
  "futures-util",
  "id3",
@@ -4268,6 +4266,7 @@ dependencies = [
  "psysonic-analysis",
  "psysonic-audio",
  "psysonic-core",
+ "psysonic-library",
  "reqwest",
  "serde",
  "serde_json",
@@ -6603,15 +6602,6 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
-[[package]]
-name = "twox-hash"
-version = "2.1.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ea3136b675547379c4bd395ca6b938e5ad3c3d20fad76e7fe85f9e0d011419c"
-dependencies = [
- "rand 0.9.4",
-]
-
 [[package]]
 name = "typed-path"
 version = "0.12.3"
@@ -6694,15 +6684,6 @@ version = "1.0.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
 
-[[package]]
-name = "unicode-normalization"
-version = "0.1.25"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
-dependencies = [
- "tinyvec",
-]
-
 [[package]]
 name = "unicode-segmentation"
 version = "1.13.2"

src-tauri/Cargo.toml

@@ -3,9 +3,10 @@ members = ["crates/*"]
 resolver = "2"
 
 [workspace.package]
-version = "1.48.0-dev"
+version = "1.48.1"
 edition = "2021"
 rust-version = "1.95"
+license = "GPL-3.0-or-later"
 
 [workspace.dependencies]
 tempfile = "3"
@@ -18,7 +19,7 @@ name = "psysonic"
 version.workspace = true
 description = "Psysonic Desktop Music Player"
 authors = []
-license = ""
+license.workspace = true
 repository = ""
 default-run = "psysonic"
 edition.workspace = true

src-tauri/about.toml

@@ -21,6 +21,8 @@ accepted = [
     "OpenSSL",
     "BSL-1.0",
     "CDLA-Permissive-2.0",
+    "GPL-3.0-or-later",
+    "bzip2-1.0.6",
 ]
 
 # Skip the build host's own platform-pinning; we want a list across all targets
@@ -38,5 +40,4 @@ targets = [
 ignore-build-dependencies = false
 ignore-dev-dependencies = true
 ignore-transitive-dependencies = false
-filter-noassertion = false
 workarounds = ["ring"]

src-tauri/capabilities/default.json

@@ -22,6 +22,7 @@
     "fs:allow-write-file",
     "fs:allow-read-file",
     "fs:allow-mkdir",
+    "fs:allow-app-write-recursive",
     "fs:scope-download-recursive",
     "fs:scope-home-recursive",
     "window-state:allow-save-window-state",

src-tauri/crates/psysonic-analysis/Cargo.toml

@@ -3,6 +3,7 @@ name = "psysonic-analysis"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license.workspace = true
 publish = false
 
 [dependencies]

src-tauri/crates/psysonic-analysis/src/analysis_runtime.rs

@@ -291,7 +291,7 @@ impl AnalysisBackfillQueueState {
     }
 }
 
-/// Frontend-maintained set of queue-neighbour track ids (next ~5 + preload next).
+/// Frontend-maintained set of queue-neighbour track ids (next ~5 in queue).
 #[derive(Default)]
 pub struct PlaybackPriorityHints {
     middle_track_ids: Mutex<HashSet<String>>,
@@ -516,6 +516,145 @@ pub async fn enqueue_track_analysis_from_file(
     enqueue_track_analysis(app, server_id, track_id, &bytes, format_hint.as_deref(), priority).await
 }
 
+/// Library-tier offline pin: reuse waveform/LUFS cached under the playback index key,
+/// plan enrichment under the library UUID, and skip work when both scopes are complete.
+pub async fn enqueue_offline_library_analysis_from_file(
+    app: &tauri::AppHandle,
+    server_index_key: &str,
+    library_server_id: &str,
+    track_id: &str,
+    file_path: &std::path::Path,
+    explicit_priority: Option<AnalysisBackfillPriority>,
+) -> Result<(), String> {
+    use tokio::io::AsyncReadExt;
+
+    use crate::track_analysis_plan::plan_track_analysis_offline_library;
+
+    let mut file = tokio::fs::File::open(file_path)
+        .await
+        .map_err(|e| e.to_string())?;
+    let mut prefix = vec![0u8; 16384];
+    let n = file.read(&mut prefix).await.map_err(|e| e.to_string())?;
+    prefix.truncate(n);
+    if prefix.is_empty() {
+        return Ok(());
+    }
+    let content_hash = analysis_cache::md5_first_16kb(&prefix);
+    let plan = plan_track_analysis_offline_library(
+        app,
+        &[server_index_key, library_server_id],
+        library_server_id,
+        track_id,
+        &content_hash,
+    );
+    if !plan.any() {
+        crate::app_deprintln!(
+            "[analysis] offline library seed skip (complete) track_id={} index={} library={}",
+            track_id,
+            server_index_key,
+            library_server_id,
+        );
+        return Ok(());
+    }
+    let bytes = tokio::fs::read(file_path)
+        .await
+        .map_err(|e| e.to_string())?;
+    let format_hint = file_path
+        .extension()
+        .and_then(|e| e.to_str())
+        .map(|e| e.to_ascii_lowercase())
+        .filter(|e| !e.is_empty());
+    let priority = explicit_priority.unwrap_or_else(|| {
+        analysis_backfill_resolve_priority(app, server_index_key, track_id, None)
+    });
+    enqueue_track_analysis_offline_library_with_plan(OfflineLibraryAnalysisEnqueue {
+        app,
+        cache_server_id: server_index_key,
+        enrichment_server_id: library_server_id,
+        track_id,
+        bytes: &bytes,
+        format_hint: format_hint.as_deref(),
+        priority,
+        plan,
+        fetch_ms: 0,
+    })
+    .await?;
+    Ok(())
+}
+
+struct OfflineLibraryAnalysisEnqueue<'a> {
+    app: &'a tauri::AppHandle,
+    cache_server_id: &'a str,
+    enrichment_server_id: &'a str,
+    track_id: &'a str,
+    bytes: &'a [u8],
+    format_hint: Option<&'a str>,
+    priority: AnalysisBackfillPriority,
+    plan: psysonic_core::track_analysis::TrackAnalysisPlan,
+    fetch_ms: u64,
+}
+
+async fn enqueue_track_analysis_offline_library_with_plan(
+    args: OfflineLibraryAnalysisEnqueue<'_>,
+) -> Result<EnqueueTrackAnalysisOutcome, String> {
+    if args.bytes.is_empty() || !args.plan.any() {
+        return Ok(EnqueueTrackAnalysisOutcome::Complete);
+    }
+    let content_hash = analysis_cache::md5_first_16kb(args.bytes);
+    if args.plan.needs_full_cpu_seed() {
+        crate::app_deprintln!(
+            "[analysis] queue full seed track_id={} hash={} need_waveform={} need_loudness={} need_enrichment={}",
+            args.track_id,
+            content_hash,
+            args.plan.need_waveform,
+            args.plan.need_loudness,
+            args.plan.enrichment.any()
+        );
+        submit_analysis_cpu_seed(
+            args.app.clone(),
+            args.cache_server_id.to_string(),
+            args.track_id.to_string(),
+            args.bytes.to_vec(),
+            args.format_hint.map(str::to_string),
+            args.priority,
+            args.fetch_ms,
+        )
+        .await?;
+        return Ok(EnqueueTrackAnalysisOutcome::QueuedFullSeed);
+    }
+    if args.plan.needs_enrichment_only() {
+        crate::app_deprintln!(
+            "[analysis] enrichment-only track_id={} hash={}",
+            args.track_id,
+            content_hash
+        );
+        let bpm_started = std::time::Instant::now();
+        let outcome = run_track_enrichment_from_bytes(
+            args.app,
+            args.enrichment_server_id,
+            args.track_id,
+            args.bytes,
+            analysis_emits_ui_events(args.priority),
+        )
+        .await;
+        if matches!(outcome, TrackEnrichmentOutcome::Failed) {
+            if let Some(cache) = args.app.try_state::<analysis_cache::AnalysisCache>() {
+                let key = analysis_cache::TrackKey {
+                    server_id: args.cache_server_id.to_string(),
+                    track_id: args.track_id.to_string(),
+                    md5_16kb: content_hash.clone(),
+                };
+                let _ = cache.touch_track_status(&key, "failed");
+            }
+            return Err("track enrichment failed".to_string());
+        }
+        let bpm_ms = bpm_started.elapsed().as_millis() as u64;
+        emit_analysis_track_perf(args.app, args.track_id, args.fetch_ms, 0, bpm_ms);
+        return Ok(EnqueueTrackAnalysisOutcome::RanEnrichmentOnly);
+    }
+    Ok(EnqueueTrackAnalysisOutcome::Complete)
+}
+
 /// Decode `bytes` for `track_id` via the cpu-seed queue. Prefer [`enqueue_track_analysis`].
 pub async fn enqueue_analysis_seed(
     app: &tauri::AppHandle,

src-tauri/crates/psysonic-analysis/src/track_analysis_plan.rs

@@ -15,8 +15,21 @@ pub fn plan_track_analysis(
     track_id: &str,
     content_hash: &str,
 ) -> TrackAnalysisPlan {
-    let (need_waveform, need_loudness) = cache_gaps(app, server_id, track_id, content_hash);
-    let enrichment = enrichment_plan(app, server_id, track_id, content_hash);
+    plan_track_analysis_offline_library(app, &[server_id], server_id, track_id, content_hash)
+}
+
+/// Offline/library download: waveform cache and enrichment facts may live under the
+/// playback index key while library rows use the UUID — try every scope before seeding.
+pub fn plan_track_analysis_offline_library(
+    app: &AppHandle,
+    cache_server_ids: &[&str],
+    _enrichment_server_id: &str,
+    track_id: &str,
+    content_hash: &str,
+) -> TrackAnalysisPlan {
+    let (need_waveform, need_loudness) =
+        cache_gaps_multi(app, cache_server_ids, track_id, content_hash);
+    let enrichment = enrichment_plan_multi(app, cache_server_ids, track_id, content_hash);
     TrackAnalysisPlan {
         need_waveform,
         need_loudness,
@@ -103,6 +116,32 @@ fn cache_gaps(
     )
 }
 
+fn cache_gaps_multi(
+    app: &AppHandle,
+    server_ids: &[&str],
+    track_id: &str,
+    content_hash: &str,
+) -> (bool, bool) {
+    let mut need_waveform = true;
+    let mut need_loudness = true;
+    for &server_id in server_ids {
+        if server_id.is_empty() {
+            continue;
+        }
+        let (nw, nl) = cache_gaps(app, server_id, track_id, content_hash);
+        if !nw {
+            need_waveform = false;
+        }
+        if !nl {
+            need_loudness = false;
+        }
+        if !need_waveform && !need_loudness {
+            break;
+        }
+    }
+    (need_waveform, need_loudness)
+}
+
 fn enrichment_plan(
     app: &AppHandle,
     server_id: &str,
@@ -117,6 +156,45 @@ fn enrichment_plan(
         .unwrap_or_default()
 }
 
+fn enrichment_plan_multi(
+    app: &AppHandle,
+    server_ids: &[&str],
+    track_id: &str,
+    content_hash: &str,
+) -> psysonic_core::track_enrichment::TrackEnrichmentPlan {
+    let mut need_bpm = true;
+    let mut need_valence = true;
+    let mut need_arousal = true;
+    let mut need_moods = true;
+    for &server_id in server_ids {
+        if server_id.is_empty() {
+            continue;
+        }
+        let plan = enrichment_plan(app, server_id, track_id, content_hash);
+        if !plan.need_bpm {
+            need_bpm = false;
+        }
+        if !plan.need_valence {
+            need_valence = false;
+        }
+        if !plan.need_arousal {
+            need_arousal = false;
+        }
+        if !plan.need_moods {
+            need_moods = false;
+        }
+        if !need_bpm && !need_valence && !need_arousal && !need_moods {
+            break;
+        }
+    }
+    psysonic_core::track_enrichment::TrackEnrichmentPlan {
+        need_bpm,
+        need_valence,
+        need_arousal,
+        need_moods,
+    }
+}
+
 fn cache_gaps_for_content(
     cache: Option<&AnalysisCache>,
     server_id: &str,
@@ -194,4 +272,14 @@ mod tests {
         assert!(!wf && !ld, "bare id should resolve stream: cached fingerprint");
     }
 
+    #[test]
+    fn playback_index_cache_row_not_visible_under_library_uuid_only() {
+        let cache = AnalysisCache::open_in_memory();
+        seed_waveform_loudness(&cache, "navidrome.test:4533", "t1", "abc");
+        let (wf, ld) = cache_gaps_for_content(Some(&cache), "library-uuid", "t1", "abc");
+        assert!(wf && ld, "library uuid alone should miss playback-scoped cache");
+        let (wf2, ld2) = cache_gaps_for_content(Some(&cache), "navidrome.test:4533", "t1", "abc");
+        assert!(!wf2 && !ld2, "playback index key should hit the cached row");
+    }
+
 }

src-tauri/crates/psysonic-audio/Cargo.toml

@@ -3,6 +3,7 @@ name = "psysonic-audio"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license.workspace = true
 publish = false
 
 [dependencies]

src-tauri/crates/psysonic-audio/src/commands.rs

@@ -14,10 +14,11 @@ use super::decode::build_source;
 use super::engine::{audio_http_client, AudioEngine};
 use super::helpers::*;
 use super::ipc::{maybe_emit_normalization_state, NormalizationStatePayload};
-use super::play_input::{
-    build_playback_source_with_probe_fallback, select_play_input,
-    spawn_legacy_stream_start_when_armed, swap_in_new_sink, url_format_hint, BuildSourceArgs,
-    PlayInputContext, SinkSwapInputs,
+use super::play_input::{select_play_input, url_format_hint, PlayInputContext};
+use super::source_build::{build_playback_source_with_probe_fallback, BuildSourceArgs};
+use super::sink_swap::{
+    spawn_legacy_stream_start_when_armed, swap_in_new_sink, LegacyStreamStartWhenArmed,
+    SinkSwapInputs,
 };
 use super::playback_rate::preserve_pitch_will_run;
 use super::preview::preview_clear_for_new_main_playback;
@@ -53,9 +54,13 @@ pub async fn audio_play(
     analysis_track_id: Option<String>,
     server_id: Option<String>,
     stream_format_suffix: Option<String>,
+    // Silent load: no `audio:playing`, sink stays paused. Optional + defaults to
+    // `false` so older/external `audio_play` callers that omit it still work.
+    start_paused: Option<bool>,
     app: AppHandle,
     state: State<'_, AudioEngine>,
 ) -> Result<(), String> {
+    let start_paused = start_paused.unwrap_or(false);
     let gapless = state.gapless_enabled.load(Ordering::Relaxed);
 
     // ── Ghost-command guard ───────────────────────────────────────────────────
@@ -311,23 +316,25 @@ pub async fn audio_play(
         };
         let needs_switch = target_rate > 0 && target_rate != current_stream_rate;
         if needs_switch {
-            let (reply_tx, reply_rx) = std::sync::mpsc::sync_channel::<Arc<rodio::MixerDeviceSink>>(0);
             let dev = state.selected_device.lock().unwrap().clone();
-            if state.stream_reopen_tx.send((target_rate, hi_res_enabled, dev, reply_tx)).is_ok() {
-                match reply_rx.recv_timeout(std::time::Duration::from_secs(5)) {
-                    Ok(new_handle) => {
-                        *state.stream_handle.lock().unwrap() = new_handle;
-                        state.stream_sample_rate.store(target_rate, Ordering::Relaxed);
-                        // Give PipeWire time to reconfigure at the new rate before
-                        // we open a Sink — only needed for large hi-res quanta.
-                        if hi_res_enabled && target_rate > 48_000 {
-                            tokio::time::sleep(Duration::from_millis(150)).await;
-                        }
-                    }
-                    Err(_) => {
-                        crate::app_eprintln!("[psysonic] stream rate switch timed out, keeping {current_stream_rate} Hz");
+            match super::engine::open_output_stream_blocking(
+                &state,
+                target_rate,
+                hi_res_enabled,
+                dev,
+            ) {
+                Ok(_) => {
+                    // Give PipeWire time to reconfigure at the new rate before
+                    // we open a Sink — only needed for large hi-res quanta.
+                    if hi_res_enabled && target_rate > 48_000 {
+                        tokio::time::sleep(Duration::from_millis(150)).await;
                     }
                 }
+                Err(_) => {
+                    crate::app_eprintln!(
+                        "[psysonic] stream rate switch timed out, keeping {current_stream_rate} Hz"
+                    );
+                }
             }
         }
 
@@ -337,7 +344,8 @@ pub async fn audio_play(
         }
     }
 
-    let sink = Arc::new(Player::connect_new(state.stream_handle.lock().unwrap().mixer()));
+    let stream = super::engine::ensure_output_stream_open(&state)?;
+    let sink = Arc::new(Player::connect_new(stream.mixer()));
     sink.set_volume(effective_volume);
 
     // ── Sink pre-fill for hi-res tracks ──────────────────────────────────────
@@ -401,7 +409,7 @@ pub async fn audio_play(
         if state.generation.load(Ordering::SeqCst) != gen {
             return Ok(()); // skipped during pre-fill — abort silently
         }
-        if !defer_playback_start {
+        if !defer_playback_start && !start_paused {
             sink.play();
         }
     }
@@ -415,24 +423,26 @@ pub async fn audio_play(
         fadeout_samples: built.fadeout_samples,
         crossfade_enabled,
         actual_fade_secs,
+        start_paused,
     });
 
     if defer_playback_start {
-        {
+        if !start_paused {
             let mut cur = state.current.lock().unwrap();
             cur.play_started = None;
             cur.paused_at = Some(0.0);
         }
-        spawn_legacy_stream_start_when_armed(
+        spawn_legacy_stream_start_when_armed(LegacyStreamStartWhenArmed {
             gen,
-            state.generation.clone(),
-            state.stream_playback_armed.clone(),
-            state.samples_played.clone(),
-            state.current.clone(),
-            app.clone(),
+            gen_arc: state.generation.clone(),
+            playback_armed: state.stream_playback_armed.clone(),
+            samples_played: state.samples_played.clone(),
+            current: state.current.clone(),
+            app: app.clone(),
             duration_secs,
-        );
-    } else {
+            hold_paused: start_paused,
+        });
+    } else if !start_paused {
         app.emit("audio:playing", duration_secs).ok();
     }
 

src-tauri/crates/psysonic-audio/src/decode.rs

@@ -166,15 +166,30 @@ impl SizedDecoder {
             inner: Cursor::new(data),
             len: data_len,
         };
+        // Symphonia 0.6 scans trailing metadata on seekable sources — hide
+        // seekability during probe (same as `new_streaming`) so preview does not
+        // read the entire in-memory file before the first sample.
+        //
+        // Exception: Ogg (Vorbis/Opus/…) must stay seekable through the probe,
+        // otherwise its demuxer never records `phys_byte_range_end` and the first
+        // seek panics (see `container_hint_is_ogg`). This source is fully
+        // in-memory, so the trailing-metadata scan it re-enables is free.
+        let gate_needed = !crate::stream::container_hint_is_mp4(format_hint)
+            && !crate::stream::container_hint_is_ogg(format_hint);
+        let probe_seek_gate = gate_needed.then(|| Arc::new(AtomicBool::new(false)));
+        let media: Box<dyn MediaSource> = match &probe_seek_gate {
+            Some(gate) => Box::new(ProbeSeekGate {
+                inner: Box::new(source),
+                seekable: gate.clone(),
+            }),
+            None => Box::new(source),
+        };
         // Hi-Res: 4 MB read-ahead so Symphonia demuxes fewer Read calls for
         // high-bitrate files (88.2 kHz/24-bit FLAC ≈ 1800 kbps).
         // Standard: 512 KB is plenty for MP3/AAC — larger buffers waste allocation
         // and compete with the playback thread at track start.
         let buf_len = if hi_res { 4 * 1024 * 1024 } else { 512 * 1024 };
-        let mss = MediaSourceStream::new(
-            Box::new(source) as Box<dyn MediaSource>,
-            MediaSourceStreamOptions { buffer_len: buf_len },
-        );
+        let mss = MediaSourceStream::new(media, MediaSourceStreamOptions { buffer_len: buf_len });
 
         let mut hint = Hint::new();
         if let Some(ext) = format_hint {
@@ -200,6 +215,10 @@ impl SizedDecoder {
                 }
             })?;
 
+        if let Some(gate) = &probe_seek_gate {
+            gate.store(true, Ordering::Relaxed);
+        }
+
         let track = format
             .tracks()
             .iter()
@@ -302,19 +321,33 @@ impl SizedDecoder {
     /// Build a decoder from any `MediaSource` (e.g. track-stream or radio).
     /// Uses `enable_gapless: false` — live streams are not seekable; gapless
     /// trimming requires seeking to read the LAME/iTunSMPB end-padding info.
+    /// `source_random_access`: the underlying source can cheaply seek to EOF
+    /// (e.g. a local file), so the probe-time trailing-metadata / stream-end scan
+    /// is not a full download. Progressive sources (ranged HTTP) pass `false`.
     pub(crate) fn new_streaming(
         media: Box<dyn MediaSource>,
         format_hint: Option<&str>,
         source_tag: &str,
+        source_random_access: bool,
     ) -> Result<Self, String> {
         // For non-MP4 progressive streams, hide seekability during the probe so
         // Symphonia 0.6 skips its trailing-metadata scan (which would seek to EOF
         // and block until the whole file is downloaded). Re-enabled right after.
         // MP4 keeps seekability (its demuxer needs it to find `moov`; tail is
         // prefetched separately).
+        //
+        // Ogg also keeps seekability through the probe, but only on random-access
+        // sources: its demuxer records `phys_byte_range_end` during the probe and
+        // panics on the first seek otherwise (see `container_hint_is_ogg`). On a
+        // local file the stream-end scan is cheap; on a progressive ranged stream
+        // it would force a full download, so there we keep the gate and accept
+        // that seeking is a no-op (the panic itself is contained in `try_seek`).
         let stream_len = media.byte_len();
-        let probe_seek_gate = (!crate::stream::container_hint_is_mp4(format_hint))
-            .then(|| Arc::new(AtomicBool::new(false)));
+        let ogg_needs_seekable_probe =
+            source_random_access && crate::stream::container_hint_is_ogg(format_hint);
+        let gate_needed = !crate::stream::container_hint_is_mp4(format_hint)
+            && !ogg_needs_seekable_probe;
+        let probe_seek_gate = gate_needed.then(|| Arc::new(AtomicBool::new(false)));
         let media: Box<dyn MediaSource> = match &probe_seek_gate {
             Some(gate) => Box::new(ProbeSeekGate { inner: media, seekable: gate.clone() }),
             None => media,
@@ -575,20 +608,36 @@ impl Source for SizedDecoder {
 
         let to_skip = self.current_frame_offset % self.channels().get() as usize;
 
-        let seek_res = self
-            .format
-            .seek(SeekMode::Accurate, SeekTo::Time { time, track_id: None })
-            .map_err(|e| rodio::source::SeekError::Other(
-                std::sync::Arc::new(std::io::Error::other(e.to_string()))
-            ))?;
+        // symphonia 0.6's OGG demuxer can `panic!` (e.g. `Option::unwrap()` on
+        // `None` in `OggReader::do_seek`) on some streams instead of returning
+        // an `Err`. `try_seek` runs on rodio's cpal output thread, so an escaping
+        // panic poisons the engine mutexes and then aborts the whole process at
+        // the non-unwinding cpal FFI boundary (the "crash on Stop" is a downstream
+        // symptom of that poison). Contain the unwind here — including the packet
+        // reads in `refine_position`, which can hit the same broken demuxer state —
+        // and surface it as a recoverable `SeekError` so the engine stays alive
+        // (the seek becomes a no-op rather than killing playback).
+        let seek_outcome = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let seek_res = self
+                .format
+                .seek(SeekMode::Accurate, SeekTo::Time { time, track_id: None })
+                .map_err(|e| e.to_string())?;
+            self.refine_position(seek_res)?;
+            Ok::<(), String>(())
+        }));
 
-        self.refine_position(seek_res)
-            .map_err(|e| rodio::source::SeekError::Other(
-                std::sync::Arc::new(std::io::Error::other(e))
-            ))?;
-
-        self.current_frame_offset += to_skip;
-        Ok(())
+        match seek_outcome {
+            Ok(Ok(())) => {
+                self.current_frame_offset += to_skip;
+                Ok(())
+            }
+            Ok(Err(e)) => Err(rodio::source::SeekError::Other(std::sync::Arc::new(
+                std::io::Error::other(e),
+            ))),
+            Err(_panic) => Err(rodio::source::SeekError::Other(std::sync::Arc::new(
+                std::io::Error::other("seek panicked inside the demuxer (contained)"),
+            ))),
+        }
     }
 }
 
@@ -1006,8 +1055,9 @@ mod tests {
     #[test]
     fn new_streaming_constructs_from_synthetic_wav() {
         let wav = synthetic_wav_bytes(0.5);
-        let decoder = SizedDecoder::new_streaming(seekable_source(wav), Some("wav"), "test-stream")
-            .expect("streaming WAV decode setup");
+        let decoder =
+            SizedDecoder::new_streaming(seekable_source(wav), Some("wav"), "test-stream", true)
+                .expect("streaming WAV decode setup");
         assert_eq!(decoder.spec.rate(), 44_100);
         assert_eq!(decoder.spec.channels().count(), 1);
         // Live streams report no total duration.
@@ -1020,6 +1070,7 @@ mod tests {
             seekable_source(vec![0x00u8; 64]),
             None,
             "test-stream",
+            true,
         );
         assert!(result.is_err());
     }

src-tauri/crates/psysonic-audio/src/device_commands.rs

@@ -2,9 +2,7 @@
 //! `commands.rs` so playback / radio / EQ aren't entangled with the device
 //! enumeration + reopen path.
 
-use std::sync::Arc;
 use std::sync::atomic::Ordering;
-use std::time::Duration;
 
 use tauri::{Emitter, State};
 
@@ -78,16 +76,13 @@ pub async fn audio_set_device(
     *state.selected_device.lock().unwrap() = device_name.clone();
 
     let rate = state.stream_sample_rate.load(Ordering::Relaxed);
-    let (reply_tx, reply_rx) = std::sync::mpsc::sync_channel::<Arc<rodio::MixerDeviceSink>>(0);
-    state.stream_reopen_tx
-        .send((rate, false, device_name, reply_tx))
-        .map_err(|e| e.to_string())?;
-
-    let new_handle = tauri::async_runtime::spawn_blocking(move || {
-        reply_rx.recv_timeout(Duration::from_secs(5)).ok()
-    }).await.unwrap_or(None).ok_or("device open timed out")?;
-
-    *state.stream_handle.lock().unwrap() = new_handle;
+    let open_rate = if rate > 0 {
+        rate
+    } else {
+        state.device_default_rate
+    };
+    super::engine::open_output_stream_blocking(&state, open_rate, false, device_name.clone())
+        .map_err(|_| "device open timed out".to_string())?;
 
     // Capture position and drop the active sink atomically so the position
     // reading is still valid (play_started / paused_at intact before take).

src-tauri/crates/psysonic-audio/src/device_resume.rs

@@ -23,10 +23,11 @@ use tauri::Emitter;
 use tauri::Manager;
 
 use super::engine::AudioEngine;
-use super::play_input::{
-    build_playback_source_with_probe_fallback, swap_in_new_sink, url_format_hint,
-    BuildSourceArgs, PlayInput, PlaybackSource, SinkSwapInputs,
+use super::play_input::{url_format_hint, PlayInput};
+use super::source_build::{
+    build_playback_source_with_probe_fallback, BuildSourceArgs, PlaybackSource,
 };
+use super::sink_swap::{swap_in_new_sink, SinkSwapInputs};
 use super::progress_task::spawn_progress_task;
 use super::stream::LocalFileSource;
 
@@ -86,6 +87,7 @@ pub(crate) async fn try_resume_after_device_change(
                     reader: Box::new(LocalFileSource { file, len }),
                     format_hint: url_format_hint(url),
                     tag: "LocalFile[device-resume]",
+                    random_access: true,
                     mp4_probe_gate: None,
                 }
             }
@@ -187,9 +189,14 @@ pub(crate) async fn try_resume_after_device_change(
         .current_channels
         .store(ps.built.output_channels as u32, Ordering::Relaxed);
 
-    let sink = Arc::new(Player::connect_new(
-        engine.stream_handle.lock().unwrap().mixer(),
-    ));
+    let stream = match super::engine::ensure_output_stream_open(&engine) {
+        Ok(s) => s,
+        Err(e) => {
+            crate::app_eprintln!("[device-resume] output stream open failed: {e}");
+            return false;
+        }
+    };
+    let sink = Arc::new(Player::connect_new(stream.mixer()));
     let effective_volume = (snap.base_volume * snap.gain_linear).clamp(0.0, 1.0);
     sink.set_volume(effective_volume);
     sink.append(ps.built.source);
@@ -205,6 +212,7 @@ pub(crate) async fn try_resume_after_device_change(
             fadeout_samples: ps.built.fadeout_samples,
             crossfade_enabled: false,
             actual_fade_secs: 0.0,
+            start_paused: false,
         },
     );
 

src-tauri/crates/psysonic-audio/src/device_watcher.rs

@@ -1,6 +1,5 @@
 //! Poll default output device and pinned-device presence; reopen stream when needed.
 use std::sync::atomic::Ordering;
-use std::sync::Arc;
 use std::time::{Duration, Instant};
 
 use tauri::Emitter;
@@ -41,8 +40,11 @@ pub(crate) async fn reopen_output_stream(
     };
 
     let rate = engine.stream_sample_rate.load(Ordering::Relaxed);
-    let reopen_tx = engine.stream_reopen_tx.clone();
-    let stream_handle = engine.stream_handle.clone();
+    let open_rate = if rate > 0 {
+        rate
+    } else {
+        engine.device_default_rate
+    };
     let current = engine.current.clone();
     let fading_out = engine.fading_out_sink.clone();
 
@@ -62,25 +64,33 @@ pub(crate) async fn reopen_output_stream(
         }
     };
 
-    let new_handle = tauri::async_runtime::spawn_blocking(move || {
-        let (reply_tx, reply_rx) =
-            std::sync::mpsc::sync_channel::<Arc<rodio::MixerDeviceSink>>(0);
-        if reopen_tx
-            .send((rate, false, device_name, reply_tx))
-            .is_err()
-        {
-            return None;
-        }
-        reply_rx.recv_timeout(Duration::from_secs(5)).ok()
+    let app_for_open = app.clone();
+    let device_name_for_open = device_name.clone();
+    let opened = tauri::async_runtime::spawn_blocking(move || {
+        let engine = app_for_open.state::<AudioEngine>();
+        super::engine::open_output_stream_blocking(
+            &engine,
+            open_rate,
+            false,
+            device_name_for_open,
+        )
+        .is_ok()
     })
     .await
-    .unwrap_or(None);
+    .unwrap_or(false);
 
-    let Some(handle) = new_handle else {
+    if !opened {
         return false;
-    };
-
-    *stream_handle.lock().unwrap() = handle;
+    }
+    // When we're not actively playing (paused/stopped), bump the generation
+    // before stopping the old sink so the still-running progress task sees the
+    // mismatch and bails out instead of emitting a spurious `audio:ended` —
+    // which would otherwise trigger a frontend restart of paused playback
+    // (#1094). The active-playback path bumps inside
+    // `try_resume_after_device_change`, so only guard the non-playing case here.
+    if !snapshot.is_playing {
+        engine.generation.fetch_add(1, Ordering::SeqCst);
+    }
     if let Some(s) = current.lock().unwrap().sink.take() {
         s.stop();
     }
@@ -224,9 +234,18 @@ pub fn start_device_watcher(engine: &AudioEngine, app: tauri::AppHandle) {
                 }
             }
 
-            // Enumerate all available output devices and the current default.
+            // The full `output_devices()` + per-device `description()` scan is the
+            // CoreAudio HAL call that contends with the audio render thread and
+            // produces a brief dropout once per poll interval (issue #996: stutter
+            // every ~3s, cadence tracking the poll exactly). It is only needed to
+            // detect a *pinned* output device disappearing. With no pin — system
+            // default, the common case — only the current default is needed, a
+            // single cheap query, so the full enumeration is skipped entirely.
+            let pinned = selected_device.lock().unwrap().clone();
+            let need_full_enum = pinned.is_some();
+
             // Suppress stderr on Unix to avoid ALSA probing noise (JACK, OSS, dmix).
-            let (current_default, available) = tauri::async_runtime::spawn_blocking(|| {
+            let (current_default, available) = tauri::async_runtime::spawn_blocking(move || {
                 use rodio::cpal::traits::{DeviceTrait, HostTrait};
                 #[cfg(unix)]
                 let _guard = unsafe {
@@ -244,26 +263,28 @@ pub fn start_device_watcher(engine: &AudioEngine, app: tauri::AppHandle) {
                 let default = host
                     .default_output_device()
                     .and_then(|d| d.description().ok().map(|desc| desc.name().to_string()));
-                let available: Vec<String> = host
-                    .output_devices()
-                    .map(|iter| {
-                        iter.filter_map(|d| d.description().ok().map(|desc| desc.name().to_string()))
-                            .collect()
-                    })
-                    .unwrap_or_default();
+                let available: Vec<String> = if need_full_enum {
+                    host.output_devices()
+                        .map(|iter| {
+                            iter.filter_map(|d| d.description().ok().map(|desc| desc.name().to_string()))
+                                .collect()
+                        })
+                        .unwrap_or_default()
+                } else {
+                    Vec::new()
+                };
                 (default, available)
             }).await.unwrap_or((None, vec![]));
 
-            // Empty list almost always means a transient enumeration failure, not
-            // that every output device vanished. Treating it as "pinned missing"
-            // caused false audio:device-reset (UI jumped back to system default)
-            // when switching to external USB / class-compliant interfaces.
-            if available.is_empty() {
+            // Empty list (only when we actually enumerated for a pinned device)
+            // almost always means a transient enumeration failure, not that every
+            // output device vanished. Treating it as "pinned missing" caused false
+            // audio:device-reset (UI jumped back to system default) when switching
+            // to external USB / class-compliant interfaces.
+            if need_full_enum && available.is_empty() {
                 continue;
             }
 
-            let pinned = selected_device.lock().unwrap().clone();
-
             #[cfg(target_os = "linux")]
             if pinned.is_some() {
                 // Do not infer "unplugged" from `output_devices()` when a device is pinned.

src-tauri/crates/psysonic-audio/src/engine.rs

@@ -7,21 +7,32 @@ use rodio::Player;
 
 use super::state::{ChainedInfo, PreloadedTrack, StreamCompletedSpill};
 
-/// Reply channel handed back to the audio-stream thread once a re-open finishes.
-pub type StreamReopenReply = std::sync::mpsc::SyncSender<Arc<rodio::MixerDeviceSink>>;
-/// Stream-thread re-open request: `(desired_rate, is_hi_res, device_name, reply_tx)`.
-pub type StreamReopenRequest = (u32, bool, Option<String>, StreamReopenReply);
+/// Reply channel handed back to the audio-stream thread once an open finishes.
+pub type StreamOpenReply =
+    std::sync::mpsc::SyncSender<(Arc<rodio::MixerDeviceSink>, u32)>;
+
+/// Requests handled on the dedicated audio-stream thread (open / idle release).
+pub enum StreamThreadMsg {
+    Open {
+        desired_rate: u32,
+        is_hi_res: bool,
+        device_name: Option<String>,
+        reply: StreamOpenReply,
+    },
+    Release {
+        reply: std::sync::mpsc::SyncSender<()>,
+    },
+}
 
 pub struct AudioEngine {
-    pub stream_handle: Arc<std::sync::Mutex<Arc<rodio::MixerDeviceSink>>>,
+    pub stream_handle: Arc<std::sync::Mutex<Option<Arc<rodio::MixerDeviceSink>>>>,
     /// Sample rate the output stream was last opened at (updated on every re-open).
     pub stream_sample_rate: Arc<AtomicU32>,
     /// The rate the device was opened at on cold start — used to restore the
     /// stream when Hi-Res is toggled off while a hi-res rate is active.
     pub device_default_rate: u32,
-    /// Sends `(desired_rate, is_hi_res, device_name, reply_tx)` to the audio-stream
-    /// thread to re-open the output device. `device_name = None` → system default.
-    pub stream_reopen_tx: std::sync::mpsc::SyncSender<StreamReopenRequest>,
+    /// Open or release the CPAL output stream on the audio-stream thread.
+    pub stream_thread_tx: std::sync::mpsc::SyncSender<StreamThreadMsg>,
     /// User-selected output device name (None = follow system default).
     pub selected_device: Arc<Mutex<Option<String>>>,
     pub current: Arc<Mutex<AudioCurrent>>,
@@ -147,6 +158,15 @@ impl AudioCurrent {
 ///   3. Device default.
 ///   4. System default (last resort).
 ///
+/// Rodio prints a stderr line on every intentional stream drop. Keep that only
+/// when runtime logging is in **debug** mode; normal/off silence the noise.
+fn finalize_mixer_device_sink(mut handle: rodio::MixerDeviceSink) -> Arc<rodio::MixerDeviceSink> {
+    if !crate::logging::should_log_debug() {
+        handle.log_on_drop(false);
+    }
+    Arc::new(handle)
+}
+
 /// Returns `(stream_handle, actual_sample_rate)`.
 fn open_stream_for_device_and_rate(device_name: Option<&str>, desired_rate: u32) -> (Arc<rodio::MixerDeviceSink>, u32) {
     use rodio::cpal::traits::{DeviceTrait, HostTrait};
@@ -214,7 +234,7 @@ fn open_stream_for_device_and_rate(device_name: Option<&str>, desired_rate: u32)
                         .and_then(|b| b.with_sample_rate(std::num::NonZeroU32::new(desired_rate).unwrap_or(std::num::NonZeroU32::MIN)).open_stream())
                     {
                         crate::app_eprintln!("[psysonic] audio stream opened at {} Hz (exact)", desired_rate);
-                        return (Arc::new(handle), desired_rate);
+                        return (finalize_mixer_device_sink(handle), desired_rate);
                     }
                 }
 
@@ -231,7 +251,7 @@ fn open_stream_for_device_and_rate(device_name: Option<&str>, desired_rate: u32)
                             "[psysonic] audio stream opened at {} Hz (highest, wanted {})",
                             rate, desired_rate
                         );
-                        return (Arc::new(handle), rate);
+                        return (finalize_mixer_device_sink(handle), rate);
                     }
                 }
             }
@@ -244,7 +264,7 @@ fn open_stream_for_device_and_rate(device_name: Option<&str>, desired_rate: u32)
                 .map(|c| c.sample_rate())
                 .unwrap_or(44100);
             crate::app_eprintln!("[psysonic] audio stream opened at {} Hz (device default)", rate);
-            return (Arc::new(handle), rate);
+            return (finalize_mixer_device_sink(handle), rate);
         }
     }
 
@@ -257,7 +277,78 @@ fn open_stream_for_device_and_rate(device_name: Option<&str>, desired_rate: u32)
         .and_then(|d| d.default_output_config().ok())
         .map(|c| c.sample_rate())
         .unwrap_or(44100);
-    (Arc::new(handle), rate)
+    (finalize_mixer_device_sink(handle), rate)
+}
+
+fn probe_device_default_rate() -> u32 {
+    use rodio::cpal::traits::{DeviceTrait, HostTrait};
+
+    rodio::cpal::default_host()
+        .default_output_device()
+        .and_then(|d| d.default_output_config().ok())
+        .map(|c| c.sample_rate())
+        .unwrap_or(44_100)
+}
+
+/// Open the output stream (blocking). Updates `stream_handle` and `stream_sample_rate`.
+pub(crate) fn open_output_stream_blocking(
+    engine: &AudioEngine,
+    desired_rate: u32,
+    is_hi_res: bool,
+    device_name: Option<String>,
+) -> Result<Arc<rodio::MixerDeviceSink>, String> {
+    let rate = if desired_rate > 0 {
+        desired_rate
+    } else {
+        engine.device_default_rate
+    };
+    let (reply_tx, reply_rx) = std::sync::mpsc::sync_channel(0);
+    engine
+        .stream_thread_tx
+        .send(StreamThreadMsg::Open {
+            desired_rate: rate,
+            is_hi_res,
+            device_name,
+            reply: reply_tx,
+        })
+        .map_err(|e| e.to_string())?;
+    let (handle, actual_rate) = reply_rx
+        .recv_timeout(Duration::from_secs(5))
+        .map_err(|_| "audio stream open timed out".to_string())?;
+    engine
+        .stream_sample_rate
+        .store(actual_rate, std::sync::atomic::Ordering::Relaxed);
+    *engine.stream_handle.lock().unwrap() = Some(handle.clone());
+    Ok(handle)
+}
+
+/// Ensure a live output stream exists; lazy-opens on first playback.
+pub(crate) fn ensure_output_stream_open(
+    engine: &AudioEngine,
+) -> Result<Arc<rodio::MixerDeviceSink>, String> {
+    if let Some(handle) = engine.stream_handle.lock().unwrap().clone() {
+        return Ok(handle);
+    }
+    let rate = engine.stream_sample_rate.load(std::sync::atomic::Ordering::Relaxed);
+    let open_rate = if rate > 0 {
+        rate
+    } else {
+        engine.device_default_rate
+    };
+    let device = engine.selected_device.lock().unwrap().clone();
+    open_output_stream_blocking(engine, open_rate, false, device)
+}
+
+pub(crate) fn request_stream_release(engine: &AudioEngine) -> Result<(), String> {
+    let (reply_tx, reply_rx) = std::sync::mpsc::sync_channel(0);
+    engine
+        .stream_thread_tx
+        .send(StreamThreadMsg::Release { reply: reply_tx })
+        .map_err(|e| e.to_string())?;
+    reply_rx
+        .recv_timeout(Duration::from_secs(5))
+        .map_err(|_| "audio stream release timed out".to_string())?;
+    Ok(())
 }
 
 pub fn create_engine() -> (AudioEngine, std::thread::JoinHandle<()>) {
@@ -269,13 +360,12 @@ pub fn create_engine() -> (AudioEngine, std::thread::JoinHandle<()>) {
         }
     }
 
-    // Channels: main thread ←→ audio-stream thread.
-    //   init_tx/rx : (Arc<rodio::MixerDeviceSink>, actual_rate) sent once at startup.
-    //   reopen_tx/rx: (desired_rate, reply_tx) — triggers a stream re-open.
-    let (init_tx, init_rx) =
-        std::sync::mpsc::sync_channel::<(Arc<rodio::MixerDeviceSink>, u32)>(0);
-    let (reopen_tx, reopen_rx) =
-        std::sync::mpsc::sync_channel::<(u32, bool, Option<String>, std::sync::mpsc::SyncSender<Arc<rodio::MixerDeviceSink>>)>(4);
+    // Channel: main thread ←→ audio-stream thread (lazy open + idle release).
+    let (ready_tx, ready_rx) = std::sync::mpsc::sync_channel::<()>(0);
+    let (stream_thread_tx, stream_thread_rx) =
+        std::sync::mpsc::sync_channel::<StreamThreadMsg>(4);
+
+    let device_default_rate = probe_device_default_rate();
 
     let thread = std::thread::Builder::new()
         .name("psysonic-audio-stream".into())
@@ -296,52 +386,63 @@ pub fn create_engine() -> (AudioEngine, std::thread::JoinHandle<()>) {
             // Thread priority is kept at default during standard-mode playback.
             // It is escalated to Max only when a Hi-Res stream reopen is requested,
             // to prevent PipeWire underruns at high quantum sizes (8192 frames).
-            let (mut _stream, rate) = open_stream_for_device_and_rate(None, 0);
-            let handle = _stream.clone();
-            init_tx.send((handle, rate)).ok();
+            let mut _stream: Option<Arc<rodio::MixerDeviceSink>> = None;
+            ready_tx.send(()).ok();
 
-            // Keep the stream alive and handle sample-rate / device-switch requests.
-            while let Ok((desired_rate, is_hi_res, device_name, reply_tx)) = reopen_rx.recv() {
-                // Escalate to Max for Hi-Res reopens (large PipeWire quanta need
-                // real-time scheduling to avoid underruns). No escalation for
-                // standard mode — the thread blocks on recv() between reopens so
-                // elevated priority would only waste scheduler budget.
-                if is_hi_res {
-                    thread_priority::set_current_thread_priority(
-                        thread_priority::ThreadPriority::Max
-                    ).ok();
+            while let Ok(msg) = stream_thread_rx.recv() {
+                match msg {
+                    StreamThreadMsg::Release { reply } => {
+                        _stream = None;
+                        let _ = reply.send(());
+                    }
+                    StreamThreadMsg::Open {
+                        desired_rate,
+                        is_hi_res,
+                        device_name,
+                        reply,
+                    } => {
+                        // Escalate to Max for Hi-Res reopens (large PipeWire quanta need
+                        // real-time scheduling to avoid underruns). No escalation for
+                        // standard mode — the thread blocks on recv() between reopens so
+                        // elevated priority would only waste scheduler budget.
+                        if is_hi_res {
+                            thread_priority::set_current_thread_priority(
+                                thread_priority::ThreadPriority::Max,
+                            )
+                            .ok();
+                        }
+
+                        _stream = None;
+
+                        // Scale the PipeWire quantum with the sample rate so wall-clock
+                        // latency stays roughly constant (≈93 ms) at all rates.
+                        #[cfg(target_os = "linux")]
+                        if desired_rate > 0 {
+                            let frames: u32 = if desired_rate > 48_000 { 8192 } else { 4096 };
+                            std::env::set_var("PIPEWIRE_LATENCY", format!("{frames}/{desired_rate}"));
+                            let latency_ms =
+                                (frames as f64 / desired_rate as f64 * 1000.0).round() as u64;
+                            std::env::set_var("PULSE_LATENCY_MSEC", latency_ms.to_string());
+                        }
+
+                        let (new_stream, actual_rate) =
+                            open_stream_for_device_and_rate(device_name.as_deref(), desired_rate);
+                        let new_handle = new_stream.clone();
+                        _stream = Some(new_stream);
+                        let _ = reply.send((new_handle, actual_rate));
+                    }
                 }
-
-                drop(_stream); // close old stream before opening new one
-
-                // Scale the PipeWire quantum with the sample rate so wall-clock
-                // latency stays roughly constant (≈93 ms) at all rates.
-                // 8192 frames at 88200 Hz ≈ 92.9 ms (same as 4096 at 48000 Hz).
-                #[cfg(target_os = "linux")]
-                {
-                    let frames: u32 = if desired_rate > 48_000 { 8192 } else { 4096 };
-                    std::env::set_var("PIPEWIRE_LATENCY", format!("{frames}/{desired_rate}"));
-                    // Keep PULSE_LATENCY_MSEC in sync so PulseAudio-based setups
-                    // get the same wall-clock quantum as PipeWire.
-                    let latency_ms = (frames as f64 / desired_rate as f64 * 1000.0).round() as u64;
-                    std::env::set_var("PULSE_LATENCY_MSEC", latency_ms.to_string());
-                }
-
-                let (new_stream, _actual) = open_stream_for_device_and_rate(device_name.as_deref(), desired_rate);
-                let new_handle = new_stream.clone();
-                _stream = new_stream;
-                reply_tx.send(new_handle).ok();
             }
         })
         .expect("spawn audio stream thread");
 
-    let (initial_handle, initial_rate) = init_rx.recv().expect("audio stream handle");
+    ready_rx.recv().expect("audio stream thread ready");
 
     let engine = AudioEngine {
-        stream_handle: Arc::new(std::sync::Mutex::new(initial_handle)),
-        stream_sample_rate: Arc::new(AtomicU32::new(initial_rate)),
-        device_default_rate: initial_rate,
-        stream_reopen_tx: reopen_tx,
+        stream_handle: Arc::new(std::sync::Mutex::new(None)),
+        stream_sample_rate: Arc::new(AtomicU32::new(0)),
+        device_default_rate,
+        stream_thread_tx,
         selected_device: Arc::new(Mutex::new(None)),
         current: Arc::new(Mutex::new(AudioCurrent {
             sink: None,

src-tauri/crates/psysonic-audio/src/lib.rs

@@ -16,6 +16,8 @@ pub mod device_commands;
 pub mod mix_commands;
 mod play_input;
 pub mod playback_rate;
+mod sink_swap;
+mod source_build;
 mod preserve_worker;
 pub mod preload_commands;
 pub(crate) mod progress_task;
@@ -24,6 +26,7 @@ pub mod transport_commands;
 mod device_resume;
 mod device_watcher;
 mod engine;
+mod stream_idle;
 #[cfg(any(target_os = "windows", target_os = "linux"))]
 mod power_resume;
 #[cfg(target_os = "windows")]
@@ -39,6 +42,7 @@ mod stream;
 
 pub use device_commands::{audio_default_output_device_name, audio_list_devices_for_engine};
 pub use device_watcher::start_device_watcher;
+pub use stream_idle::start_stream_idle_watcher;
 pub use engine::{create_engine, refresh_http_user_agent, AudioEngine};
 pub use helpers::{
     cleanup_orphan_stream_spill_dir, take_stream_completed_for_url,

src-tauri/crates/psysonic-audio/src/play_input.rs

@@ -15,11 +15,10 @@ use super::analysis_dispatch::{
     prepare_playback_analysis, spawn_track_analysis_bytes, spawn_track_analysis_file,
     TrackAnalysisOrigin,
 };
-use super::decode::{build_source, build_streaming_source, BuiltSource, SizedDecoder};
 use super::engine::{audio_http_client, AudioEngine};
 use super::helpers::{
     content_type_to_hint, fetch_data, format_hint_from_content_disposition,
-    normalize_stream_suffix_for_hint, resolve_playback_format_hint, sniff_stream_format_extension,
+    normalize_stream_suffix_for_hint, sniff_stream_format_extension,
     same_playback_target,
     STREAM_FORMAT_SNIFF_PROBE_BYTES,
 };
@@ -41,6 +40,9 @@ pub(crate) enum PlayInput {
         reader: Box<dyn MediaSource>,
         format_hint: Option<String>,
         tag: &'static str,
+        /// Source can cheaply seek to EOF (local file). Drives whether Ogg keeps
+        /// seekability through the probe so its seek path does not panic.
+        random_access: bool,
         /// When set, Symphonia probe waits for moov (tail or fast-start prefix).
         mp4_probe_gate: Option<super::stream::RangedMp4ProbeGate>,
     },
@@ -202,6 +204,7 @@ fn open_local_file_input(
         reader: Box::new(reader),
         format_hint: local_hint,
         tag: "local-file",
+        random_access: true,
         mp4_probe_gate: None,
     })
 }
@@ -346,6 +349,7 @@ async fn open_ranged_or_streaming_input(
             reader: Box::new(reader),
             format_hint: stream_hint,
             tag: "ranged-stream",
+            random_access: false,
             mp4_probe_gate,
         }));
     }
@@ -401,47 +405,6 @@ async fn open_ranged_or_streaming_input(
     }))
 }
 
-/// Legacy `AudioStreamReader`: keep the sink paused until the download task arms
-/// playback, then reset counters and emit `audio:playing` so the UI does not
-/// extrapolate ahead of audible output.
-pub(super) fn spawn_legacy_stream_start_when_armed(
-    gen: u64,
-    gen_arc: Arc<AtomicU64>,
-    playback_armed: Arc<AtomicBool>,
-    samples_played: Arc<AtomicU64>,
-    current: Arc<Mutex<super::engine::AudioCurrent>>,
-    app: AppHandle,
-    duration_secs: f64,
-) {
-    tokio::spawn(async move {
-        loop {
-            if gen_arc.load(Ordering::SeqCst) != gen {
-                return;
-            }
-            if playback_armed.load(Ordering::Relaxed) {
-                break;
-            }
-            tokio::time::sleep(Duration::from_millis(50)).await;
-        }
-        if gen_arc.load(Ordering::SeqCst) != gen {
-            return;
-        }
-        samples_played.store(0, Ordering::Relaxed);
-        let sink = current.lock().unwrap().sink.clone();
-        if let Some(sink) = sink {
-            {
-                let mut cur = current.lock().unwrap();
-                cur.play_started = Some(std::time::Instant::now());
-                cur.paused_at = None;
-                cur.seek_offset = 0.0;
-            }
-            sink.play();
-            app.emit("audio:playing", duration_secs).ok();
-            crate::app_deprintln!("[stream] legacy track-stream: playback started after buffer ready");
-        }
-    });
-}
-
 /// Pulled out of the format_hint extraction block in `audio_play` — strip the
 /// query string first so Subsonic-style URLs (`stream.view?...&v=1.16.1&...`)
 /// don't latch onto random query-param substrings; only accept short
@@ -460,459 +423,3 @@ pub(crate) fn url_format_hint(url: &str) -> Option<String> {
         })
         .map(|s| s.to_lowercase())
 }
-
-/// Arguments forwarded from `audio_play` into the source-build pipeline.
-/// Bundles the format-hint inputs, playback-shaping parameters and the shared
-/// done flag so that `build_playback_source_with_probe_fallback` stays below
-/// the `clippy::too_many_arguments` threshold.
-pub(crate) struct BuildSourceArgs<'a> {
-    pub url: &'a str,
-    pub gen: u64,
-    pub cache_id_for_tasks: Option<&'a str>,
-    pub server_id: Option<&'a str>,
-    pub url_format_hint: Option<&'a str>,
-    pub stream_format_suffix: Option<&'a str>,
-    pub done_flag: Arc<AtomicBool>,
-    pub fade_in_dur: Duration,
-    pub hi_res_enabled: bool,
-    pub duration_hint: f64,
-}
-
-/// Output of `build_source_from_play_input`: the wrapped rodio source plus
-/// whether the chosen source path is seekable (only the Streaming variant
-/// is not).
-pub(crate) struct PlaybackSource {
-    pub(crate) built: BuiltSource,
-    pub(crate) is_seekable: bool,
-}
-
-/// State + decisions audio_play computed before the sink swap.
-pub(crate) struct SinkSwapInputs {
-    pub(crate) sink: Arc<rodio::Player>,
-    pub(crate) duration_secs: f64,
-    pub(crate) volume: f32,
-    pub(crate) gain_linear: f32,
-    pub(crate) fadeout_trigger: Arc<AtomicBool>,
-    pub(crate) fadeout_samples: Arc<std::sync::atomic::AtomicU64>,
-    pub(crate) crossfade_enabled: bool,
-    pub(crate) actual_fade_secs: f32,
-}
-
-/// Atomically swap the new sink into `state.current`, then handle the old
-/// sink: trigger sample-level fade-out (crossfade enabled) or stop it
-/// immediately (hard cut). The fade-out is handed off to a small spawned
-/// task that drops the old sink ~`actual_fade_secs + 0.5 s` later.
-pub(crate) fn swap_in_new_sink(state: &State<'_, AudioEngine>, inputs: SinkSwapInputs) {
-    use std::time::Instant;
-
-    let SinkSwapInputs {
-        sink,
-        duration_secs,
-        volume,
-        gain_linear,
-        fadeout_trigger: new_fadeout_trigger,
-        fadeout_samples: new_fadeout_samples,
-        crossfade_enabled,
-        actual_fade_secs,
-    } = inputs;
-
-    let (old_sink, old_fadeout_trigger, old_fadeout_samples) = {
-        let mut cur = state.current.lock().unwrap();
-        let old = cur.sink.take();
-        let old_fo_trigger = cur.fadeout_trigger.take();
-        let old_fo_samples = cur.fadeout_samples.take();
-        cur.sink = Some(sink);
-        cur.duration_secs = duration_secs;
-        cur.seek_offset = 0.0;
-        cur.play_started = Some(Instant::now());
-        cur.paused_at = None;
-        cur.replay_gain_linear = gain_linear;
-        cur.base_volume = volume.clamp(0.0, 1.0);
-        cur.fadeout_trigger = Some(new_fadeout_trigger);
-        cur.fadeout_samples = Some(new_fadeout_samples);
-        (old, old_fo_trigger, old_fo_samples)
-    };
-
-    if crossfade_enabled {
-        if let Some(old) = old_sink {
-            // Trigger sample-level fade-out on Track A via TriggeredFadeOut.
-            // Calculate total fade samples from the measured actual_fade_secs.
-            let rate = state.current_sample_rate.load(Ordering::Relaxed);
-            let ch = state.current_channels.load(Ordering::Relaxed);
-            let fade_total = (actual_fade_secs as f64 * rate as f64 * ch as f64) as u64;
-
-            if let (Some(trigger), Some(samples)) = (old_fadeout_trigger, old_fadeout_samples) {
-                samples.store(fade_total.max(1), Ordering::SeqCst);
-                trigger.store(true, Ordering::SeqCst);
-            }
-
-            // Keep old sink alive until the fade completes + small margin,
-            // then drop it. No volume stepping needed — the fade-out runs
-            // at sample level inside the audio thread.
-            *state.fading_out_sink.lock().unwrap() = Some(old);
-            let fo_arc = state.fading_out_sink.clone();
-            let cleanup_dur = Duration::from_secs_f32(actual_fade_secs + 0.5);
-            tokio::spawn(async move {
-                tokio::time::sleep(cleanup_dur).await;
-                if let Some(s) = fo_arc.lock().unwrap().take() {
-                    s.stop();
-                }
-            });
-        }
-    } else if let Some(old) = old_sink {
-        old.stop();
-    }
-}
-
-fn play_media_format_hint(input: &PlayInput) -> Option<String> {
-    match input {
-        PlayInput::SeekableMedia { format_hint, .. } | PlayInput::Streaming { format_hint, .. } => {
-            format_hint.clone()
-        }
-        PlayInput::Bytes(_) => None,
-    }
-}
-
-/// Ranged HTTP probe/decode failed in a way that may succeed after the
-/// background download finishes (moov-at-end, demuxer EOF during partial buffer).
-fn is_ranged_stream_probe_failure(err: &str) -> bool {
-    err.contains("ranged-stream")
-        && (err.contains("format probe failed")
-            || err.contains("moov metadata")
-            || err.contains("end of stream"))
-}
-
-/// Completed ranged download or spill file for `url`, if ready.
-async fn try_take_completed_stream_bytes(
-    url: &str,
-    state: &State<'_, AudioEngine>,
-) -> Option<Vec<u8>> {
-    if let Some(data) = super::helpers::take_stream_completed_for_url(state, url) {
-        return Some(data);
-    }
-    let spill_path = {
-        let guard = state.stream_completed_spill.lock().unwrap();
-        guard
-            .as_ref()
-            .filter(|p| same_playback_target(&p.url, url))
-            .map(|p| p.path.clone())
-    };
-    if let Some(path) = spill_path {
-        let data = tokio::fs::read(&path).await.ok()?;
-        if !data.is_empty() {
-            return Some(data);
-        }
-    }
-    None
-}
-
-/// Ranged assembly can be byte-complete but missing `moov` (holes) or non-audio HTTP body.
-async fn prefer_clean_http_bytes_for_fallback(
-    url: &str,
-    gen: u64,
-    state: &State<'_, AudioEngine>,
-    app: &AppHandle,
-    ranged_data: Vec<u8>,
-    format_hint: Option<&str>,
-    label: &str,
-) -> Result<Option<Vec<u8>>, String> {
-    let is_mp4 = super::stream::container_hint_is_mp4(format_hint);
-    if is_mp4 {
-        super::stream::log_isobmff_buffer_diagnostic(&ranged_data, format_hint, label);
-        if !super::stream::isobmff_buffer_looks_complete(&ranged_data)
-            || super::stream::mp4_suspect_zero_holes(&ranged_data)
-        {
-            crate::app_deprintln!(
-                "[stream] ranged buffer looks incomplete or holey — refetching via sequential HTTP"
-            );
-            if let Some(fresh) = fetch_data(url, state, gen, app).await? {
-                if super::stream::isobmff_buffer_looks_complete(&fresh) {
-                    return Ok(Some(fresh));
-                }
-                super::stream::log_isobmff_buffer_diagnostic(&fresh, format_hint, "http-refetch");
-            }
-        }
-    }
-    Ok(Some(ranged_data))
-}
-
-/// Wait for the in-flight ranged download to finish, then HTTP-fetch if needed.
-pub(super) async fn wait_or_fetch_bytes_for_stream_fallback(
-    url: &str,
-    gen: u64,
-    state: &State<'_, AudioEngine>,
-    app: &AppHandle,
-    format_hint: Option<&str>,
-) -> Result<Option<Vec<u8>>, String> {
-    use std::time::{Duration, Instant};
-
-    let deadline = Instant::now() + Duration::from_secs(TRACK_READ_TIMEOUT_SECS);
-    loop {
-        if state.generation.load(Ordering::SeqCst) != gen {
-            return Ok(None);
-        }
-        if let Some(data) = try_take_completed_stream_bytes(url, state).await {
-            crate::app_deprintln!(
-                "[stream] full-buffer fallback: using completed download ({} KiB)",
-                data.len() / 1024
-            );
-            return prefer_clean_http_bytes_for_fallback(
-                url,
-                gen,
-                state,
-                app,
-                data,
-                format_hint,
-                "ranged-cache",
-            )
-            .await;
-        }
-        if Instant::now() >= deadline {
-            break;
-        }
-        tokio::time::sleep(Duration::from_millis(50)).await;
-    }
-    crate::app_deprintln!(
-        "[stream] full-buffer fallback: download still in progress after {}s — HTTP fetch",
-        TRACK_READ_TIMEOUT_SECS
-    );
-    fetch_data(url, state, gen, app).await
-}
-
-fn is_in_memory_probe_failure(err: &str) -> bool {
-    err.contains("format probe failed")
-        || err.contains("could not open audio stream")
-        || err.contains("no playable audio track")
-}
-
-/// Like [`build_source_from_play_input`], but on ranged-stream probe failure waits
-/// for a full download (or fetches it) and retries from in-memory bytes.
-pub(crate) async fn build_playback_source_with_probe_fallback(
-    play_input: PlayInput,
-    args: BuildSourceArgs<'_>,
-    state: &State<'_, AudioEngine>,
-    app: &AppHandle,
-) -> Result<PlaybackSource, String> {
-    let BuildSourceArgs {
-        url,
-        gen,
-        cache_id_for_tasks,
-        server_id,
-        url_format_hint,
-        stream_format_suffix,
-        done_flag,
-        fade_in_dur,
-        hi_res_enabled,
-        duration_hint,
-    } = args;
-    let media_hint = play_media_format_hint(&play_input);
-    let effective_hint = resolve_playback_format_hint(
-        url_format_hint,
-        stream_format_suffix,
-        media_hint.as_deref(),
-        None,
-    );
-    if let Some(ref h) = effective_hint {
-        crate::app_deprintln!("[stream] playback format hint: {h}");
-    }
-
-    match build_source_from_play_input(
-        play_input,
-        state,
-        effective_hint.as_deref(),
-        done_flag.clone(),
-        fade_in_dur,
-        hi_res_enabled,
-        duration_hint,
-    )
-    .await
-    {
-        Ok(p) => Ok(p),
-        Err(e) if is_ranged_stream_probe_failure(&e) => {
-            crate::app_deprintln!(
-                "[stream] ranged-stream probe failed — trying full-buffer fallback: {}",
-                e
-            );
-            let data = match wait_or_fetch_bytes_for_stream_fallback(
-                url,
-                gen,
-                state,
-                app,
-                effective_hint.as_deref(),
-            )
-            .await?
-            {
-                Some(d) => d,
-                None => return Err(e),
-            };
-            if state.generation.load(Ordering::SeqCst) != gen {
-                return Err("ranged-stream: superseded during full-buffer fallback".into());
-            }
-            let bytes_hint = resolve_playback_format_hint(
-                url_format_hint,
-                stream_format_suffix,
-                media_hint.as_deref(),
-                Some(&data),
-            );
-            if bytes_hint.as_ref() != effective_hint.as_ref() {
-                crate::app_deprintln!(
-                    "[stream] full-buffer fallback: resolved hint {:?} (was {:?})",
-                    bytes_hint,
-                    effective_hint
-                );
-            }
-            if let Some(track_id) = cache_id_for_tasks
-                .map(str::trim)
-                .filter(|s| !s.is_empty())
-            {
-                let (sid, high) =
-                    prepare_playback_analysis(app, state, server_id, track_id, None);
-                spawn_track_analysis_bytes(
-                    app.clone(),
-                    TrackAnalysisOrigin::StreamDownloadComplete,
-                    sid,
-                    track_id.to_string(),
-                    data.clone(),
-                    high,
-                    Some((gen, state.generation.clone())),
-                );
-            }
-            match build_source_from_play_input(
-                PlayInput::Bytes(data.clone()),
-                state,
-                bytes_hint.as_deref(),
-                done_flag.clone(),
-                fade_in_dur,
-                hi_res_enabled,
-                duration_hint,
-            )
-            .await
-            {
-                Ok(p) => Ok(p),
-                Err(pe) if is_in_memory_probe_failure(&pe) => {
-                    if super::stream::container_hint_is_mp4(bytes_hint.as_deref()) {
-                        super::stream::log_isobmff_buffer_diagnostic(
-                            &data,
-                            bytes_hint.as_deref(),
-                            "ranged-cache-probe-fail",
-                        );
-                    }
-                    crate::app_deprintln!(
-                        "[stream] in-memory probe failed — sequential HTTP refetch: {}",
-                        pe
-                    );
-                    let fresh = match fetch_data(url, state, gen, app).await? {
-                        Some(d) => d,
-                        None => return Err(pe),
-                    };
-                    if super::stream::container_hint_is_mp4(bytes_hint.as_deref()) {
-                        super::stream::log_isobmff_buffer_diagnostic(
-                            &fresh,
-                            bytes_hint.as_deref(),
-                            "http-refetch-after-probe-fail",
-                        );
-                    }
-                    build_source_from_play_input(
-                        PlayInput::Bytes(fresh),
-                        state,
-                        bytes_hint.as_deref(),
-                        done_flag,
-                        fade_in_dur,
-                        hi_res_enabled,
-                        duration_hint,
-                    )
-                    .await
-                }
-                Err(pe) => Err(pe),
-            }
-        }
-        Err(e) => Err(e),
-    }
-}
-
-/// Dispatch [`PlayInput`] → fully wrapped rodio source. For Bytes the full
-/// in-memory pipeline (incl. iTunSMPB scan); for SeekableMedia / Streaming
-/// the streaming variant runs the decoder build on a blocking thread.
-pub(super) async fn build_source_from_play_input(
-    play_input: PlayInput,
-    state: &State<'_, AudioEngine>,
-    format_hint: Option<&str>,
-    done_flag: Arc<AtomicBool>,
-    fade_in_dur: Duration,
-    hi_res_enabled: bool,
-    duration_hint: f64,
-) -> Result<PlaybackSource, String> {
-    // Always 0 — no application-level resampling. Rodio handles conversion to
-    // the output device rate internally; we let every track play at its native rate.
-    let target_rate: u32 = 0;
-    let mut is_seekable = true;
-    let built = match play_input {
-        PlayInput::Bytes(data) => build_source(
-            data,
-            duration_hint,
-            state.eq_gains.clone(),
-            state.eq_enabled.clone(),
-            state.eq_pre_gain.clone(),
-            state.playback_rate.clone(),
-            done_flag,
-            fade_in_dur,
-            state.samples_played.clone(),
-            target_rate,
-            format_hint,
-            hi_res_enabled,
-        ),
-        PlayInput::SeekableMedia {
-            reader,
-            format_hint: media_hint,
-            tag,
-            mp4_probe_gate,
-        } => {
-            if let Some(gate) = mp4_probe_gate.as_ref() {
-                super::stream::wait_for_ranged_mp4_probe_ready(gate).await?;
-                if gate.gen_arc.load(Ordering::SeqCst) != gate.gen {
-                    return Err("ranged-stream: superseded before moov metadata ready".into());
-                }
-            }
-            let decoder = tokio::task::spawn_blocking(move || {
-                SizedDecoder::new_streaming(reader, media_hint.as_deref(), tag)
-            })
-            .await
-            .map_err(|e| e.to_string())??;
-            build_streaming_source(
-                decoder,
-                duration_hint,
-                state.eq_gains.clone(),
-                state.eq_enabled.clone(),
-                state.eq_pre_gain.clone(),
-                state.playback_rate.clone(),
-                done_flag,
-                fade_in_dur,
-                state.samples_played.clone(),
-                target_rate,
-                None,
-            )
-        }
-        PlayInput::Streaming { reader, format_hint: stream_hint } => {
-            is_seekable = false;
-            let decoder = tokio::task::spawn_blocking(move || {
-                SizedDecoder::new_streaming(Box::new(reader), stream_hint.as_deref(), "track-stream")
-            })
-            .await
-            .map_err(|e| e.to_string())??;
-            build_streaming_source(
-                decoder,
-                duration_hint,
-                state.eq_gains.clone(),
-                state.eq_enabled.clone(),
-                state.eq_pre_gain.clone(),
-                state.playback_rate.clone(),
-                done_flag,
-                fade_in_dur,
-                state.samples_played.clone(),
-                target_rate,
-                Some(state.stream_playback_armed.clone()),
-            )
-        }
-    }?;
-    Ok(PlaybackSource { built, is_seekable })
-}

src-tauri/crates/psysonic-audio/src/power_resume.rs

@@ -4,11 +4,11 @@
 use std::sync::Mutex;
 use std::time::{Duration, Instant};
 
-use tauri::AppHandle;
-use tauri::Manager;
+use tauri::{AppHandle, Emitter, Manager};
 
 use super::device_watcher::{reopen_output_stream, ReopenNotify};
-use super::engine::AudioEngine;
+use super::engine::{request_stream_release, AudioEngine};
+use super::stream_idle::{output_stream_is_needed, teardown_playback_sinks_for_idle_release};
 
 static RESUME_REOPEN_DEBOUNCE: Mutex<Option<Instant>> = Mutex::new(None);
 const DEBOUNCE: Duration = Duration::from_millis(900);
@@ -30,10 +30,22 @@ pub(crate) fn debounce_allow_resume_reopen() -> bool {
 pub(crate) async fn reopen_audio_after_system_resume(app: &AppHandle) {
     tokio::time::sleep(Duration::from_millis(400)).await;
 
-    let device_name = match app.try_state::<AudioEngine>() {
-        Some(e) => e.selected_device.lock().unwrap().clone(),
-        None => return,
+    let Some(state) = app.try_state::<AudioEngine>() else {
+        return;
     };
+    let engine = state.inner();
+
+    if !output_stream_is_needed(engine) {
+        if engine.stream_handle.lock().unwrap().is_some() {
+            teardown_playback_sinks_for_idle_release(engine);
+            let _ = request_stream_release(engine);
+            *engine.stream_handle.lock().unwrap() = None;
+            let _ = app.emit("audio:output-released", ());
+        }
+        return;
+    }
+
+    let device_name = engine.selected_device.lock().unwrap().clone();
 
     if reopen_output_stream(app, device_name, ReopenNotify::DeviceChanged).await {
         crate::app_eprintln!("[psysonic] audio output reopened after system resume");

src-tauri/crates/psysonic-audio/src/preview.rs

@@ -1,6 +1,6 @@
 //! Short preview playback on a secondary sink (same output stream).
-use std::sync::atomic::Ordering;
-use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicU64, AtomicUsize, Ordering};
+use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 
 use rodio::Player;
@@ -10,11 +10,16 @@ use tauri::{AppHandle, Emitter, State};
 use super::decode::SizedDecoder;
 use super::engine::{audio_http_client, AudioEngine};
 use super::helpers::{
-    content_type_to_hint, format_hint_from_content_disposition, resolve_playback_format_hint,
+    content_type_to_hint, format_hint_from_content_disposition, normalize_stream_suffix_for_hint,
+    resolve_playback_format_hint, sniff_stream_format_extension, STREAM_FORMAT_SNIFF_PROBE_BYTES,
     MASTER_HEADROOM,
 };
 use super::play_input::url_format_hint;
 use super::sources::PriorityBoostSource;
+use super::stream::{
+    mp4_needs_tail_prefetch, ranged_download_task, wait_for_ranged_mp4_probe_ready,
+    RangedHttpSource, RangedMp4ProbeGate,
+};
 
 // ────────────────────────────────────────────────────────────────────────────
 // Preview engine — secondary Sink on the same OutputStream, fed by Symphonia.
@@ -132,7 +137,201 @@ pub(crate) fn resolve_preview_format_hint(
     )
 }
 
+fn preview_http_client(state: &AudioEngine) -> reqwest::Client {
+    reqwest::Client::builder()
+        .timeout(Duration::from_secs(300))
+        .use_rustls_tls()
+        .user_agent(psysonic_core::user_agent::subsonic_wire_user_agent())
+        .build()
+        .unwrap_or_else(|_| audio_http_client(state))
+}
+
+/// Open a preview decoder — ranged HTTP when the server supports it (starts
+/// after ~384 KiB buffered), otherwise falls back to a full in-memory download.
+async fn open_preview_decoder(
+    url: &str,
+    format_suffix: Option<&str>,
+    gen: u64,
+    state: &AudioEngine,
+    app: &AppHandle,
+) -> Result<Option<SizedDecoder>, String> {
+    let preview_http = preview_http_client(state);
+    let response = preview_http
+        .get(url)
+        .send()
+        .await
+        .map_err(|e| format!("preview: connection failed: {e}"))?
+        .error_for_status()
+        .map_err(|e| format!("preview: HTTP {e}"))?;
+
+    let mut stream_hint = content_type_to_hint(
+        response
+            .headers()
+            .get(reqwest::header::CONTENT_TYPE)
+            .and_then(|v| v.to_str().ok())
+            .unwrap_or(""),
+    )
+    .or_else(|| {
+        response
+            .headers()
+            .get(reqwest::header::CONTENT_DISPOSITION)
+            .and_then(|v| v.to_str().ok())
+            .and_then(format_hint_from_content_disposition)
+    })
+    .or_else(|| normalize_stream_suffix_for_hint(format_suffix))
+    .or_else(|| preview_format_hint_from_url(url))
+    .or_else(|| url_format_hint(url));
+
+    let supports_range = response
+        .headers()
+        .get(reqwest::header::ACCEPT_RANGES)
+        .and_then(|v| v.to_str().ok())
+        .is_some_and(|v| v.to_ascii_lowercase().contains("bytes"));
+    let total_size = response.content_length();
+
+    if stream_hint.is_none() && supports_range {
+        if let Some(total_u64) = total_size.filter(|&t| t > 0) {
+            let last = total_u64
+                .saturating_sub(1)
+                .min((STREAM_FORMAT_SNIFF_PROBE_BYTES - 1) as u64);
+            if let Ok(pr) = preview_http
+                .get(url)
+                .header(reqwest::header::RANGE, format!("bytes=0-{last}"))
+                .send()
+                .await
+            {
+                let stat = pr.status();
+                let ok = stat == reqwest::StatusCode::PARTIAL_CONTENT
+                    || stat == reqwest::StatusCode::OK;
+                if ok {
+                    if let Ok(bytes) = pr.bytes().await {
+                        if !bytes.is_empty() {
+                            stream_hint = sniff_stream_format_extension(&bytes).or(stream_hint);
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    if let (true, Some(total), true) = (supports_range, total_size, stream_hint.is_some()) {
+        if state.preview_gen.load(Ordering::SeqCst) != gen {
+            return Ok(None);
+        }
+        let total_usize = total as usize;
+        crate::app_deprintln!(
+            "[preview] ranged open — total={} KB, hint={:?}",
+            total_usize / 1024,
+            stream_hint
+        );
+        let buf = Arc::new(Mutex::new(vec![0u8; total_usize]));
+        let downloaded_to = Arc::new(AtomicUsize::new(0));
+        let done = Arc::new(AtomicBool::new(false));
+        let playback_armed = Arc::new(AtomicBool::new(false));
+        let tail_ready = Arc::new(AtomicBool::new(false));
+        let tail_filled_from = Arc::new(AtomicU64::new(0));
+        let tail_prefetch = mp4_needs_tail_prefetch(&[], stream_hint.as_deref());
+        let mp4_probe_gate = tail_prefetch.then(|| RangedMp4ProbeGate {
+            tail_ready: tail_ready.clone(),
+            buf: buf.clone(),
+            downloaded_to: downloaded_to.clone(),
+            gen_arc: state.preview_gen.clone(),
+            gen,
+            format_hint: stream_hint.clone(),
+        });
+        tokio::spawn(ranged_download_task(
+            gen,
+            state.preview_gen.clone(),
+            preview_http,
+            app.clone(),
+            0.0,
+            url.to_string(),
+            response,
+            buf.clone(),
+            downloaded_to.clone(),
+            done.clone(),
+            state.stream_completed_cache.clone(),
+            state.stream_completed_spill.clone(),
+            state.normalization_engine.clone(),
+            state.normalization_target_lufs.clone(),
+            state.loudness_pre_analysis_attenuation_db.clone(),
+            None,
+            None,
+            None,
+            playback_armed,
+            stream_hint.clone(),
+            tail_ready.clone(),
+            tail_filled_from.clone(),
+        ));
+        if let Some(ref gate) = mp4_probe_gate {
+            wait_for_ranged_mp4_probe_ready(gate).await?;
+            if state.preview_gen.load(Ordering::SeqCst) != gen {
+                return Ok(None);
+            }
+        }
+        let reader = RangedHttpSource {
+            buf,
+            downloaded_to,
+            tail_ready,
+            tail_filled_from,
+            total_size: total,
+            pos: 0,
+            done,
+            gen_arc: state.preview_gen.clone(),
+            gen,
+        };
+        let hint = stream_hint.clone();
+        let decoder = tokio::task::spawn_blocking(move || {
+            SizedDecoder::new_streaming(Box::new(reader), hint.as_deref(), "preview-stream", false)
+        })
+        .await
+        .map_err(|e| format!("preview: decoder thread: {e}"))??;
+        return Ok(Some(decoder));
+    }
+
+    crate::app_deprintln!(
+        "[preview] buffered download — accept-ranges={}, content-length={:?}, hint={:?}",
+        supports_range,
+        total_size,
+        stream_hint
+    );
+    let content_type = response
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .map(str::to_string);
+    let content_disposition = response
+        .headers()
+        .get(reqwest::header::CONTENT_DISPOSITION)
+        .and_then(|v| v.to_str().ok())
+        .map(str::to_string);
+    let bytes = response
+        .bytes()
+        .await
+        .map_err(|e| format!("preview: read body: {e}"))?
+        .to_vec();
+    if state.preview_gen.load(Ordering::SeqCst) != gen {
+        return Ok(None);
+    }
+    let hint = resolve_preview_format_hint(
+        url,
+        content_type.as_deref(),
+        content_disposition.as_deref(),
+        format_suffix,
+        &bytes,
+    );
+    let bytes_for_blocking = bytes;
+    let hint_for_blocking = hint.clone();
+    let decoder = tokio::task::spawn_blocking(move || {
+        SizedDecoder::new(bytes_for_blocking, hint_for_blocking.as_deref(), false)
+    })
+    .await
+    .map_err(|e| format!("preview: decoder thread: {e}"))??;
+    Ok(Some(decoder))
+}
+
 #[tauri::command]
+#[allow(clippy::too_many_arguments)] // Tauri IPC — args map 1:1 to the JS invoke payload.
 pub async fn audio_preview_play(
     id: String,
     url: String,
@@ -164,65 +363,24 @@ pub async fn audio_preview_play(
         preview_pause_main(&state);
     }
 
-    // ── Download ─────────────────────────────────────────────────────────────
-    // Dedicated client with a generous timeout. The shared `audio_http_client`
-    // caps at 30 s, which aborts mid-download on multi-hundred-megabyte
-    // uncompressed files (e.g. 18-min Hi-Res WAV ~600 MB) — those need
-    // ~60–120 s on a typical home LAN. The watchdog (30 s wall-clock) still
-    // bounds how long the preview plays once the bytes are in memory, so a
-    // long download just means a longer "loading" spinner before audio starts.
-    let preview_http = reqwest::Client::builder()
-        .timeout(Duration::from_secs(300))
-        .use_rustls_tls()
-        .user_agent(psysonic_core::user_agent::subsonic_wire_user_agent())
-        .build()
-        .unwrap_or_else(|_| audio_http_client(&state));
-    let response = preview_http
-        .get(&url)
-        .send()
-        .await
-        .map_err(|e| format!("preview: connection failed: {e}"))?
-        .error_for_status()
-        .map_err(|e| format!("preview: HTTP {e}"))?;
-    let content_type = response
-        .headers()
-        .get(reqwest::header::CONTENT_TYPE)
-        .and_then(|v| v.to_str().ok())
-        .map(str::to_string);
-    let content_disposition = response
-        .headers()
-        .get(reqwest::header::CONTENT_DISPOSITION)
-        .and_then(|v| v.to_str().ok())
-        .map(str::to_string);
-    let bytes = response
-        .bytes()
-        .await
-        .map_err(|e| format!("preview: read body: {e}"))?
-        .to_vec();
+    // ── Open decoder (ranged stream when possible) ───────────────────────────
+    let decoder = match open_preview_decoder(
+        &url,
+        format_suffix.as_deref(),
+        gen,
+        &state,
+        &app,
+    )
+    .await?
+    {
+        Some(d) => d,
+        None => return Ok(()),
+    };
 
     if state.preview_gen.load(Ordering::SeqCst) != gen {
-        // A newer preview started while we were downloading — bail.
         return Ok(());
     }
 
-    // ── Decode ───────────────────────────────────────────────────────────────
-    let hint = resolve_preview_format_hint(
-        &url,
-        content_type.as_deref(),
-        content_disposition.as_deref(),
-        format_suffix.as_deref(),
-        &bytes,
-    );
-    let bytes_for_blocking = bytes;
-    let hint_for_blocking = hint.clone();
-    let decoder = tokio::task::spawn_blocking(move || {
-        SizedDecoder::new(bytes_for_blocking, hint_for_blocking.as_deref(), false)
-    })
-    .await
-    .map_err(|e| format!("preview: decoder thread: {e}"))??;
-
-    if state.preview_gen.load(Ordering::SeqCst) != gen { return Ok(()); }
-
     // ── Build source pipeline ────────────────────────────────────────────────
     // Seek FIRST on the bare decoder, THEN cap with take_duration. Capping
     // before the seek made take_duration's wall-clock counter tick from
@@ -241,7 +399,8 @@ pub async fn audio_preview_play(
     let source = PriorityBoostSource::new(source);
 
     // ── Build secondary sink on the existing OutputStream ────────────────────
-    let sink = Arc::new(Player::connect_new(state.stream_handle.lock().unwrap().mixer()));
+    let stream = super::engine::ensure_output_stream_open(&state)?;
+    let sink = Arc::new(Player::connect_new(stream.mixer()));
     sink.set_volume((volume.clamp(0.0, 1.0) * MASTER_HEADROOM).clamp(0.0, 1.0));
     sink.append(source);
 

src-tauri/crates/psysonic-audio/src/radio_commands.rs

@@ -124,7 +124,7 @@ pub async fn audio_play_radio(
 
     let hint_clone = fmt_hint.clone();
     let decoder = tokio::task::spawn_blocking(move || {
-        SizedDecoder::new_streaming(Box::new(reader), hint_clone.as_deref(), "radio")
+        SizedDecoder::new_streaming(Box::new(reader), hint_clone.as_deref(), "radio", false)
     })
     .await
     .map_err(|e| e.to_string())??;
@@ -150,7 +150,8 @@ pub async fn audio_play_radio(
 
     if state.generation.load(Ordering::SeqCst) != gen { return Ok(()); }
 
-    let sink = Arc::new(Player::connect_new(state.stream_handle.lock().unwrap().mixer()));
+    let stream = super::engine::ensure_output_stream_open(&state)?;
+    let sink = Arc::new(Player::connect_new(stream.mixer()));
     sink.set_volume((volume.clamp(0.0, 1.0) * MASTER_HEADROOM).clamp(0.0, 1.0));
     sink.append(boosted);
 

src-tauri/crates/psysonic-audio/src/sink_swap.rs

@@ -0,0 +1,165 @@
+//! Sink-lifecycle glue for `audio_play`: atomically swap a freshly built sink
+//! into `state.current` (handing off the old one to a crossfade tail or a hard
+//! stop), and the legacy non-seekable path that holds a sink paused until the
+//! download task arms playback. Split out of `play_input.rs` so source
+//! selection and source building stay focused on their own concerns.
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use tauri::{AppHandle, Emitter, State};
+
+use super::engine::{AudioCurrent, AudioEngine};
+
+/// Args for [`spawn_legacy_stream_start_when_armed`].
+pub(super) struct LegacyStreamStartWhenArmed {
+    pub gen: u64,
+    pub gen_arc: Arc<AtomicU64>,
+    pub playback_armed: Arc<AtomicBool>,
+    pub samples_played: Arc<AtomicU64>,
+    pub current: Arc<Mutex<AudioCurrent>>,
+    pub app: AppHandle,
+    pub duration_secs: f64,
+    pub hold_paused: bool,
+}
+
+/// Legacy `AudioStreamReader`: keep the sink paused until the download task arms
+/// playback, then reset counters and emit `audio:playing` so the UI does not
+/// extrapolate ahead of audible output.
+pub(super) fn spawn_legacy_stream_start_when_armed(args: LegacyStreamStartWhenArmed) {
+    let LegacyStreamStartWhenArmed {
+        gen,
+        gen_arc,
+        playback_armed,
+        samples_played,
+        current,
+        app,
+        duration_secs,
+        hold_paused,
+    } = args;
+    tokio::spawn(async move {
+        loop {
+            if gen_arc.load(Ordering::SeqCst) != gen {
+                return;
+            }
+            if playback_armed.load(Ordering::Relaxed) {
+                break;
+            }
+            tokio::time::sleep(Duration::from_millis(50)).await;
+        }
+        if gen_arc.load(Ordering::SeqCst) != gen {
+            return;
+        }
+        samples_played.store(0, Ordering::Relaxed);
+        let sink = current.lock().unwrap().sink.clone();
+        if let Some(sink) = sink {
+            if hold_paused {
+                sink.pause();
+                let mut cur = current.lock().unwrap();
+                cur.play_started = None;
+                if cur.paused_at.is_none() {
+                    cur.paused_at = Some(0.0);
+                }
+                cur.seek_offset = 0.0;
+                crate::app_deprintln!(
+                    "[stream] legacy track-stream: buffer ready, holding paused (silent prepare)"
+                );
+            } else {
+                {
+                    let mut cur = current.lock().unwrap();
+                    cur.play_started = Some(Instant::now());
+                    cur.paused_at = None;
+                    cur.seek_offset = 0.0;
+                }
+                sink.play();
+                app.emit("audio:playing", duration_secs).ok();
+                crate::app_deprintln!("[stream] legacy track-stream: playback started after buffer ready");
+            }
+        }
+    });
+}
+
+/// State + decisions audio_play computed before the sink swap.
+pub(crate) struct SinkSwapInputs {
+    pub(crate) sink: Arc<rodio::Player>,
+    pub(crate) duration_secs: f64,
+    pub(crate) volume: f32,
+    pub(crate) gain_linear: f32,
+    pub(crate) fadeout_trigger: Arc<AtomicBool>,
+    pub(crate) fadeout_samples: Arc<AtomicU64>,
+    pub(crate) crossfade_enabled: bool,
+    pub(crate) actual_fade_secs: f32,
+    pub(crate) start_paused: bool,
+}
+
+/// Atomically swap the new sink into `state.current`, then handle the old
+/// sink: trigger sample-level fade-out (crossfade enabled) or stop it
+/// immediately (hard cut). The fade-out is handed off to a small spawned
+/// task that drops the old sink ~`actual_fade_secs + 0.5 s` later.
+pub(crate) fn swap_in_new_sink(state: &State<'_, AudioEngine>, inputs: SinkSwapInputs) {
+    let SinkSwapInputs {
+        sink,
+        duration_secs,
+        volume,
+        gain_linear,
+        fadeout_trigger: new_fadeout_trigger,
+        fadeout_samples: new_fadeout_samples,
+        crossfade_enabled,
+        actual_fade_secs,
+        start_paused,
+    } = inputs;
+
+    let (old_sink, old_fadeout_trigger, old_fadeout_samples) = {
+        let mut cur = state.current.lock().unwrap();
+        let old = cur.sink.take();
+        let old_fo_trigger = cur.fadeout_trigger.take();
+        let old_fo_samples = cur.fadeout_samples.take();
+        cur.sink = Some(sink.clone());
+        cur.duration_secs = duration_secs;
+        cur.seek_offset = 0.0;
+        if start_paused {
+            sink.pause();
+            cur.play_started = None;
+            cur.paused_at = Some(0.0);
+        } else {
+            cur.play_started = Some(Instant::now());
+            cur.paused_at = None;
+        }
+        cur.replay_gain_linear = gain_linear;
+        cur.base_volume = volume.clamp(0.0, 1.0);
+        cur.fadeout_trigger = Some(new_fadeout_trigger);
+        cur.fadeout_samples = Some(new_fadeout_samples);
+        (old, old_fo_trigger, old_fo_samples)
+    };
+
+    if crossfade_enabled {
+        if let Some(old) = old_sink {
+            // Trigger sample-level fade-out on Track A via TriggeredFadeOut.
+            // Calculate total fade samples from the measured actual_fade_secs.
+            let rate = state.current_sample_rate.load(Ordering::Relaxed);
+            let ch = state.current_channels.load(Ordering::Relaxed);
+            let fade_total = (actual_fade_secs as f64 * rate as f64 * ch as f64) as u64;
+
+            if let (Some(trigger), Some(samples)) = (old_fadeout_trigger, old_fadeout_samples) {
+                samples.store(fade_total.max(1), Ordering::SeqCst);
+                trigger.store(true, Ordering::SeqCst);
+            }
+
+            // Keep old sink alive until the fade completes + small margin,
+            // then drop it. No volume stepping needed — the fade-out runs
+            // at sample level inside the audio thread.
+            *state.fading_out_sink.lock().unwrap() = Some(old);
+            let fo_arc = state.fading_out_sink.clone();
+            let cleanup_dur = Duration::from_secs_f32(actual_fade_secs + 0.5);
+            tokio::spawn(async move {
+                tokio::time::sleep(cleanup_dur).await;
+                if let Some(s) = fo_arc.lock().unwrap().take() {
+                    s.stop();
+                }
+            });
+        }
+    } else if let Some(old) = old_sink {
+        old.stop();
+    }
+}

src-tauri/crates/psysonic-audio/src/source_build.rs

@@ -0,0 +1,404 @@
+//! Source-building pipeline for `audio_play`: turn a resolved [`PlayInput`]
+//! into a fully wrapped rodio source, including the ranged-stream probe
+//! fallback (wait for / fetch a full download and retry from in-memory bytes
+//! when a partial ranged buffer can't be probed yet). Split out of
+//! `play_input.rs` so source *selection* stays separate from source *building*.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::Duration;
+
+use tauri::{AppHandle, State};
+
+use super::analysis_dispatch::{
+    prepare_playback_analysis, spawn_track_analysis_bytes, TrackAnalysisOrigin,
+};
+use super::decode::{build_source, build_streaming_source, BuiltSource, SizedDecoder};
+use super::engine::AudioEngine;
+use super::helpers::{fetch_data, resolve_playback_format_hint, same_playback_target};
+use super::play_input::PlayInput;
+use super::stream::TRACK_READ_TIMEOUT_SECS;
+
+/// Arguments forwarded from `audio_play` into the source-build pipeline.
+/// Bundles the format-hint inputs, playback-shaping parameters and the shared
+/// done flag so that `build_playback_source_with_probe_fallback` stays below
+/// the `clippy::too_many_arguments` threshold.
+pub(crate) struct BuildSourceArgs<'a> {
+    pub url: &'a str,
+    pub gen: u64,
+    pub cache_id_for_tasks: Option<&'a str>,
+    pub server_id: Option<&'a str>,
+    pub url_format_hint: Option<&'a str>,
+    pub stream_format_suffix: Option<&'a str>,
+    pub done_flag: Arc<AtomicBool>,
+    pub fade_in_dur: Duration,
+    pub hi_res_enabled: bool,
+    pub duration_hint: f64,
+}
+
+/// Output of `build_source_from_play_input`: the wrapped rodio source plus
+/// whether the chosen source path is seekable (only the Streaming variant
+/// is not).
+pub(crate) struct PlaybackSource {
+    pub(crate) built: BuiltSource,
+    pub(crate) is_seekable: bool,
+}
+
+fn play_media_format_hint(input: &PlayInput) -> Option<String> {
+    match input {
+        PlayInput::SeekableMedia { format_hint, .. } | PlayInput::Streaming { format_hint, .. } => {
+            format_hint.clone()
+        }
+        PlayInput::Bytes(_) => None,
+    }
+}
+
+/// Ranged HTTP probe/decode failed in a way that may succeed after the
+/// background download finishes (moov-at-end, demuxer EOF during partial buffer).
+fn is_ranged_stream_probe_failure(err: &str) -> bool {
+    err.contains("ranged-stream")
+        && (err.contains("format probe failed")
+            || err.contains("moov metadata")
+            || err.contains("end of stream"))
+}
+
+/// Completed ranged download or spill file for `url`, if ready.
+async fn try_take_completed_stream_bytes(
+    url: &str,
+    state: &State<'_, AudioEngine>,
+) -> Option<Vec<u8>> {
+    if let Some(data) = super::helpers::take_stream_completed_for_url(state, url) {
+        return Some(data);
+    }
+    let spill_path = {
+        let guard = state.stream_completed_spill.lock().unwrap();
+        guard
+            .as_ref()
+            .filter(|p| same_playback_target(&p.url, url))
+            .map(|p| p.path.clone())
+    };
+    if let Some(path) = spill_path {
+        let data = tokio::fs::read(&path).await.ok()?;
+        if !data.is_empty() {
+            return Some(data);
+        }
+    }
+    None
+}
+
+/// Ranged assembly can be byte-complete but missing `moov` (holes) or non-audio HTTP body.
+async fn prefer_clean_http_bytes_for_fallback(
+    url: &str,
+    gen: u64,
+    state: &State<'_, AudioEngine>,
+    app: &AppHandle,
+    ranged_data: Vec<u8>,
+    format_hint: Option<&str>,
+    label: &str,
+) -> Result<Option<Vec<u8>>, String> {
+    let is_mp4 = super::stream::container_hint_is_mp4(format_hint);
+    if is_mp4 {
+        super::stream::log_isobmff_buffer_diagnostic(&ranged_data, format_hint, label);
+        if !super::stream::isobmff_buffer_looks_complete(&ranged_data)
+            || super::stream::mp4_suspect_zero_holes(&ranged_data)
+        {
+            crate::app_deprintln!(
+                "[stream] ranged buffer looks incomplete or holey — refetching via sequential HTTP"
+            );
+            if let Some(fresh) = fetch_data(url, state, gen, app).await? {
+                if super::stream::isobmff_buffer_looks_complete(&fresh) {
+                    return Ok(Some(fresh));
+                }
+                super::stream::log_isobmff_buffer_diagnostic(&fresh, format_hint, "http-refetch");
+            }
+        }
+    }
+    Ok(Some(ranged_data))
+}
+
+/// Wait for the in-flight ranged download to finish, then HTTP-fetch if needed.
+async fn wait_or_fetch_bytes_for_stream_fallback(
+    url: &str,
+    gen: u64,
+    state: &State<'_, AudioEngine>,
+    app: &AppHandle,
+    format_hint: Option<&str>,
+) -> Result<Option<Vec<u8>>, String> {
+    use std::time::Instant;
+
+    let deadline = Instant::now() + Duration::from_secs(TRACK_READ_TIMEOUT_SECS);
+    loop {
+        if state.generation.load(Ordering::SeqCst) != gen {
+            return Ok(None);
+        }
+        if let Some(data) = try_take_completed_stream_bytes(url, state).await {
+            crate::app_deprintln!(
+                "[stream] full-buffer fallback: using completed download ({} KiB)",
+                data.len() / 1024
+            );
+            return prefer_clean_http_bytes_for_fallback(
+                url,
+                gen,
+                state,
+                app,
+                data,
+                format_hint,
+                "ranged-cache",
+            )
+            .await;
+        }
+        if Instant::now() >= deadline {
+            break;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+    crate::app_deprintln!(
+        "[stream] full-buffer fallback: download still in progress after {}s — HTTP fetch",
+        TRACK_READ_TIMEOUT_SECS
+    );
+    fetch_data(url, state, gen, app).await
+}
+
+fn is_in_memory_probe_failure(err: &str) -> bool {
+    err.contains("format probe failed")
+        || err.contains("could not open audio stream")
+        || err.contains("no playable audio track")
+}
+
+/// Like [`build_source_from_play_input`], but on ranged-stream probe failure waits
+/// for a full download (or fetches it) and retries from in-memory bytes.
+pub(crate) async fn build_playback_source_with_probe_fallback(
+    play_input: PlayInput,
+    args: BuildSourceArgs<'_>,
+    state: &State<'_, AudioEngine>,
+    app: &AppHandle,
+) -> Result<PlaybackSource, String> {
+    let BuildSourceArgs {
+        url,
+        gen,
+        cache_id_for_tasks,
+        server_id,
+        url_format_hint,
+        stream_format_suffix,
+        done_flag,
+        fade_in_dur,
+        hi_res_enabled,
+        duration_hint,
+    } = args;
+    let media_hint = play_media_format_hint(&play_input);
+    let effective_hint = resolve_playback_format_hint(
+        url_format_hint,
+        stream_format_suffix,
+        media_hint.as_deref(),
+        None,
+    );
+    if let Some(ref h) = effective_hint {
+        crate::app_deprintln!("[stream] playback format hint: {h}");
+    }
+
+    match build_source_from_play_input(
+        play_input,
+        state,
+        effective_hint.as_deref(),
+        done_flag.clone(),
+        fade_in_dur,
+        hi_res_enabled,
+        duration_hint,
+    )
+    .await
+    {
+        Ok(p) => Ok(p),
+        Err(e) if is_ranged_stream_probe_failure(&e) => {
+            crate::app_deprintln!(
+                "[stream] ranged-stream probe failed — trying full-buffer fallback: {}",
+                e
+            );
+            let data = match wait_or_fetch_bytes_for_stream_fallback(
+                url,
+                gen,
+                state,
+                app,
+                effective_hint.as_deref(),
+            )
+            .await?
+            {
+                Some(d) => d,
+                None => return Err(e),
+            };
+            if state.generation.load(Ordering::SeqCst) != gen {
+                return Err("ranged-stream: superseded during full-buffer fallback".into());
+            }
+            let bytes_hint = resolve_playback_format_hint(
+                url_format_hint,
+                stream_format_suffix,
+                media_hint.as_deref(),
+                Some(&data),
+            );
+            if bytes_hint.as_ref() != effective_hint.as_ref() {
+                crate::app_deprintln!(
+                    "[stream] full-buffer fallback: resolved hint {:?} (was {:?})",
+                    bytes_hint,
+                    effective_hint
+                );
+            }
+            if let Some(track_id) = cache_id_for_tasks
+                .map(str::trim)
+                .filter(|s| !s.is_empty())
+            {
+                let (sid, high) =
+                    prepare_playback_analysis(app, state, server_id, track_id, None);
+                spawn_track_analysis_bytes(
+                    app.clone(),
+                    TrackAnalysisOrigin::StreamDownloadComplete,
+                    sid,
+                    track_id.to_string(),
+                    data.clone(),
+                    high,
+                    Some((gen, state.generation.clone())),
+                );
+            }
+            match build_source_from_play_input(
+                PlayInput::Bytes(data.clone()),
+                state,
+                bytes_hint.as_deref(),
+                done_flag.clone(),
+                fade_in_dur,
+                hi_res_enabled,
+                duration_hint,
+            )
+            .await
+            {
+                Ok(p) => Ok(p),
+                Err(pe) if is_in_memory_probe_failure(&pe) => {
+                    if super::stream::container_hint_is_mp4(bytes_hint.as_deref()) {
+                        super::stream::log_isobmff_buffer_diagnostic(
+                            &data,
+                            bytes_hint.as_deref(),
+                            "ranged-cache-probe-fail",
+                        );
+                    }
+                    crate::app_deprintln!(
+                        "[stream] in-memory probe failed — sequential HTTP refetch: {}",
+                        pe
+                    );
+                    let fresh = match fetch_data(url, state, gen, app).await? {
+                        Some(d) => d,
+                        None => return Err(pe),
+                    };
+                    if super::stream::container_hint_is_mp4(bytes_hint.as_deref()) {
+                        super::stream::log_isobmff_buffer_diagnostic(
+                            &fresh,
+                            bytes_hint.as_deref(),
+                            "http-refetch-after-probe-fail",
+                        );
+                    }
+                    build_source_from_play_input(
+                        PlayInput::Bytes(fresh),
+                        state,
+                        bytes_hint.as_deref(),
+                        done_flag,
+                        fade_in_dur,
+                        hi_res_enabled,
+                        duration_hint,
+                    )
+                    .await
+                }
+                Err(pe) => Err(pe),
+            }
+        }
+        Err(e) => Err(e),
+    }
+}
+
+/// Dispatch [`PlayInput`] → fully wrapped rodio source. For Bytes the full
+/// in-memory pipeline (incl. iTunSMPB scan); for SeekableMedia / Streaming
+/// the streaming variant runs the decoder build on a blocking thread.
+async fn build_source_from_play_input(
+    play_input: PlayInput,
+    state: &State<'_, AudioEngine>,
+    format_hint: Option<&str>,
+    done_flag: Arc<AtomicBool>,
+    fade_in_dur: Duration,
+    hi_res_enabled: bool,
+    duration_hint: f64,
+) -> Result<PlaybackSource, String> {
+    // Always 0 — no application-level resampling. Rodio handles conversion to
+    // the output device rate internally; we let every track play at its native rate.
+    let target_rate: u32 = 0;
+    let mut is_seekable = true;
+    let built = match play_input {
+        PlayInput::Bytes(data) => build_source(
+            data,
+            duration_hint,
+            state.eq_gains.clone(),
+            state.eq_enabled.clone(),
+            state.eq_pre_gain.clone(),
+            state.playback_rate.clone(),
+            done_flag,
+            fade_in_dur,
+            state.samples_played.clone(),
+            target_rate,
+            format_hint,
+            hi_res_enabled,
+        ),
+        PlayInput::SeekableMedia {
+            reader,
+            format_hint: media_hint,
+            tag,
+            random_access,
+            mp4_probe_gate,
+        } => {
+            if let Some(gate) = mp4_probe_gate.as_ref() {
+                super::stream::wait_for_ranged_mp4_probe_ready(gate).await?;
+                if gate.gen_arc.load(Ordering::SeqCst) != gate.gen {
+                    return Err("ranged-stream: superseded before moov metadata ready".into());
+                }
+            }
+            let decoder = tokio::task::spawn_blocking(move || {
+                SizedDecoder::new_streaming(reader, media_hint.as_deref(), tag, random_access)
+            })
+            .await
+            .map_err(|e| e.to_string())??;
+            build_streaming_source(
+                decoder,
+                duration_hint,
+                state.eq_gains.clone(),
+                state.eq_enabled.clone(),
+                state.eq_pre_gain.clone(),
+                state.playback_rate.clone(),
+                done_flag,
+                fade_in_dur,
+                state.samples_played.clone(),
+                target_rate,
+                None,
+            )
+        }
+        PlayInput::Streaming { reader, format_hint: stream_hint } => {
+            is_seekable = false;
+            let decoder = tokio::task::spawn_blocking(move || {
+                SizedDecoder::new_streaming(
+                    Box::new(reader),
+                    stream_hint.as_deref(),
+                    "track-stream",
+                    false,
+                )
+            })
+            .await
+            .map_err(|e| e.to_string())??;
+            build_streaming_source(
+                decoder,
+                duration_hint,
+                state.eq_gains.clone(),
+                state.eq_enabled.clone(),
+                state.eq_pre_gain.clone(),
+                state.playback_rate.clone(),
+                done_flag,
+                fade_in_dur,
+                state.samples_played.clone(),
+                target_rate,
+                Some(state.stream_playback_armed.clone()),
+            )
+        }
+    }?;
+    Ok(PlaybackSource { built, is_seekable })
+}

src-tauri/crates/psysonic-audio/src/stream/mod.rs

@@ -21,6 +21,23 @@ pub(crate) use mp4::{
     container_hint_is_mp4, isobmff_buffer_looks_complete, log_isobmff_buffer_diagnostic,
     mp4_needs_tail_prefetch, mp4_suspect_zero_holes,
 };
+
+/// True when the container hint denotes an Ogg-encapsulated stream (Vorbis,
+/// Opus, Speex, FLAC-in-Ogg).
+///
+/// symphonia 0.6's Ogg demuxer records the physical stream's byte range at
+/// construction time, but only when the source reports `is_seekable()` *during
+/// the probe*. If seekability is hidden then (see `ProbeSeekGate`),
+/// `phys_byte_range_end` stays `None` and the first real seek panics with
+/// `Option::unwrap()` on `None` (`demuxer.rs:180`). Sources that can cheaply
+/// seek to EOF must therefore stay seekable through the probe for Ogg.
+pub(crate) fn container_hint_is_ogg(hint: Option<&str>) -> bool {
+    let Some(h) = hint else { return false };
+    matches!(
+        h.to_ascii_lowercase().as_str(),
+        "ogg" | "oga" | "ogx" | "opus" | "spx"
+    )
+}
 pub(crate) use local_file::LocalFileSource;
 pub(crate) use radio::{RadioLiveState, RadioSharedFlags, radio_download_task};
 pub(crate) use ranged_http::{RangedHttpSource, ranged_download_task};

src-tauri/crates/psysonic-audio/src/stream_idle.rs

@@ -0,0 +1,306 @@
+//! Release the CPAL/rodio output stream after playback has been idle so the OS
+//! can sleep (issue #1071 — Windows `powercfg` "audio stream in use").
+
+use std::sync::atomic::Ordering;
+use std::time::{Duration, Instant};
+
+use tauri::{AppHandle, Emitter, Manager};
+
+use super::engine::AudioEngine;
+
+/// Wall-clock idle period before closing the output device handle.
+pub(crate) const OUTPUT_STREAM_IDLE_RELEASE_SECS: u64 = 60;
+
+const IDLE_POLL_SECS: u64 = 5;
+
+/// Returns true while the app must keep an open output stream (playing, preview, crossfade).
+pub(crate) fn output_stream_is_needed(engine: &AudioEngine) -> bool {
+    if engine.preview_sink.lock().unwrap().is_some() {
+        return true;
+    }
+    if engine.fading_out_sink.lock().unwrap().is_some() {
+        return true;
+    }
+
+    let cur = engine.current.lock().unwrap();
+    if let Some(sink) = &cur.sink {
+        if sink.empty() {
+            return false;
+        }
+        if cur.play_started.is_some() && cur.paused_at.is_none() {
+            return true;
+        }
+    }
+
+    if let Some(rs) = engine.radio_state.lock().unwrap().as_ref() {
+        if !rs.flags.is_paused.load(Ordering::Relaxed) {
+            return true;
+        }
+    }
+
+    false
+}
+
+/// Stop sinks tied to the open stream; keep pause position / URLs for cold resume.
+pub(crate) fn teardown_playback_sinks_for_idle_release(engine: &AudioEngine) {
+    if let Some(s) = engine.preview_sink.lock().unwrap().take() {
+        s.stop();
+    }
+    if let Some(s) = engine.fading_out_sink.lock().unwrap().take() {
+        s.stop();
+    }
+    let mut cur = engine.current.lock().unwrap();
+    if let Some(s) = cur.sink.take() {
+        s.stop();
+    }
+    cur.play_started = None;
+}
+
+fn close_output_device_handle(engine: &AudioEngine, app: &AppHandle) -> Result<(), String> {
+    super::engine::request_stream_release(engine)?;
+    *engine.stream_handle.lock().unwrap() = None;
+    let _ = app.emit("audio:output-released", ());
+    Ok(())
+}
+
+/// Release the output device after the idle timer (pause with no other active audio).
+pub(crate) fn release_output_stream(
+    engine: &AudioEngine,
+    app: &AppHandle,
+) -> Result<(), String> {
+    if engine.stream_handle.lock().unwrap().is_none() {
+        return Ok(());
+    }
+    teardown_playback_sinks_for_idle_release(engine);
+    close_output_device_handle(engine, app)?;
+    crate::app_eprintln!(
+        "[psysonic] audio output stream released after {}s idle",
+        OUTPUT_STREAM_IDLE_RELEASE_SECS
+    );
+    Ok(())
+}
+
+/// Release immediately on explicit stop / queue end — do not wait for the idle timer.
+pub(crate) fn release_output_stream_on_stop(
+    engine: &AudioEngine,
+    app: &AppHandle,
+) -> Result<(), String> {
+    if engine.stream_handle.lock().unwrap().is_none() {
+        return Ok(());
+    }
+    // `audio_stop` already tore down the main sink; clear any crossfade/preview tail
+    // still tied to the open device before closing the handle.
+    if engine.preview_sink.lock().unwrap().is_some()
+        || engine.fading_out_sink.lock().unwrap().is_some()
+    {
+        teardown_playback_sinks_for_idle_release(engine);
+    }
+    close_output_device_handle(engine, app)?;
+    crate::app_eprintln!("[psysonic] audio output stream released on stop");
+    Ok(())
+}
+
+/// Resolves the engine from `app` each poll (the engine is managed Tauri state),
+/// so it takes only the `AppHandle` — no engine reference is needed here.
+pub fn start_stream_idle_watcher(app: AppHandle) {
+    tauri::async_runtime::spawn(async move {
+        let mut idle_since: Option<Instant> = None;
+        loop {
+            tokio::time::sleep(Duration::from_secs(IDLE_POLL_SECS)).await;
+            let Some(state) = app.try_state::<AudioEngine>() else {
+                idle_since = None;
+                continue;
+            };
+            let engine = state.inner();
+            let stream_open = engine.stream_handle.lock().unwrap().is_some();
+            if !stream_open {
+                idle_since = None;
+                continue;
+            }
+            if output_stream_is_needed(engine) {
+                idle_since = None;
+                continue;
+            }
+            let since = *idle_since.get_or_insert_with(Instant::now);
+            if since.elapsed() < Duration::from_secs(OUTPUT_STREAM_IDLE_RELEASE_SECS) {
+                continue;
+            }
+            let _ = release_output_stream(engine, &app);
+            idle_since = None;
+        }
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64};
+    use std::sync::{Arc, Mutex, RwLock};
+
+    use ringbuf::HeapCons;
+    use rodio::source::Zero;
+    use rodio::{ChannelCount, Player, SampleRate};
+
+    use super::super::engine::AudioCurrent;
+    use super::super::playback_rate::PlaybackRateAtomics;
+    use super::super::stream::{RadioLiveState, RadioSharedFlags};
+
+    /// A device-less rodio `Player` with one infinite source appended, so
+    /// `empty()` reports `false` without ever opening an output device.
+    /// Returns the queue output too — keep it alive for the test's duration.
+    fn nonempty_player() -> (Arc<Player>, rodio::queue::SourcesQueueOutput) {
+        let (player, out) = Player::new();
+        player.append(Zero::new(
+            ChannelCount::new(2).unwrap(),
+            SampleRate::new(44_100).unwrap(),
+        ));
+        (Arc::new(player), out)
+    }
+
+    fn radio_session(is_paused: bool) -> RadioLiveState {
+        let (tx, _rx) = std::sync::mpsc::channel::<HeapCons<u8>>();
+        RadioLiveState {
+            url: "http://example.test/stream".to_string(),
+            gen: 0,
+            // Detached no-op task; never polled. Drop just aborts it.
+            task: tokio::spawn(async {}),
+            flags: Arc::new(RadioSharedFlags {
+                is_paused: AtomicBool::new(is_paused),
+                is_hard_paused: AtomicBool::new(false),
+                new_cons_tx: Mutex::new(tx),
+            }),
+        }
+    }
+
+    fn minimal_engine() -> AudioEngine {
+        let (stream_thread_tx, _) = std::sync::mpsc::sync_channel(0);
+        AudioEngine {
+            stream_handle: Arc::new(Mutex::new(None)),
+            stream_sample_rate: Arc::new(AtomicU32::new(0)),
+            device_default_rate: 48_000,
+            stream_thread_tx,
+            selected_device: Arc::new(Mutex::new(None)),
+            current: Arc::new(Mutex::new(AudioCurrent {
+                sink: None,
+                duration_secs: 0.0,
+                seek_offset: 0.0,
+                play_started: None,
+                paused_at: None,
+                replay_gain_linear: 1.0,
+                base_volume: 0.8,
+                fadeout_trigger: None,
+                fadeout_samples: None,
+            })),
+            generation: Arc::new(AtomicU64::new(0)),
+            http_client: Arc::new(RwLock::new(reqwest::Client::new())),
+            eq_gains: Arc::new(std::array::from_fn(|_| AtomicU32::new(0))),
+            eq_enabled: Arc::new(AtomicBool::new(false)),
+            eq_pre_gain: Arc::new(AtomicU32::new(0)),
+            playback_rate: PlaybackRateAtomics::new(),
+            preloaded: Arc::new(Mutex::new(None)),
+            stream_completed_cache: Arc::new(Mutex::new(None)),
+            stream_completed_spill: Arc::new(Mutex::new(None)),
+            current_is_seekable: Arc::new(AtomicBool::new(true)),
+            stream_playback_armed: Arc::new(AtomicBool::new(true)),
+            crossfade_enabled: Arc::new(AtomicBool::new(false)),
+            crossfade_secs: Arc::new(AtomicU32::new(0)),
+            fading_out_sink: Arc::new(Mutex::new(None)),
+            gapless_enabled: Arc::new(AtomicBool::new(false)),
+            normalization_engine: Arc::new(AtomicU32::new(0)),
+            normalization_target_lufs: Arc::new(AtomicU32::new(0)),
+            loudness_pre_analysis_attenuation_db: Arc::new(AtomicU32::new(0)),
+            chained_info: Arc::new(Mutex::new(None)),
+            samples_played: Arc::new(AtomicU64::new(0)),
+            current_sample_rate: Arc::new(AtomicU32::new(44_100)),
+            current_channels: Arc::new(AtomicU32::new(2)),
+            gapless_switch_at: Arc::new(AtomicU64::new(0)),
+            radio_state: Mutex::new(None),
+            current_playback_url: Arc::new(Mutex::new(None)),
+            current_analysis_track_id: Arc::new(Mutex::new(None)),
+            current_playback_server_id: Arc::new(Mutex::new(None)),
+            ranged_loudness_seed_hold: Arc::new(Mutex::new(None)),
+            preview_sink: Arc::new(Mutex::new(None)),
+            preview_gen: Arc::new(AtomicU64::new(0)),
+            preview_main_resume: Arc::new(AtomicBool::new(false)),
+            preview_song_id: Arc::new(Mutex::new(None)),
+        }
+    }
+
+    #[test]
+    fn idle_when_no_sink_and_no_preview() {
+        let engine = minimal_engine();
+        assert!(!output_stream_is_needed(&engine));
+    }
+
+    #[test]
+    fn idle_when_sink_empty() {
+        // A live but drained main sink (track finished) must not pin the device.
+        let (player, _out) = Player::new(); // no source appended → empty()
+        let player = Arc::new(player);
+        let engine = minimal_engine();
+        {
+            let mut cur = engine.current.lock().unwrap();
+            cur.sink = Some(player);
+            cur.play_started = Some(Instant::now());
+            cur.paused_at = None;
+        }
+        assert!(!output_stream_is_needed(&engine));
+    }
+
+    #[test]
+    fn needed_when_sink_playing() {
+        let (sink, _out) = nonempty_player();
+        let engine = minimal_engine();
+        {
+            let mut cur = engine.current.lock().unwrap();
+            cur.sink = Some(sink);
+            cur.play_started = Some(Instant::now());
+            cur.paused_at = None; // actively playing
+        }
+        assert!(output_stream_is_needed(&engine));
+    }
+
+    #[test]
+    fn idle_when_sink_paused() {
+        // Non-empty sink but paused (paused_at set) — the idle watcher may release.
+        let (sink, _out) = nonempty_player();
+        let engine = minimal_engine();
+        {
+            let mut cur = engine.current.lock().unwrap();
+            cur.sink = Some(sink);
+            cur.play_started = Some(Instant::now());
+            cur.paused_at = Some(12.0);
+        }
+        assert!(!output_stream_is_needed(&engine));
+    }
+
+    #[test]
+    fn needed_when_preview_sink_present() {
+        let (sink, _out) = nonempty_player();
+        let engine = minimal_engine();
+        *engine.preview_sink.lock().unwrap() = Some(sink);
+        assert!(output_stream_is_needed(&engine));
+    }
+
+    #[test]
+    fn needed_when_fading_out_sink_present() {
+        let (sink, _out) = nonempty_player();
+        let engine = minimal_engine();
+        *engine.fading_out_sink.lock().unwrap() = Some(sink);
+        assert!(output_stream_is_needed(&engine));
+    }
+
+    #[tokio::test]
+    async fn needed_when_radio_playing() {
+        let engine = minimal_engine();
+        *engine.radio_state.lock().unwrap() = Some(radio_session(false));
+        assert!(output_stream_is_needed(&engine));
+    }
+
+    #[tokio::test]
+    async fn idle_when_radio_paused() {
+        let engine = minimal_engine();
+        *engine.radio_state.lock().unwrap() = Some(radio_session(true));
+        assert!(!output_stream_is_needed(&engine));
+    }
+}

src-tauri/crates/psysonic-audio/src/transport_commands.rs

@@ -130,6 +130,8 @@ pub fn audio_stop(state: State<'_, AudioEngine>, app: AppHandle) {
     cur.seek_offset   = 0.0;
     cur.play_started  = None;
     cur.paused_at     = None;
+    drop(cur);
+    let _ = super::stream_idle::release_output_stream_on_stop(state.inner(), &app);
 }
 
 #[tauri::command]

src-tauri/crates/psysonic-core/Cargo.toml

@@ -3,6 +3,7 @@ name = "psysonic-core"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license.workspace = true
 publish = false
 
 [dependencies]

src-tauri/crates/psysonic-core/src/cover_cache_layout.rs

@@ -29,17 +29,38 @@ pub fn is_fetch_only_cover_id(id: &str) -> bool {
         || id.starts_with("ra-")
 }
 
+/// Windows reserved device names (case-insensitive) — invalid as path components.
+const WINDOWS_RESERVED_NAMES: &[&str] = &[
+    "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8",
+    "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
+];
+
 /// Sanitize a single path segment for Windows / Unix (Navidrome ids are usually already safe).
+/// Also used for media layout artist/album/title segments from server metadata.
 pub fn sanitize_path_segment(segment: &str) -> String {
     const FORBIDDEN: &[char] = &['\\', '/', ':', '*', '?', '"', '<', '>', '|'];
-    let trimmed = segment.trim();
+    let trimmed = segment.trim().trim_end_matches(['.', ' ']).to_string();
     if trimmed.is_empty() {
         return "_".to_string();
     }
-    trimmed
+    let cleaned: String = trimmed
         .chars()
-        .map(|c| if FORBIDDEN.contains(&c) { '_' } else { c })
-        .collect()
+        .map(|c| {
+            if c.is_control() || FORBIDDEN.contains(&c) {
+                '_'
+            } else {
+                c
+            }
+        })
+        .collect();
+    if cleaned.is_empty() || cleaned == "." || cleaned == ".." {
+        return "_".to_string();
+    }
+    let upper = cleaned.to_ascii_uppercase();
+    if WINDOWS_RESERVED_NAMES.contains(&upper.as_str()) {
+        return format!("_{cleaned}");
+    }
+    cleaned
 }
 
 /// Relative path under `{root}/{server_segment}/` — change format here only.
@@ -256,6 +277,13 @@ mod tests {
         base
     }
 
+    #[test]
+    fn sanitize_rejects_dot_dot_and_reserved_names() {
+        assert_eq!(sanitize_path_segment(".."), "_");
+        assert_eq!(sanitize_path_segment("CON"), "_CON");
+        assert_eq!(sanitize_path_segment(" trailing. "), "trailing");
+    }
+
     #[test]
     fn segment_disk_usage_counts_canonical_only() {
         let server = test_server_dir("usage");

src-tauri/crates/psysonic-core/src/lib.rs

@@ -5,6 +5,8 @@
 //! between `psysonic-audio`, `psysonic-analysis`, and other domain crates.
 
 pub mod cover_cache_layout;
+pub mod log_sanitize;
+pub mod media_layout;
 pub mod logging;
 pub mod ports;
 pub mod track_analysis;

src-tauri/crates/psysonic-core/src/log_sanitize.rs

@@ -0,0 +1,378 @@
+//! Redact secrets and partially mask remote server hostnames before log lines
+//! are stored or exported (PsyLab / Settings log export).
+
+const SENSITIVE_QUERY_KEYS: &[&str] = &[
+    "t", "s", "p", "token", "password", "passwd", "secret", "api_key", "apikey",
+    "access_token", "refresh_token", "auth",
+];
+
+const SENSITIVE_KV_KEYS: &[&str] = &[
+    "password", "passwd", "token", "secret", "api_key", "apikey", "access_token",
+    "refresh_token", "authorization", "auth",
+];
+
+/// Sanitize one runtime log line for display and export.
+pub fn sanitize_log_line(line: &str) -> String {
+    let mut out = redact_bearer_tokens(line);
+    out = redact_sensitive_key_values(&out);
+    out = redact_urls_in_text(&out);
+    out
+}
+
+/// Never panic on the logging hot path — fall back to the raw line if needed.
+pub fn sanitize_log_line_infallible(line: &str) -> String {
+    std::panic::catch_unwind(|| sanitize_log_line(line)).unwrap_or_else(|_| line.to_string())
+}
+
+fn redact_bearer_tokens(line: &str) -> String {
+    let marker = "Bearer ";
+    let mut s = line.to_string();
+    let mut search_from = 0;
+    while let Some(rel) = s[search_from..].find(marker) {
+        let idx = search_from + rel;
+        let start = idx + marker.len();
+        let end = s[start..]
+            .find(|c: char| c.is_whitespace() || c == '"' || c == '\'' || c == ')' || c == ']')
+            .map(|i| start + i)
+            .unwrap_or(s.len());
+        if end > start {
+            s.replace_range(start..end, "REDACTED");
+        }
+        search_from = start + "REDACTED".len();
+    }
+    s
+}
+
+fn redact_sensitive_key_values(line: &str) -> String {
+    let mut out = line.to_string();
+    for key in SENSITIVE_KV_KEYS {
+        for sep in [':', '='] {
+            let needle = format!("{key}{sep}");
+            let lower = out.to_ascii_lowercase();
+            let mut search_from = 0;
+            while let Some(rel) = lower[search_from..].find(&needle) {
+                let idx = search_from + rel;
+                let val_start = idx + needle.len();
+                let slice = &out[val_start..];
+                let trimmed = slice.trim_start();
+                let ws = slice.len().saturating_sub(trimmed.len());
+                let val_start = val_start + ws;
+                let end = trimmed
+                    .find(|c: char| c.is_whitespace() || c == '&' || c == ',' || c == ';' || c == ')')
+                    .unwrap_or(trimmed.len());
+                if end > 0 {
+                    out.replace_range(val_start..val_start + end, "REDACTED");
+                }
+                search_from = val_start + "REDACTED".len();
+                if search_from >= out.len() {
+                    break;
+                }
+            }
+        }
+    }
+    out
+}
+
+fn url_char_ends_url(ch: char, s: &str, byte_off: usize) -> bool {
+    if ch.is_whitespace() || ch == '"' || ch == '\'' || ch == '>' {
+        return true;
+    }
+    if ch == ')' || ch == ']' || ch == ',' {
+        if let Some(next) = s[byte_off..].chars().nth(1) {
+            return next.is_whitespace() || next == '"' || next == '\'';
+        }
+    }
+    false
+}
+
+fn redact_urls_in_text(line: &str) -> String {
+    let mut out = String::with_capacity(line.len());
+    let mut cursor = 0;
+    while cursor < line.len() {
+        let slice = &line[cursor..];
+        let rel = match (slice.find("http://"), slice.find("https://")) {
+            (Some(h), Some(s)) => Some(h.min(s)),
+            (Some(h), None) => Some(h),
+            (None, Some(s)) => Some(s),
+            (None, None) => None,
+        };
+        let Some(rel) = rel else {
+            out.push_str(slice);
+            break;
+        };
+        out.push_str(&slice[..rel]);
+        let url_start = cursor + rel;
+        let url_slice = &line[url_start..];
+        let scheme_len = if url_slice.starts_with("https://") { 8 } else { 7 };
+        let mut url_end = scheme_len;
+        for (off, ch) in url_slice[scheme_len..].char_indices() {
+            let abs = scheme_len + off;
+            if url_char_ends_url(ch, url_slice, abs) {
+                break;
+            }
+            url_end = abs + ch.len_utf8();
+        }
+        out.push_str(&redact_url(&line[url_start..url_start + url_end]));
+        cursor = url_start + url_end;
+    }
+    out
+}
+
+fn redact_url(raw: &str) -> String {
+    let (url, suffix) = split_trailing_punct(raw);
+    let mut out = String::new();
+
+    let scheme_end = url.find("://").map(|i| i + 3).unwrap_or(0);
+    out.push_str(&url[..scheme_end]);
+
+    let mut rest = &url[scheme_end..];
+    if let Some(at) = rest.rfind('@') {
+        // Drop userinfo entirely.
+        out.push_str("***@");
+        rest = &rest[at + 1..];
+    }
+
+    let (hostport, path) = split_host_path(rest);
+    let (host, port) = split_host_port(&hostport);
+    let masked_host = mask_hostname(&host);
+    out.push_str(&masked_host);
+    if let Some(p) = port {
+        out.push(':');
+        out.push_str(&p);
+    }
+    if let Some((path_only, query)) = path.split_once('?') {
+        out.push_str(path_only);
+        out.push('?');
+        out.push_str(&redact_query_string(query));
+    } else {
+        out.push_str(&path);
+    }
+
+    format!("{out}{suffix}")
+}
+
+fn split_trailing_punct(raw: &str) -> (&str, &str) {
+    let mut end = raw.len();
+    while end > 0 {
+        let ch = raw.as_bytes()[end - 1] as char;
+        if ch == ')' || ch == ']' || ch == ',' {
+            end -= 1;
+            continue;
+        }
+        break;
+    }
+    (&raw[..end], &raw[end..])
+}
+
+fn split_host_path(rest: &str) -> (String, String) {
+    if rest.starts_with('[') {
+        if let Some(end) = rest.find(']') {
+            let hostport = &rest[..=end];
+            return (hostport.to_string(), rest[end + 1..].to_string());
+        }
+    }
+    if let Some(slash) = rest.find('/') {
+        (rest[..slash].to_string(), rest[slash..].to_string())
+    } else {
+        (rest.to_string(), String::new())
+    }
+}
+
+fn split_host_port(hostport: &str) -> (String, Option<String>) {
+    if hostport.starts_with('[') {
+        if let Some(end) = hostport.find("]:") {
+            return (
+                hostport[..=end].to_string(),
+                Some(hostport[end + 2..].to_string()),
+            );
+        }
+        return (hostport.to_string(), None);
+    }
+    if let Some((h, p)) = hostport.rsplit_once(':') {
+        if !h.is_empty() && p.chars().all(|c| c.is_ascii_digit()) && !h.contains(':') {
+            return (h.to_string(), Some(p.to_string()));
+        }
+    }
+    (hostport.to_string(), None)
+}
+
+fn redact_query_string(query: &str) -> String {
+    query
+        .split('&')
+        .map(|pair| {
+            let (k, _v) = pair.split_once('=').unwrap_or((pair, ""));
+            if is_sensitive_query_key(k) {
+                format!("{k}=REDACTED")
+            } else {
+                pair.to_string()
+            }
+        })
+        .collect::<Vec<_>>()
+        .join("&")
+}
+
+fn is_sensitive_query_key(key: &str) -> bool {
+    let k = key.trim().to_ascii_lowercase();
+    SENSITIVE_QUERY_KEYS.iter().any(|needle| *needle == k)
+}
+
+fn is_lan_ipv4(ip: &str) -> bool {
+    let parts: Vec<&str> = ip.split('.').collect();
+    if parts.len() != 4 {
+        return false;
+    }
+    let Ok(a) = parts[0].parse::<u8>() else { return false };
+    let Ok(b) = parts[1].parse::<u8>() else { return false };
+    a == 127
+        || a == 10
+        || (a == 172 && (16..=31).contains(&b))
+        || (a == 192 && b == 168)
+}
+
+fn is_lan_ipv6(host: &str) -> bool {
+    let h = host.to_ascii_lowercase();
+    if h == "::1" {
+        return true;
+    }
+    if h.starts_with("fe8") || h.starts_with("fe9") || h.starts_with("fea") || h.starts_with("feb") {
+        return true;
+    }
+    if h.starts_with("fc") || h.starts_with("fd") {
+        return true;
+    }
+    if let Some(rest) = h.strip_prefix("::ffff:") {
+        if rest.contains('.') {
+            return is_lan_ipv4(rest);
+        }
+        if let Some((a, b)) = rest.split_once(':') {
+            if let (Ok(v1), Ok(v2)) = (u16::from_str_radix(a, 16), u16::from_str_radix(b, 16)) {
+                let ip = format!(
+                    "{}.{}.{}.{}",
+                    (v1 >> 8) & 0xff,
+                    v1 & 0xff,
+                    (v2 >> 8) & 0xff,
+                    v2 & 0xff
+                );
+                return is_lan_ipv4(&ip);
+            }
+        }
+    }
+    false
+}
+
+fn is_lan_host(host: &str) -> bool {
+    let stripped = host.trim().trim_matches(|c| c == '[' || c == ']');
+    let lower = stripped.to_ascii_lowercase();
+    if lower.is_empty() || lower == "localhost" || lower.ends_with(".local") {
+        return true;
+    }
+    if stripped.contains(':') {
+        return is_lan_ipv6(stripped);
+    }
+    if stripped.chars().all(|c| c.is_ascii_digit() || c == '.') && stripped.matches('.').count() == 3 {
+        return is_lan_ipv4(stripped);
+    }
+    false
+}
+
+fn mask_label_prefix(label: &str) -> String {
+    let mut chars = label.chars();
+    let c1 = chars.next();
+    let c2 = chars.next();
+    match (c1, c2) {
+        (None, _) => "*".to_string(),
+        (Some(a), None) => a.to_string(),
+        (Some(a), Some(b)) => {
+            let rest = label.chars().count().saturating_sub(2);
+            let stars = rest.clamp(1, 4);
+            format!("{a}{b}{}", "*".repeat(stars))
+        }
+    }
+}
+
+fn mask_public_ipv4(ip: &str) -> String {
+    let parts: Vec<&str> = ip.split('.').collect();
+    if parts.len() != 4 {
+        return "***".to_string();
+    }
+    format!("{}.*.*.{}", parts[0], parts[3])
+}
+
+fn mask_hostname(host: &str) -> String {
+    let stripped = host.trim().trim_matches(|c| c == '[' || c == ']');
+    if is_lan_host(stripped) {
+        return host.to_string();
+    }
+
+    if stripped.chars().all(|c| c.is_ascii_digit() || c == '.') && stripped.matches('.').count() == 3 {
+        return mask_public_ipv4(stripped);
+    }
+
+    if stripped.contains(':') {
+        return "[ipv6-redacted]".to_string();
+    }
+
+    let parts: Vec<&str> = stripped.split('.').collect();
+    if parts.is_empty() {
+        return "***".to_string();
+    }
+
+    let masked_first = mask_label_prefix(parts[0]);
+
+    if parts.len() == 1 {
+        masked_first
+    } else {
+        format!("{}.{}", masked_first, parts[1..].join("."))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn redacts_subsonic_wire_auth_params() {
+        let line = "GET https://music.example.com/rest/stream.view?id=1&t=abc&s=def&p=ghi";
+        let out = sanitize_log_line(line);
+        assert!(out.contains("t=REDACTED"));
+        assert!(out.contains("s=REDACTED"));
+        assert!(out.contains("p=REDACTED"));
+        assert!(!out.contains("abc"));
+    }
+
+    #[test]
+    fn masks_remote_hostname_keeps_lan_ip() {
+        let remote = sanitize_log_line("connect https://my-server.example.com:4533/rest/ping");
+        assert!(remote.contains("my****.example.com"));
+        assert!(!remote.contains("my-server.example.com"));
+
+        let lan = sanitize_log_line("connect http://192.168.1.42:4533/rest/ping");
+        assert!(lan.contains("192.168.1.42"));
+    }
+
+    #[test]
+    fn redacts_bearer_and_password_kv() {
+        let line = "auth header Bearer eyJhbGciOiJIUzI1NiJ9.xyz password=sekrit";
+        let out = sanitize_log_line(line);
+        assert!(out.contains("Bearer REDACTED"));
+        assert!(!out.contains("eyJhbGci"));
+        assert!(out.contains("password=REDACTED"));
+        assert!(!out.contains("sekrit"));
+    }
+
+    #[test]
+    fn strips_url_userinfo() {
+        let line = "fetch https://user:pass@10.0.0.5:4533/rest/ping";
+        let out = sanitize_log_line(line);
+        assert!(out.contains("***@10.0.0.5"));
+        assert!(!out.contains("user:pass"));
+    }
+
+    #[test]
+    fn stream_log_with_em_dash_does_not_panic() {
+        let line = "[stream] RangedHttpSource selected — total=15666KB, hint=Some(\"mp3\")";
+        let out = sanitize_log_line(line);
+        assert!(out.contains('—'));
+        assert!(out.contains("RangedHttpSource"));
+    }
+}

src-tauri/crates/psysonic-core/src/logging.rs

@@ -101,6 +101,7 @@ pub fn should_log_debug() -> bool {
 }
 
 pub fn append_log_line(line: String) {
+    let line = crate::log_sanitize::sanitize_log_line_infallible(&line);
     let seq = LOG_SEQ.fetch_add(1, Ordering::Relaxed) + 1;
     {
         let mut buf = log_buffer().lock().unwrap();

src-tauri/crates/psysonic-core/src/media_layout.rs

@@ -0,0 +1,364 @@
+//! Local playback disk layout — artist/album/track paths from library-index fields.
+//!
+//! Mirrors the contract in `implementation-spec.md` (local playback unification).
+//! `server_segment` uses [`cover_cache_layout::sanitize_path_segment`] on the URL
+//! index key; artist/album/filename segments are derived from track metadata only.
+
+use std::path::{Component, Path, PathBuf};
+
+use crate::cover_cache_layout::sanitize_path_segment;
+
+/// Max length for a single path component after sanitization (Windows budget).
+pub const MAX_SEGMENT_LEN: usize = 120;
+
+/// Inputs required to build hierarchical media paths (library index row projection).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TrackPathInput {
+    pub artist: Option<String>,
+    pub album_artist: Option<String>,
+    pub album: String,
+    pub title: String,
+    pub track_number: Option<i64>,
+    pub disc_number: Option<i64>,
+    pub suffix: Option<String>,
+    /// When set, used to detect compilation albums from `raw_json` (OpenSubsonic).
+    pub raw_json: Option<String>,
+}
+
+/// Tier subdirectory under the media root (`cache/`, `library/`, or `favorites/`).
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LocalTier {
+    Ephemeral,
+    Library,
+    /// Auto-synced starred favorites — separate from user-pinned `library/`.
+    Favorites,
+}
+
+impl LocalTier {
+    pub fn subdir(self) -> &'static str {
+        match self {
+            Self::Ephemeral => "cache",
+            Self::Library => "library",
+            Self::Favorites => "favorites",
+        }
+    }
+
+    pub fn parse(s: &str) -> Option<Self> {
+        match s.trim().to_ascii_lowercase().as_str() {
+            "ephemeral" | "cache" => Some(Self::Ephemeral),
+            "library" => Some(Self::Library),
+            "favorites" | "favorite-auto" | "favorite_auto" => Some(Self::Favorites),
+            _ => None,
+        }
+    }
+}
+
+/// Stable fingerprint for invalidation when library metadata changes (§8 spec).
+pub fn layout_fingerprint(input: &TrackPathInput) -> String {
+    let artist_seg = artist_folder_segment(input);
+    let album_seg = album_folder_segment(&input.album);
+    let stem = track_filename_stem(input);
+    let suffix = input
+        .suffix
+        .as_deref()
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .unwrap_or("");
+    let track_n = input.track_number.unwrap_or(0);
+    let disc_n = input.disc_number.unwrap_or(0);
+    format!(
+        "artist={artist_seg}|album_artist={}|album={album_seg}|title={}|track={track_n}|disc={disc_n}|stem={stem}|suffix={suffix}",
+        input
+            .album_artist
+            .as_deref()
+            .map(str::trim)
+            .unwrap_or(""),
+        input.title.trim(),
+    )
+}
+
+/// Relative path under `{tier}/{server_segment}/`: `{artist}/{album}/{file}.{suffix}`.
+pub fn relative_path_for_track(
+    server_index_key: &str,
+    input: &TrackPathInput,
+    suffix: &str,
+) -> PathBuf {
+    let server_segment = sanitize_path_segment(server_index_key);
+    let artist = artist_folder_segment(input);
+    let album = album_folder_segment(&input.album);
+    let stem = track_filename_stem(input);
+    let ext = suffix.trim().trim_start_matches('.');
+    let filename = if ext.is_empty() {
+        sanitize_and_truncate_segment(&stem, MAX_SEGMENT_LEN)
+    } else {
+        format!(
+            "{}.{}",
+            sanitize_and_truncate_segment(&stem, MAX_SEGMENT_LEN),
+            sanitize_path_segment(ext)
+        )
+    };
+    PathBuf::from(server_segment)
+        .join(artist)
+        .join(album)
+        .join(filename)
+}
+
+/// Absolute file path: `{media_root}/{tier}/…relative_path…`.
+pub fn absolute_track_path(
+    media_root: &Path,
+    tier: LocalTier,
+    server_index_key: &str,
+    input: &TrackPathInput,
+    suffix: &str,
+) -> PathBuf {
+    media_root
+        .join(tier.subdir())
+        .join(relative_path_for_track(server_index_key, input, suffix))
+}
+
+/// Defense-in-depth: resolved paths must stay under `{media_root}/{tier}/`.
+pub fn ensure_track_path_within_tier(
+    media_root: &Path,
+    tier: LocalTier,
+    absolute: &Path,
+) -> Result<(), String> {
+    let tier_root = media_root.join(tier.subdir());
+    let Ok(rel) = absolute.strip_prefix(&tier_root) else {
+        return Err(format!(
+            "path `{}` escapes tier root `{}`",
+            absolute.display(),
+            tier_root.display()
+        ));
+    };
+    for comp in rel.components() {
+        if matches!(comp, Component::ParentDir | Component::RootDir | Component::Prefix(_)) {
+            return Err(format!(
+                "path `{}` contains forbidden component `{comp:?}`",
+                absolute.display()
+            ));
+        }
+    }
+    Ok(())
+}
+
+fn artist_folder_segment(input: &TrackPathInput) -> String {
+    let artist = input.artist.as_deref().map(str::trim).unwrap_or("");
+    let album_artist = input.album_artist.as_deref().map(str::trim).unwrap_or("");
+    let chosen = if artist.is_empty() || track_is_compilation(input) {
+        if !album_artist.is_empty() {
+            album_artist
+        } else {
+            "Various Artists"
+        }
+    } else {
+        artist
+    };
+    sanitize_and_truncate_segment(chosen, MAX_SEGMENT_LEN)
+}
+
+fn album_folder_segment(album: &str) -> String {
+    let trimmed = album.trim();
+    let fallback = if trimmed.is_empty() { "Unknown Album" } else { trimmed };
+    sanitize_and_truncate_segment(fallback, MAX_SEGMENT_LEN)
+}
+
+fn track_filename_stem(input: &TrackPathInput) -> String {
+    let title = input.title.trim();
+    let title = if title.is_empty() { "Unknown Title" } else { title };
+    let track_n = input.track_number.unwrap_or(0).max(0) as u32;
+    let disc_n = input.disc_number.unwrap_or(1).max(0) as u32;
+    if disc_n > 1 {
+        format!("{disc_n:02}-{track_n:02} - {title}")
+    } else {
+        format!("{track_n:02} - {title}")
+    }
+}
+
+fn track_is_compilation(input: &TrackPathInput) -> bool {
+    if various_artists_label(input.artist.as_deref().unwrap_or("")) {
+        return true;
+    }
+    let Some(raw) = input.raw_json.as_deref().filter(|s| !s.is_empty()) else {
+        return false;
+    };
+    raw_json_marks_compilation(raw)
+}
+
+/// Best-effort probe aligned with `album_compilation_filter::compilation_raw_json_sql`.
+fn raw_json_marks_compilation(raw: &str) -> bool {
+    let lower = raw.to_ascii_lowercase();
+    lower.contains("\"iscompilation\":true")
+        || lower.contains("\"iscompilation\": true")
+        || lower.contains("\"compilation\":true")
+        || lower.contains("\"compilation\": true")
+        || lower.contains("\"compilation\":1")
+        || lower.contains("\"releaseTypes\"") && lower.contains("compilation")
+}
+
+fn various_artists_label(s: &str) -> bool {
+    let lower = s.trim().to_ascii_lowercase();
+    lower.contains("various artists")
+}
+
+fn sanitize_and_truncate_segment(segment: &str, max_len: usize) -> String {
+    let sanitized = sanitize_path_segment(segment);
+    // Code points — keep in sync with `[...sanitized].length` in `mediaLayout.ts`.
+    if sanitized.chars().count() <= max_len {
+        return sanitized;
+    }
+    let hash = short_hash(segment);
+    let keep = max_len.saturating_sub(1 + hash.len());
+    let mut out = sanitized.chars().take(keep).collect::<String>();
+    out.push('_');
+    out.push_str(&hash);
+    out
+}
+
+/// Keep in sync with `shortHash` in `src/utils/media/mediaLayout.ts` (UTF-16 code units).
+fn short_hash(s: &str) -> String {
+    let mut h: u32 = 0;
+    for unit in s.encode_utf16() {
+        h = h.wrapping_mul(31).wrapping_add(unit as u32);
+    }
+    format!("{:08x}", h)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn sample_input() -> TrackPathInput {
+        TrackPathInput {
+            artist: Some("Radiohead".to_string()),
+            album_artist: None,
+            album: "OK Computer".to_string(),
+            title: "Paranoid Android".to_string(),
+            track_number: Some(6),
+            disc_number: Some(1),
+            suffix: Some("mp3".to_string()),
+            raw_json: None,
+        }
+    }
+
+    #[test]
+    fn relative_path_uses_library_segments() {
+        let rel = relative_path_for_track("host:4533", &sample_input(), "mp3");
+        assert_eq!(
+            rel,
+            PathBuf::from("host_4533")
+                .join("Radiohead")
+                .join("OK Computer")
+                .join("06 - Paranoid Android.mp3")
+        );
+    }
+
+    #[test]
+    fn multi_disc_adds_disc_prefix() {
+        let mut input = sample_input();
+        input.disc_number = Some(2);
+        let rel = relative_path_for_track("srv", &input, "flac");
+        assert!(rel
+            .file_name()
+            .and_then(|n| n.to_str())
+            .is_some_and(|n| n.starts_with("02-06 - Paranoid Android.flac")));
+    }
+
+    #[test]
+    fn compilation_uses_album_artist_folder() {
+        let input = TrackPathInput {
+            artist: Some("Various Artists".to_string()),
+            album_artist: Some("Original Soundtrack".to_string()),
+            album: "Film Score".to_string(),
+            title: "Main Theme".to_string(),
+            track_number: Some(1),
+            disc_number: Some(1),
+            suffix: Some("mp3".to_string()),
+            raw_json: None,
+        };
+        let rel = relative_path_for_track("srv", &input, "mp3");
+        assert_eq!(rel.components().nth(1).and_then(|c| c.as_os_str().to_str()), Some("Original Soundtrack"));
+    }
+
+    #[test]
+    fn empty_artist_falls_back_to_various_artists() {
+        let input = TrackPathInput {
+            artist: None,
+            album_artist: None,
+            album: "Comp".to_string(),
+            title: "Song".to_string(),
+            track_number: Some(1),
+            disc_number: Some(1),
+            suffix: Some("mp3".to_string()),
+            raw_json: None,
+        };
+        let rel = relative_path_for_track("srv", &input, "mp3");
+        assert_eq!(rel.components().nth(1).and_then(|c| c.as_os_str().to_str()), Some("Various Artists"));
+    }
+
+    #[test]
+    fn layout_fingerprint_is_stable() {
+        let a = layout_fingerprint(&sample_input());
+        let b = layout_fingerprint(&sample_input());
+        assert_eq!(a, b);
+        assert!(a.contains("Radiohead"));
+        assert!(a.contains("OK Computer"));
+    }
+
+    #[test]
+    fn tier_subdirs_are_fixed() {
+        assert_eq!(LocalTier::Ephemeral.subdir(), "cache");
+        assert_eq!(LocalTier::Library.subdir(), "library");
+        assert_eq!(LocalTier::Favorites.subdir(), "favorites");
+        assert_eq!(LocalTier::parse("ephemeral"), Some(LocalTier::Ephemeral));
+        assert_eq!(LocalTier::parse("library"), Some(LocalTier::Library));
+        assert_eq!(LocalTier::parse("favorite-auto"), Some(LocalTier::Favorites));
+    }
+
+    #[test]
+    fn absolute_path_includes_tier() {
+        let root = Path::new("/media");
+        let path = absolute_track_path(root, LocalTier::Library, "srv", &sample_input(), "mp3");
+        assert!(path.starts_with(root.join("library")));
+    }
+
+    #[test]
+    fn dot_dot_metadata_does_not_escape_tier_root() {
+        let input = TrackPathInput {
+            artist: Some("..".to_string()),
+            album_artist: None,
+            album: "..".to_string(),
+            title: "Song".to_string(),
+            track_number: Some(1),
+            disc_number: Some(1),
+            suffix: Some("mp3".to_string()),
+            raw_json: None,
+        };
+        let root = Path::new("/media");
+        let path = absolute_track_path(root, LocalTier::Library, "srv", &input, "mp3");
+        assert!(path.starts_with(root.join("library")));
+        ensure_track_path_within_tier(root, LocalTier::Library, &path).unwrap();
+    }
+
+    #[test]
+    fn short_hash_matches_ts_imul31_utf16() {
+        // "Radiohead" — same as mediaLayout.test parity anchor.
+        assert_eq!(short_hash("Radiohead"), "3da68c3b");
+    }
+
+    #[test]
+    fn sanitize_and_truncate_uses_code_point_threshold() {
+        let cyrillic_a = '\u{0430}';
+        let hundred: String = std::iter::repeat_n(cyrillic_a, 100).collect();
+        assert!(hundred.len() > MAX_SEGMENT_LEN);
+        assert_eq!(hundred.chars().count(), 100);
+        assert_eq!(
+            sanitize_and_truncate_segment(&hundred, MAX_SEGMENT_LEN),
+            hundred
+        );
+
+        let long: String = std::iter::repeat_n(cyrillic_a, 130).collect();
+        let truncated = sanitize_and_truncate_segment(&long, MAX_SEGMENT_LEN);
+        assert!(truncated.ends_with("_eef20600"));
+        assert_eq!(truncated.chars().count(), MAX_SEGMENT_LEN);
+    }
+}

src-tauri/crates/psysonic-integration/Cargo.toml

@@ -3,6 +3,7 @@ name = "psysonic-integration"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license.workspace = true
 publish = false
 
 [dependencies]

src-tauri/crates/psysonic-integration/src/remote.rs

@@ -287,11 +287,31 @@ pub async fn resolve_stream_url(url: String) -> String {
     resolve_playlist_url(&client, &url).await.unwrap_or(url)
 }
 
-/// Proxy Last.fm API calls through Rust/reqwest to avoid WebView networking restrictions.
-/// `params` is a list of [key, value] pairs (method must be included).
-/// If `sign` is true an api_sig is computed. If `get` is true, a GET request is made.
+/// Default Audioscrobbler v2 endpoint (Last.fm). Other presets (Libre.fm,
+/// Rocksky, GNU FM, Maloja compat) pass their own `base_url`.
+const LASTFM_API_BASE: &str = "https://ws.audioscrobbler.com/2.0/";
+
+/// Generic Audioscrobbler v2 transport. Provider-agnostic: the caller supplies
+/// the endpoint `base_url`, so Last.fm, Libre.fm, Rocksky, custom GNU FM and the
+/// Shared HTTP client for the Music Network provider transports
+/// (audioscrobbler / listenbrainz / maloja). A bounded timeout keeps a hung
+/// provider from leaving scrobble/probe/loved-sync promises unresolved — the
+/// sibling `fetch_*` commands in this module set the same kind of bound.
+fn provider_http_client() -> Result<reqwest::Client, String> {
+    reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(15))
+        .build()
+        .map_err(|e| e.to_string())
+}
+
+/// Maloja Audioscrobbler-compat surface all share this one command.
+///
+/// `params` is a list of [key, value] pairs (method must be included). If `sign`
+/// is true an `api_sig` is computed (MD5 of sorted params + secret). If `get` is
+/// true a GET request is made, otherwise a form POST.
 #[tauri::command]
-pub async fn lastfm_request(
+pub async fn audioscrobbler_request(
+    base_url: String,
     params: Vec<[String; 2]>,
     sign: bool,
     get: bool,
@@ -300,6 +320,8 @@ pub async fn lastfm_request(
 ) -> Result<serde_json::Value, String> {
     use std::collections::HashMap;
 
+    let base = if base_url.trim().is_empty() { LASTFM_API_BASE.to_string() } else { base_url };
+
     let mut map: HashMap<String, String> = params.into_iter().map(|[k, v]| (k, v)).collect();
     map.insert("api_key".into(), api_key.clone());
 
@@ -317,17 +339,17 @@ pub async fn lastfm_request(
 
     map.insert("format".into(), "json".into());
 
-    let client = reqwest::Client::new();
+    let client = provider_http_client()?;
     let resp = if get {
         client
-            .get("https://ws.audioscrobbler.com/2.0/")
+            .get(&base)
             .query(&map)
             .header("User-Agent", subsonic_wire_user_agent())
             .send()
             .await
     } else {
         client
-            .post("https://ws.audioscrobbler.com/2.0/")
+            .post(&base)
             .form(&map)
             .header("User-Agent", subsonic_wire_user_agent())
             .send()
@@ -337,7 +359,88 @@ pub async fn lastfm_request(
     let json: serde_json::Value = resp.json().await.map_err(|e| e.to_string())?;
 
     if let Some(err) = json.get("error") {
-        return Err(format!("Last.fm {} {}", err, json.get("message").and_then(|m| m.as_str()).unwrap_or("")));
+        return Err(format!("Audioscrobbler {} {}", err, json.get("message").and_then(|m| m.as_str()).unwrap_or("")));
+    }
+
+    Ok(json)
+}
+
+/// Generic ListenBrainz transport. Used by both the direct
+/// `api.listenbrainz.org` preset and the Maloja `/apis/listenbrainz` compat
+/// surface — they differ only by `base_url`. Auth is a `Token` header.
+///
+/// `path` is appended to `base_url` (e.g. `/1/submit-listens`). When `json_body`
+/// is present the request is a POST with that body; otherwise a GET.
+#[tauri::command]
+pub async fn listenbrainz_request(
+    base_url: String,
+    path: String,
+    auth_token: String,
+    json_body: Option<serde_json::Value>,
+) -> Result<serde_json::Value, String> {
+    let url = format!("{}{}", base_url.trim_end_matches('/'), path);
+    let client = provider_http_client()?;
+
+    let mut req = if json_body.is_some() {
+        client.post(&url)
+    } else {
+        client.get(&url)
+    };
+    req = req
+        .header("Authorization", format!("Token {}", auth_token))
+        .header("User-Agent", subsonic_wire_user_agent());
+    if let Some(body) = json_body {
+        req = req.json(&body);
+    }
+
+    let resp = req.send().await.map_err(|e| e.to_string())?;
+    let status = resp.status();
+    let json: serde_json::Value = resp.json().await.map_err(|e| e.to_string())?;
+
+    if !status.is_success() {
+        let msg = json.get("error").and_then(|m| m.as_str()).unwrap_or("");
+        return Err(format!("ListenBrainz {} {}", status.as_u16(), msg));
+    }
+
+    Ok(json)
+}
+
+/// Generic Maloja native (`/apis/mlj_1`) transport. Protocol-agnostic JSON:
+/// the caller builds the body (including the Maloja key) and chooses the path.
+///
+/// `path` is appended to `base_url`. When `json_body` is present the request is a
+/// POST with that body; otherwise a GET with `query` pairs.
+#[tauri::command]
+pub async fn maloja_request(
+    base_url: String,
+    path: String,
+    query: Vec<[String; 2]>,
+    json_body: Option<serde_json::Value>,
+) -> Result<serde_json::Value, String> {
+    let url = format!("{}{}", base_url.trim_end_matches('/'), path);
+    let client = provider_http_client()?;
+
+    let resp = if let Some(body) = json_body {
+        client.post(&url).json(&body)
+    } else {
+        let q: Vec<(String, String)> = query.into_iter().map(|[k, v]| (k, v)).collect();
+        client.get(&url).query(&q)
+    }
+    .header("User-Agent", subsonic_wire_user_agent())
+    .send()
+    .await
+    .map_err(|e| e.to_string())?;
+
+    let status = resp.status();
+    let json: serde_json::Value = resp.json().await.map_err(|e| e.to_string())?;
+
+    if !status.is_success() {
+        let msg = json
+            .get("error")
+            .and_then(|e| e.get("desc").or_else(|| e.get("type")))
+            .and_then(|m| m.as_str())
+            .unwrap_or("");
+        return Err(format!("Maloja {} {}", status.as_u16(), msg));
     }
 
     Ok(json)
@@ -495,4 +598,66 @@ mod tests {
             Some("https://pls.example/audio".to_string())
         );
     }
+
+    // ── audioscrobbler_request ────────────────────────────────────────────────
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn audioscrobbler_request_uses_custom_base_url() {
+        let server = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/2.0/"))
+            .respond_with(ResponseTemplate::new(200).set_body_raw(
+                r#"{"similarartists":{"artist":[{"name":"Boards of Canada"}]}}"#,
+                "application/json",
+            ))
+            .mount(&server)
+            .await;
+
+        let base = format!("{}/2.0/", server.uri());
+        let json = audioscrobbler_request(
+            base,
+            vec![
+                ["method".into(), "artist.getSimilar".into()],
+                ["artist".into(), "Aphex Twin".into()],
+            ],
+            false,
+            true,
+            "key".into(),
+            "secret".into(),
+        )
+        .await
+        .expect("request should succeed");
+
+        assert_eq!(
+            json["similarartists"]["artist"][0]["name"].as_str(),
+            Some("Boards of Canada")
+        );
+    }
+
+    #[tokio::test(flavor = "multi_thread")]
+    async fn audioscrobbler_request_surfaces_api_error() {
+        let server = MockServer::start().await;
+        Mock::given(method("POST"))
+            .and(wm_path("/2.0/"))
+            .respond_with(ResponseTemplate::new(200).set_body_raw(
+                r#"{"error":9,"message":"Invalid session key"}"#,
+                "application/json",
+            ))
+            .mount(&server)
+            .await;
+
+        let base = format!("{}/2.0/", server.uri());
+        let err = audioscrobbler_request(
+            base,
+            vec![["method".into(), "track.scrobble".into()]],
+            true,
+            false,
+            "key".into(),
+            "secret".into(),
+        )
+        .await
+        .expect_err("api error should map to Err");
+
+        assert!(err.contains("Audioscrobbler 9"), "unexpected error: {err}");
+    }
 }

src-tauri/crates/psysonic-library/Cargo.toml

@@ -3,6 +3,7 @@ name = "psysonic-library"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license.workspace = true
 publish = false
 
 [dependencies]
@@ -15,8 +16,6 @@ serde_json = "1"
 rusqlite = { version = "0.40", features = ["bundled"] }
 reqwest = { version = "0.13", default-features = false, features = ["json", "rustls", "gzip", "brotli"] }
 tokio = { version = "1", features = ["rt", "rt-multi-thread", "sync", "macros", "time"] }
-twox-hash = "2"
-unicode-normalization = "0.1"
 
 [dev-dependencies]
 tokio = { version = "1", features = ["rt", "macros", "rt-multi-thread", "test-util"] }

src-tauri/crates/psysonic-library/migrations/001_initial.sql

@@ -248,6 +248,23 @@ CREATE TABLE play_session (
   CHECK (completion IN ('partial', 'full'))
 );
 
+CREATE TABLE track_genre (
+  server_id  TEXT NOT NULL,
+  track_id   TEXT NOT NULL,
+  genre      TEXT NOT NULL,
+  album_id   TEXT,
+  library_id TEXT,
+  PRIMARY KEY (server_id, track_id, genre COLLATE NOCASE),
+  FOREIGN KEY (server_id, track_id) REFERENCES track(server_id, id) ON DELETE CASCADE
+);
+
+CREATE TABLE library_data_migration (
+  id            TEXT PRIMARY KEY,
+  cursor_rowid  INTEGER NOT NULL DEFAULT 0,
+  completed_at  INTEGER,
+  started_at    INTEGER
+);
+
 CREATE INDEX idx_track_album   ON track(server_id, album_id)               WHERE deleted = 0;
 CREATE INDEX idx_track_artist  ON track(server_id, artist_id)              WHERE deleted = 0;
 CREATE INDEX idx_track_updated ON track(server_id, server_updated_at DESC) WHERE deleted = 0;
@@ -293,3 +310,7 @@ CREATE INDEX idx_play_session_started
 CREATE INDEX idx_track_fact_mood_tag
   ON track_fact(server_id, fact_kind, value_text, track_id)
   WHERE fact_kind = 'mood_tag';
+
+CREATE INDEX idx_track_genre_browse
+  ON track_genre(server_id, genre COLLATE NOCASE, album_id, track_id)
+  WHERE album_id IS NOT NULL AND album_id != '';

src-tauri/crates/psysonic-library/migrations/002_album_browse_index.sql

@@ -1,10 +0,0 @@
--- Plain All Albums browse: read from `album` with ORDER BY name (not track GROUP BY).
-CREATE INDEX IF NOT EXISTS idx_album_server_name_browse
-  ON album(server_id, name COLLATE NOCASE);
-
--- Scoped album EXISTS probes: (server, album, library) on live tracks.
-CREATE INDEX IF NOT EXISTS idx_track_server_album_library_browse
-  ON track(server_id, album_id, library_id)
-  WHERE deleted = 0
-    AND album_id IS NOT NULL
-    AND album_id != '';

src-tauri/crates/psysonic-library/migrations/002_n1_bulk_unreliable.sql

@@ -1,6 +0,0 @@
--- psysonic-library schema v2 — large-library ingest policy (R7-15).
--- Per-server learned flag: when N1 (`/api/song`) returns HTTP 500 beyond a
--- deep offset on a large catalog, the strategy selector stops choosing N1 for
--- that server on future initial syncs (spec §6.3 / R7-15 Q1/Q5). Additive
--- column, DEFAULT 0 → existing rows keep N1 eligible until they hit the wall.
-ALTER TABLE sync_state ADD COLUMN n1_bulk_unreliable INTEGER NOT NULL DEFAULT 0;

src-tauri/crates/psysonic-library/migrations/003_track_remap_indexes.sql

@@ -1,10 +0,0 @@
--- Remap detection (§6.9) and unstable-id servers: without these indexes
--- each upsert in a 500-row batch can scan the whole track table.
-
-CREATE INDEX IF NOT EXISTS idx_track_remap_path
-  ON track(server_id, server_path)
-  WHERE deleted = 0 AND server_path IS NOT NULL AND server_path != '';
-
-CREATE INDEX IF NOT EXISTS idx_track_remap_hash
-  ON track(server_id, content_hash)
-  WHERE deleted = 0 AND content_hash IS NOT NULL AND content_hash != '';

src-tauri/crates/psysonic-library/migrations/004_track_title_index.sql

@@ -1,4 +0,0 @@
--- Browse / sort-by-title without sorting the full server slice on every page.
-CREATE INDEX IF NOT EXISTS idx_track_title
-  ON track(server_id, title COLLATE NOCASE)
-  WHERE deleted = 0;

src-tauri/crates/psysonic-library/migrations/005_track_genre_year_indexes.sql

@@ -1,8 +0,0 @@
--- Advanced search filters on genre and year (partial indexes — only non-null rows).
-CREATE INDEX IF NOT EXISTS idx_track_genre
-  ON track(server_id, genre COLLATE NOCASE)
-  WHERE deleted = 0 AND genre IS NOT NULL;
-
-CREATE INDEX IF NOT EXISTS idx_track_year
-  ON track(server_id, year)
-  WHERE deleted = 0 AND year IS NOT NULL;

src-tauri/crates/psysonic-library/migrations/006_play_session.sql

@@ -1,22 +0,0 @@
--- Player listening history — see workdocs player-stats spec §3.1
-CREATE TABLE play_session (
-  id               INTEGER PRIMARY KEY AUTOINCREMENT,
-  server_id        TEXT NOT NULL,
-  track_id         TEXT NOT NULL,
-  started_at_ms    INTEGER NOT NULL,
-  listened_sec     REAL NOT NULL,
-  position_max_sec REAL NOT NULL,
-  completion       TEXT NOT NULL,
-  end_reason       TEXT NOT NULL,
-  FOREIGN KEY (server_id, track_id) REFERENCES track(server_id, id),
-  CHECK (completion IN ('partial', 'full'))
-);
-
-CREATE INDEX idx_play_session_server_time
-  ON play_session(server_id, started_at_ms DESC);
-
-CREATE INDEX idx_play_session_track
-  ON play_session(server_id, track_id, started_at_ms DESC);
-
-CREATE INDEX idx_play_session_started
-  ON play_session(started_at_ms DESC);

src-tauri/crates/psysonic-library/migrations/007_resync_gen.sql

@@ -1,4 +0,0 @@
--- Full-resync orphan sweep (mark-and-sweep via generation stamp).
--- Rows ingested during a resync pass carry the active `resync_gen`; after
--- IS-6 succeeds, live rows with a stale generation are soft-deleted.
-ALTER TABLE track ADD COLUMN resync_gen INTEGER NOT NULL DEFAULT 0;

src-tauri/crates/psysonic-library/migrations/008_mood_tag_index.sql

@@ -1,4 +0,0 @@
--- Atomic mood tags for Advanced Search (EXISTS on track_fact).
-CREATE INDEX IF NOT EXISTS idx_track_fact_mood_tag
-  ON track_fact(server_id, fact_kind, value_text, track_id)
-  WHERE fact_kind = 'mood_tag';

src-tauri/crates/psysonic-library/migrations/009_purge_mood_facts.sql

@@ -1,3 +0,0 @@
--- Oximedia mood heuristics were misleading; drop accumulated mood facts.
-DELETE FROM track_fact
- WHERE fact_kind IN ('mood_tag', 'moods', 'valence', 'arousal', 'mood_labels');

src-tauri/crates/psysonic-library/migrations/010_genre_album_browse_index.sql

@@ -1,8 +0,0 @@
--- Genre album browse: filter by (server, genre) then group by album_id.
-CREATE INDEX IF NOT EXISTS idx_track_genre_album_browse
-  ON track(server_id, genre COLLATE NOCASE, album_id)
-  WHERE deleted = 0
-    AND genre IS NOT NULL
-    AND TRIM(genre) != ''
-    AND album_id IS NOT NULL
-    AND album_id != '';

src-tauri/crates/psysonic-library/migrations/011_genre_album_name_browse_index.sql

@@ -1,8 +0,0 @@
--- Genre album browse sort: (server, genre, album name, album_id) covering walk.
-CREATE INDEX IF NOT EXISTS idx_track_genre_album_name_browse
-  ON track(server_id, genre COLLATE NOCASE, album COLLATE NOCASE, album_id)
-  WHERE deleted = 0
-    AND genre IS NOT NULL
-    AND TRIM(genre) != ''
-    AND album_id IS NOT NULL
-    AND album_id != '';

src-tauri/crates/psysonic-library/migrations/012_track_genre_legacy_repair.sql

@@ -0,0 +1,22 @@
+-- Repair for DBs that recorded legacy migrations 002–011 (removed) before
+-- multi-genre tables shipped. Safe on fresh installs (IF NOT EXISTS).
+CREATE TABLE IF NOT EXISTS track_genre (
+  server_id  TEXT NOT NULL,
+  track_id   TEXT NOT NULL,
+  genre      TEXT NOT NULL,
+  album_id   TEXT,
+  library_id TEXT,
+  PRIMARY KEY (server_id, track_id, genre COLLATE NOCASE),
+  FOREIGN KEY (server_id, track_id) REFERENCES track(server_id, id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_track_genre_browse
+  ON track_genre(server_id, genre COLLATE NOCASE, album_id, track_id)
+  WHERE album_id IS NOT NULL AND album_id != '';
+
+CREATE TABLE IF NOT EXISTS library_data_migration (
+  id            TEXT PRIMARY KEY,
+  cursor_rowid  INTEGER NOT NULL DEFAULT 0,
+  completed_at  INTEGER,
+  started_at    INTEGER
+);

src-tauri/crates/psysonic-library/src/album_browse.rs

@@ -1,499 +0,0 @@
-//! Paginated All Albums browse from the local index (plain, no filters).
-//!
-//! Prefers the synced `album` table (≈5k rows) with LIMIT/OFFSET. Falls back to
-//! track `GROUP BY` only when the album catalog is not populated (N1 ingest).
-
-use crate::dto::{
-    LibraryAlbumBrowseRequest, LibraryAlbumBrowseResponse, LibraryAlbumDto, LibrarySortClause,
-    SortDir,
-};
-use crate::search::library_scope_filter_sql;
-use crate::store::LibraryStore;
-use rusqlite::types::Value as SqlValue;
-use serde_json::Value;
-
-fn trimmed_nonempty(s: Option<&str>) -> Option<String> {
-    s.map(str::trim)
-        .filter(|s| !s.is_empty())
-        .map(String::from)
-}
-
-fn effective_scope_ids(req: &LibraryAlbumBrowseRequest) -> Vec<String> {
-    if let Some(ids) = &req.library_scope_ids {
-        let trimmed: Vec<_> = ids
-            .iter()
-            .filter(|s| !s.trim().is_empty())
-            .cloned()
-            .collect();
-        if !trimmed.is_empty() {
-            return trimmed;
-        }
-    }
-    trimmed_nonempty(req.library_scope.as_deref())
-        .map(|s| vec![s])
-        .unwrap_or_default()
-}
-
-fn album_table_order_sql(sort: &[LibrarySortClause]) -> String {
-    let mut keys: Vec<String> = Vec::new();
-    for s in sort {
-        let col = match s.field.as_str() {
-            "name" => "a.name COLLATE NOCASE",
-            "artist" => "a.artist COLLATE NOCASE",
-            "year" => "a.year",
-            _ => continue,
-        };
-        let dir = match s.dir {
-            SortDir::Asc => "ASC",
-            SortDir::Desc => "DESC",
-        };
-        keys.push(format!("{col} {dir}"));
-    }
-    if keys.is_empty() {
-        keys.push("a.name COLLATE NOCASE ASC".to_string());
-    }
-    keys.push("a.id ASC".to_string());
-    format!("ORDER BY {}", keys.join(", "))
-}
-
-fn track_group_order_sql(sort: &[LibrarySortClause]) -> String {
-    let mut keys: Vec<String> = Vec::new();
-    for s in sort {
-        let col = match s.field.as_str() {
-            "name" => "COALESCE(a.name, la.album_name) COLLATE NOCASE",
-            "artist" => "COALESCE(a.artist, la.artist) COLLATE NOCASE",
-            "year" => "COALESCE(a.year, la.year)",
-            _ => continue,
-        };
-        let dir = match s.dir {
-            SortDir::Asc => "ASC",
-            SortDir::Desc => "DESC",
-        };
-        keys.push(format!("{col} {dir}"));
-    }
-    if keys.is_empty() {
-        keys.push("COALESCE(a.name, la.album_name) COLLATE NOCASE ASC".to_string());
-    }
-    keys.push("la.album_id ASC".to_string());
-    format!("ORDER BY {}", keys.join(", "))
-}
-
-fn push_album_id_allowlist(
-    where_clauses: &mut Vec<String>,
-    params: &mut Vec<SqlValue>,
-    column: &str,
-    ids: Option<&[String]>,
-) {
-    let Some(ids) = ids else {
-        return;
-    };
-    if ids.is_empty() {
-        where_clauses.push("1 = 0".to_string());
-        return;
-    }
-    let placeholders = (0..ids.len()).map(|_| "?").collect::<Vec<_>>().join(", ");
-    where_clauses.push(format!("{column} IN ({placeholders})"));
-    for id in ids {
-        params.push(SqlValue::Text(id.clone()));
-    }
-}
-
-/// `album` rows have no `library_id`; scope is enforced via matching tracks.
-fn push_album_table_library_scope(
-    where_clauses: &mut Vec<String>,
-    params: &mut Vec<SqlValue>,
-    scope_ids: &[String],
-) {
-    if scope_ids.is_empty() {
-        return;
-    }
-    let (clause, scope_params) = library_scope_filter_sql("t_scope", scope_ids);
-    let Some(scope_clause) = clause else {
-        return;
-    };
-    where_clauses.push(format!(
-        "EXISTS (SELECT 1 FROM track t_scope \
-         WHERE t_scope.server_id = a.server_id \
-           AND t_scope.album_id = a.id \
-           AND t_scope.deleted = 0 \
-           AND {scope_clause})"
-    ));
-    params.extend(scope_params);
-}
-
-fn map_row(r: &rusqlite::Row<'_>) -> rusqlite::Result<LibraryAlbumDto> {
-    let raw: Option<String> = r.get(12)?;
-    Ok(LibraryAlbumDto {
-        server_id: r.get(0)?,
-        id: r.get(1)?,
-        name: r.get(2)?,
-        artist: r.get(3)?,
-        artist_id: r.get(4)?,
-        song_count: r.get(5)?,
-        duration_sec: r.get(6)?,
-        year: r.get(7)?,
-        genre: r.get(8)?,
-        cover_art_id: r.get(9)?,
-        starred_at: r.get(10)?,
-        synced_at: r.get(11)?,
-        raw_json: raw
-            .as_deref()
-            .and_then(|s| serde_json::from_str(s).ok())
-            .unwrap_or(Value::Null),
-    })
-}
-
-pub(crate) fn album_table_usable(store: &LibraryStore, server_id: &str) -> Result<bool, String> {
-    store
-        .with_read_conn(|c| {
-            c.query_row(
-                "SELECT EXISTS(
-                   SELECT 1 FROM album
-                   WHERE server_id = ?1 AND song_count IS NOT NULL
-                   LIMIT 1
-                 )",
-                rusqlite::params![server_id],
-                |r| r.get(0),
-            )
-        })
-        .map_err(|e| e.to_string())
-}
-
-fn list_albums_from_table(
-    store: &LibraryStore,
-    req: &LibraryAlbumBrowseRequest,
-) -> Result<LibraryAlbumBrowseResponse, String> {
-    let limit = req.limit.max(1);
-    let offset = req.offset;
-    let order_sql = album_table_order_sql(&req.sort);
-
-    let mut where_clauses = vec!["a.server_id = ?1".to_string()];
-    let mut params: Vec<SqlValue> = vec![SqlValue::Text(req.server_id.clone())];
-
-    let scope_ids = effective_scope_ids(req);
-    push_album_table_library_scope(&mut where_clauses, &mut params, &scope_ids);
-    push_album_id_allowlist(
-        &mut where_clauses,
-        &mut params,
-        "a.id",
-        req.restrict_album_ids.as_deref(),
-    );
-
-    let where_sql = where_clauses.join(" AND ");
-    let sql = format!(
-        "SELECT \
-           a.server_id, \
-           a.id, \
-           a.name, \
-           a.artist, \
-           a.artist_id, \
-           a.song_count, \
-           a.duration_sec, \
-           a.year, \
-           a.genre, \
-           a.cover_art_id, \
-           a.starred_at, \
-           a.synced_at, \
-           a.raw_json \
-         FROM album a \
-         WHERE {where_sql} \
-         {order_sql} \
-         LIMIT ? OFFSET ?"
-    );
-
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let albums: Vec<LibraryAlbumDto> = store
-        .with_read_conn(|conn| {
-            let mut stmt = conn.prepare(&sql)?;
-            let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), map_row)?;
-            rows.collect::<rusqlite::Result<Vec<_>>>()
-        })
-        .map_err(|e| e.to_string())?;
-
-    let has_more = albums.len() as u32 == limit;
-    Ok(LibraryAlbumBrowseResponse {
-        albums,
-        has_more,
-        source: "local".to_string(),
-    })
-}
-
-fn list_albums_from_tracks(
-    store: &LibraryStore,
-    req: &LibraryAlbumBrowseRequest,
-) -> Result<LibraryAlbumBrowseResponse, String> {
-    let limit = req.limit.max(1);
-    let offset = req.offset;
-    let order_sql = track_group_order_sql(&req.sort);
-
-    let mut where_clauses = vec![
-        "t.deleted = 0".to_string(),
-        "t.server_id = ?1".to_string(),
-        "t.album_id IS NOT NULL AND t.album_id != ''".to_string(),
-    ];
-    let mut params: Vec<SqlValue> = vec![SqlValue::Text(req.server_id.clone())];
-
-    let scope_ids = effective_scope_ids(req);
-    if let (Some(clause), scope_params) = library_scope_filter_sql("t", &scope_ids) {
-        where_clauses.push(clause);
-        params.extend(scope_params);
-    }
-    push_album_id_allowlist(
-        &mut where_clauses,
-        &mut params,
-        "t.album_id",
-        req.restrict_album_ids.as_deref(),
-    );
-
-    let where_sql = where_clauses.join(" AND ");
-    let sql = format!(
-        "SELECT \
-           la.server_id, \
-           la.album_id, \
-           COALESCE(a.name, la.album_name), \
-           COALESCE(a.artist, la.artist), \
-           COALESCE(a.artist_id, la.artist_id), \
-           COALESCE(a.song_count, la.track_count), \
-           COALESCE(a.duration_sec, la.duration_sec), \
-           COALESCE(a.year, la.year), \
-           COALESCE(a.genre, la.genre), \
-           COALESCE(a.cover_art_id, la.cover_art_id), \
-           COALESCE(a.starred_at, la.starred_at), \
-           COALESCE(a.synced_at, la.synced_at), \
-           a.raw_json \
-         FROM ( \
-           SELECT \
-             t.server_id, \
-             t.album_id, \
-             MAX(t.album) AS album_name, \
-             MAX(t.artist) AS artist, \
-             MAX(t.artist_id) AS artist_id, \
-             MAX(t.year) AS year, \
-             MAX(t.genre) AS genre, \
-             MAX(t.cover_art_id) AS cover_art_id, \
-             MAX(t.starred_at) AS starred_at, \
-             MAX(t.synced_at) AS synced_at, \
-             COUNT(*) AS track_count, \
-             COALESCE(SUM(t.duration_sec), 0) AS duration_sec \
-           FROM track t \
-           WHERE {where_sql} \
-           GROUP BY t.server_id, t.album_id \
-         ) la \
-         LEFT JOIN album a ON a.server_id = la.server_id AND a.id = la.album_id \
-         {order_sql} \
-         LIMIT ? OFFSET ?"
-    );
-
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let albums: Vec<LibraryAlbumDto> = store
-        .with_read_conn(|conn| {
-            let mut stmt = conn.prepare(&sql)?;
-            let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), map_row)?;
-            rows.collect::<rusqlite::Result<Vec<_>>>()
-        })
-        .map_err(|e| e.to_string())?;
-
-    let has_more = albums.len() as u32 == limit;
-    Ok(LibraryAlbumBrowseResponse {
-        albums,
-        has_more,
-        source: "local".to_string(),
-    })
-}
-
-fn browse_is_scoped(req: &LibraryAlbumBrowseRequest) -> bool {
-    !effective_scope_ids(req).is_empty()
-        || req
-            .restrict_album_ids
-            .as_ref()
-            .is_some_and(|ids| !ids.is_empty())
-}
-
-pub fn list_albums(
-    store: &LibraryStore,
-    req: &LibraryAlbumBrowseRequest,
-) -> Result<LibraryAlbumBrowseResponse, String> {
-    let scope_ids = effective_scope_ids(req);
-    // Unscoped, or a single library: `album` table + EXISTS (fast on ~5k rows).
-    // Multi-library union: filter tracks by `library_id IN (...)` then GROUP BY.
-    if album_table_usable(store, &req.server_id)?
-        && (!browse_is_scoped(req) || scope_ids.len() == 1)
-    {
-        return list_albums_from_table(store, req);
-    }
-    if !crate::dto::track_index_nonempty(store, &req.server_id)? {
-        return Ok(LibraryAlbumBrowseResponse {
-            albums: Vec::new(),
-            has_more: false,
-            source: "local".to_string(),
-        });
-    }
-    list_albums_from_tracks(store, req)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::repos::{TrackRepository, TrackRow};
-
-    fn track(server: &str, id: &str, album_id: &str, album: &str, library_id: Option<&str>) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: format!("{album} track"),
-            title_sort: None,
-            artist: Some("Band".into()),
-            artist_id: Some("art-1".into()),
-            album: album.into(),
-            album_id: Some(album_id.into()),
-            album_artist: Some("Band".into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: Some(2020),
-            genre: None,
-            suffix: Some("mp3".into()),
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: library_id.map(String::from),
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    fn req(server: &str, limit: u32, offset: u32) -> LibraryAlbumBrowseRequest {
-        LibraryAlbumBrowseRequest {
-            server_id: server.into(),
-            library_scope: None,
-            library_scope_ids: None,
-            sort: Vec::new(),
-            restrict_album_ids: None,
-            limit,
-            offset,
-        }
-    }
-
-    fn seed_album(
-        store: &LibraryStore,
-        server_id: &str,
-        id: &str,
-        name: &str,
-        song_count: i64,
-    ) {
-        store
-            .with_conn("misc", |c| {
-                c.execute(
-                    "INSERT INTO album (server_id, id, name, artist, song_count, duration_sec, synced_at, raw_json) \
-                     VALUES (?1, ?2, ?3, 'Band', ?4, 400, 1, '{}')",
-                    rusqlite::params![server_id, id, name, song_count],
-                )
-            })
-            .unwrap();
-    }
-
-    #[test]
-    fn lists_albums_grouped_from_tracks() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "al-1", "Alpha", None),
-                track("s1", "t2", "al-2", "Beta", None),
-            ])
-            .unwrap();
-
-        let resp = list_albums(&store, &req("s1", 50, 0)).unwrap();
-        assert_eq!(resp.albums.len(), 2);
-        assert!(!resp.has_more);
-    }
-
-    #[test]
-    fn prefers_album_table_when_synced_catalog_exists() {
-        let store = LibraryStore::open_in_memory();
-        seed_album(&store, "s1", "al-1", "Alpha", 10);
-        seed_album(&store, "s1", "al-2", "Beta", 8);
-
-        let resp = list_albums(&store, &req("s1", 50, 0)).unwrap();
-        assert_eq!(resp.albums.len(), 2);
-        assert_eq!(resp.albums[0].name, "Alpha");
-        assert_eq!(resp.albums[1].name, "Beta");
-    }
-
-    #[test]
-    fn library_scope_narrows_results() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "al-1", "In", Some("lib-a")),
-                track("s1", "t2", "al-2", "Out", Some("lib-b")),
-            ])
-            .unwrap();
-        seed_album(&store, "s1", "al-1", "In", 1);
-        seed_album(&store, "s1", "al-2", "Out", 1);
-
-        let mut scoped = req("s1", 50, 0);
-        scoped.library_scope_ids = Some(vec!["lib-a".into()]);
-        let resp = list_albums(&store, &scoped).unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].id, "al-1");
-    }
-
-    #[test]
-    fn multi_library_scope_unions_albums() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "al-1", "Alpha", Some("lib-a")),
-                track("s1", "t2", "al-2", "Beta", Some("lib-b")),
-                track("s1", "t3", "al-3", "Gamma", Some("lib-c")),
-            ])
-            .unwrap();
-        seed_album(&store, "s1", "al-1", "Alpha", 1);
-        seed_album(&store, "s1", "al-2", "Beta", 1);
-        seed_album(&store, "s1", "al-3", "Gamma", 1);
-
-        let mut scoped = req("s1", 50, 0);
-        scoped.library_scope_ids = Some(vec!["lib-a".into(), "lib-b".into()]);
-        let resp = list_albums(&store, &scoped).unwrap();
-        assert_eq!(resp.albums.len(), 2);
-        assert_eq!(resp.albums[0].id, "al-1");
-        assert_eq!(resp.albums[1].id, "al-2");
-    }
-
-    #[test]
-    fn multi_library_scope_includes_track_only_albums() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "al-1", "Alpha", Some("lib-a")),
-                track("s1", "t2", "al-2", "Zulu", Some("lib-b")),
-            ])
-            .unwrap();
-        seed_album(&store, "s1", "al-1", "Alpha", 1);
-
-        let mut scoped = req("s1", 50, 0);
-        scoped.library_scope_ids = Some(vec!["lib-a".into(), "lib-b".into()]);
-        let resp = list_albums(&store, &scoped).unwrap();
-        assert_eq!(resp.albums.len(), 2);
-        assert_eq!(resp.albums[0].id, "al-1");
-        assert_eq!(resp.albums[1].id, "al-2");
-    }
-}

src-tauri/crates/psysonic-library/src/album_compilation_filter.rs

@@ -1,5 +1,6 @@
 //! OpenSubsonic compilation flag in entity `raw_json` (Navidrome: `compilation`,
-//! `isCompilation`, or `releaseTypes` containing `Compilation`).
+//! `isCompilation`, or `releaseTypes` containing `Compilation`), plus the same
+//! "Various Artists" heuristics the web UI uses when structured flags are absent.
 
 /// SQL predicate on any row with a `raw_json` column (album or track).
 pub fn compilation_raw_json_sql(table_alias: &str) -> String {
@@ -17,6 +18,63 @@ pub fn compilation_raw_json_sql(table_alias: &str) -> String {
     )
 }
 
+fn various_artists_like_sql(column: &str) -> String {
+    format!(
+        "lower(trim(coalesce({column}, ''))) LIKE '%various artists%'",
+        column = column
+    )
+}
+
+/// Full compilation predicate for browse filters — JSON flags plus VA artist labels.
+pub fn compilation_predicate_sql(
+    table_alias: &str,
+    artist_column: Option<&str>,
+    album_artist_column: Option<&str>,
+) -> String {
+    let mut parts = vec![compilation_raw_json_sql(table_alias)];
+    parts.push(format!(
+        "lower(trim(coalesce(json_extract({a}.raw_json, '$.displayArtist'), ''))) LIKE '%various artists%'",
+        a = table_alias
+    ));
+    if let Some(col) = artist_column {
+        parts.push(various_artists_like_sql(col));
+    }
+    if let Some(col) = album_artist_column {
+        parts.push(various_artists_like_sql(col));
+    }
+    format!("({})", parts.join(" OR "))
+}
+
+pub fn various_artists_label(s: &str) -> bool {
+    s.trim().to_ascii_lowercase().contains("various artists")
+}
+
+/// SQL mirror of [`pick_album_group_artist`] for track-grouped browse subqueries
+/// (`la`). Used where `ORDER BY` / `COALESCE(a.artist, …)` must stay in SQL;
+/// keep both implementations in sync.
+pub fn sql_track_group_display_artist(alias: &str) -> String {
+    format!(
+        "CASE WHEN trim(coalesce({a}.album_artist, '')) != '' \
+         THEN trim({a}.album_artist) \
+         ELSE NULLIF(trim(coalesce({a}.artist, '')), '') END",
+        a = alias
+    )
+}
+
+/// Row-mapper form of the album-artist display rule — mirror of
+/// [`sql_track_group_display_artist`]. Prefer a non-empty album-artist tag;
+/// fall back to track artist only when album artist is absent (solo albums without TALB).
+pub fn pick_album_group_artist(
+    track_artist: Option<String>,
+    album_artist: Option<String>,
+) -> Option<String> {
+    let aa = album_artist.as_deref().unwrap_or("").trim();
+    if !aa.is_empty() {
+        return Some(aa.to_string());
+    }
+    track_artist.filter(|s| !s.trim().is_empty())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -27,4 +85,80 @@ mod tests {
         assert!(sql.contains("$.compilation"));
         assert!(sql.contains("$.releaseTypes"));
     }
+
+    #[test]
+    fn predicate_includes_artist_columns() {
+        let sql = compilation_predicate_sql("t", Some("t.artist"), Some("t.album_artist"));
+        assert!(sql.contains("t.artist"));
+        assert!(sql.contains("t.album_artist"));
+        assert!(sql.contains("$.displayArtist"));
+    }
+
+    #[test]
+    fn pick_album_group_artist_prefers_nonempty_album_artist() {
+        assert_eq!(
+            pick_album_group_artist(Some("Alice".into()), Some("Various Artists".into())),
+            Some("Various Artists".to_string())
+        );
+        assert_eq!(
+            pick_album_group_artist(Some("Groove Armada".into()), Some("Underworld".into())),
+            Some("Underworld".to_string())
+        );
+        assert_eq!(
+            pick_album_group_artist(Some("Alice".into()), Some("Bob".into())),
+            Some("Bob".to_string())
+        );
+    }
+
+    #[test]
+    fn pick_album_group_artist_falls_back_to_track_artist() {
+        assert_eq!(
+            pick_album_group_artist(Some("Alice".into()), None),
+            Some("Alice".to_string())
+        );
+        assert_eq!(
+            pick_album_group_artist(Some("Alice".into()), Some("".into())),
+            Some("Alice".to_string())
+        );
+        assert_eq!(pick_album_group_artist(None, None), None);
+    }
+
+    #[test]
+    fn sql_track_group_display_artist_matches_pick_album_group_artist() {
+        let conn = rusqlite::Connection::open_in_memory().unwrap();
+        conn.execute(
+            "CREATE TABLE la (artist TEXT, album_artist TEXT)",
+            [],
+        )
+        .unwrap();
+        let sql = format!("SELECT {} FROM la", sql_track_group_display_artist("la"));
+
+        let cases: [(&str, &str); 7] = [
+            ("Groove Armada", "Underworld"),
+            ("Alice", ""),
+            ("", "Various Artists"),
+            ("Alice", "Bob"),
+            ("  ", "Bob"),
+            ("Alice", "   "),
+            ("", ""),
+        ];
+
+        for (track, album) in cases {
+            conn.execute("DELETE FROM la", []).unwrap();
+            conn.execute(
+                "INSERT INTO la (artist, album_artist) VALUES (?1, ?2)",
+                rusqlite::params![track, album],
+            )
+            .unwrap();
+            let sql_out: Option<String> = conn.query_row(&sql, [], |r| r.get(0)).ok();
+            let rust_out = pick_album_group_artist(
+                (!track.is_empty()).then(|| track.to_string()),
+                (!album.is_empty()).then(|| album.to_string()),
+            );
+            assert_eq!(
+                sql_out, rust_out,
+                "track={track:?} album={album:?}"
+            );
+        }
+    }
 }

src-tauri/crates/psysonic-library/src/artist_lossless_browse.rs

@@ -81,12 +81,13 @@ pub fn get_artist_lossless_browse(
     }
     let album_where_sql = album_where.join(" AND ");
 
+    let la_artist = crate::album_compilation_filter::sql_track_group_display_artist("la");
     let albums_sql = format!(
         "SELECT \
            la.server_id, \
            la.album_id, \
            COALESCE(a.name, la.album_name), \
-           COALESCE(a.artist, la.artist), \
+           COALESCE(a.artist, {la_artist}), \
            COALESCE(a.artist_id, la.artist_id), \
            COALESCE(a.song_count, la.track_count), \
            COALESCE(a.duration_sec, la.duration_sec), \
@@ -102,6 +103,7 @@ pub fn get_artist_lossless_browse(
              t.album_id, \
              MAX(t.album) AS album_name, \
              MAX(t.artist) AS artist, \
+             MAX(t.album_artist) AS album_artist, \
              MAX(t.artist_id) AS artist_id, \
              MAX(t.year) AS year, \
              MAX(t.genre) AS genre, \

src-tauri/crates/psysonic-library/src/browse_support.rs

@@ -6,7 +6,7 @@ use tauri::State;
 use crate::dto::CatalogYearBoundsDto;
 use crate::dto::GenreAlbumCountDto;
 use crate::runtime::LibraryRuntime;
-use crate::search::library_scope_filter_sql;
+use crate::search::library_scope_equals_sql;
 use crate::store::LibraryStore;
 
 #[derive(Debug, Clone, serde::Deserialize)]
@@ -34,7 +34,7 @@ pub(crate) fn reconcile_album_stars(
 ) -> Result<(), String> {
     runtime
         .store
-        .with_conn("misc", |conn| {
+        .with_conn("browse.reconcile_album_stars", |conn| {
             if starred.is_empty() {
                 conn.execute(
                     "UPDATE album SET starred_at = NULL \
@@ -106,52 +106,42 @@ pub fn library_get_catalog_year_bounds(
     catalog_year_bounds_for_server(&runtime.store, &server_id)
 }
 
-fn effective_genre_count_scope_ids(
-    library_scope: Option<&str>,
-    library_scope_ids: Option<&[String]>,
-) -> Vec<String> {
-    if let Some(ids) = library_scope_ids {
-        let trimmed: Vec<_> = ids
-            .iter()
-            .filter(|s| !s.trim().is_empty())
-            .cloned()
-            .collect();
-        if !trimmed.is_empty() {
-            return trimmed;
-        }
-    }
-    library_scope
-        .map(str::trim)
-        .filter(|s| !s.is_empty())
-        .map(|s| vec![s.to_string()])
-        .unwrap_or_default()
-}
-
 pub(crate) fn genre_album_counts_for_server(
     store: &LibraryStore,
     server_id: &str,
     library_scope: Option<&str>,
-    library_scope_ids: Option<&[String]>,
 ) -> Result<Vec<GenreAlbumCountDto>, String> {
-    let scope_ids = effective_genre_count_scope_ids(library_scope, library_scope_ids);
     store
         .with_read_conn(|conn| {
-            let mut sql = String::from(
-                "SELECT t.genre, COUNT(DISTINCT t.album_id) AS album_count, COUNT(*) AS song_count \
-                 FROM track t \
-                 WHERE t.server_id = ?1 AND t.deleted = 0 \
-                   AND t.genre IS NOT NULL AND TRIM(t.genre) != '' \
-                   AND t.album_id IS NOT NULL AND t.album_id != ''",
-            );
+            let scoped = library_scope.is_some_and(|s| !s.trim().is_empty());
+            let mut sql = if scoped {
+                String::from(
+                    "SELECT tg.genre, COUNT(DISTINCT tg.album_id) AS album_count, \
+                            COUNT(DISTINCT tg.track_id) AS song_count \
+                     FROM track_genre tg \
+                     INNER JOIN track t \
+                       ON t.server_id = tg.server_id AND t.id = tg.track_id AND t.deleted = 0 \
+                     WHERE tg.server_id = ?1 \
+                       AND tg.album_id IS NOT NULL AND tg.album_id != ''",
+                )
+            } else {
+                String::from(
+                    "SELECT tg.genre, COUNT(DISTINCT tg.album_id) AS album_count, \
+                            COUNT(DISTINCT tg.track_id) AS song_count \
+                     FROM track_genre tg \
+                     WHERE tg.server_id = ?1 \
+                       AND tg.album_id IS NOT NULL AND tg.album_id != ''",
+                )
+            };
             let mut params: Vec<rusqlite::types::Value> =
                 vec![rusqlite::types::Value::Text(server_id.to_string())];
-            if let (Some(clause), scope_params) = library_scope_filter_sql("t", &scope_ids) {
-                sql.push_str(&format!(" AND {clause}"));
-                params.extend(scope_params);
+            if let Some(scope) = library_scope.filter(|s| !s.trim().is_empty()) {
+                sql.push_str(&format!(" AND {}", library_scope_equals_sql("t")));
+                params.push(rusqlite::types::Value::Text(scope.to_string()));
             }
             sql.push_str(
-                " GROUP BY t.genre COLLATE NOCASE \
-                 ORDER BY album_count DESC, t.genre COLLATE NOCASE ASC",
+                " GROUP BY tg.genre COLLATE NOCASE \
+                 ORDER BY album_count DESC, tg.genre COLLATE NOCASE ASC",
             );
             let mut stmt = conn.prepare(&sql)?;
             let rows = stmt
@@ -174,13 +164,11 @@ pub fn library_get_genre_album_counts(
     runtime: State<'_, LibraryRuntime>,
     server_id: String,
     library_scope: Option<String>,
-    library_scope_ids: Option<Vec<String>>,
 ) -> Result<Vec<GenreAlbumCountDto>, String> {
     genre_album_counts_for_server(
         &runtime.store,
         &server_id,
         library_scope.as_deref(),
-        library_scope_ids.as_deref(),
     )
 }
 
@@ -332,7 +320,7 @@ mod tests {
             .upsert_batch(&rock_one)
             .unwrap();
 
-        let counts = genre_album_counts_for_server(&store, "s1", None, None).unwrap();
+        let counts = genre_album_counts_for_server(&store, "s1", None).unwrap();
         assert_eq!(counts.len(), 2);
         assert_eq!(counts[0].value, "Rock");
         assert_eq!(counts[0].album_count, 2);
@@ -355,13 +343,33 @@ mod tests {
             .upsert_batch(&[scoped, other])
             .unwrap();
 
-        let counts = genre_album_counts_for_server(&store, "s1", Some("lib1"), None).unwrap();
+        let counts = genre_album_counts_for_server(&store, "s1", Some("lib1")).unwrap();
         assert_eq!(counts.len(), 1);
         assert_eq!(counts[0].value, "Rock");
         assert_eq!(counts[0].album_count, 1);
         assert_eq!(counts[0].song_count, 1);
     }
 
+    #[test]
+    fn genre_album_counts_scope_reads_library_id_from_track_raw_json() {
+        let store = Arc::new(LibraryStore::open_in_memory());
+        let mut scoped = make_row("s1", "r1", "al_a", 1);
+        scoped.genre = Some("Rock".into());
+        scoped.library_id = None;
+        scoped.raw_json = r#"{"libraryId":"lib1"}"#.into();
+        let mut other = make_row("s1", "r2", "al_b", 1);
+        other.genre = Some("Rock".into());
+        other.library_id = None;
+        other.raw_json = r#"{"libraryId":"lib2"}"#.into();
+        TrackRepository::new(&store)
+            .upsert_batch(&[scoped, other])
+            .unwrap();
+
+        let counts = genre_album_counts_for_server(&store, "s1", Some("lib1")).unwrap();
+        assert_eq!(counts.len(), 1);
+        assert_eq!(counts[0].album_count, 1);
+    }
+
     #[test]
     fn reconcile_album_stars_clears_all_when_server_list_empty() {
         let store = Arc::new(LibraryStore::open_in_memory());

src-tauri/crates/psysonic-library/src/canonical.rs

@@ -81,7 +81,7 @@ pub fn link_all_tracks_for_server(
     server_id: &str,
     now: i64,
 ) -> Result<u32, String> {
-    store.with_conn_mut("misc", |conn| {
+    store.with_conn_mut("canonical.link_all_tracks", |conn| {
         let tx = conn.transaction()?;
         let mut stmt = tx.prepare(
             "SELECT id, isrc, mbid_recording FROM track \

src-tauri/crates/psysonic-library/src/commands.rs

@@ -20,16 +20,10 @@ use crate::cover_resolve::CoverEntryDto;
 use crate::cross_server;
 use crate::dto::{
     count_local_tracks, local_tracks_max_updated_ms, track_index_nonempty, ArtifactInputDto,
-    FactInputDto,     LibraryAdvancedSearchRequest, LibraryAdvancedSearchResponse,
-    LibraryClusterAdvancedSearchRequest, LibraryClusterListTracksRequest, LibraryClusterResolveRequest,
-    LibraryClusterResolveResponse, LibraryClusterAlbumsResponse, LibraryClusterArtistsResponse,
-    LibraryClusterScopeRequest, LibraryClusterPlayerStatsRequest, LibraryClusterPlayerStatsDayDetailRequest,
-    LibraryClusterEntityDetailRequest, LibraryClusterAlbumDetailResponse,
-    LibraryClusterArtistDetailResponse,
+    FactInputDto, LibraryAdvancedSearchRequest, LibraryAdvancedSearchResponse,
     LibraryCrossServerSearchResponse, LibraryLiveSearchRequest, LibraryLiveSearchResponse, LibraryTrackDto,
     LibraryTracksEnvelope, OfflinePathDto, PlaySessionDayDetailDto, PlaySessionHeatmapDayDto,
-    PlaySessionInputDto, PlaySessionMostPlayedDto, PlaySessionRecentDayDto, PlaySessionYearBoundsDto,
-    PlaySessionYearSummaryDto, PurgeReportDto, SyncJobDto, SyncStateDto,
+    PlaySessionInputDto, PlaySessionRecentDayDto, PlaySessionYearBoundsDto, PlaySessionYearSummaryDto, PurgeReportDto, SyncJobDto, SyncStateDto,
     TrackArtifactDto, TrackFactDto, TrackRefDto,
 };
 use crate::live_search;
@@ -402,6 +396,40 @@ pub async fn library_get_tracks_by_album(
     Ok(rows.iter().map(LibraryTrackDto::from_row).collect())
 }
 
+/// Upsert Subsonic API song payloads into the library index so pin/download can
+/// build `media/library/…` paths before a full sync has ingested the rows.
+#[tauri::command]
+pub fn library_upsert_songs_from_api(
+    runtime: State<'_, LibraryRuntime>,
+    server_id: String,
+    songs: Vec<serde_json::Value>,
+) -> Result<u32, String> {
+    use crate::sync::subsonic_song_to_track_row;
+    use psysonic_integration::subsonic::Song;
+
+    if songs.is_empty() {
+        return Ok(0);
+    }
+    let synced_at = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_err(|e| e.to_string())?
+        .as_secs() as i64;
+    let repo = TrackRepository::new(&runtime.store);
+    let mut rows = Vec::with_capacity(songs.len());
+    for raw in songs {
+        let song: Song = serde_json::from_value(raw.clone()).map_err(|e| e.to_string())?;
+        rows.push(subsonic_song_to_track_row(
+            &server_id,
+            &song,
+            &raw,
+            synced_at,
+            None,
+        ));
+    }
+    repo.upsert_batch(&rows)?;
+    Ok(rows.len() as u32)
+}
+
 #[tauri::command]
 pub async fn library_get_artifact(
     runtime: State<'_, LibraryRuntime>,
@@ -448,7 +476,7 @@ pub async fn library_get_offline_path(
 ) -> Result<OfflinePathDto, String> {
     let path = runtime
         .store
-        .with_conn("misc", |conn| {
+        .with_conn("cmd.get_offline_path", |conn| {
             conn.query_row(
                 "SELECT local_path FROM track_offline \
                  WHERE server_id = ?1 AND track_id = ?2",
@@ -479,16 +507,6 @@ pub async fn library_advanced_search(
     library_spawn_blocking(move || advanced_search::run_advanced_search(&store, &request)).await
 }
 
-#[tauri::command]
-pub async fn library_cluster_advanced_search(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterAdvancedSearchRequest,
-) -> Result<LibraryAdvancedSearchResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    library_spawn_blocking(move || crate::server_cluster::run_cluster_advanced_search(&store, request))
-        .await
-}
-
 #[tauri::command]
 pub async fn library_list_lossless_albums(
     runtime: State<'_, LibraryRuntime>,
@@ -498,15 +516,6 @@ pub async fn library_list_lossless_albums(
     library_spawn_blocking(move || crate::lossless_albums::list_lossless_albums(&store, &request)).await
 }
 
-#[tauri::command]
-pub async fn library_list_albums(
-    runtime: State<'_, LibraryRuntime>,
-    request: crate::dto::LibraryAlbumBrowseRequest,
-) -> Result<crate::dto::LibraryAlbumBrowseResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    library_spawn_blocking(move || crate::album_browse::list_albums(&store, &request)).await
-}
-
 #[tauri::command]
 pub async fn library_list_albums_by_genre(
     runtime: State<'_, LibraryRuntime>,
@@ -517,6 +526,23 @@ pub async fn library_list_albums_by_genre(
         .await
 }
 
+#[tauri::command]
+pub fn library_genre_tags_inspect(
+    runtime: State<'_, LibraryRuntime>,
+) -> Result<crate::genre_tags_backfill::GenreTagsInspectDto, String> {
+    crate::genre_tags_backfill::inspect_genre_tags_backfill(&runtime.store)
+}
+
+#[tauri::command]
+pub async fn library_genre_tags_run(
+    app: tauri::AppHandle,
+    runtime: State<'_, LibraryRuntime>,
+) -> Result<(), String> {
+    let store = Arc::clone(&runtime.store);
+    library_spawn_blocking(move || crate::genre_tags_backfill::run_genre_tags_backfill(&store, &app))
+        .await
+}
+
 #[tauri::command]
 pub async fn library_get_artist_lossless_browse(
     runtime: State<'_, LibraryRuntime>,
@@ -571,265 +597,6 @@ pub async fn library_search_cross_server(
     cross_server::run_cross_server_search(&runtime.store, &query, limit, servers.as_deref())
 }
 
-#[tauri::command]
-pub async fn library_cluster_list_tracks(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterListTracksRequest,
-) -> Result<LibraryTracksEnvelope, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let limit = request.limit.unwrap_or(100);
-    let offset = request.offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::list_merged_tracks(
-            &store,
-            &servers_ordered,
-            limit,
-            offset,
-            &request.library_scopes,
-        )
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_list_albums(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterListTracksRequest,
-) -> Result<LibraryClusterAlbumsResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let limit = request.limit.unwrap_or(100);
-    let offset = request.offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::list_merged_albums(
-            &store,
-            &servers_ordered,
-            limit,
-            offset,
-            &request.library_scopes,
-        )
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_list_artists(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterListTracksRequest,
-) -> Result<LibraryClusterArtistsResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let limit = request.limit.unwrap_or(100);
-    let offset = request.offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::list_merged_artists(
-            &store,
-            &servers_ordered,
-            limit,
-            offset,
-            &request.library_scopes,
-        )
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_list_favorites(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterScopeRequest,
-) -> Result<LibraryTracksEnvelope, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let limit = request.limit.unwrap_or(500);
-    let offset = request.offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::list_merged_favorite_tracks(&store, &servers_ordered, limit, offset)
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_list_favorite_albums(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterScopeRequest,
-) -> Result<LibraryClusterAlbumsResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let limit = request.limit.unwrap_or(500);
-    let offset = request.offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::list_merged_favorite_albums(&store, &servers_ordered, limit, offset)
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_list_favorite_artists(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterScopeRequest,
-) -> Result<LibraryClusterArtistsResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let limit = request.limit.unwrap_or(500);
-    let offset = request.offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::list_merged_favorite_artists(&store, &servers_ordered, limit, offset)
-    })
-    .await
-}
-
-#[tauri::command]
-pub fn library_cluster_player_stats_year_summary(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterPlayerStatsRequest,
-) -> Result<PlaySessionYearSummaryDto, String> {
-    crate::server_cluster::cluster_year_summary(
-        &runtime.store,
-        &request.servers_ordered,
-        request.year,
-    )
-}
-
-#[tauri::command]
-pub fn library_cluster_player_stats_heatmap(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterPlayerStatsRequest,
-) -> Result<Vec<PlaySessionHeatmapDayDto>, String> {
-    crate::server_cluster::cluster_heatmap(
-        &runtime.store,
-        &request.servers_ordered,
-        request.year,
-    )
-}
-
-#[tauri::command]
-pub fn library_cluster_player_stats_day_detail(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterPlayerStatsDayDetailRequest,
-) -> Result<PlaySessionDayDetailDto, String> {
-    crate::server_cluster::cluster_day_detail(
-        &runtime.store,
-        &request.servers_ordered,
-        &request.date_iso,
-    )
-}
-
-#[tauri::command]
-pub fn library_cluster_player_stats_recent_days(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterScopeRequest,
-) -> Result<Vec<PlaySessionRecentDayDto>, String> {
-    crate::server_cluster::cluster_recent_days(
-        &runtime.store,
-        &request.servers_ordered,
-        request.limit.unwrap_or(30),
-    )
-}
-
-#[tauri::command]
-pub fn library_cluster_player_stats_most_played(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterScopeRequest,
-) -> Result<Vec<PlaySessionMostPlayedDto>, String> {
-    crate::server_cluster::cluster_most_played(
-        &runtime.store,
-        &request.servers_ordered,
-        request.limit.unwrap_or(50),
-    )
-}
-
-#[tauri::command]
-pub async fn library_cluster_resolve_candidates(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterResolveRequest,
-) -> Result<LibraryClusterResolveResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    library_spawn_blocking(move || {
-        if let Some(key) = request.cluster_key.filter(|k| !k.is_empty()) {
-            let candidates = crate::server_cluster::resolve_candidates_by_cluster_key(
-                &store,
-                &request.servers_ordered,
-                &key,
-            )?;
-            return Ok(LibraryClusterResolveResponse {
-                candidates,
-                cluster_key: Some(key),
-            });
-        }
-        let server_id = request
-            .server_id
-            .as_deref()
-            .filter(|s| !s.is_empty())
-            .ok_or_else(|| "cluster_key or (server_id, track_id) required".to_string())?;
-        let track_id = request
-            .track_id
-            .as_deref()
-            .filter(|s| !s.is_empty())
-            .ok_or_else(|| "cluster_key or (server_id, track_id) required".to_string())?;
-        let cluster_key =
-            crate::server_cluster::cluster_key_for_track(&store, server_id, track_id)?;
-        let candidates = crate::server_cluster::resolve_candidates_for_track(
-            &store,
-            &request.servers_ordered,
-            server_id,
-            track_id,
-        )?;
-        Ok(LibraryClusterResolveResponse {
-            candidates,
-            cluster_key,
-        })
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_album_detail(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterEntityDetailRequest,
-) -> Result<LibraryClusterAlbumDetailResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let server_id = request.server_id;
-    let entity_id = request.entity_id;
-    library_spawn_blocking(move || {
-        crate::server_cluster::cluster_album_detail(&store, &servers_ordered, &server_id, &entity_id)
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_cluster_artist_detail(
-    runtime: State<'_, LibraryRuntime>,
-    request: LibraryClusterEntityDetailRequest,
-) -> Result<LibraryClusterArtistDetailResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let servers_ordered = request.servers_ordered;
-    let server_id = request.server_id;
-    let entity_id = request.entity_id;
-    library_spawn_blocking(move || {
-        crate::server_cluster::cluster_artist_detail(&store, &servers_ordered, &server_id, &entity_id)
-    })
-    .await
-}
-
-#[tauri::command]
-pub async fn library_search_cluster(
-    runtime: State<'_, LibraryRuntime>,
-    query: String,
-    limit: Option<u32>,
-    offset: Option<u32>,
-    servers_ordered: Vec<String>,
-) -> Result<LibraryCrossServerSearchResponse, String> {
-    let store = Arc::clone(&runtime.store);
-    let limit = limit.unwrap_or(100);
-    let offset = offset.unwrap_or(0);
-    library_spawn_blocking(move || {
-        crate::server_cluster::run_cluster_search(&store, &query, limit, offset, &servers_ordered)
-    })
-    .await
-}
-
 // ── helpers ──────────────────────────────────────────────────────────
 
 fn hydrate_refs(
@@ -1197,12 +964,6 @@ async fn library_sync_start_inner(
         };
         if let Some(runtime) = app_for_emit.try_state::<LibraryRuntime>() {
             let _ = runtime.store.checkpoint_wal("sync.checkpoint");
-            if outcome.ok {
-                let _ = crate::server_cluster::rebuild_cluster_keys_for_server(
-                    &runtime.store,
-                    &server_id_for_emit,
-                );
-            }
         }
         let _ = app_for_emit.emit(LibrarySyncProgressPayload::IDLE_EVENT_NAME, &outcome);
 
@@ -1284,7 +1045,7 @@ pub fn patch_content_hash(
     }
     runtime
         .store
-        .with_conn("misc", |conn| {
+        .with_conn("cmd.patch_content_hash", |conn| {
             conn.execute(
                 "UPDATE track SET content_hash = ?3 \
                  WHERE server_id = ?1 AND id = ?2",
@@ -1331,7 +1092,7 @@ pub(crate) fn apply_track_patch(
 
     runtime
         .store
-        .with_conn("misc", |conn| {
+        .with_conn("cmd.patch_track", |conn| {
             // One UPDATE per field present — keeps SQL simple and
             // matches the spec's per-field patch semantics.
             if let Some(v) = starred_at {
@@ -1467,7 +1228,7 @@ pub fn library_purge_server(
     let mut report = PurgeReportDto::default();
     runtime
         .store
-        .with_conn_mut("misc", |conn| {
+        .with_conn_mut("cmd.purge_server", |conn| {
             let tx = conn.transaction()?;
             let track_count: i64 =
                 tx.query_row("SELECT COUNT(*) FROM track WHERE server_id = ?1", params![server_id], |r| r.get(0))?;

src-tauri/crates/psysonic-library/src/dto.rs

@@ -4,7 +4,6 @@
 
 use serde::{Deserialize, Serialize};
 use serde_json::Value;
-use std::collections::HashMap;
 
 use crate::filter::{EntityKind, FilterOp};
 use crate::repos::TrackRow;
@@ -366,14 +365,6 @@ pub struct PlaySessionRecentDayDto {
     pub partial_count: u32,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct PlaySessionMostPlayedDto {
-    pub track: LibraryTrackDto,
-    pub track_play_count: u32,
-    pub total_listened_sec: f64,
-}
-
 /// Earliest/latest calendar years with at least one session (local TZ).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
@@ -399,38 +390,6 @@ pub struct GenreAlbumCountDto {
     pub song_count: u32,
 }
 
-/// `library_list_albums` request — paginated plain All Albums browse (local index).
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryAlbumBrowseRequest {
-    pub server_id: String,
-    #[serde(default)]
-    pub library_scope: Option<String>,
-    #[serde(default)]
-    pub library_scope_ids: Option<Vec<String>>,
-    #[serde(default)]
-    pub sort: Vec<LibrarySortClause>,
-    #[serde(default)]
-    pub restrict_album_ids: Option<Vec<String>>,
-    #[serde(default = "default_album_browse_limit")]
-    pub limit: u32,
-    #[serde(default)]
-    pub offset: u32,
-}
-
-fn default_album_browse_limit() -> u32 {
-    30
-}
-
-/// `library_list_albums` response.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryAlbumBrowseResponse {
-    pub albums: Vec<LibraryAlbumDto>,
-    pub has_more: bool,
-    pub source: String,
-}
-
 /// `library_list_albums_by_genre` request — paginated genre album browse (local index).
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(rename_all = "camelCase")]
@@ -440,8 +399,6 @@ pub struct LibraryGenreAlbumsRequest {
     #[serde(default)]
     pub library_scope: Option<String>,
     #[serde(default)]
-    pub library_scope_ids: Option<Vec<String>>,
-    #[serde(default)]
     pub sort: Vec<LibrarySortClause>,
     #[serde(default = "default_genre_album_limit")]
     pub limit: u32,
@@ -563,9 +520,6 @@ pub struct LibraryAdvancedSearchRequest {
     pub server_id: String,
     #[serde(default)]
     pub library_scope: Option<String>,
-    /// Multiple music-folder ids (OR). Takes precedence over `library_scope` when non-empty.
-    #[serde(default)]
-    pub library_scope_ids: Option<Vec<String>>,
     #[serde(default)]
     pub query: Option<String>,
     pub entity_types: Vec<EntityKind>,
@@ -651,14 +605,6 @@ pub struct LibraryLosslessAlbumsRequest {
     pub server_id: String,
     #[serde(default)]
     pub library_scope: Option<String>,
-    /// Multiple music-folder ids (OR). Preferred over `library_scope` when length > 1.
-    #[serde(default)]
-    pub library_scope_ids: Option<Vec<String>>,
-    #[serde(default)]
-    pub sort: Vec<LibrarySortClause>,
-    /// Navidrome-scoped album ids from getAlbumList2 (authoritative when track `library_id` is sparse).
-    #[serde(default)]
-    pub restrict_album_ids: Option<Vec<String>>,
     #[serde(default = "default_lossless_limit")]
     pub limit: u32,
     #[serde(default)]
@@ -712,158 +658,6 @@ pub struct LibraryCrossServerSearchResponse {
     pub servers_searched: Vec<String>,
 }
 
-/// Cluster candidate row for playback / write fan-out resolution.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterCandidateDto {
-    pub server_id: String,
-    pub track_id: String,
-    pub duration_sec: i64,
-    pub priority_rank: u32,
-    pub is_winner: bool,
-}
-
-/// `library_cluster_list_tracks` request.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterListTracksRequest {
-    /// Ordered member server ids (index 0 = highest priority).
-    pub servers_ordered: Vec<String>,
-    #[serde(default)]
-    pub limit: Option<u32>,
-    #[serde(default)]
-    pub offset: Option<u32>,
-    /// Per-member music-folder scopes (`server_id` → folder ids). Omitted members = all libraries.
-    #[serde(default)]
-    pub library_scopes: HashMap<String, Vec<String>>,
-}
-
-/// `library_cluster_advanced_search` request.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterAdvancedSearchRequest {
-    /// Ordered member server ids (index 0 = highest priority).
-    pub servers_ordered: Vec<String>,
-    #[serde(default)]
-    pub query: Option<String>,
-    pub entity_types: Vec<EntityKind>,
-    #[serde(default)]
-    pub filters: Vec<LibraryFilterClause>,
-    #[serde(default)]
-    pub starred_only: Option<bool>,
-    #[serde(default)]
-    pub restrict_album_ids: Option<Vec<String>>,
-    /// Per-member album allowlists from getAlbumList2 (`server_id` → album ids).
-    #[serde(default)]
-    pub restrict_album_scopes: HashMap<String, Vec<String>>,
-    #[serde(default)]
-    pub query_album_title_only: Option<bool>,
-    #[serde(default)]
-    pub sort: Vec<LibrarySortClause>,
-    pub limit: u32,
-    #[serde(default)]
-    pub offset: u32,
-    #[serde(default)]
-    pub skip_totals: bool,
-    /// Per-member music-folder scopes (`server_id` → folder ids). Omitted members = all libraries.
-    #[serde(default)]
-    pub library_scopes: HashMap<String, Vec<String>>,
-}
-
-/// Merged album browse response for cluster scope.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterAlbumsResponse {
-    pub albums: Vec<LibraryAlbumDto>,
-    pub has_more: bool,
-}
-
-/// Merged artist browse response for cluster scope.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterArtistsResponse {
-    pub artists: Vec<LibraryArtistDto>,
-    pub has_more: bool,
-}
-
-/// Cluster player stats / favorites scope request.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterScopeRequest {
-    pub servers_ordered: Vec<String>,
-    #[serde(default)]
-    pub limit: Option<u32>,
-    #[serde(default)]
-    pub offset: Option<u32>,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterPlayerStatsRequest {
-    pub servers_ordered: Vec<String>,
-    pub year: i32,
-}
-
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterPlayerStatsDayDetailRequest {
-    pub servers_ordered: Vec<String>,
-    pub date_iso: String,
-}
-
-/// `library_cluster_resolve_candidates` request — provide cluster_key OR seed track.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterResolveRequest {
-    pub servers_ordered: Vec<String>,
-    #[serde(default)]
-    pub cluster_key: Option<String>,
-    #[serde(default)]
-    pub server_id: Option<String>,
-    #[serde(default)]
-    pub track_id: Option<String>,
-}
-
-/// `library_cluster_resolve_candidates` response.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterResolveResponse {
-    pub candidates: Vec<LibraryClusterCandidateDto>,
-    #[serde(default)]
-    pub cluster_key: Option<String>,
-}
-
-/// `library_cluster_album_detail` request.
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterEntityDetailRequest {
-    pub servers_ordered: Vec<String>,
-    pub server_id: String,
-    pub entity_id: String,
-}
-
-/// Virtual aggregate album detail (spec §4).
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterAlbumDetailResponse {
-    pub album: LibraryAlbumDto,
-    pub tracks: Vec<LibraryTrackDto>,
-    pub owner_server_id: String,
-    pub related_albums: Vec<LibraryAlbumDto>,
-}
-
-/// Virtual aggregate artist detail (spec §4).
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
-#[serde(rename_all = "camelCase")]
-pub struct LibraryClusterArtistDetailResponse {
-    pub artist: LibraryArtistDto,
-    pub albums: Vec<LibraryAlbumDto>,
-    pub top_tracks: Vec<LibraryTrackDto>,
-    pub owner_server_id: String,
-    #[serde(default)]
-    pub artist_key: Option<String>,
-}
-
 /// Read `MAX(server_updated_at)` for non-deleted tracks on this server
 /// — used by `SyncStateDto` so callers can show "tracks watermark" in
 /// Settings without a separate column.

src-tauri/crates/psysonic-library/src/genre_album_browse.rs

@@ -7,7 +7,7 @@ use crate::dto::{
     LibraryAlbumDto, LibraryGenreAlbumsRequest, LibraryGenreAlbumsResponse, LibrarySortClause,
     SortDir,
 };
-use crate::search::library_scope_filter_sql;
+use crate::search::library_scope_equals_sql;
 use crate::store::LibraryStore;
 use rusqlite::types::Value as SqlValue;
 use serde_json::Value;
@@ -18,36 +18,21 @@ fn trimmed_nonempty(s: Option<&str>) -> Option<String> {
         .map(String::from)
 }
 
-fn effective_genre_scope_ids(req: &LibraryGenreAlbumsRequest) -> Vec<String> {
-    if let Some(ids) = &req.library_scope_ids {
-        let trimmed: Vec<_> = ids
-            .iter()
-            .filter(|s| !s.trim().is_empty())
-            .cloned()
-            .collect();
-        if !trimmed.is_empty() {
-            return trimmed;
-        }
-    }
-    trimmed_nonempty(req.library_scope.as_deref())
-        .map(|s| vec![s])
-        .unwrap_or_default()
-}
-
 fn genre_album_order_sql(sort: &[LibrarySortClause]) -> String {
+    let la_artist = crate::album_compilation_filter::sql_track_group_display_artist("la");
     let mut keys: Vec<String> = Vec::new();
     for s in sort {
         let col = match s.field.as_str() {
-            "name" => "COALESCE(a.name, la.album_name) COLLATE NOCASE",
-            "artist" => "COALESCE(a.artist, la.artist) COLLATE NOCASE",
-            "year" => "COALESCE(a.year, la.year)",
+            "name" => "COALESCE(a.name, la.album_name) COLLATE NOCASE".to_string(),
+            "artist" => format!("COALESCE(a.artist, {la_artist}) COLLATE NOCASE"),
+            "year" => "COALESCE(a.year, la.year)".to_string(),
             _ => continue,
         };
         let dir = match s.dir {
             SortDir::Asc => "ASC",
             SortDir::Desc => "DESC",
         };
-        keys.push(format!("{col} {dir}"));
+        keys.push(format!("{col} {dir}", col = col));
     }
     if keys.is_empty() {
         keys.push("COALESCE(a.name, la.album_name) COLLATE NOCASE ASC".to_string());
@@ -60,10 +45,16 @@ fn count_genre_albums(
     conn: &rusqlite::Connection,
     where_sql: &str,
     params: &[SqlValue],
+    library_scoped: bool,
 ) -> Result<u32, rusqlite::Error> {
-    let count_sql = format!(
-        "SELECT COUNT(DISTINCT t.album_id) FROM track t WHERE {where_sql}"
-    );
+    let from = if library_scoped {
+        "FROM track_genre tg \
+         INNER JOIN track t \
+           ON t.server_id = tg.server_id AND t.id = tg.track_id AND t.deleted = 0"
+    } else {
+        "FROM track_genre tg"
+    };
+    let count_sql = format!("SELECT COUNT(DISTINCT tg.album_id) {from} WHERE {where_sql}");
     let n: i64 = conn.query_row(
         &count_sql,
         rusqlite::params_from_iter(params.iter()),
@@ -123,29 +114,29 @@ pub fn list_albums_by_genre(
     let order_sql = genre_album_order_sql(&req.sort);
 
     let mut where_clauses = vec![
-        "t.deleted = 0".to_string(),
-        "t.server_id = ?1".to_string(),
-        "t.album_id IS NOT NULL AND t.album_id != ''".to_string(),
-        "t.genre = ?2 COLLATE NOCASE".to_string(),
+        "tg.server_id = ?1".to_string(),
+        "tg.album_id IS NOT NULL AND tg.album_id != ''".to_string(),
+        "tg.genre = ?2 COLLATE NOCASE".to_string(),
     ];
     let mut params: Vec<SqlValue> = vec![
         SqlValue::Text(req.server_id.clone()),
         SqlValue::Text(genre.to_string()),
     ];
 
-    let scope_ids = effective_genre_scope_ids(req);
-    if let (Some(clause), scope_params) = library_scope_filter_sql("t", &scope_ids) {
-        where_clauses.push(clause);
-        params.extend(scope_params);
+    let library_scoped = trimmed_nonempty(req.library_scope.as_deref()).is_some();
+    if let Some(scope) = trimmed_nonempty(req.library_scope.as_deref()) {
+        where_clauses.push(library_scope_equals_sql("t"));
+        params.push(SqlValue::Text(scope));
     }
 
     let where_sql = where_clauses.join(" AND ");
+    let la_artist = crate::album_compilation_filter::sql_track_group_display_artist("la");
     let sql = format!(
         "SELECT \
            la.server_id, \
            la.album_id, \
            COALESCE(a.name, la.album_name), \
-           COALESCE(a.artist, la.artist), \
+           COALESCE(a.artist, {la_artist}), \
            COALESCE(a.artist_id, la.artist_id), \
            COALESCE(a.song_count, la.track_count), \
            COALESCE(a.duration_sec, la.duration_sec), \
@@ -157,10 +148,11 @@ pub fn list_albums_by_genre(
            a.raw_json \
          FROM ( \
            SELECT \
-             t.server_id, \
-             t.album_id, \
+             tg.server_id, \
+             tg.album_id, \
              MAX(t.album) AS album_name, \
              MAX(t.artist) AS artist, \
+             MAX(t.album_artist) AS album_artist, \
              MAX(t.artist_id) AS artist_id, \
              MAX(t.year) AS year, \
              MAX(t.genre) AS genre, \
@@ -169,9 +161,11 @@ pub fn list_albums_by_genre(
              MAX(t.synced_at) AS synced_at, \
              COUNT(*) AS track_count, \
              COALESCE(SUM(t.duration_sec), 0) AS duration_sec \
-           FROM track t \
+           FROM track_genre tg \
+           INNER JOIN track t \
+             ON t.server_id = tg.server_id AND t.id = tg.track_id AND t.deleted = 0 \
            WHERE {where_sql} \
-           GROUP BY t.server_id, t.album_id \
+           GROUP BY tg.server_id, tg.album_id \
          ) la \
          LEFT JOIN album a ON a.server_id = la.server_id AND a.id = la.album_id \
          {order_sql} \
@@ -184,7 +178,7 @@ pub fn list_albums_by_genre(
 
     store.with_read_conn(|conn| {
         let total = if req.include_total {
-            Some(count_genre_albums(conn, &where_sql, &count_params)?)
+            Some(count_genre_albums(conn, &where_sql, &count_params, library_scoped)?)
         } else {
             None
         };
@@ -270,7 +264,6 @@ mod tests {
                 server_id: "s1".into(),
                 genre: "Rock".into(),
                 library_scope: Some("lib1".into()),
-                library_scope_ids: None,
                 sort: vec![LibrarySortClause {
                     field: "name".into(),
                     dir: SortDir::Asc,
@@ -290,7 +283,6 @@ mod tests {
                 server_id: "s1".into(),
                 genre: "Rock".into(),
                 library_scope: None,
-                library_scope_ids: None,
                 sort: vec![],
                 limit: 1,
                 offset: 0,
@@ -301,4 +293,49 @@ mod tests {
         assert_eq!(all.total, Some(3));
         assert!(all.has_more);
     }
+
+    #[test]
+    fn list_albums_by_atomic_genre_from_compound_tag() {
+        let store = LibraryStore::open_in_memory();
+        TrackRepository::new(&store)
+            .upsert_batch(&[track(
+                "s1",
+                "t1",
+                "al_a",
+                "Noise Metal/Dark Ambient/Experimental Black Metal",
+            )])
+            .unwrap();
+
+        let dark = list_albums_by_genre(
+            &store,
+            &LibraryGenreAlbumsRequest {
+                server_id: "s1".into(),
+                genre: "Dark Ambient".into(),
+                library_scope: None,
+                sort: vec![],
+                limit: 10,
+                offset: 0,
+                include_total: true,
+            },
+        )
+        .unwrap();
+        assert_eq!(dark.total, Some(1));
+        assert_eq!(dark.albums.len(), 1);
+        assert_eq!(dark.albums[0].id, "al_a");
+
+        let noise = list_albums_by_genre(
+            &store,
+            &LibraryGenreAlbumsRequest {
+                server_id: "s1".into(),
+                genre: "Noise Metal".into(),
+                library_scope: None,
+                sort: vec![],
+                limit: 10,
+                offset: 0,
+                include_total: true,
+            },
+        )
+        .unwrap();
+        assert_eq!(noise.total, Some(1));
+    }
 }

src-tauri/crates/psysonic-library/src/genre_tags.rs

@@ -0,0 +1,226 @@
+//! Atomic genre resolution for multi-value tags (OpenSubsonic `genres[]` first,
+//! Navidrome-default string split as fallback).
+
+use std::collections::HashSet;
+
+use rusqlite::{params, Transaction};
+use serde_json::Value;
+
+const GENRE_SEPARATORS: [&str; 3] = [";", "/", ","];
+
+/// Fallback split when the server sent no `genres[]` array (legacy Subsonic).
+pub fn split_genre_tags(raw: &str) -> Vec<String> {
+    let trimmed = raw.trim();
+    if trimmed.is_empty() {
+        return Vec::new();
+    }
+    let mut parts = vec![trimmed.to_string()];
+    for sep in GENRE_SEPARATORS {
+        let mut next = Vec::new();
+        for part in parts {
+            for sub in part.split(sep) {
+                next.push(sub.to_string());
+            }
+        }
+        parts = next;
+    }
+    dedupe_genres(parts)
+}
+
+fn dedupe_genres(genres: Vec<String>) -> Vec<String> {
+    let mut seen = HashSet::new();
+    let mut out = Vec::new();
+    for g in genres {
+        let t = g.trim();
+        if t.is_empty() {
+            continue;
+        }
+        let key = t.to_ascii_lowercase();
+        if seen.insert(key) {
+            out.push(t.to_string());
+        }
+    }
+    out
+}
+
+fn parse_genres_array_value(value: &Value) -> Option<Vec<String>> {
+    let arr = value.as_array()?;
+    if arr.is_empty() {
+        return None;
+    }
+    let mut out = Vec::new();
+    for item in arr {
+        if let Some(name) = item.get("name").and_then(|v| v.as_str()) {
+            let t = name.trim();
+            if !t.is_empty() {
+                out.push(t.to_string());
+            }
+        } else if let Some(s) = item.as_str() {
+            let t = s.trim();
+            if !t.is_empty() {
+                out.push(t.to_string());
+            }
+        }
+    }
+    if out.is_empty() {
+        None
+    } else {
+        Some(dedupe_genres(out))
+    }
+}
+
+fn parse_genres_json_str(genres_json: &str) -> Option<Vec<String>> {
+    let trimmed = genres_json.trim();
+    if trimmed.is_empty() {
+        return None;
+    }
+    let value: Value = serde_json::from_str(trimmed).ok()?;
+    parse_genres_array_value(&value)
+}
+
+/// Source-priority resolver (§2.0): `genres[]` from parsed payload, else split `genre`.
+pub fn genres_for_track_value(raw_json: &Value, genre: Option<&str>) -> Vec<String> {
+    if let Some(genres) = raw_json.get("genres").and_then(parse_genres_array_value) {
+        return genres;
+    }
+    genre
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(split_genre_tags)
+        .unwrap_or_default()
+}
+
+/// Backfill path: `genres_json` from `json_extract(raw_json, '$.genres')`.
+pub fn genres_for_track_extracted(genres_json: Option<&str>, genre: Option<&str>) -> Vec<String> {
+    if let Some(json) = genres_json {
+        if let Some(genres) = parse_genres_json_str(json) {
+            return genres;
+        }
+    }
+    genre
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(split_genre_tags)
+        .unwrap_or_default()
+}
+
+pub fn genres_for_track_raw_json(raw_json: &str, genre: Option<&str>) -> Vec<String> {
+    if let Ok(value) = serde_json::from_str::<Value>(raw_json) {
+        return genres_for_track_value(&value, genre);
+    }
+    genre
+        .map(str::trim)
+        .filter(|s| !s.is_empty())
+        .map(split_genre_tags)
+        .unwrap_or_default()
+}
+
+pub fn replace_track_genre_rows(
+    tx: &Transaction<'_>,
+    server_id: &str,
+    track_id: &str,
+    album_id: Option<&str>,
+    library_id: Option<&str>,
+    genres: &[String],
+) -> rusqlite::Result<()> {
+    tx.execute(
+        "DELETE FROM track_genre WHERE server_id = ?1 AND track_id = ?2",
+        params![server_id, track_id],
+    )?;
+    if genres.is_empty() {
+        return Ok(());
+    }
+    let mut insert = tx.prepare_cached(
+        "INSERT OR IGNORE INTO track_genre (server_id, track_id, genre, album_id, library_id) \
+         VALUES (?1, ?2, ?3, ?4, ?5)",
+    )?;
+    for genre in genres {
+        insert.execute(params![server_id, track_id, genre, album_id, library_id])?;
+    }
+    Ok(())
+}
+
+pub fn delete_track_genre_for_track(
+    conn: &rusqlite::Connection,
+    server_id: &str,
+    track_id: &str,
+) -> rusqlite::Result<()> {
+    conn.execute(
+        "DELETE FROM track_genre WHERE server_id = ?1 AND track_id = ?2",
+        params![server_id, track_id],
+    )?;
+    Ok(())
+}
+
+pub fn delete_track_genre_for_server_tracks(
+    conn: &rusqlite::Connection,
+    server_id: &str,
+    track_ids: &[String],
+) -> rusqlite::Result<()> {
+    if track_ids.is_empty() {
+        return Ok(());
+    }
+    for id in track_ids {
+        delete_track_genre_for_track(conn, server_id, id)?;
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn split_separators_and_dedupe() {
+        assert_eq!(
+            split_genre_tags("Rock/Jazz"),
+            vec!["Rock".to_string(), "Jazz".to_string()]
+        );
+        assert_eq!(
+            split_genre_tags("Rock; Jazz, Electronic"),
+            vec![
+                "Rock".to_string(),
+                "Jazz".to_string(),
+                "Electronic".to_string()
+            ]
+        );
+        assert_eq!(split_genre_tags("Rock/rock/ROCK"), vec!["Rock".to_string()]);
+        assert!(split_genre_tags("").is_empty());
+    }
+
+    #[test]
+    fn array_wins_over_genre_string() {
+        let raw = json!({
+            "genres": [{"name": "A"}, {"name": "B"}],
+            "genre": "A/B/C"
+        });
+        assert_eq!(
+            genres_for_track_value(&raw, Some("A/B/C")),
+            vec!["A".to_string(), "B".to_string()]
+        );
+    }
+
+    #[test]
+    fn bare_string_array_and_empty_array_fallback() {
+        let bare = json!({ "genres": ["A", "B"] });
+        assert_eq!(
+            genres_for_track_value(&bare, None),
+            vec!["A".to_string(), "B".to_string()]
+        );
+        let empty = json!({ "genres": [], "genre": "A/B" });
+        assert_eq!(
+            genres_for_track_value(&empty, Some("A/B")),
+            vec!["A".to_string(), "B".to_string()]
+        );
+    }
+
+    #[test]
+    fn extracted_json_matches_value_path() {
+        let genres_json = r#"[{"name":"Jazz"},{"name":"Rock"}]"#;
+        assert_eq!(
+            genres_for_track_extracted(Some(genres_json), Some("Noise/Metal")),
+            vec!["Jazz".to_string(), "Rock".to_string()]
+        );
+    }
+}

src-tauri/crates/psysonic-library/src/genre_tags_backfill.rs

@@ -0,0 +1,318 @@
+//! One-time blocking backfill: populate `track_genre` from existing `track` rows.
+
+use std::time::{SystemTime, UNIX_EPOCH};
+
+use rusqlite::{params, Connection, OptionalExtension};
+use tauri::{AppHandle, Emitter};
+
+use crate::genre_tags::{genres_for_track_extracted, replace_track_genre_rows};
+use crate::store::LibraryStore;
+
+pub const GENRE_TAGS_MIGRATION_ID: &str = "genre_tags_v1";
+
+const BATCH_SIZE: i64 = 10_000;
+
+type BackfillTrackRow = (
+    i64,
+    String,
+    String,
+    Option<String>,
+    Option<String>,
+    Option<String>,
+    Option<String>,
+);
+
+fn ensure_genre_tags_tables(conn: &mut Connection) -> rusqlite::Result<()> {
+    crate::store::ensure_genre_tags_schema(conn)
+}
+
+#[derive(Debug, Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GenreTagsInspectDto {
+    pub needed: bool,
+    pub total_tracks: u64,
+    pub done_tracks: u64,
+}
+
+#[derive(Debug, Clone, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GenreTagsProgressEvent {
+    pub done: u64,
+    pub total: u64,
+}
+
+fn now_unix() -> i64 {
+    SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .map(|d| d.as_secs() as i64)
+        .unwrap_or(0)
+}
+
+fn migration_completed(conn: &Connection) -> Result<bool, rusqlite::Error> {
+    let completed: Option<Option<i64>> = conn
+        .query_row(
+            "SELECT completed_at FROM library_data_migration WHERE id = ?1",
+            params![GENRE_TAGS_MIGRATION_ID],
+            |r| r.get(0),
+        )
+        .optional()?;
+    Ok(completed.flatten().is_some())
+}
+
+fn count_live_tracks(conn: &Connection) -> Result<u64, rusqlite::Error> {
+    let n: i64 = conn.query_row(
+        "SELECT COUNT(*) FROM track WHERE deleted = 0",
+        [],
+        |r| r.get(0),
+    )?;
+    Ok(n.max(0) as u64)
+}
+
+fn cursor_rowid(conn: &Connection) -> Result<i64, rusqlite::Error> {
+    let rowid: Option<i64> = conn
+        .query_row(
+            "SELECT cursor_rowid FROM library_data_migration WHERE id = ?1",
+            params![GENRE_TAGS_MIGRATION_ID],
+            |r| r.get(0),
+        )
+        .optional()?;
+    Ok(rowid.unwrap_or(0))
+}
+
+pub fn inspect_genre_tags_backfill(store: &LibraryStore) -> Result<GenreTagsInspectDto, String> {
+    store.with_conn_mut("genre_tags.ensure_schema", ensure_genre_tags_tables)?;
+    store.with_read_conn(|conn| {
+        let total_tracks = count_live_tracks(conn)?;
+        if total_tracks == 0 {
+            return Ok(GenreTagsInspectDto {
+                needed: false,
+                total_tracks: 0,
+                done_tracks: 0,
+            });
+        }
+        if migration_completed(conn)? {
+            return Ok(GenreTagsInspectDto {
+                needed: false,
+                total_tracks,
+                done_tracks: total_tracks,
+            });
+        }
+        let cursor = cursor_rowid(conn)?;
+        let done: i64 = conn.query_row(
+            "SELECT COUNT(*) FROM track WHERE deleted = 0 AND rowid <= ?1",
+            params![cursor],
+            |r| r.get(0),
+        )?;
+        Ok(GenreTagsInspectDto {
+            needed: true,
+            total_tracks,
+            done_tracks: done.max(0) as u64,
+        })
+    })
+}
+
+fn emit_progress(app: &AppHandle, done: u64, total: u64) -> Result<(), String> {
+    app.emit(
+        "genre_tags:progress",
+        GenreTagsProgressEvent { done, total },
+    )
+    .map_err(|e| e.to_string())
+}
+
+pub fn run_genre_tags_backfill(store: &LibraryStore, app: &AppHandle) -> Result<(), String> {
+    run_genre_tags_backfill_impl(store, Some(app))
+}
+
+fn run_genre_tags_backfill_impl(
+    store: &LibraryStore,
+    app: Option<&AppHandle>,
+) -> Result<(), String> {
+    let inspect = inspect_genre_tags_backfill(store)?;
+    if !inspect.needed {
+        return Ok(());
+    }
+    let total = inspect.total_tracks;
+
+    loop {
+        let (batch_done, finished) = store.with_conn_mut("genre_tags.backfill", |conn| {
+            if migration_completed(conn)? {
+                return Ok::<(i64, bool), rusqlite::Error>((total as i64, true));
+            }
+
+            conn.execute(
+                "INSERT INTO library_data_migration (id, cursor_rowid, started_at) \
+                 VALUES (?1, 0, ?2) \
+                 ON CONFLICT(id) DO UPDATE SET \
+                   started_at = COALESCE(library_data_migration.started_at, excluded.started_at)",
+                params![GENRE_TAGS_MIGRATION_ID, now_unix()],
+            )?;
+
+            let cursor = cursor_rowid(conn)?;
+
+            let mut stmt = conn.prepare(
+                "SELECT rowid, server_id, id, genre, \
+                        CASE WHEN json_valid(raw_json) THEN json_extract(raw_json, '$.genres') END, \
+                        album_id, library_id \
+                 FROM track \
+                 WHERE deleted = 0 AND rowid > ?1 \
+                 ORDER BY rowid \
+                 LIMIT ?2",
+            )?;
+
+            let rows: Vec<BackfillTrackRow> =
+                stmt
+                    .query_map(params![cursor, BATCH_SIZE], |r| {
+                        Ok((
+                            r.get(0)?,
+                            r.get(1)?,
+                            r.get(2)?,
+                            r.get(3)?,
+                            r.get(4)?,
+                            r.get(5)?,
+                            r.get(6)?,
+                        ))
+                    })?
+                    .collect::<rusqlite::Result<Vec<_>>>()?;
+
+            if rows.is_empty() {
+                conn.execute(
+                    "UPDATE library_data_migration SET completed_at = ?2, cursor_rowid = \
+                     (SELECT COALESCE(MAX(rowid), 0) FROM track WHERE deleted = 0) \
+                     WHERE id = ?1",
+                    params![GENRE_TAGS_MIGRATION_ID, now_unix()],
+                )?;
+                return Ok((total as i64, true));
+            }
+
+            let tx = conn.unchecked_transaction()?;
+            let mut last_rowid = cursor;
+            for (rowid, server_id, track_id, genre, genres_json, album_id, library_id) in rows {
+                let genres = genres_for_track_extracted(
+                    genres_json.as_deref(),
+                    genre.as_deref(),
+                );
+                replace_track_genre_rows(
+                    &tx,
+                    &server_id,
+                    &track_id,
+                    album_id.as_deref(),
+                    library_id.as_deref(),
+                    &genres,
+                )?;
+                last_rowid = rowid;
+            }
+            tx.commit()?;
+
+            conn.execute(
+                "UPDATE library_data_migration SET cursor_rowid = ?2 WHERE id = ?1",
+                params![GENRE_TAGS_MIGRATION_ID, last_rowid],
+            )?;
+
+            let done: i64 = conn.query_row(
+                "SELECT COUNT(*) FROM track WHERE deleted = 0 AND rowid <= ?1",
+                params![last_rowid],
+                |r| r.get(0),
+            )?;
+            Ok((done, false))
+        })?;
+
+        if let Some(app) = app {
+            emit_progress(app, batch_done.max(0) as u64, total)?;
+        }
+
+        if finished {
+            break;
+        }
+    }
+
+    // Belt-and-suspenders: all live tracks processed but `completed_at` not set
+    // (can happen when rowid gaps from soft-deletes make done == total early).
+    store.with_conn_mut("genre_tags.backfill.finalize", |conn| {
+        if migration_completed(conn)? {
+            return Ok(());
+        }
+        let cursor = cursor_rowid(conn)?;
+        let pending: i64 = conn.query_row(
+            "SELECT COUNT(*) FROM track WHERE deleted = 0 AND rowid > ?1",
+            params![cursor],
+            |r| r.get(0),
+        )?;
+        if pending == 0 {
+            conn.execute(
+                "UPDATE library_data_migration SET completed_at = ?2, cursor_rowid = \
+                 (SELECT COALESCE(MAX(rowid), 0) FROM track WHERE deleted = 0) \
+                 WHERE id = ?1",
+                params![GENRE_TAGS_MIGRATION_ID, now_unix()],
+            )?;
+        }
+        Ok(())
+    })?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::repos::track::{TrackRepository, TrackRow};
+    use crate::store::LibraryStore;
+
+    fn track(server_id: &str, id: &str, genre: &str, deleted: bool) -> TrackRow {
+        TrackRow {
+            server_id: server_id.into(),
+            id: id.into(),
+            title: id.into(),
+            title_sort: None,
+            artist: Some("Artist".into()),
+            artist_id: None,
+            album: "Album".into(),
+            album_id: Some("al1".into()),
+            album_artist: None,
+            duration_sec: 100,
+            track_number: Some(1),
+            disc_number: Some(1),
+            year: None,
+            genre: Some(genre.into()),
+            suffix: None,
+            bit_rate: None,
+            size_bytes: None,
+            cover_art_id: None,
+            starred_at: None,
+            user_rating: None,
+            play_count: None,
+            played_at: None,
+            server_path: None,
+            library_id: Some("lib1".into()),
+            isrc: None,
+            mbid_recording: None,
+            bpm: None,
+            replay_gain_track_db: None,
+            replay_gain_album_db: None,
+            content_hash: None,
+            server_updated_at: None,
+            server_created_at: None,
+            deleted,
+            synced_at: 1,
+            raw_json: "{}".into(),
+        }
+    }
+
+    #[test]
+    fn backfill_marks_complete_when_rowid_gaps_leave_pending_rows() {
+        let store = LibraryStore::open_in_memory();
+        let live: Vec<TrackRow> = (1..=5)
+            .map(|n| track("s1", &format!("t{n}"), "Rock", false))
+            .collect();
+        let mut batch = live;
+        for n in 6..=20 {
+            batch.push(track("s1", &format!("del{n}"), "Rock", true));
+        }
+        batch.push(track("s1", "t6", "Jazz", false));
+        TrackRepository::new(&store).upsert_batch(&batch).unwrap();
+
+        run_genre_tags_backfill_impl(&store, None).unwrap();
+
+        let inspect = inspect_genre_tags_backfill(&store).unwrap();
+        assert!(!inspect.needed, "backfill should complete despite rowid gaps");
+    }
+}

src-tauri/crates/psysonic-library/src/lib.rs

@@ -9,7 +9,6 @@
 
 pub(crate) mod bulk_ingest;
 pub mod advanced_search;
-pub mod album_browse;
 pub mod album_compilation_filter;
 pub mod browse_support;
 mod advanced_search_mood;
@@ -26,6 +25,8 @@ pub mod dto;
 pub mod enrichment;
 pub mod filter;
 pub mod genre_album_browse;
+pub mod genre_tags;
+pub mod genre_tags_backfill;
 pub mod mood_groups;
 pub mod live_search;
 pub mod lossless_albums;
@@ -34,7 +35,6 @@ pub mod payload;
 pub mod repos;
 pub mod runtime;
 pub mod search;
-pub mod server_cluster;
 pub mod store;
 pub mod sync;
 pub(crate) mod track_fts;

src-tauri/crates/psysonic-library/src/live_search.rs

@@ -244,8 +244,9 @@ fn query_albums(
            ORDER BY rank \
            LIMIT ?\
          ) \
-         SELECT t.server_id, t.album_id, t.album, t.artist, t.artist_id, t.year, \
-                t.genre, t.cover_art_id, t.starred_at, t.synced_at, MIN(h.rank) AS best_rank \
+         SELECT t.server_id, t.album_id, MAX(t.album), MAX(t.artist), MAX(t.album_artist), \
+                MAX(t.artist_id), MAX(t.year), MAX(t.genre), MAX(t.cover_art_id), \
+                MAX(t.starred_at), MAX(t.synced_at), MIN(h.rank) AS best_rank \
          FROM fts_hits h \
          JOIN track t ON t.rowid = h.rowid \
          WHERE t.server_id = ? \
@@ -261,24 +262,29 @@ fn query_albums(
     params.push(rusqlite::types::Value::Integer(LIVE_SEARCH_FTS_CANDIDATE_CAP));
     params.push(rusqlite::types::Value::Text(server_id.to_string()));
     append_library_scope(&mut sql, &mut params, library_scope);
-    sql.push_str(" GROUP BY t.album_id ORDER BY best_rank LIMIT ?");
+    sql.push_str(" GROUP BY t.server_id, t.album_id ORDER BY best_rank LIMIT ?");
     params.push(rusqlite::types::Value::Integer(i64::from(limit)));
     let mut stmt = conn.prepare(&sql)?;
     let mut out = Vec::new();
     for row in stmt.query_map(rusqlite::params_from_iter(params.iter()), |r| {
+        let track_artist: Option<String> = r.get(3)?;
+        let album_artist: Option<String> = r.get(4)?;
         Ok(LibraryAlbumDto {
             server_id: r.get(0)?,
             id: r.get(1)?,
             name: r.get(2)?,
-            artist: r.get(3)?,
-            artist_id: r.get(4)?,
+            artist: crate::album_compilation_filter::pick_album_group_artist(
+                track_artist,
+                album_artist,
+            ),
+            artist_id: r.get(5)?,
             song_count: None,
             duration_sec: None,
-            year: r.get(5)?,
-            genre: r.get(6)?,
-            cover_art_id: r.get(7)?,
-            starred_at: r.get(8)?,
-            synced_at: r.get(9)?,
+            year: r.get(6)?,
+            genre: r.get(7)?,
+            cover_art_id: r.get(8)?,
+            starred_at: r.get(9)?,
+            synced_at: r.get(10)?,
             raw_json: serde_json::Value::Null,
         })
     })? {

src-tauri/crates/psysonic-library/src/lossless_albums.rs

@@ -2,12 +2,9 @@
 //!
 //! Mirrors the frontend allowlist in `src/utils/library/losslessFormats.ts`.
 
-use crate::dto::{
-    LibraryAlbumDto, LibraryLosslessAlbumsRequest, LibraryLosslessAlbumsResponse, LibrarySortClause,
-    SortDir,
-};
+use crate::dto::{LibraryAlbumDto, LibraryLosslessAlbumsRequest, LibraryLosslessAlbumsResponse};
 use crate::lossless_formats::track_is_lossless_sql;
-use crate::search::library_scope_filter_sql;
+use crate::search::library_scope_equals_sql;
 use crate::store::LibraryStore;
 use rusqlite::types::Value as SqlValue;
 use serde_json::Value;
@@ -18,45 +15,6 @@ fn trimmed_nonempty(s: Option<&str>) -> Option<String> {
         .map(String::from)
 }
 
-fn effective_lossless_scope_ids(req: &LibraryLosslessAlbumsRequest) -> Vec<String> {
-    if let Some(ids) = &req.library_scope_ids {
-        let trimmed: Vec<_> = ids
-            .iter()
-            .filter(|s| !s.trim().is_empty())
-            .cloned()
-            .collect();
-        if !trimmed.is_empty() {
-            return trimmed;
-        }
-    }
-    trimmed_nonempty(req.library_scope.as_deref())
-        .map(|s| vec![s])
-        .unwrap_or_default()
-}
-
-fn lossless_album_order(sort: &[LibrarySortClause]) -> String {
-    let mut keys: Vec<String> = Vec::new();
-    for s in sort {
-        let col = match s.field.as_str() {
-            "name" => "COALESCE(a.name, la.album_name) COLLATE NOCASE",
-            "artist" => "COALESCE(a.artist, la.artist) COLLATE NOCASE",
-            _ => continue,
-        };
-        let dir = match s.dir {
-            SortDir::Asc => "ASC",
-            SortDir::Desc => "DESC",
-        };
-        keys.push(format!("{col} {dir}"));
-    }
-    if keys.is_empty() {
-        return "ORDER BY la.max_bit_depth DESC, \
-          COALESCE(a.name, la.album_name) COLLATE NOCASE ASC, la.album_id ASC"
-            .to_string();
-    }
-    keys.push("la.album_id ASC".to_string());
-    format!("ORDER BY {}", keys.join(", "))
-}
-
 /// Paginated lossless albums for one server. Returns empty when the index has
 /// no matching tracks — caller may fall back to the Navidrome song-stream walk.
 pub fn list_lossless_albums(
@@ -79,32 +37,20 @@ pub fn list_lossless_albums(
     ];
     let mut params: Vec<SqlValue> = vec![SqlValue::Text(req.server_id.clone())];
 
-    let scope_ids = effective_lossless_scope_ids(req);
-    if !scope_ids.is_empty() {
-        let match_expr = crate::search::library_scope_match_sql("t");
-        where_clauses.push(format!("({match_expr}) IS NOT NULL AND TRIM({match_expr}) != ''"));
-        if let (Some(clause), scope_params) = library_scope_filter_sql("t", &scope_ids) {
-            where_clauses.push(clause);
-            for p in scope_params {
-                params.push(p);
-            }
-        }
+    if let Some(scope) = trimmed_nonempty(req.library_scope.as_deref()) {
+        let clause = library_scope_equals_sql("t");
+        where_clauses.push(clause);
+        params.push(SqlValue::Text(scope));
     }
-    push_album_id_allowlist(
-        &mut where_clauses,
-        &mut params,
-        "t.album_id",
-        req.restrict_album_ids.as_deref(),
-    );
 
-    let order_sql = lossless_album_order(&req.sort);
     let where_sql = where_clauses.join(" AND ");
+    let la_artist = crate::album_compilation_filter::sql_track_group_display_artist("la");
     let sql = format!(
         "SELECT \
            la.server_id, \
            la.album_id, \
            COALESCE(a.name, la.album_name), \
-           COALESCE(a.artist, la.artist), \
+           COALESCE(a.artist, {la_artist}), \
            COALESCE(a.artist_id, la.artist_id), \
            COALESCE(a.song_count, la.track_count), \
            COALESCE(a.duration_sec, la.duration_sec), \
@@ -120,6 +66,7 @@ pub fn list_lossless_albums(
              t.album_id, \
              MAX(t.album) AS album_name, \
              MAX(t.artist) AS artist, \
+             MAX(t.album_artist) AS album_artist, \
              MAX(t.artist_id) AS artist_id, \
              MAX(t.year) AS year, \
              MAX(t.genre) AS genre, \
@@ -136,7 +83,9 @@ pub fn list_lossless_albums(
            GROUP BY t.server_id, t.album_id \
          ) la \
          LEFT JOIN album a ON a.server_id = la.server_id AND a.id = la.album_id \
-         {order_sql} \
+         ORDER BY la.max_bit_depth DESC, \
+           COALESCE(a.name, la.album_name) COLLATE NOCASE ASC, \
+           la.album_id ASC \
          LIMIT ? OFFSET ?"
     );
 
@@ -159,26 +108,6 @@ pub fn list_lossless_albums(
     })
 }
 
-fn push_album_id_allowlist(
-    where_clauses: &mut Vec<String>,
-    params: &mut Vec<SqlValue>,
-    column: &str,
-    ids: Option<&[String]>,
-) {
-    let Some(ids) = ids else {
-        return;
-    };
-    if ids.is_empty() {
-        where_clauses.push("1 = 0".to_string());
-        return;
-    }
-    let placeholders = (0..ids.len()).map(|_| "?").collect::<Vec<_>>().join(", ");
-    where_clauses.push(format!("{column} IN ({placeholders})"));
-    for id in ids {
-        params.push(SqlValue::Text(id.clone()));
-    }
-}
-
 fn empty_response() -> LibraryLosslessAlbumsResponse {
     LibraryLosslessAlbumsResponse {
         albums: Vec::new(),
@@ -276,9 +205,6 @@ mod tests {
         LibraryLosslessAlbumsRequest {
             server_id: server.into(),
             library_scope: None,
-            library_scope_ids: None,
-            sort: Vec::new(),
-            restrict_album_ids: None,
             limit,
             offset,
         }
@@ -347,79 +273,6 @@ mod tests {
         assert_eq!(resp.albums[0].id, "al1");
     }
 
-    #[test]
-    fn library_scope_ids_union_narrows_results() {
-        let store = LibraryStore::open_in_memory();
-        let mut a = track_with_suffix("s1", "t1", "al1", "A", "flac", 16);
-        a.library_id = Some("lib1".into());
-        let mut b = track_with_suffix("s1", "t2", "al2", "B", "flac", 16);
-        b.library_id = Some("lib2".into());
-        let mut c = track_with_suffix("s1", "t3", "al3", "C", "flac", 16);
-        c.library_id = Some("lib3".into());
-        TrackRepository::new(&store)
-            .upsert_batch(&[a, b, c])
-            .unwrap();
-
-        let mut scoped = req("s1", 50, 0);
-        scoped.library_scope_ids = Some(vec!["lib1".into(), "lib3".into()]);
-        let resp = list_lossless_albums(&store, &scoped).unwrap();
-        assert_eq!(resp.albums.len(), 2);
-        assert_eq!(resp.albums[0].id, "al1");
-        assert_eq!(resp.albums[1].id, "al3");
-    }
-
-    #[test]
-    fn name_sort_overrides_bit_depth_default() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track_with_suffix("s1", "t1", "al_z", "Zulu", "flac", 24),
-                track_with_suffix("s1", "t2", "al_a", "Alpha", "flac", 16),
-            ])
-            .unwrap();
-
-        let mut sorted = req("s1", 50, 0);
-        sorted.sort = vec![LibrarySortClause {
-            field: "name".into(),
-            dir: SortDir::Asc,
-        }];
-        let resp = list_lossless_albums(&store, &sorted).unwrap();
-        assert_eq!(resp.albums[0].id, "al_a");
-        assert_eq!(resp.albums[1].id, "al_z");
-    }
-
-    #[test]
-    fn matches_suffix_from_raw_json_when_column_null() {
-        let store = LibraryStore::open_in_memory();
-        let mut row = track_with_suffix("s1", "t1", "al_json", "Json", "mp3", 0);
-        row.suffix = None;
-        row.raw_json = r#"{"suffix":"flac","bitDepth":24}"#.into();
-        TrackRepository::new(&store)
-            .upsert_batch(&[row])
-            .unwrap();
-
-        let resp = list_lossless_albums(&store, &req("s1", 50, 0)).unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].id, "al_json");
-    }
-
-    #[test]
-    fn restrict_album_ids_narrows_lossless_results() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track_with_suffix("s1", "t1", "al_keep", "Keep", "flac", 24),
-                track_with_suffix("s1", "t2", "al_drop", "Drop", "flac", 24),
-            ])
-            .unwrap();
-
-        let mut restricted = req("s1", 50, 0);
-        restricted.restrict_album_ids = Some(vec!["al_keep".into()]);
-        let resp = list_lossless_albums(&store, &restricted).unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].id, "al_keep");
-    }
-
     #[test]
     fn pagination_sets_has_more() {
         let store = LibraryStore::open_in_memory();

src-tauri/crates/psysonic-library/src/lossless_formats.rs

@@ -7,22 +7,14 @@ pub const LOSSLESS_SUFFIXES: &[&str] = &[
     "flac", "wav", "wave", "aiff", "aif", "dsf", "dff", "ape", "wv", "shn", "tta",
 ];
 
-/// Effective suffix — hot `track.suffix`, then Navidrome `raw_json.suffix`.
-pub fn track_suffix_expr(table_alias: &str) -> String {
-    format!(
-        "LOWER(COALESCE(NULLIF({table_alias}.suffix, ''), \
-         CAST(json_extract({table_alias}.raw_json, '$.suffix') AS TEXT), ''))"
-    )
-}
-
-/// `track_suffix_expr IN ('flac', …)` for SQL WHERE clauses.
+/// `LOWER(alias.suffix) IN ('flac', …)` for SQL WHERE clauses.
 pub fn track_is_lossless_sql(table_alias: &str) -> String {
     let list = LOSSLESS_SUFFIXES
         .iter()
         .map(|s| format!("'{s}'"))
         .collect::<Vec<_>>()
         .join(", ");
-    format!("{} IN ({list})", track_suffix_expr(table_alias))
+    format!("LOWER({table_alias}.suffix) IN ({list})")
 }
 
 /// Album has at least one indexed lossless track (same allowlist as browse).
@@ -58,6 +50,6 @@ mod tests {
         let sql = track_is_lossless_sql("t");
         assert!(sql.contains("'flac'"));
         assert!(sql.contains("'tta'"));
-        assert!(sql.contains("json_extract(t.raw_json, '$.suffix')"));
+        assert!(sql.starts_with("LOWER(t.suffix) IN ("));
     }
 }

src-tauri/crates/psysonic-library/src/repos/sync_state.rs

@@ -29,7 +29,7 @@ impl<'a> SyncStateRepository<'a> {
     /// if none exists. All non-PK columns fall back to their schema DEFAULTs
     /// (`sync_phase='idle'`, `initial_sync_cursor_json='{}'`, …).
     pub fn ensure(&self, server_id: &str, library_scope: &str) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.ensure", |conn| {
             conn.execute(
                 "INSERT OR IGNORE INTO sync_state (server_id, library_scope) VALUES (?1, ?2)",
                 params![server_id, library_scope],
@@ -73,7 +73,7 @@ impl<'a> SyncStateRepository<'a> {
         cursor: &Value,
     ) -> Result<(), String> {
         let json = serde_json::to_string(cursor).map_err(|e| e.to_string())?;
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_initial_sync_cursor", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, initial_sync_cursor_json) \
                  VALUES (?1, ?2, ?3) \
@@ -134,7 +134,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         flags: u32,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_capability_flags", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, capability_flags) \
                  VALUES (?1, ?2, ?3) \
@@ -192,7 +192,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         phase: &str,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_sync_phase", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, sync_phase) \
                  VALUES (?1, ?2, ?3) \
@@ -212,7 +212,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         last_scan_iso: Option<&str>,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_server_last_scan_iso", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, server_last_scan_iso) \
                  VALUES (?1, ?2, ?3) \
@@ -232,7 +232,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         last_modified_ms: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_indexes_last_modified_ms", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, indexes_last_modified_ms) \
                  VALUES (?1, ?2, ?3) \
@@ -330,7 +330,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         epoch_ms: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_next_poll_at", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, next_poll_at) \
                  VALUES (?1, ?2, ?3) \
@@ -375,7 +375,7 @@ impl<'a> SyncStateRepository<'a> {
         stats: &Value,
     ) -> Result<(), String> {
         let json = serde_json::to_string(stats).map_err(|e| e.to_string())?;
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_poll_stats_json", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, poll_stats_json) \
                  VALUES (?1, ?2, ?3) \
@@ -412,7 +412,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         count: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_local_track_count", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, local_track_count) \
                  VALUES (?1, ?2, ?3) \
@@ -447,7 +447,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         count: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_server_track_count", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, server_track_count) \
                  VALUES (?1, ?2, ?3) \
@@ -488,7 +488,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         unreliable: bool,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_n1_bulk_unreliable", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, n1_bulk_unreliable) \
                  VALUES (?1, ?2, ?3) \
@@ -508,7 +508,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         epoch_ms: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_last_full_sync_at", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, last_full_sync_at) \
                  VALUES (?1, ?2, ?3) \
@@ -528,7 +528,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         epoch_ms: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_last_delta_sync_at", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, last_delta_sync_at) \
                  VALUES (?1, ?2, ?3) \
@@ -549,7 +549,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         last_modified_ms: i64,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_artists_last_modified_ms", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, artists_last_modified_ms) \
                  VALUES (?1, ?2, ?3) \
@@ -570,7 +570,7 @@ impl<'a> SyncStateRepository<'a> {
         library_scope: &str,
         tier: &str,
     ) -> Result<(), String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("sync_state.set_library_tier", |conn| {
             conn.execute(
                 "INSERT INTO sync_state (server_id, library_scope, library_tier) \
                  VALUES (?1, ?2, ?3) \

src-tauri/crates/psysonic-library/src/repos/track.rs

@@ -1,7 +1,23 @@
-use rusqlite::{params, OptionalExtension};
+use rusqlite::{params, OptionalExtension, Transaction};
 
+use crate::genre_tags::{self, genres_for_track_raw_json};
 use crate::store::{LibraryStore, WriteOpTiming};
 
+fn sync_track_genre_row(tx: &Transaction<'_>, row: &TrackRow) -> rusqlite::Result<()> {
+    if row.deleted {
+        return genre_tags::delete_track_genre_for_track(tx, &row.server_id, &row.id);
+    }
+    let genres = genres_for_track_raw_json(&row.raw_json, row.genre.as_deref());
+    genre_tags::replace_track_genre_rows(
+        tx,
+        &row.server_id,
+        &row.id,
+        row.album_id.as_deref(),
+        row.library_id.as_deref(),
+        &genres,
+    )
+}
+
 /// One row of the `track` table — every hot column from spec §5.1 plus
 /// `raw_json` (the full normalized SubsonicSong). Sync code (PR-2/PR-3) is
 /// expected to project ingested payloads into this shape, not to talk SQL
@@ -181,6 +197,7 @@ impl<'a> TrackRepository<'a> {
                         r.raw_json,
                     ])?;
                 }
+                sync_track_genre_row(&tx, r)?;
             }
             drop(upsert);
             tx.commit()?;
@@ -191,7 +208,7 @@ impl<'a> TrackRepository<'a> {
 
     /// Next generation stamp for a full-resync orphan sweep on this server.
     pub fn next_resync_gen(&self, server_id: &str) -> Result<i64, String> {
-        self.store.with_conn("misc", |c| {
+        self.store.with_conn("track.next_resync_gen", |c| {
             c.query_row(
                 "SELECT COALESCE(MAX(resync_gen), 0) + 1 FROM track WHERE server_id = ?1",
                 params![server_id],
@@ -203,7 +220,15 @@ impl<'a> TrackRepository<'a> {
     /// IS-7 — soft-delete live rows not re-stamped during the active resync.
     pub fn sweep_resync_orphans(&self, server_id: &str, resync_gen: i64) -> Result<u32, String> {
         let now = now_unix_ms();
-        let changed = self.store.with_conn_mut("misc", |c| {
+        let changed = self.store.with_conn_mut("track.sweep_resync_orphans", |c| {
+            c.execute(
+                "DELETE FROM track_genre \
+                 WHERE server_id = ?1 AND track_id IN ( \
+                   SELECT id FROM track \
+                   WHERE server_id = ?1 AND deleted = 0 AND resync_gen != ?2 \
+                 )",
+                params![server_id, resync_gen],
+            )?;
             c.execute(
                 "UPDATE track SET deleted = 1, synced_at = ?3 \
                  WHERE server_id = ?1 AND deleted = 0 AND resync_gen != ?2",
@@ -228,6 +253,18 @@ impl<'a> TrackRepository<'a> {
         })
     }
 
+    /// All live rows for a Subsonic track id (any server). Used when legacy offline
+    /// folders name the server by URL index key rather than profile UUID.
+    pub fn find_live_by_id(&self, track_id: &str) -> Result<Vec<TrackRow>, String> {
+        self.store.with_read_conn(|conn| {
+            let mut stmt = conn.prepare(SELECT_TRACK_BY_ID_ONLY)?;
+            let rows = stmt
+                .query_map(params![track_id], row_to_track_row)?
+                .collect::<Result<Vec<_>, _>>()?;
+            Ok(rows)
+        })
+    }
+
     /// Batch SELECT — `library_get_tracks_batch`. Caller-supplied refs
     /// preserve their order in the result; unknown / deleted refs
     /// are silently dropped (frontend reads `tracks.length` against
@@ -292,6 +329,26 @@ impl<'a> TrackRepository<'a> {
         })
     }
 
+    /// Legacy offline rows keyed by library `server_id` (index key scope).
+    pub fn list_offline_local_paths(
+        &self,
+        server_id: &str,
+    ) -> Result<Vec<(String, String, Option<String>)>, String> {
+        self.store.with_read_conn(|conn| {
+            let mut stmt = conn.prepare(
+                "SELECT track_id, local_path, suffix FROM track_offline WHERE server_id = ?1",
+            )?;
+            let rows = stmt.query_map(params![server_id], |row| {
+                Ok((
+                    row.get::<_, String>(0)?,
+                    row.get::<_, String>(1)?,
+                    row.get::<_, Option<String>>(2)?,
+                ))
+            })?;
+            rows.collect::<rusqlite::Result<Vec<_>>>()
+        })
+    }
+
     /// Tracks with `content_hash` and an analysis BPM fact — may still lack waveform/LUFS.
     /// Confirmed per id via [`TrackAnalysisNeedsWorkQuery`].
     pub fn list_analysis_hash_bpm_ids_after(
@@ -386,12 +443,15 @@ impl<'a> TrackRepository<'a> {
         if rows.is_empty() {
             return Ok(RemapStats::default());
         }
-        self.store.with_conn_mut("misc", |conn| {
+        self.store.with_conn_mut("track.upsert_batch_remap", |conn| {
             let tx = conn.transaction()?;
             let mut remapped: Vec<RemapEntry> = Vec::new();
             let mut upsert = tx.prepare_cached(UPSERT_SQL)?;
             let mut remap_lookup = if unstable_track_ids {
-                Some(tx.prepare_cached(REMAP_LOOKUP_SQL)?)
+                Some((
+                    tx.prepare_cached(REMAP_LOOKUP_BY_HASH_SQL)?,
+                    tx.prepare_cached(REMAP_LOOKUP_BY_PATH_SQL)?,
+                ))
             } else {
                 None
             };
@@ -402,11 +462,12 @@ impl<'a> TrackRepository<'a> {
                 // then do we retarget children to the new id, since
                 // child tables FK→track(server_id, id) and would refuse
                 // an UPDATE pointing at an id that doesn't exist yet.
-                let detected_old: Option<String> = if let Some(ref mut lookup) = remap_lookup {
-                    detect_remap_target_cached(lookup, r)?
-                } else {
-                    None
-                };
+                let detected_old: Option<String> =
+                    if let Some((ref mut by_hash, ref mut by_path)) = remap_lookup {
+                        detect_remap_target_cached(by_hash, by_path, r)?
+                    } else {
+                        None
+                    };
 
                 upsert.execute(params![
                     r.server_id,
@@ -445,6 +506,7 @@ impl<'a> TrackRepository<'a> {
                     r.synced_at,
                     r.raw_json,
                 ])?;
+                sync_track_genre_row(&tx, r)?;
 
                 if let Some(old_id) = detected_old {
                     remap_existing_to_new(
@@ -485,38 +547,76 @@ impl<'a> TrackRepository<'a> {
     }
 }
 
-const REMAP_LOOKUP_SQL: &str = r#"
+// Two single-column lookups instead of one `OR` across `content_hash`
+// and `server_path`. The combined `OR` form could not use the partial
+// `idx_track_remap_hash` / `idx_track_remap_path` indexes — SQLite only
+// applies a partial index when the query's WHERE provably implies the
+// index predicate (`… != ''`), and an `OR` spanning two columns blocks
+// the per-branch index plan. The result was a full `track` scan per
+// incoming row → O(rows × catalog) on large libraries (observed:
+// `upsert_batch_remap exec_ms=162001` on a ~200k-track Navidrome sync).
+// Each statement below repeats the index predicate so the planner picks
+// the matching partial index (SEARCH, not SCAN); hash wins over path,
+// matching §6.9's strong-key priority.
+const REMAP_LOOKUP_BY_HASH_SQL: &str = r#"
 SELECT id FROM track
  WHERE server_id = ?1
    AND deleted = 0
-   AND id != ?2
-   AND (
-     (?3 IS NOT NULL AND content_hash = ?3)
-     OR (?4 IS NOT NULL AND server_path = ?4)
-   )
+   AND content_hash IS NOT NULL
+   AND content_hash != ''
+   AND content_hash = ?2
+   AND id != ?3
+ LIMIT 1
+"#;
+
+const REMAP_LOOKUP_BY_PATH_SQL: &str = r#"
+SELECT id FROM track
+ WHERE server_id = ?1
+   AND deleted = 0
+   AND server_path IS NOT NULL
+   AND server_path != ''
+   AND server_path = ?2
+   AND id != ?3
  LIMIT 1
 "#;
 
 /// Run the `SELECT old.id` half of §6.9 — returns `Some(old_id)` if a
 /// non-deleted row with a different id on this server matches the
-/// incoming row's `content_hash` or `server_path`.
+/// incoming row's `content_hash` or `server_path`. Hash is the stronger
+/// key, so it is checked first.
 fn detect_remap_target_cached(
-    lookup: &mut rusqlite::Statement<'_>,
+    by_hash: &mut rusqlite::Statement<'_>,
+    by_path: &mut rusqlite::Statement<'_>,
     incoming: &TrackRow,
 ) -> rusqlite::Result<Option<String>> {
     // Empty-string sentinels are *not* eligible — spec §6.9 explicitly
     // excludes them so the file-tree default never collides.
     let hash = incoming.content_hash.as_deref().filter(|s| !s.is_empty());
     let path = incoming.server_path.as_deref().filter(|s| !s.is_empty());
-    if hash.is_none() && path.is_none() {
-        return Ok(None);
+
+    if let Some(hash) = hash {
+        let old = by_hash
+            .query_row(params![incoming.server_id, hash, incoming.id], |row| {
+                row.get::<_, String>(0)
+            })
+            .optional()?;
+        if old.is_some() {
+            return Ok(old);
+        }
     }
-    lookup
-        .query_row(
-            params![incoming.server_id, incoming.id, hash, path],
-            |row| row.get::<_, String>(0),
-        )
-        .optional()
+
+    if let Some(path) = path {
+        let old = by_path
+            .query_row(params![incoming.server_id, path, incoming.id], |row| {
+                row.get::<_, String>(0)
+            })
+            .optional()?;
+        if old.is_some() {
+            return Ok(old);
+        }
+    }
+
+    Ok(None)
 }
 
 /// Run the §6.9 retarget half — UPDATE every FK-bound child to the
@@ -583,6 +683,13 @@ const SELECT_TRACK_BY_ID: &str = "SELECT server_id, id, title, title_sort, artis
   content_hash, server_updated_at, server_created_at, deleted, synced_at, raw_json \
   FROM track WHERE server_id = ?1 AND id = ?2 AND deleted = 0";
 
+const SELECT_TRACK_BY_ID_ONLY: &str = "SELECT server_id, id, title, title_sort, artist, artist_id, \
+  album, album_id, album_artist, duration_sec, track_number, disc_number, year, genre, suffix, \
+  bit_rate, size_bytes, cover_art_id, starred_at, user_rating, play_count, played_at, \
+  server_path, library_id, isrc, mbid_recording, bpm, replay_gain_track_db, replay_gain_album_db, \
+  content_hash, server_updated_at, server_created_at, deleted, synced_at, raw_json \
+  FROM track WHERE id = ?1 AND deleted = 0";
+
 const SELECT_TRACKS_BY_ALBUM: &str = "SELECT server_id, id, title, title_sort, artist, artist_id, \
   album, album_id, album_artist, duration_sec, track_number, disc_number, year, genre, suffix, \
   bit_rate, size_bytes, cover_art_id, starred_at, user_rating, play_count, played_at, \
@@ -1004,8 +1111,9 @@ mod tests {
         repo.upsert_batch_initial_ingest(&rows).unwrap();
         let elapsed = start.elapsed();
         assert!(
-            elapsed < std::time::Duration::from_millis(500),
-            "initial ingest batch(500) took {elapsed:?}"
+            elapsed < std::time::Duration::from_millis(1000),
+            "initial ingest batch(500) took {elapsed:?}; includes per-row track_genre \
+             maintenance and large raw_json payloads"
         );
     }
 
@@ -1181,6 +1289,48 @@ mod tests {
         assert_eq!(count, 2, "both rows kept; identity-less rows can't shadow");
     }
 
+    #[test]
+    fn remap_lookup_uses_partial_indexes_not_full_scan() {
+        // Regression: the §6.9 remap lookup must hit
+        // idx_track_remap_hash / idx_track_remap_path. The prior
+        // `OR`-based query fell back to a full `track` scan on every
+        // incoming row → O(rows × catalog) stalls on large libraries
+        // (`upsert_batch_remap exec_ms=162001` on a ~200k Navidrome sync).
+        let store = LibraryStore::open_in_memory();
+        let plan = |sql: &str| -> String {
+            store
+                .with_conn("misc", |c| {
+                    let mut stmt = c.prepare(&format!("EXPLAIN QUERY PLAN {sql}"))?;
+                    let rows: rusqlite::Result<Vec<String>> = stmt
+                        .query_map(params!["s1", "v", "id"], |r| r.get::<_, String>(3))?
+                        .collect();
+                    rows
+                })
+                .unwrap()
+                .join("\n")
+        };
+
+        let hash_plan = plan(REMAP_LOOKUP_BY_HASH_SQL);
+        assert!(
+            hash_plan.contains("idx_track_remap_hash"),
+            "hash lookup must use idx_track_remap_hash, got: {hash_plan}"
+        );
+        assert!(
+            !hash_plan.contains("SCAN"),
+            "hash lookup must not full-scan track, got: {hash_plan}"
+        );
+
+        let path_plan = plan(REMAP_LOOKUP_BY_PATH_SQL);
+        assert!(
+            path_plan.contains("idx_track_remap_path"),
+            "path lookup must use idx_track_remap_path, got: {path_plan}"
+        );
+        assert!(
+            !path_plan.contains("SCAN"),
+            "path lookup must not full-scan track, got: {path_plan}"
+        );
+    }
+
     #[test]
     fn remap_is_noop_when_new_id_matches_existing_id() {
         // Standard delta-sync: same id, same hash. Must not trigger

src-tauri/crates/psysonic-library/src/repos/track_id_history.rs

@@ -26,7 +26,7 @@ impl<'a> TrackIdHistoryRepository<'a> {
         server_id: &str,
         old_id: &str,
     ) -> Result<Option<String>, String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("track_id_history.lookup", |conn| {
             conn.query_row(
                 "SELECT new_id FROM track_id_history \
                  WHERE server_id = ?1 AND old_id = ?2",
@@ -40,7 +40,7 @@ impl<'a> TrackIdHistoryRepository<'a> {
     /// Count the rows recorded for this server — used by tests and by
     /// post-sync diagnostics (Settings „Library index" panel later).
     pub fn count_for_server(&self, server_id: &str) -> Result<i64, String> {
-        self.store.with_conn("misc", |conn| {
+        self.store.with_conn("track_id_history.count", |conn| {
             conn.query_row(
                 "SELECT COUNT(*) FROM track_id_history WHERE server_id = ?1",
                 params![server_id],

src-tauri/crates/psysonic-library/src/search.rs

@@ -171,11 +171,6 @@ pub(crate) fn fts_album_title_prefix_match_query(raw: &str) -> Option<String> {
     fts_prefix_token_expr(raw).map(|tokens| format!("album : {tokens}"))
 }
 
-/// All Albums title search — any query word may prefix-match the album column.
-pub(crate) fn fts_album_title_prefix_any_token_match_query(raw: &str) -> Option<String> {
-    fts_prefix_token_or_expr(raw).map(|tokens| format!("album : ({tokens})"))
-}
-
 /// Live Search album match — any query word may hit album or album_artist (Navidrome parity).
 pub(crate) fn fts_album_prefix_any_token_match_query(raw: &str) -> Option<String> {
     fts_prefix_token_or_expr(raw).map(|tokens| {
@@ -231,35 +226,6 @@ pub(crate) fn library_scope_equals_sql(table_alias: &str) -> String {
     format!("{} = ?", library_scope_match_sql(table_alias))
 }
 
-/// `library_id` filter for one or more Navidrome music-folder scopes.
-pub(crate) fn library_scope_filter_sql(
-    table_alias: &str,
-    scope_ids: &[String],
-) -> (Option<String>, Vec<rusqlite::types::Value>) {
-    use rusqlite::types::Value as SqlValue;
-    if scope_ids.is_empty() {
-        return (None, Vec::new());
-    }
-    if scope_ids.len() == 1 {
-        return (
-            Some(library_scope_equals_sql(table_alias)),
-            vec![SqlValue::Text(scope_ids[0].clone())],
-        );
-    }
-    let match_sql = library_scope_match_sql(table_alias);
-    let placeholders = (0..scope_ids.len())
-        .map(|_| "?")
-        .collect::<Vec<_>>()
-        .join(", ");
-    (
-        Some(format!("{match_sql} IN ({placeholders})")),
-        scope_ids
-            .iter()
-            .map(|s| SqlValue::Text(s.clone()))
-            .collect(),
-    )
-}
-
 pub(crate) fn aliased_track_columns(alias: &str) -> String {
     crate::repos::track_columns()
         .split(',')
@@ -354,36 +320,6 @@ pub(crate) fn like_contains(raw: &str) -> String {
     format!("%{escaped}%")
 }
 
-/// Whitespace-split tokens for substring LIKE (any non-empty segment).
-pub(crate) fn like_name_tokens(raw: &str) -> Vec<String> {
-    raw.split_whitespace()
-        .map(str::trim)
-        .filter(|t| !t.is_empty())
-        .map(str::to_string)
-        .collect()
-}
-
-/// `(col LIKE ? OR …)` — any query word may match as a case-insensitive substring.
-pub(crate) fn like_any_token_contains_clause(column: &str, raw: &str) -> Option<(String, Vec<String>)> {
-    let tokens = like_name_tokens(raw);
-    if tokens.is_empty() {
-        return None;
-    }
-    let col = format!("{column} COLLATE NOCASE");
-    if tokens.len() == 1 {
-        return Some((
-            format!("{col} LIKE ? ESCAPE '\\'"),
-            vec![like_contains(&tokens[0])],
-        ));
-    }
-    let parts: Vec<String> = tokens
-        .iter()
-        .map(|_| format!("{col} LIKE ? ESCAPE '\\'"))
-        .collect();
-    let params: Vec<String> = tokens.iter().map(|t| like_contains(t)).collect();
-    Some((format!("({})", parts.join(" OR ")), params))
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -526,23 +462,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn fts_album_title_prefix_any_token_match_query_or_words() {
-        assert_eq!(
-            fts_album_title_prefix_any_token_match_query("dark side").as_deref(),
-            Some("album : (\"dark\"* OR \"side\"*)")
-        );
-    }
-
-    #[test]
-    fn like_any_token_contains_clause_ors_words() {
-        let (sql, params) = like_any_token_contains_clause("a.name", "dark side").unwrap();
-        assert!(sql.contains(" OR "));
-        assert_eq!(params.len(), 2);
-        assert_eq!(params[0], "%dark%");
-        assert_eq!(params[1], "%side%");
-    }
-
     #[test]
     fn fts_track_match_query_or_across_display_columns() {
         let q = fts_track_match_query("manowar").unwrap();

src-tauri/crates/psysonic-library/src/server_cluster/advanced_search.rs

@@ -1,595 +0,0 @@
-//! Cluster-scope advanced search: run per-server advanced search, then merge
-//! winners by cluster identity keys with server-priority precedence.
-
-use std::collections::{BTreeSet, HashMap, HashSet};
-
-use rusqlite::types::Value as SqlValue;
-
-use crate::advanced_search::run_advanced_search;
-use crate::dto::{
-    LibraryAdvancedSearchRequest, LibraryAdvancedSearchResponse, LibraryAlbumDto, LibraryArtistDto,
-    LibraryClusterAdvancedSearchRequest, LibrarySearchTotals, LibraryTrackDto,
-};
-use crate::search::PAGE_LIMIT_MAX;
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-
-pub fn run_cluster_advanced_search(
-    store: &LibraryStore,
-    req: LibraryClusterAdvancedSearchRequest,
-) -> Result<LibraryAdvancedSearchResponse, String> {
-    if req.servers_ordered.is_empty() {
-        return Ok(empty_response(req.skip_totals));
-    }
-
-    let page_limit = req.limit.clamp(1, PAGE_LIMIT_MAX);
-    let page_offset = req.offset as usize;
-    let per_server_limit = req
-        .limit
-        .saturating_add(req.offset)
-        .clamp(1, PAGE_LIMIT_MAX);
-
-    let mut all_tracks: Vec<LibraryTrackDto> = Vec::new();
-    let mut all_albums: Vec<LibraryAlbumDto> = Vec::new();
-    let mut all_artists: Vec<LibraryArtistDto> = Vec::new();
-    let mut applied_filters = BTreeSet::new();
-
-    for server_id in &req.servers_ordered {
-        let server_req = LibraryAdvancedSearchRequest {
-            server_id: server_id.clone(),
-            library_scope: None,
-            library_scope_ids: req
-                .library_scopes
-                .get(server_id)
-                .filter(|ids| !ids.is_empty())
-                .cloned(),
-            query: req.query.clone(),
-            entity_types: req.entity_types.clone(),
-            filters: req.filters.clone(),
-            starred_only: req.starred_only,
-            restrict_album_ids: req
-                .restrict_album_scopes
-                .get(server_id)
-                .filter(|ids| !ids.is_empty())
-                .cloned()
-                .or_else(|| req.restrict_album_ids.clone()),
-            query_album_title_only: req.query_album_title_only,
-            sort: req.sort.clone(),
-            limit: per_server_limit,
-            offset: 0,
-            skip_totals: true,
-        };
-        let resp = run_advanced_search(store, &server_req)?;
-        all_tracks.extend(resp.tracks);
-        all_albums.extend(resp.albums);
-        all_artists.extend(resp.artists);
-        applied_filters.extend(resp.applied_filters);
-    }
-
-    let merged_tracks = merge_tracks_by_cluster_key(store, all_tracks)?;
-    let merged_albums = if req
-        .query
-        .as_ref()
-        .is_some_and(|q| !q.trim().is_empty())
-    {
-        dedupe_album_search_hits(all_albums)
-    } else {
-        merge_albums_by_album_key(store, all_albums)?
-    };
-    let merged_artists = merge_artists_by_artist_key(store, all_artists)?;
-
-    let totals = if req.skip_totals {
-        LibrarySearchTotals::default()
-    } else {
-        LibrarySearchTotals {
-            artists: merged_artists.len() as u32,
-            albums: merged_albums.len() as u32,
-            tracks: merged_tracks.len() as u32,
-        }
-    };
-
-    Ok(LibraryAdvancedSearchResponse {
-        artists: merged_artists
-            .into_iter()
-            .skip(page_offset)
-            .take(page_limit as usize)
-            .collect(),
-        albums: merged_albums
-            .into_iter()
-            .skip(page_offset)
-            .take(page_limit as usize)
-            .collect(),
-        tracks: merged_tracks
-            .into_iter()
-            .skip(page_offset)
-            .take(page_limit as usize)
-            .collect(),
-        totals,
-        applied_filters: applied_filters.into_iter().collect(),
-        source: "local".to_string(),
-    })
-}
-
-fn empty_response(skip_totals: bool) -> LibraryAdvancedSearchResponse {
-    LibraryAdvancedSearchResponse {
-        artists: Vec::new(),
-        albums: Vec::new(),
-        tracks: Vec::new(),
-        totals: if skip_totals {
-            LibrarySearchTotals::default()
-        } else {
-            LibrarySearchTotals {
-                artists: 0,
-                albums: 0,
-                tracks: 0,
-            }
-        },
-        applied_filters: Vec::new(),
-        source: "local".to_string(),
-    }
-}
-
-fn merge_tracks_by_cluster_key(
-    store: &LibraryStore,
-    tracks: Vec<LibraryTrackDto>,
-) -> Result<Vec<LibraryTrackDto>, String> {
-    let refs: Vec<(String, String)> = tracks
-        .iter()
-        .map(|t| (t.server_id.clone(), t.id.clone()))
-        .collect();
-    let key_map = lookup_track_cluster_keys(store, &refs)?;
-
-    let mut seen = HashSet::new();
-    let mut out = Vec::new();
-    for track in tracks {
-        let key = key_map
-            .get(&(track.server_id.clone(), track.id.clone()))
-            .and_then(|v| v.clone())
-            .unwrap_or_else(|| format!("solo:{}:{}", track.server_id, track.id));
-        if seen.insert(key) {
-            out.push(track);
-        }
-    }
-    Ok(out)
-}
-
-/// Text search — keep distinct `(server_id, album_id)` rows; do not collapse
-/// same-server albums that share an `album_key` (tribute / variant titles).
-fn dedupe_album_search_hits(albums: Vec<LibraryAlbumDto>) -> Vec<LibraryAlbumDto> {
-    let mut seen = HashSet::new();
-    let mut out = Vec::new();
-    for album in albums {
-        if seen.insert((album.server_id.clone(), album.id.clone())) {
-            out.push(album);
-        }
-    }
-    out
-}
-
-fn merge_albums_by_album_key(
-    store: &LibraryStore,
-    albums: Vec<LibraryAlbumDto>,
-) -> Result<Vec<LibraryAlbumDto>, String> {
-    let refs: Vec<(String, String)> = albums
-        .iter()
-        .map(|a| (a.server_id.clone(), a.id.clone()))
-        .collect();
-    let key_map = lookup_album_keys(store, &refs)?;
-
-    let mut seen = HashSet::new();
-    let mut out = Vec::new();
-    for album in albums {
-        let key = key_map
-            .get(&(album.server_id.clone(), album.id.clone()))
-            .and_then(|v| v.clone())
-            .unwrap_or_else(|| format!("solo:{}:{}", album.server_id, album.id));
-        if seen.insert(key) {
-            out.push(album);
-        }
-    }
-    Ok(out)
-}
-
-fn merge_artists_by_artist_key(
-    store: &LibraryStore,
-    artists: Vec<LibraryArtistDto>,
-) -> Result<Vec<LibraryArtistDto>, String> {
-    let refs: Vec<(String, String)> = artists
-        .iter()
-        .map(|a| (a.server_id.clone(), a.id.clone()))
-        .collect();
-    let key_map = lookup_artist_keys(store, &refs)?;
-
-    let mut seen = HashSet::new();
-    let mut out = Vec::new();
-    for artist in artists {
-        let key = key_map
-            .get(&(artist.server_id.clone(), artist.id.clone()))
-            .and_then(|v| v.clone())
-            .unwrap_or_else(|| format!("solo:{}:{}", artist.server_id, artist.id));
-        if seen.insert(key) {
-            out.push(artist);
-        }
-    }
-    Ok(out)
-}
-
-fn lookup_track_cluster_keys(
-    store: &LibraryStore,
-    refs: &[(String, String)],
-) -> Result<HashMap<(String, String), Option<String>>, String> {
-    lookup_keys_with_values(
-        store,
-        refs,
-        &format!(
-            "SELECT w.server_id, w.entity_id, k.cluster_key
-             FROM wanted w
-             LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-               ON k.server_id = w.server_id AND k.track_id = w.entity_id"
-        ),
-    )
-}
-
-fn lookup_album_keys(
-    store: &LibraryStore,
-    refs: &[(String, String)],
-) -> Result<HashMap<(String, String), Option<String>>, String> {
-    lookup_keys_with_values(
-        store,
-        refs,
-        &format!(
-            "SELECT w.server_id, w.entity_id, MIN(k.album_key)
-             FROM wanted w
-             LEFT JOIN track t
-               ON t.server_id = w.server_id AND t.album_id = w.entity_id AND t.deleted = 0
-             LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-               ON k.server_id = t.server_id AND k.track_id = t.id
-             GROUP BY w.server_id, w.entity_id"
-        ),
-    )
-}
-
-fn lookup_artist_keys(
-    store: &LibraryStore,
-    refs: &[(String, String)],
-) -> Result<HashMap<(String, String), Option<String>>, String> {
-    lookup_keys_with_values(
-        store,
-        refs,
-        &format!(
-            "SELECT w.server_id, w.entity_id, MIN(k.artist_key)
-             FROM wanted w
-             LEFT JOIN track t
-               ON t.server_id = w.server_id
-              AND COALESCE(NULLIF(t.artist_id, ''), t.artist) = w.entity_id
-              AND t.deleted = 0
-             LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-               ON k.server_id = t.server_id AND k.track_id = t.id
-             GROUP BY w.server_id, w.entity_id"
-        ),
-    )
-}
-
-fn lookup_keys_with_values(
-    store: &LibraryStore,
-    refs: &[(String, String)],
-    query_sql: &str,
-) -> Result<HashMap<(String, String), Option<String>>, String> {
-    if refs.is_empty() {
-        return Ok(HashMap::new());
-    }
-
-    let values_sql = std::iter::repeat_n("(?, ?)", refs.len()).collect::<Vec<_>>().join(", ");
-    let sql = format!("WITH wanted(server_id, entity_id) AS (VALUES {values_sql}) {query_sql}");
-
-    let mut bind: Vec<SqlValue> = Vec::with_capacity(refs.len() * 2);
-    for (server_id, entity_id) in refs {
-        bind.push(SqlValue::Text(server_id.clone()));
-        bind.push(SqlValue::Text(entity_id.clone()));
-    }
-
-    store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let mut rows = stmt.query(rusqlite::params_from_iter(bind.iter()))?;
-        let mut out = HashMap::new();
-        while let Some(row) = rows.next()? {
-            let server_id: String = row.get(0)?;
-            let entity_id: String = row.get(1)?;
-            let key: Option<String> = row.get(2)?;
-            out.insert((server_id, entity_id), key);
-        }
-        Ok(out)
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use crate::filter::EntityKind;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    use super::*;
-
-    fn track(server: &str, id: &str, artist: &str, artist_id: &str, album: &str, album_id: &str) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: "Song".into(),
-            title_sort: None,
-            artist: Some(artist.into()),
-            artist_id: Some(artist_id.into()),
-            album: album.into(),
-            album_id: Some(album_id.into()),
-            album_artist: Some(artist.into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: Some(2024),
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn merges_tracks_by_cluster_key_with_priority() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Band", "art-1", "LP", "alb-1"),
-                track("s2", "t2", "Band", "art-2", "LP", "alb-2"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = run_cluster_advanced_search(
-            &store,
-            LibraryClusterAdvancedSearchRequest {
-                servers_ordered: vec!["s1".into(), "s2".into()],
-                query: None,
-                entity_types: vec![EntityKind::Track],
-                filters: Vec::new(),
-                starred_only: None,
-                restrict_album_ids: None,
-                restrict_album_scopes: HashMap::new(),
-                query_album_title_only: None,
-                sort: Vec::new(),
-                limit: 50,
-                offset: 0,
-                skip_totals: false,
-                library_scopes: HashMap::new(),
-            },
-        )
-        .unwrap();
-
-        assert_eq!(resp.tracks.len(), 1);
-        assert_eq!(resp.tracks[0].server_id, "s1");
-        assert_eq!(resp.totals.tracks, 1);
-        assert_eq!(resp.totals.albums, 0);
-        assert_eq!(resp.totals.artists, 0);
-    }
-
-    fn insert_album(store: &LibraryStore, server: &str, id: &str, name: &str) {
-        store
-            .with_conn("misc", |c| {
-                c.execute(
-                    "INSERT INTO album (server_id, id, name, synced_at, raw_json) \
-                     VALUES (?1, ?2, ?3, 1, '{}')",
-                    rusqlite::params![server, id, name],
-                )
-            })
-            .unwrap();
-    }
-
-    #[test]
-    fn cluster_text_search_respects_per_member_library_scope() {
-        let store = LibraryStore::open_in_memory();
-        let mut in_scope = track("s1", "t1", "Band", "art-1", "Metallica", "alb-in");
-        in_scope.library_id = Some("lib-a".into());
-        let mut out_scope = track("s1", "t2", "Band", "art-2", "Metallica Tribute", "alb-out");
-        out_scope.library_id = Some("lib-b".into());
-        TrackRepository::new(&store)
-            .upsert_batch(&[in_scope, out_scope])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let mut scopes = HashMap::new();
-        scopes.insert("s1".into(), vec!["lib-a".into()]);
-
-        let resp = run_cluster_advanced_search(
-            &store,
-            LibraryClusterAdvancedSearchRequest {
-                servers_ordered: vec!["s1".into()],
-                query: Some("metallica".into()),
-                entity_types: vec![EntityKind::Album],
-                filters: Vec::new(),
-                starred_only: None,
-                restrict_album_ids: None,
-                restrict_album_scopes: HashMap::new(),
-                query_album_title_only: Some(true),
-                sort: Vec::new(),
-                limit: 50,
-                offset: 0,
-                skip_totals: false,
-                library_scopes: scopes,
-            },
-        )
-        .unwrap();
-
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].id, "alb-in");
-    }
-
-    #[test]
-    fn cluster_metallica_text_search_unions_table_and_track_catalog() {
-        let store = LibraryStore::open_in_memory();
-        insert_album(&store, "s1", "al_self", "Metallica");
-        store
-            .with_conn("misc", |c| {
-                c.execute(
-                    "UPDATE album SET song_count = 10 WHERE server_id = 's1' AND id = 'al_self'",
-                    [],
-                )
-            })
-            .unwrap();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Apocalyptica", "art-1", "Plays Metallica Vol. 2", "al_plays"),
-                track("s1", "t2", "Various", "art-2", "The Metallica Blacklist", "al_black"),
-                track("s1", "t3", "Pink Floyd", "art-3", "Wish You Were Here", "al_wish"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = run_cluster_advanced_search(
-            &store,
-            LibraryClusterAdvancedSearchRequest {
-                servers_ordered: vec!["s1".into()],
-                query: Some("metallica".into()),
-                entity_types: vec![EntityKind::Album],
-                filters: Vec::new(),
-                starred_only: None,
-                restrict_album_ids: None,
-                restrict_album_scopes: HashMap::new(),
-                query_album_title_only: Some(true),
-                sort: Vec::new(),
-                limit: 50,
-                offset: 0,
-                skip_totals: false,
-                library_scopes: HashMap::new(),
-            },
-        )
-        .unwrap();
-
-        let ids: Vec<&str> = resp.albums.iter().map(|a| a.id.as_str()).collect();
-        assert_eq!(ids.len(), 3, "expected {ids:?}");
-        assert!(ids.contains(&"al_self"));
-        assert!(ids.contains(&"al_plays"));
-        assert!(ids.contains(&"al_black"));
-    }
-
-    #[test]
-    fn text_search_keeps_distinct_same_server_albums_with_shared_album_key() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Band", "art-1", "Metallica", "alb-1"),
-                track("s1", "t2", "Band", "art-2", "Plays Metallica Vol. 2", "alb-2"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = run_cluster_advanced_search(
-            &store,
-            LibraryClusterAdvancedSearchRequest {
-                servers_ordered: vec!["s1".into()],
-                query: Some("metallica".into()),
-                entity_types: vec![EntityKind::Album],
-                filters: Vec::new(),
-                starred_only: None,
-                restrict_album_ids: None,
-                restrict_album_scopes: HashMap::new(),
-                query_album_title_only: Some(true),
-                sort: Vec::new(),
-                limit: 50,
-                offset: 0,
-                skip_totals: false,
-                library_scopes: HashMap::new(),
-            },
-        )
-        .unwrap();
-
-        assert_eq!(resp.albums.len(), 2);
-    }
-
-    #[test]
-    fn merges_albums_by_album_key_with_priority() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Band", "art-1", "LP", "alb-1"),
-                track("s2", "t2", "Band", "art-2", "LP", "alb-2"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = run_cluster_advanced_search(
-            &store,
-            LibraryClusterAdvancedSearchRequest {
-                servers_ordered: vec!["s1".into(), "s2".into()],
-                query: None,
-                entity_types: vec![EntityKind::Album],
-                filters: Vec::new(),
-                starred_only: None,
-                restrict_album_ids: None,
-                restrict_album_scopes: HashMap::new(),
-                query_album_title_only: None,
-                sort: Vec::new(),
-                limit: 50,
-                offset: 0,
-                skip_totals: false,
-                library_scopes: HashMap::new(),
-            },
-        )
-        .unwrap();
-
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].server_id, "s1");
-    }
-
-    #[test]
-    fn applies_offset_after_merge() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Band A", "art-a1", "LP A", "alb-a1"),
-                track("s2", "t2", "Band A", "art-a2", "LP A", "alb-a2"),
-                track("s1", "t3", "Band B", "art-b1", "LP B", "alb-b1"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = run_cluster_advanced_search(
-            &store,
-            LibraryClusterAdvancedSearchRequest {
-                servers_ordered: vec!["s1".into(), "s2".into()],
-                query: None,
-                entity_types: vec![EntityKind::Track],
-                filters: Vec::new(),
-                starred_only: None,
-                restrict_album_ids: None,
-                restrict_album_scopes: HashMap::new(),
-                query_album_title_only: None,
-                sort: Vec::new(),
-                limit: 1,
-                offset: 1,
-                skip_totals: false,
-                library_scopes: HashMap::new(),
-            },
-        )
-        .unwrap();
-
-        assert_eq!(resp.tracks.len(), 1);
-        assert_eq!(resp.totals.tracks, 2);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/db.rs

@@ -1,171 +0,0 @@
-//! Attached `library-cluster.db` schema and metadata.
-
-use std::path::{Path, PathBuf};
-
-use rusqlite::{params, Connection, OptionalExtension};
-
-pub const CLUSTER_DB_FILENAME: &str = "library-cluster.db";
-pub const ATTACH_ALIAS: &str = "cluster";
-pub const NORM_VERSION: &str = "1";
-
-pub fn cluster_db_path(library_db_path: &Path) -> PathBuf {
-    library_db_path.with_file_name(CLUSTER_DB_FILENAME)
-}
-
-fn escape_sqlite_path(path: &str) -> String {
-    path.replace('\'', "''")
-}
-
-fn init_cluster_on_attached(conn: &Connection) -> rusqlite::Result<()> {
-    conn.execute(
-        &format!(
-            "CREATE TABLE IF NOT EXISTS {ATTACH_ALIAS}.track_cluster_key (
-               server_id    TEXT NOT NULL,
-               track_id     TEXT NOT NULL,
-               cluster_key  TEXT NOT NULL,
-               album_key    TEXT,
-               artist_key   TEXT,
-               duration_sec INTEGER,
-               PRIMARY KEY (server_id, track_id)
-             )"
-        ),
-        [],
-    )?;
-    conn.execute(
-        &format!(
-            "CREATE INDEX IF NOT EXISTS {ATTACH_ALIAS}.idx_cluster_key \
-             ON track_cluster_key(cluster_key)"
-        ),
-        [],
-    )?;
-    conn.execute(
-        &format!(
-            "CREATE INDEX IF NOT EXISTS {ATTACH_ALIAS}.idx_album_key \
-             ON track_cluster_key(album_key)"
-        ),
-        [],
-    )?;
-    conn.execute(
-        &format!(
-            "CREATE INDEX IF NOT EXISTS {ATTACH_ALIAS}.idx_artist_key \
-             ON track_cluster_key(artist_key)"
-        ),
-        [],
-    )?;
-    conn.execute(
-        &format!(
-            "CREATE TABLE IF NOT EXISTS {ATTACH_ALIAS}.cluster_meta (
-               key TEXT PRIMARY KEY,
-               value TEXT
-             )"
-        ),
-        [],
-    )?;
-    init_cluster_meta(conn)?;
-    Ok(())
-}
-
-fn init_cluster_file(cluster_path: &Path) -> rusqlite::Result<()> {
-    let cluster_conn = Connection::open(cluster_path)?;
-    cluster_conn.execute_batch(
-        "CREATE TABLE IF NOT EXISTS track_cluster_key (
-           server_id    TEXT NOT NULL,
-           track_id     TEXT NOT NULL,
-           cluster_key  TEXT NOT NULL,
-           album_key    TEXT,
-           artist_key   TEXT,
-           duration_sec INTEGER,
-           PRIMARY KEY (server_id, track_id)
-         );
-         CREATE INDEX IF NOT EXISTS idx_cluster_key ON track_cluster_key(cluster_key);
-         CREATE INDEX IF NOT EXISTS idx_album_key  ON track_cluster_key(album_key);
-         CREATE INDEX IF NOT EXISTS idx_artist_key ON track_cluster_key(artist_key);
-         CREATE TABLE IF NOT EXISTS cluster_meta (
-           key TEXT PRIMARY KEY,
-           value TEXT
-         );",
-    )?;
-    cluster_conn.execute(
-        "INSERT OR IGNORE INTO cluster_meta (key, value) VALUES ('norm_version', ?1)",
-        params![NORM_VERSION],
-    )?;
-    Ok(())
-}
-
-/// Create or migrate the cluster file, then attach it to `conn`.
-pub fn attach_cluster_database(conn: &Connection, cluster_path: &Path) -> rusqlite::Result<()> {
-    if let Some(parent) = cluster_path.parent() {
-        std::fs::create_dir_all(parent).map_err(|e| {
-            rusqlite::Error::SqliteFailure(
-                rusqlite::ffi::Error::new(rusqlite::ffi::SQLITE_IOERR),
-                Some(e.to_string()),
-            )
-        })?;
-    }
-    init_cluster_file(cluster_path)?;
-    let path_str = escape_sqlite_path(&cluster_path.to_string_lossy());
-    conn.execute_batch(&format!(
-        "ATTACH DATABASE '{path_str}' AS {ATTACH_ALIAS}"
-    ))?;
-    Ok(())
-}
-
-/// In-memory cluster DB for tests — attach then init schema on the alias.
-pub fn attach_cluster_database_uri(conn: &Connection, uri: &str) -> rusqlite::Result<()> {
-    let path_str = escape_sqlite_path(uri);
-    conn.execute_batch(&format!(
-        "ATTACH DATABASE '{path_str}' AS {ATTACH_ALIAS}"
-    ))?;
-    init_cluster_on_attached(conn)
-}
-
-pub fn ensure_cluster_schema(conn: &Connection) -> rusqlite::Result<()> {
-    init_cluster_on_attached(conn)
-}
-
-pub fn init_cluster_meta(conn: &Connection) -> rusqlite::Result<()> {
-    conn.execute(
-        &format!(
-            "INSERT OR IGNORE INTO {ATTACH_ALIAS}.cluster_meta (key, value) VALUES ('norm_version', ?1)"
-        ),
-        params![NORM_VERSION],
-    )?;
-    Ok(())
-}
-
-pub fn stored_norm_version(conn: &Connection) -> rusqlite::Result<Option<String>> {
-    conn.query_row(
-        &format!(
-            "SELECT value FROM {ATTACH_ALIAS}.cluster_meta WHERE key = 'norm_version'"
-        ),
-        [],
-        |row| row.get(0),
-    )
-    .optional()
-}
-
-pub fn needs_norm_rebuild(conn: &Connection) -> rusqlite::Result<bool> {
-    Ok(stored_norm_version(conn)?.as_deref() != Some(NORM_VERSION))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn schema_creates_cluster_tables_on_attach() {
-        let conn = Connection::open_in_memory().unwrap();
-        attach_cluster_database_uri(&conn, "file:cluster_mem?mode=memory&cache=shared").unwrap();
-        let count: i64 = conn
-            .query_row(
-                &format!(
-                    "SELECT COUNT(*) FROM {ATTACH_ALIAS}.sqlite_master \
-                     WHERE type='table' AND name='track_cluster_key'"
-                ),
-                [],
-                |r| r.get(0),
-            )
-            .unwrap();
-        assert_eq!(count, 1);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/keys.rs

@@ -1,135 +0,0 @@
-//! Derive `cluster_key`, `album_key`, and `artist_key` from track metadata.
-
-use std::hash::{Hash, Hasher};
-
-use twox_hash::XxHash64;
-
-use super::norm::norm_field;
-
-const FIELD_SEP: u8 = 0x1f;
-
-/// Precomputed keys for one track. `None` when any required field normalizes empty.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct TrackClusterKeys {
-    pub cluster_key: String,
-    pub album_key: String,
-    pub artist_key: String,
-}
-
-fn effective_artist<'a>(artist: Option<&'a str>, album_artist: Option<&'a str>) -> Option<&'a str> {
-    artist
-        .filter(|s| !s.is_empty())
-        .or_else(|| album_artist.filter(|s| !s.is_empty()))
-}
-
-fn effective_album_artist<'a>(
-    album_artist: Option<&'a str>,
-    artist: Option<&'a str>,
-) -> Option<&'a str> {
-    album_artist
-        .filter(|s| !s.is_empty())
-        .or_else(|| artist.filter(|s| !s.is_empty()))
-}
-
-fn hash_parts(parts: &[&str], sep: Option<u8>) -> String {
-    let mut hasher = XxHash64::with_seed(0);
-    for (i, part) in parts.iter().enumerate() {
-        if i > 0 {
-            if let Some(sep) = sep {
-                sep.hash(&mut hasher);
-            }
-        }
-        part.hash(&mut hasher);
-    }
-    format!("{:016x}", hasher.finish())
-}
-
-/// Compute cluster identity keys from raw track fields (spec §2.1–2.5).
-pub fn compute_track_cluster_keys(
-    artist: Option<&str>,
-    album_artist: Option<&str>,
-    title: &str,
-    album: &str,
-) -> Option<TrackClusterKeys> {
-    let artist_src = effective_artist(artist, album_artist)?;
-    let norm_artist = norm_field(artist_src);
-    let norm_title = norm_field(title);
-    let norm_album = norm_field(album);
-    if norm_artist.is_empty() || norm_title.is_empty() || norm_album.is_empty() {
-        return None;
-    }
-
-    let cluster_key = hash_parts(&[&norm_artist, &norm_title, &norm_album], Some(FIELD_SEP));
-
-    let album_artist_src = effective_album_artist(album_artist, artist).unwrap_or(artist_src);
-    let norm_album_artist = norm_field(album_artist_src);
-    let album_key = hash_parts(&[&norm_album_artist, &norm_album], None);
-    let artist_key = hash_parts(&[&norm_artist], None);
-
-    Some(TrackClusterKeys {
-        cluster_key,
-        album_key,
-        artist_key,
-    })
-}
-
-/// Stable cross-server artist merge key from display name alone (spec §2.5).
-pub fn artist_key_from_display_name(name: &str) -> Option<String> {
-    let norm = norm_field(name);
-    if norm.is_empty() {
-        return None;
-    }
-    Some(hash_parts(&[&norm], None))
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn same_metadata_yields_same_keys() {
-        let a = compute_track_cluster_keys(
-            Some("Artist"),
-            None,
-            "Title",
-            "Album",
-        )
-        .unwrap();
-        let b = compute_track_cluster_keys(
-            Some("artist"),
-            None,
-            "title",
-            "album",
-        )
-        .unwrap();
-        assert_eq!(a, b);
-    }
-
-    #[test]
-    fn artist_falls_back_to_album_artist_for_cluster_key() {
-        let with = compute_track_cluster_keys(None, Some("Band"), "Song", "LP").unwrap();
-        let direct = compute_track_cluster_keys(Some("Band"), None, "Song", "LP").unwrap();
-        assert_eq!(with.cluster_key, direct.cluster_key);
-    }
-
-    #[test]
-    fn empty_title_or_album_yields_none() {
-        assert!(compute_track_cluster_keys(Some("A"), None, "", "Album").is_none());
-        assert!(compute_track_cluster_keys(Some("A"), None, "Title", "").is_none());
-        assert!(compute_track_cluster_keys(None, None, "Title", "Album").is_none());
-    }
-
-    #[test]
-    fn artist_key_from_display_name_matches_track_derived_key() {
-        let from_track = compute_track_cluster_keys(Some("Pink Floyd"), None, "x", "y").unwrap();
-        let from_name = artist_key_from_display_name("Pink Floyd").unwrap();
-        assert_eq!(from_track.artist_key, from_name);
-    }
-
-    #[test]
-    fn punctuation_insensitive_cluster_key() {
-        let a = compute_track_cluster_keys(Some("Pink Floyd"), None, "Time", "Dark Side").unwrap();
-        let b = compute_track_cluster_keys(Some("Pink Floyd"), None, "Time!", "Dark Side.").unwrap();
-        assert_eq!(a.cluster_key, b.cluster_key);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/library_scope.rs

@@ -1,89 +0,0 @@
-//! Per-member music-folder (`library_scope`) filters for merged cluster queries.
-
-use std::collections::HashMap;
-
-use rusqlite::types::Value as SqlValue;
-
-use crate::search::{library_scope_equals_sql, library_scope_match_sql};
-
-/// `(sql_suffix, bind_params)` — AND ( (server + optional scope) OR … ).
-pub(crate) fn scope_filter_sql_and_params(
-    table_alias: &str,
-    servers_ordered: &[String],
-    scopes: &HashMap<String, Vec<String>>,
-) -> (String, Vec<SqlValue>) {
-    if scopes.is_empty() {
-        return (String::new(), Vec::new());
-    }
-    let mut parts = Vec::with_capacity(servers_ordered.len());
-    let mut params = Vec::new();
-    for sid in servers_ordered {
-        if let Some(scope_ids) = scopes.get(sid).filter(|v| !v.is_empty()) {
-            if scope_ids.len() == 1 {
-                let eq = library_scope_equals_sql(table_alias);
-                parts.push(format!("({table_alias}.server_id = ? AND {eq})"));
-                params.push(SqlValue::Text(sid.clone()));
-                params.push(SqlValue::Text(scope_ids[0].clone()));
-            } else {
-                let match_sql = library_scope_match_sql(table_alias);
-                let ph = (0..scope_ids.len())
-                    .map(|_| "?")
-                    .collect::<Vec<_>>()
-                    .join(", ");
-                parts.push(format!(
-                    "({table_alias}.server_id = ? AND {match_sql} IN ({ph}))"
-                ));
-                params.push(SqlValue::Text(sid.clone()));
-                for id in scope_ids {
-                    params.push(SqlValue::Text(id.clone()));
-                }
-            }
-        } else {
-            parts.push(format!("({table_alias}.server_id = ?)"));
-            params.push(SqlValue::Text(sid.clone()));
-        }
-    }
-    (format!(" AND ({})", parts.join(" OR ")), params)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::search::library_scope_filter_sql;
-
-    #[test]
-    fn scope_filter_empty_when_no_scopes() {
-        let (sql, params) = scope_filter_sql_and_params("t", &["s1".into()], &HashMap::new());
-        assert!(sql.is_empty());
-        assert!(params.is_empty());
-    }
-
-    #[test]
-    fn scope_filter_binds_scoped_and_unscoped_members() {
-        let mut scopes = HashMap::new();
-        scopes.insert("s1".into(), vec!["lib-a".into()]);
-        let (sql, params) = scope_filter_sql_and_params(
-            "t",
-            &["s1".into(), "s2".into()],
-            &scopes,
-        );
-        assert!(sql.contains("t.server_id = ?"));
-        assert_eq!(params.len(), 3);
-    }
-
-    #[test]
-    fn scope_filter_multi_folder_on_one_member() {
-        let mut scopes = HashMap::new();
-        scopes.insert("s1".into(), vec!["lib-a".into(), "lib-b".into()]);
-        let (sql, params) = scope_filter_sql_and_params("t", &["s1".into()], &scopes);
-        assert!(sql.contains(" IN ("));
-        assert_eq!(params.len(), 3);
-    }
-
-    #[test]
-    fn single_scope_uses_equals() {
-        let (sql, params) = library_scope_filter_sql("t", &["lib-a".into()]);
-        assert!(sql.unwrap().contains("= ?"));
-        assert_eq!(params.len(), 1);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/list.rs

@@ -1,204 +0,0 @@
-//! Merged track listing for cluster scope (spec §4 Tier 1).
-
-use rusqlite::types::Value as SqlValue;
-
-use crate::dto::{LibraryTrackDto, LibraryTracksEnvelope};
-use crate::repos;
-use crate::search::{aliased_track_columns, PAGE_LIMIT_MAX};
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-use super::library_scope::scope_filter_sql_and_params;
-use super::merge::DURATION_TOLERANCE_SEC;
-use super::priority::{in_list_sql, priority_case_sql};
-
-/// List merged tracks — one row per `cluster_key` (priority winner), solo rows
-/// for empty-key tracks and duration outliers.
-pub fn list_merged_tracks(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-    offset: u32,
-    library_scopes: &std::collections::HashMap<String, Vec<String>>,
-) -> Result<LibraryTracksEnvelope, String> {
-    if servers_ordered.is_empty() {
-        return Ok(LibraryTracksEnvelope {
-            tracks: vec![],
-            total: 0,
-        });
-    }
-    let limit = limit.clamp(1, PAGE_LIMIT_MAX);
-    let offset = offset.min(i32::MAX as u32) as i32;
-    let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-    let (scope_sql, mut scope_params) = scope_filter_sql_and_params("t", servers_ordered, library_scopes);
-
-    let cols = aliased_track_columns("t");
-    let sql = format!(
-        "WITH candidates AS (
-           SELECT
-             t.rowid AS tid,
-             t.server_id,
-             t.id AS track_id,
-             k.cluster_key,
-             COALESCE(k.duration_sec, t.duration_sec) AS dur,
-             ({priority_sql}) AS priority_rank
-           FROM track t
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           WHERE t.deleted = 0 AND t.server_id IN ({in_placeholders}){scope_sql}
-         ),
-         refs AS (
-           SELECT cluster_key, MIN(priority_rank) AS best_rank
-             FROM candidates
-            WHERE cluster_key IS NOT NULL
-            GROUP BY cluster_key
-         ),
-         ref_dur AS (
-           SELECT c.cluster_key, c.dur AS ref_dur
-             FROM candidates c
-             JOIN refs r ON c.cluster_key = r.cluster_key AND c.priority_rank = r.best_rank
-         ),
-         partitioned AS (
-           SELECT c.tid,
-             CASE
-               WHEN c.cluster_key IS NULL THEN 'solo:' || c.server_id || ':' || c.track_id
-               WHEN ABS(c.dur - rd.ref_dur) <= {tol} THEN c.cluster_key
-               ELSE 'solo:' || c.server_id || ':' || c.track_id
-             END AS merge_key,
-             c.priority_rank
-           FROM candidates c
-           LEFT JOIN ref_dur rd ON c.cluster_key = rd.cluster_key
-         ),
-         winners AS (
-           SELECT tid,
-             ROW_NUMBER() OVER (PARTITION BY merge_key ORDER BY priority_rank) AS rn
-           FROM partitioned
-         )
-         SELECT {cols}
-           FROM winners w
-           JOIN track t ON t.rowid = w.tid
-          WHERE w.rn = 1
-          ORDER BY t.title COLLATE NOCASE, t.server_id, t.id
-          LIMIT ? OFFSET ?",
-        tol = DURATION_TOLERANCE_SEC,
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut priority_params);
-    params.append(&mut in_params);
-    params.append(&mut scope_params);
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let tracks: Vec<LibraryTrackDto> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), |r| {
-            repos::row_to_track_row(r).map(|row| LibraryTrackDto::from_row(&row))
-        })?;
-        rows.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-
-    Ok(LibraryTracksEnvelope {
-        total: tracks.len() as u32,
-        tracks,
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use std::collections::HashMap;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    fn track(server: &str, id: &str, title: &str, artist: &str, album: &str, dur: i64) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: title.into(),
-            title_sort: None,
-            artist: Some(artist.into()),
-            artist_id: None,
-            album: album.into(),
-            album_id: None,
-            album_artist: Some(artist.into()),
-            duration_sec: dur,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: None,
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn merge_collapses_same_cluster_key_by_priority() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Song", "Band", "LP", 200),
-                track("s2", "t2", "Song", "Band", "LP", 201),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let env = list_merged_tracks(&store, &["s1".into(), "s2".into()], 50, 0, &HashMap::new()).unwrap();
-        assert_eq!(env.tracks.len(), 1);
-        assert_eq!(env.tracks[0].server_id, "s1");
-    }
-
-    #[test]
-    fn unavailable_priority_falls_through() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Song", "Band", "LP", 200),
-                track("s2", "t2", "Song", "Band", "LP", 201),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let env = list_merged_tracks(&store, &["s2".into()], 50, 0, &std::collections::HashMap::new()).unwrap();
-        assert_eq!(env.tracks.len(), 1);
-        assert_eq!(env.tracks[0].server_id, "s2");
-    }
-
-    #[test]
-    fn empty_key_tracks_never_merge() {
-        let store = LibraryStore::open_in_memory();
-        store
-            .with_conn_mut("misc", |c| {
-                c.execute(
-                    "INSERT INTO track (server_id, id, title, artist, album, duration_sec, synced_at, raw_json) \
-                     VALUES ('s1', 't1', 'A', '', 'X', 1, 1, '{}'), \
-                            ('s2', 't2', 'A', '', 'X', 1, 1, '{}')",
-                    [],
-                )
-            })
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-        let env = list_merged_tracks(&store, &["s1".into(), "s2".into()], 50, 0, &HashMap::new()).unwrap();
-        assert_eq!(env.tracks.len(), 2);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/list_albums.rs

@@ -1,285 +0,0 @@
-//! Merged album listing for cluster scope (spec §4 Tier 1 — dedup by `album_key`).
-
-use rusqlite::types::Value as SqlValue;
-use serde_json::Value;
-
-use crate::dto::{LibraryAlbumDto, LibraryClusterAlbumsResponse};
-use crate::search::PAGE_LIMIT_MAX;
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-use super::library_scope::scope_filter_sql_and_params;
-use super::merge::ALBUM_ROLLUP_AND_PARTITION_CTE;
-use super::priority::{in_list_sql, priority_case_sql};
-
-pub fn list_merged_albums(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-    offset: u32,
-    library_scopes: &std::collections::HashMap<String, Vec<String>>,
-) -> Result<LibraryClusterAlbumsResponse, String> {
-    if servers_ordered.is_empty() {
-        return Ok(LibraryClusterAlbumsResponse {
-            albums: vec![],
-            has_more: false,
-        });
-    }
-    let limit = limit.clamp(1, PAGE_LIMIT_MAX);
-    let offset = offset.min(i32::MAX as u32) as i32;
-    let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-    let (scope_sql, mut scope_params) = scope_filter_sql_and_params("t", servers_ordered, library_scopes);
-
-    let sql = format!(
-        "WITH candidates AS (
-           SELECT
-             t.rowid AS tid,
-             t.server_id,
-             t.album_id,
-             k.album_key,
-             ({priority_sql}) AS priority_rank
-           FROM track t
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           WHERE t.deleted = 0
-             AND t.server_id IN ({in_placeholders})
-             AND t.album_id IS NOT NULL AND t.album_id != ''{scope_sql}
-         ),
-         {ALBUM_ROLLUP_AND_PARTITION_CTE}
-         winners AS (
-           SELECT tid,
-             ROW_NUMBER() OVER (PARTITION BY merge_key ORDER BY priority_rank) AS rn
-           FROM partitioned
-         )
-         SELECT
-           t.server_id,
-           t.album_id,
-           COALESCE(a.name, t.album),
-           COALESCE(a.artist, t.artist),
-           COALESCE(a.artist_id, t.artist_id),
-           COALESCE(a.song_count, (
-             SELECT COUNT(*) FROM track c
-              WHERE c.server_id = t.server_id AND c.album_id = t.album_id AND c.deleted = 0
-           )),
-           COALESCE(a.duration_sec, (
-             SELECT COALESCE(SUM(c.duration_sec), 0) FROM track c
-              WHERE c.server_id = t.server_id AND c.album_id = t.album_id AND c.deleted = 0
-           )),
-           COALESCE(a.year, t.year),
-           COALESCE(a.genre, t.genre),
-           COALESCE(a.cover_art_id, t.cover_art_id),
-           COALESCE(a.starred_at, t.starred_at),
-           COALESCE(a.synced_at, t.synced_at),
-           a.raw_json
-         FROM winners w
-         JOIN track t ON t.rowid = w.tid
-         LEFT JOIN album a ON a.server_id = t.server_id AND a.id = t.album_id
-        WHERE w.rn = 1
-        ORDER BY COALESCE(a.name, t.album) COLLATE NOCASE, t.server_id, t.album_id
-        LIMIT ? OFFSET ?",
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut priority_params);
-    params.append(&mut in_params);
-    params.append(&mut scope_params);
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let albums: Vec<LibraryAlbumDto> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), map_album_row)?;
-        rows.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-
-    let has_more = albums.len() as u32 == limit;
-    Ok(LibraryClusterAlbumsResponse { albums, has_more })
-}
-
-fn map_album_row(r: &rusqlite::Row<'_>) -> rusqlite::Result<LibraryAlbumDto> {
-    let raw: Option<String> = r.get(12)?;
-    Ok(LibraryAlbumDto {
-        server_id: r.get(0)?,
-        id: r.get(1)?,
-        name: r.get(2)?,
-        artist: r.get(3)?,
-        artist_id: r.get(4)?,
-        song_count: r.get(5)?,
-        duration_sec: r.get(6)?,
-        year: r.get(7)?,
-        genre: r.get(8)?,
-        cover_art_id: r.get(9)?,
-        starred_at: r.get(10)?,
-        synced_at: r.get(11)?,
-        raw_json: raw
-            .and_then(|s| serde_json::from_str(&s).ok())
-            .unwrap_or(Value::Null),
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    fn track(
-        server: &str,
-        id: &str,
-        title: &str,
-        artist: &str,
-        album: &str,
-        album_id: &str,
-    ) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: title.into(),
-            title_sort: None,
-            artist: Some(artist.into()),
-            artist_id: Some(format!("art-{server}")),
-            album: album.into(),
-            album_id: Some(album_id.into()),
-            album_artist: Some(artist.into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: Some(2020),
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn merge_collapses_same_album_key_by_priority() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "A", "Band", "LP", "alb1"),
-                track("s2", "t2", "B", "Band", "LP", "alb2"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = list_merged_albums(
-            &store,
-            &["s1".into(), "s2".into()],
-            50,
-            0,
-            &std::collections::HashMap::new(),
-        )
-        .unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].server_id, "s1");
-    }
-
-    #[test]
-    fn rollup_collapses_multiple_tracks_per_server_album() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "A", "Band", "LP", "alb1"),
-                track("s1", "t2", "B", "Band", "LP", "alb1"),
-                track("s1", "t3", "C", "Band", "LP", "alb1"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = list_merged_albums(
-            &store,
-            &["s1".into()],
-            50,
-            0,
-            &std::collections::HashMap::new(),
-        )
-        .unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].id, "alb1");
-    }
-
-    fn track_no_key(server: &str, id: &str, album_id: &str) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: "".into(),
-            title_sort: None,
-            artist: Some("Band".into()),
-            artist_id: Some(format!("art-{server}")),
-            album: "LP".into(),
-            album_id: Some(album_id.into()),
-            album_artist: Some("Band".into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: Some(2020),
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn rollup_uses_album_key_when_some_tracks_lack_keys() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "A", "Band", "LP", "alb1"),
-                track_no_key("s1", "t2", "alb1"),
-                track("s2", "t3", "B", "Band", "LP", "alb2"),
-                track_no_key("s2", "t4", "alb2"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = list_merged_albums(
-            &store,
-            &["s1".into(), "s2".into()],
-            50,
-            0,
-            &std::collections::HashMap::new(),
-        )
-        .unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].server_id, "s1");
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/list_artists.rs

@@ -1,230 +0,0 @@
-//! Merged artist listing for cluster scope (spec §4 Tier 1 — dedup by `artist_key`).
-
-use rusqlite::types::Value as SqlValue;
-use serde_json::Value;
-
-use crate::dto::{LibraryArtistDto, LibraryClusterArtistsResponse};
-use crate::search::PAGE_LIMIT_MAX;
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-use super::library_scope::scope_filter_sql_and_params;
-use super::priority::{in_list_sql, priority_case_sql};
-
-pub fn list_merged_artists(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-    offset: u32,
-    library_scopes: &std::collections::HashMap<String, Vec<String>>,
-) -> Result<LibraryClusterArtistsResponse, String> {
-    if servers_ordered.is_empty() {
-        return Ok(LibraryClusterArtistsResponse {
-            artists: vec![],
-            has_more: false,
-        });
-    }
-    let limit = limit.clamp(1, PAGE_LIMIT_MAX);
-    let offset = offset.min(i32::MAX as u32) as i32;
-    let (in_placeholders, in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, priority_params) = priority_case_sql("c.server_id", servers_ordered);
-    let (scope_sql, scope_params) = scope_filter_sql_and_params("t", servers_ordered, library_scopes);
-
-    // Artist-first catalog: one row per artist (not per track), then merge by
-    // `artist_key`. The previous track-scan + window over every row was O(tracks)
-    // with correlated album counts and blocked the Artists browse page on large libs.
-    let sql = format!(
-        "WITH artist_keys AS (
-           SELECT
-             t.server_id,
-             COALESCE(NULLIF(t.artist_id, ''), t.artist) AS artist_ref,
-             MIN(k.artist_key) AS artist_key
-           FROM track t
-           INNER JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           WHERE t.deleted = 0
-             AND t.server_id IN ({in_placeholders}){scope_sql}
-             AND k.artist_key IS NOT NULL
-           GROUP BY t.server_id, artist_ref
-         ),
-         track_artists AS (
-           SELECT
-             t.server_id,
-             COALESCE(NULLIF(t.artist_id, ''), t.artist) AS id,
-             MAX(t.artist) AS name,
-             COUNT(DISTINCT CASE
-               WHEN t.album_id IS NOT NULL AND t.album_id != '' THEN t.album_id
-             END) AS album_count,
-             MAX(t.synced_at) AS synced_at,
-             CAST(NULL AS TEXT) AS raw_json
-           FROM track t
-           WHERE t.deleted = 0
-             AND t.server_id IN ({in_placeholders}){scope_sql}
-             AND COALESCE(t.artist, '') != ''
-             AND NOT EXISTS (
-               SELECT 1 FROM artist ar
-                WHERE ar.server_id = t.server_id
-                  AND ar.id = COALESCE(NULLIF(t.artist_id, ''), t.artist)
-             )
-           GROUP BY t.server_id, COALESCE(NULLIF(t.artist_id, ''), t.artist)
-         ),
-         catalog AS (
-           SELECT ar.server_id, ar.id, ar.name, ar.album_count, ar.synced_at, ar.raw_json
-             FROM artist ar
-            WHERE ar.server_id IN ({in_placeholders})
-           UNION ALL
-           SELECT server_id, id, name, album_count, synced_at, raw_json
-             FROM track_artists
-         ),
-         candidates AS (
-           SELECT
-             c.server_id,
-             c.id,
-             c.name,
-             c.album_count,
-             c.synced_at,
-             c.raw_json,
-             ({priority_sql}) AS priority_rank,
-             CASE
-               WHEN ak.artist_key IS NOT NULL THEN ak.artist_key
-               ELSE 'solo:' || c.server_id || ':' || c.id
-             END AS merge_key
-           FROM catalog c
-           LEFT JOIN artist_keys ak
-             ON ak.server_id = c.server_id AND ak.artist_ref = c.id
-         ),
-         winners AS (
-           SELECT
-             server_id,
-             id,
-             name,
-             album_count,
-             synced_at,
-             raw_json,
-             ROW_NUMBER() OVER (PARTITION BY merge_key ORDER BY priority_rank) AS rn
-           FROM candidates
-         )
-         SELECT server_id, id, name, album_count, synced_at, raw_json
-           FROM winners
-          WHERE rn = 1
-          ORDER BY name COLLATE NOCASE, server_id
-          LIMIT ? OFFSET ?",
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.extend(in_params.iter().cloned());
-    params.extend(scope_params.iter().cloned());
-    params.extend(in_params.iter().cloned());
-    params.extend(scope_params.iter().cloned());
-    params.extend(in_params.iter().cloned());
-    params.extend(priority_params);
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let artists: Vec<LibraryArtistDto> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), map_artist_row)?;
-        rows.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-
-    let has_more = artists.len() as u32 == limit;
-    Ok(LibraryClusterArtistsResponse { artists, has_more })
-}
-
-fn map_artist_row(r: &rusqlite::Row<'_>) -> rusqlite::Result<LibraryArtistDto> {
-    let raw: Option<String> = r.get(5)?;
-    Ok(LibraryArtistDto {
-        server_id: r.get(0)?,
-        id: r.get(1)?,
-        name: r.get(2)?,
-        album_count: r.get(3)?,
-        synced_at: r.get(4)?,
-        raw_json: raw
-            .and_then(|s| serde_json::from_str(&s).ok())
-            .unwrap_or(Value::Null),
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    fn track(server: &str, id: &str, artist: &str) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: "Song".into(),
-            title_sort: None,
-            artist: Some(artist.into()),
-            artist_id: Some(format!("art-{server}")),
-            album: "LP".into(),
-            album_id: Some("alb1".into()),
-            album_artist: Some(artist.into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: None,
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn merge_collapses_same_artist_key_by_priority() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[track("s1", "t1", "Band"), track("s2", "t2", "Band")])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let resp = list_merged_artists(&store, &["s1".into(), "s2".into()], 50, 0, &std::collections::HashMap::new()).unwrap();
-        assert_eq!(resp.artists.len(), 1);
-        assert_eq!(resp.artists[0].server_id, "s1");
-    }
-
-    #[test]
-    fn prefers_artist_table_album_count_when_present() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[track("s1", "t1", "Band"), track("s2", "t2", "Band")])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-        store
-            .with_conn("test", |conn| {
-                conn.execute(
-                    "INSERT INTO artist (server_id, id, name, album_count, synced_at, raw_json) \
-                     VALUES ('s1', 'art-s1', 'Band', 3, 1, '{}'), \
-                            ('s2', 'art-s2', 'Band', 2, 1, '{}')",
-                    [],
-                )
-            })
-            .unwrap();
-
-        let resp = list_merged_artists(&store, &["s1".into(), "s2".into()], 50, 0, &std::collections::HashMap::new()).unwrap();
-        assert_eq!(resp.artists.len(), 1);
-        assert_eq!(resp.artists[0].server_id, "s1");
-        assert_eq!(resp.artists[0].album_count, Some(3));
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/list_favorites.rs

@@ -1,452 +0,0 @@
-//! Merged favorites — starred on any member counts (spec §4 Tier 2).
-
-use rusqlite::types::Value as SqlValue;
-use serde_json::Value;
-
-use crate::dto::{
-    LibraryAlbumDto, LibraryArtistDto, LibraryClusterAlbumsResponse, LibraryClusterArtistsResponse, LibraryTrackDto,
-    LibraryTracksEnvelope,
-};
-use crate::repos;
-use crate::search::{aliased_track_columns, PAGE_LIMIT_MAX};
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-use super::merge::DURATION_TOLERANCE_SEC;
-use super::priority::{in_list_sql, priority_case_sql};
-
-/// Merged starred tracks — one row per merge group when **any** member is starred.
-pub fn list_merged_favorite_tracks(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-    offset: u32,
-) -> Result<LibraryTracksEnvelope, String> {
-    if servers_ordered.is_empty() {
-        return Ok(LibraryTracksEnvelope {
-            tracks: vec![],
-            total: 0,
-        });
-    }
-    let limit = limit.clamp(1, PAGE_LIMIT_MAX);
-    let offset = offset.min(i32::MAX as u32) as i32;
-    let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-
-    let cols = aliased_track_columns("t");
-    let sql = format!(
-        "WITH candidates AS (
-           SELECT
-             t.rowid AS tid,
-             t.server_id,
-             t.id AS track_id,
-             k.cluster_key,
-             COALESCE(k.duration_sec, t.duration_sec) AS dur,
-             t.starred_at,
-             ({priority_sql}) AS priority_rank
-           FROM track t
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           WHERE t.deleted = 0 AND t.server_id IN ({in_placeholders})
-         ),
-         refs AS (
-           SELECT cluster_key, MIN(priority_rank) AS best_rank
-             FROM candidates
-            WHERE cluster_key IS NOT NULL
-            GROUP BY cluster_key
-         ),
-         ref_dur AS (
-           SELECT c.cluster_key, c.dur AS ref_dur
-             FROM candidates c
-             JOIN refs r ON c.cluster_key = r.cluster_key AND c.priority_rank = r.best_rank
-         ),
-         partitioned AS (
-           SELECT c.tid,
-             CASE
-               WHEN c.cluster_key IS NULL THEN 'solo:' || c.server_id || ':' || c.track_id
-               WHEN ABS(c.dur - rd.ref_dur) <= {tol} THEN c.cluster_key
-               ELSE 'solo:' || c.server_id || ':' || c.track_id
-             END AS merge_key,
-             c.priority_rank
-           FROM candidates c
-           LEFT JOIN ref_dur rd ON c.cluster_key = rd.cluster_key
-         ),
-         starred_merge AS (
-           SELECT DISTINCT p.merge_key
-             FROM partitioned p
-             JOIN candidates c ON c.tid = p.tid
-            WHERE c.starred_at IS NOT NULL
-         ),
-         winners AS (
-           SELECT p.tid, p.merge_key,
-             ROW_NUMBER() OVER (PARTITION BY p.merge_key ORDER BY p.priority_rank) AS rn
-           FROM partitioned p
-           JOIN starred_merge s ON s.merge_key = p.merge_key
-         )
-         SELECT {cols}
-           FROM winners w
-           JOIN track t ON t.rowid = w.tid
-          WHERE w.rn = 1
-          ORDER BY t.title COLLATE NOCASE, t.server_id, t.id
-          LIMIT ? OFFSET ?",
-        tol = DURATION_TOLERANCE_SEC,
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut priority_params);
-    params.append(&mut in_params);
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let tracks: Vec<LibraryTrackDto> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), |r| {
-            repos::row_to_track_row(r).map(|row| LibraryTrackDto::from_row(&row))
-        })?;
-        rows.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-
-    Ok(LibraryTracksEnvelope {
-        total: tracks.len() as u32,
-        tracks,
-    })
-}
-
-/// Merged favorite albums — one row per album merge group when any member is starred.
-pub fn list_merged_favorite_albums(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-    offset: u32,
-) -> Result<LibraryClusterAlbumsResponse, String> {
-    if servers_ordered.is_empty() {
-        return Ok(LibraryClusterAlbumsResponse {
-            albums: vec![],
-            has_more: false,
-        });
-    }
-    let limit = limit.clamp(1, PAGE_LIMIT_MAX);
-    let offset = offset.min(i32::MAX as u32) as i32;
-    let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-
-    let sql = format!(
-        "WITH candidates AS (
-           SELECT
-             t.rowid AS tid,
-             t.server_id,
-             t.album_id,
-             k.album_key,
-             COALESCE(a.starred_at, t.starred_at) AS starred_at,
-             ({priority_sql}) AS priority_rank
-           FROM track t
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           LEFT JOIN album a
-             ON a.server_id = t.server_id AND a.id = t.album_id
-           WHERE t.deleted = 0
-             AND t.server_id IN ({in_placeholders})
-             AND t.album_id IS NOT NULL AND t.album_id != ''
-         ),
-         album_rollup AS (
-           SELECT
-             c.server_id,
-             c.album_id,
-             MIN(c.tid) AS tid,
-             MIN(c.priority_rank) AS priority_rank,
-             MAX(c.album_key) AS album_key,
-             MAX(c.starred_at) AS starred_at
-           FROM candidates c
-           GROUP BY c.server_id, c.album_id
-         ),
-         partitioned AS (
-           SELECT
-             r.tid,
-             CASE
-               WHEN r.album_key IS NOT NULL THEN r.album_key
-               ELSE 'solo:' || r.server_id || ':' || r.album_id
-             END AS merge_key,
-             r.priority_rank,
-             r.starred_at
-           FROM album_rollup r
-         ),
-         starred_merge AS (
-           SELECT DISTINCT merge_key
-             FROM partitioned
-            WHERE starred_at IS NOT NULL
-         ),
-         winners AS (
-           SELECT p.tid,
-             ROW_NUMBER() OVER (PARTITION BY p.merge_key ORDER BY p.priority_rank) AS rn
-           FROM partitioned p
-           JOIN starred_merge s ON s.merge_key = p.merge_key
-         )
-         SELECT
-           t.server_id,
-           t.album_id,
-           COALESCE(a.name, t.album),
-           COALESCE(a.artist, t.artist),
-           COALESCE(a.artist_id, t.artist_id),
-           COALESCE(a.song_count, (
-             SELECT COUNT(*) FROM track c
-              WHERE c.server_id = t.server_id AND c.album_id = t.album_id AND c.deleted = 0
-           )),
-           COALESCE(a.duration_sec, (
-             SELECT COALESCE(SUM(c.duration_sec), 0) FROM track c
-              WHERE c.server_id = t.server_id AND c.album_id = t.album_id AND c.deleted = 0
-           )),
-           COALESCE(a.year, t.year),
-           COALESCE(a.genre, t.genre),
-           COALESCE(a.cover_art_id, t.cover_art_id),
-           COALESCE(a.starred_at, t.starred_at),
-           COALESCE(a.synced_at, t.synced_at),
-           a.raw_json
-         FROM winners w
-         JOIN track t ON t.rowid = w.tid
-         LEFT JOIN album a ON a.server_id = t.server_id AND a.id = t.album_id
-        WHERE w.rn = 1
-        ORDER BY COALESCE(a.name, t.album) COLLATE NOCASE, t.server_id, t.album_id
-        LIMIT ? OFFSET ?",
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut priority_params);
-    params.append(&mut in_params);
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let albums: Vec<LibraryAlbumDto> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), map_album_row)?;
-        rows.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-    Ok(LibraryClusterAlbumsResponse {
-        has_more: albums.len() as u32 == limit,
-        albums,
-    })
-}
-
-/// Merged favorite artists — one row per artist merge group when any member track is starred.
-pub fn list_merged_favorite_artists(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-    offset: u32,
-) -> Result<LibraryClusterArtistsResponse, String> {
-    if servers_ordered.is_empty() {
-        return Ok(LibraryClusterArtistsResponse {
-            artists: vec![],
-            has_more: false,
-        });
-    }
-    let limit = limit.clamp(1, PAGE_LIMIT_MAX);
-    let offset = offset.min(i32::MAX as u32) as i32;
-    let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-
-    let sql = format!(
-        "WITH candidates AS (
-           SELECT
-             t.rowid AS tid,
-             t.server_id,
-             COALESCE(NULLIF(t.artist_id, ''), t.artist) AS artist_ref,
-             k.artist_key,
-             t.starred_at,
-             ({priority_sql}) AS priority_rank
-           FROM track t
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           WHERE t.deleted = 0
-             AND t.server_id IN ({in_placeholders})
-             AND COALESCE(t.artist, '') != ''
-         ),
-         partitioned AS (
-           SELECT c.tid,
-             CASE
-               WHEN c.artist_key IS NULL THEN 'solo:' || c.server_id || ':' || c.artist_ref
-               ELSE c.artist_key
-             END AS merge_key,
-             c.priority_rank,
-             c.starred_at
-           FROM candidates c
-         ),
-         starred_merge AS (
-           SELECT DISTINCT merge_key
-             FROM partitioned
-            WHERE starred_at IS NOT NULL
-         ),
-         winners AS (
-           SELECT p.tid,
-             ROW_NUMBER() OVER (PARTITION BY p.merge_key ORDER BY p.priority_rank) AS rn
-           FROM partitioned p
-           JOIN starred_merge s ON s.merge_key = p.merge_key
-         )
-         SELECT
-           t.server_id,
-           COALESCE(NULLIF(t.artist_id, ''), t.artist),
-           COALESCE(ar.name, t.artist),
-           COALESCE(ar.album_count, (
-             SELECT COUNT(DISTINCT c.album_id) FROM track c
-              WHERE c.server_id = t.server_id
-                AND c.deleted = 0
-                AND c.album_id IS NOT NULL
-                AND (c.artist_id = t.artist_id OR c.artist = t.artist)
-           )),
-           COALESCE(ar.synced_at, t.synced_at),
-           ar.raw_json
-         FROM winners w
-         JOIN track t ON t.rowid = w.tid
-         LEFT JOIN artist ar ON ar.server_id = t.server_id
-           AND ar.id = COALESCE(NULLIF(t.artist_id, ''), t.artist)
-        WHERE w.rn = 1
-        ORDER BY COALESCE(ar.name, t.artist) COLLATE NOCASE, t.server_id
-        LIMIT ? OFFSET ?",
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut priority_params);
-    params.append(&mut in_params);
-    params.push(SqlValue::Integer(limit as i64));
-    params.push(SqlValue::Integer(offset as i64));
-
-    let artists: Vec<LibraryArtistDto> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), map_artist_row)?;
-        rows.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-    Ok(LibraryClusterArtistsResponse {
-        has_more: artists.len() as u32 == limit,
-        artists,
-    })
-}
-
-fn map_album_row(r: &rusqlite::Row<'_>) -> rusqlite::Result<LibraryAlbumDto> {
-    let raw: Option<String> = r.get(12)?;
-    Ok(LibraryAlbumDto {
-        server_id: r.get(0)?,
-        id: r.get(1)?,
-        name: r.get(2)?,
-        artist: r.get(3)?,
-        artist_id: r.get(4)?,
-        song_count: r.get(5)?,
-        duration_sec: r.get(6)?,
-        year: r.get(7)?,
-        genre: r.get(8)?,
-        cover_art_id: r.get(9)?,
-        starred_at: r.get(10)?,
-        synced_at: r.get(11)?,
-        raw_json: raw
-            .and_then(|s| serde_json::from_str(&s).ok())
-            .unwrap_or(Value::Null),
-    })
-}
-
-fn map_artist_row(r: &rusqlite::Row<'_>) -> rusqlite::Result<LibraryArtistDto> {
-    let raw: Option<String> = r.get(5)?;
-    Ok(LibraryArtistDto {
-        server_id: r.get(0)?,
-        id: r.get(1)?,
-        name: r.get(2)?,
-        album_count: r.get(3)?,
-        synced_at: r.get(4)?,
-        raw_json: raw
-            .and_then(|s| serde_json::from_str(&s).ok())
-            .unwrap_or(Value::Null),
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    fn track(server: &str, id: &str, starred: bool) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: "Song".into(),
-            title_sort: None,
-            artist: Some("Band".into()),
-            artist_id: Some("a1".into()),
-            album: "LP".into(),
-            album_id: Some("alb1".into()),
-            album_artist: Some("Band".into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: None,
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: if starred { Some(1) } else { None },
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn starred_on_lower_priority_still_surfaces_merged_row() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[track("s1", "t1", false), track("s2", "t2", true)])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let env = list_merged_favorite_tracks(&store, &["s1".into(), "s2".into()], 50, 0).unwrap();
-        assert_eq!(env.tracks.len(), 1);
-        assert_eq!(env.tracks[0].server_id, "s1");
-    }
-
-    #[test]
-    fn unstarred_merge_group_excluded() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[track("s1", "t1", false), track("s2", "t2", false)])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-        let env = list_merged_favorite_tracks(&store, &["s1".into(), "s2".into()], 50, 0).unwrap();
-        assert!(env.tracks.is_empty());
-    }
-
-    #[test]
-    fn favorite_albums_merge_when_any_member_starred() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[track("s1", "t1", false), track("s2", "t2", true)])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-        let resp = list_merged_favorite_albums(&store, &["s1".into(), "s2".into()], 50, 0).unwrap();
-        assert_eq!(resp.albums.len(), 1);
-        assert_eq!(resp.albums[0].server_id, "s1");
-    }
-
-    #[test]
-    fn favorite_artists_merge_when_any_member_starred() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[track("s1", "t1", false), track("s2", "t2", true)])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-        let resp =
-            list_merged_favorite_artists(&store, &["s1".into(), "s2".into()], 50, 0).unwrap();
-        assert_eq!(resp.artists.len(), 1);
-        assert_eq!(resp.artists[0].server_id, "s1");
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/merge.rs

@@ -1,89 +0,0 @@
-//! Duration guard and partition keys for cluster merge (spec §2.3).
-
-pub const DURATION_TOLERANCE_SEC: i64 = 5;
-
-/// Roll up per-track candidates to one row per `(server_id, album_id)` before
-/// partitioning by `album_key` (spec §4 — album lists dedup by `album_key`).
-pub const ALBUM_ROLLUP_AND_PARTITION_CTE: &str = "
-  album_rollup AS (
-    SELECT
-      c.server_id,
-      c.album_id,
-      MIN(c.tid) AS tid,
-      MIN(c.priority_rank) AS priority_rank,
-      MAX(c.album_key) AS album_key
-    FROM candidates c
-    GROUP BY c.server_id, c.album_id
-  ),
-  partitioned AS (
-    SELECT
-      r.tid,
-      CASE
-        WHEN r.album_key IS NOT NULL THEN r.album_key
-        ELSE 'solo:' || r.server_id || ':' || r.album_id
-      END AS merge_key,
-      r.priority_rank
-    FROM album_rollup r
-  ),
-";
-
-/// Synthetic partition for tracks without a `cluster_key` row (never merged).
-pub fn solo_partition_key(server_id: &str, track_id: &str) -> String {
-    format!("solo:{server_id}:{track_id}")
-}
-
-/// Within one `cluster_key` group, split rows that fall outside ± tolerance of
-/// the reference (priority-1 available candidate duration). Returns partition
-/// keys: merged survivors share `cluster_key`; outliers get solo keys.
-pub fn duration_partitions(
-    cluster_key: &str,
-    rows: &[(String, String, i64, u32)],
-) -> Vec<(String, String, String)> {
-    // (server_id, track_id, duration_sec, priority_rank)
-    if rows.is_empty() {
-        return Vec::new();
-    }
-    let mut sorted = rows.to_vec();
-    sorted.sort_by_key(|(_, _, _, rank)| *rank);
-    let reference_duration = sorted[0].2;
-
-    let mut merged: Vec<&(String, String, i64, u32)> = Vec::new();
-    let mut outliers: Vec<&(String, String, i64, u32)> = Vec::new();
-    for row in &sorted {
-        if (row.2 - reference_duration).abs() <= DURATION_TOLERANCE_SEC {
-            merged.push(row);
-        } else {
-            outliers.push(row);
-        }
-    }
-
-    let mut out = Vec::new();
-    if !merged.is_empty() {
-        merged.sort_by_key(|(_, _, _, rank)| *rank);
-        let (sid, tid, _, _) = merged[0];
-        out.push((cluster_key.to_string(), sid.clone(), tid.clone()));
-    }
-    for (sid, tid, _, _) in outliers {
-        out.push((solo_partition_key(sid, tid), sid.clone(), tid.clone()));
-    }
-    out
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn outlier_splits_to_solo_partition() {
-        let rows = vec![
-            ("s1".into(), "t1".into(), 180, 0),
-            ("s2".into(), "t2".into(), 182, 1),
-            ("s3".into(), "t3".into(), 240, 2),
-        ];
-        let parts = duration_partitions("ck1", &rows);
-        assert_eq!(parts.len(), 2);
-        assert_eq!(parts[0].0, "ck1");
-        assert_eq!(parts[0].1, "s1");
-        assert_eq!(parts[1].0, "solo:s3:t3");
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/mod.rs

@@ -1,44 +0,0 @@
-//! Server cluster identity — derived `cluster_key` / `album_key` / `artist_key`
-//! in a separate attached SQLite DB (`library-cluster.db`). Distinct from
-//! `repos/play_session/cluster.rs` (listening-session time-gap grouping).
-
-mod detail;
-mod advanced_search;
-mod db;
-mod keys;
-mod library_scope;
-mod list;
-mod list_albums;
-mod list_artists;
-mod list_favorites;
-mod merge;
-mod norm;
-mod play_stats;
-mod priority;
-mod rebuild;
-mod resolve;
-mod search;
-
-pub use detail::{cluster_album_detail, cluster_artist_detail};
-pub use advanced_search::run_cluster_advanced_search;
-pub use db::{
-    attach_cluster_database, attach_cluster_database_uri, cluster_db_path, ensure_cluster_schema,
-    init_cluster_meta, needs_norm_rebuild, ATTACH_ALIAS, CLUSTER_DB_FILENAME, NORM_VERSION,
-};
-pub use keys::{compute_track_cluster_keys, TrackClusterKeys};
-pub use list::list_merged_tracks;
-pub use list_albums::list_merged_albums;
-pub use list_artists::list_merged_artists;
-pub use list_favorites::list_merged_favorite_tracks;
-pub use list_favorites::{list_merged_favorite_albums, list_merged_favorite_artists};
-pub use merge::DURATION_TOLERANCE_SEC;
-pub use play_stats::{
-    cluster_day_detail, cluster_heatmap, cluster_most_played, cluster_recent_days, cluster_year_summary,
-};
-pub use rebuild::{
-    rebuild_all_cluster_keys, rebuild_cluster_keys_for_server, rebuild_if_norm_version_stale,
-};
-pub use resolve::{
-    cluster_key_for_track, resolve_candidates_by_cluster_key, resolve_candidates_for_track,
-};
-pub use search::{run_cluster_random_tracks, run_cluster_search};

src-tauri/crates/psysonic-library/src/server_cluster/norm.rs

@@ -1,43 +0,0 @@
-//! Cheap Unicode normalization for cluster identity keys (spec §2.2).
-
-use unicode_normalization::UnicodeNormalization;
-
-/// NFD → drop combining marks → lowercase → letters/digits only.
-pub fn norm_field(raw: &str) -> String {
-    raw.nfd()
-        .filter(|c| !unicode_normalization::char::is_combining_mark(*c))
-        .flat_map(|c| c.to_lowercase())
-        .filter(|c| c.is_alphanumeric())
-        .collect()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn strips_diacritics_and_punctuation() {
-        assert_eq!(norm_field("Café"), "cafe");
-        assert_eq!(norm_field("Mötley Crüe"), "motleycrue");
-        assert_eq!(norm_field("Hello, World!"), "helloworld");
-    }
-
-    #[test]
-    fn lowercases_and_removes_whitespace() {
-        assert_eq!(norm_field("  Pink   FLOYD  "), "pinkfloyd");
-        assert_eq!(norm_field("The\tBeatles\n"), "thebeatles");
-    }
-
-    #[test]
-    fn preserves_unicode_letters_and_digits() {
-        assert_eq!(norm_field("Sigur Rós"), "sigurros");
-        assert_eq!(norm_field("Track 99"), "track99");
-    }
-
-    #[test]
-    fn empty_or_non_alnum_only_becomes_empty() {
-        assert_eq!(norm_field(""), "");
-        assert_eq!(norm_field("   "), "");
-        assert_eq!(norm_field("---"), "");
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/play_stats.rs

@@ -1,595 +0,0 @@
-//! Cluster-scoped player statistics — aggregate `play_session` across members (spec §4 Tier 2).
-
-use std::collections::HashMap;
-
-use rusqlite::types::Value as SqlValue;
-
-use crate::dto::{
-    PlaySessionDayDetailDto, PlaySessionDayTotalsDto, PlaySessionDayTrackDto, PlaySessionHeatmapDayDto,
-    PlaySessionMostPlayedDto, PlaySessionRecentDayDto, PlaySessionYearSummaryDto,
-};
-use crate::repos;
-use crate::search::aliased_track_columns;
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-use super::merge::DURATION_TOLERANCE_SEC;
-use super::priority::in_list_sql;
-use super::priority::priority_case_sql;
-
-const RECENT_DAYS_LIMIT_MAX: u32 = 90;
-const MOST_PLAYED_LIMIT_MAX: u32 = 200;
-
-#[derive(Default)]
-struct DayAgg {
-    total_listened_sec: f64,
-    track_play_count: u32,
-    full_count: u32,
-    partial_count: u32,
-    plays: Vec<(i64, f64)>,
-}
-
-fn server_filter_sql(servers_ordered: &[String]) -> Result<(String, Vec<SqlValue>), String> {
-    if servers_ordered.is_empty() {
-        return Err("servers_ordered required".into());
-    }
-    let (placeholders, params) = in_list_sql(servers_ordered);
-    Ok((format!("ps.server_id IN ({placeholders})"), params))
-}
-
-fn unique_track_expr() -> &'static str {
-    "COALESCE(k.cluster_key, ps.server_id || ':' || ps.track_id)"
-}
-
-fn count_listening_sessions(plays: &[(i64, f64)]) -> u32 {
-    const GAP_MS: i64 = 30 * 60 * 1000;
-    if plays.is_empty() {
-        return 0;
-    }
-    let mut sorted = plays.to_vec();
-    sorted.sort_by_key(|p| p.0);
-    let mut sessions = 1u32;
-    let mut prev_end = sorted[0].0 + (sorted[0].1 * 1000.0) as i64;
-    for (started, listened) in sorted.iter().skip(1) {
-        if *started - prev_end > GAP_MS {
-            sessions += 1;
-        }
-        let end = *started + (*listened * 1000.0) as i64;
-        prev_end = prev_end.max(end);
-    }
-    sessions
-}
-
-fn validate_date_iso(date_iso: &str) -> Result<(), String> {
-    if date_iso.len() != 10 || date_iso.as_bytes()[4] != b'-' || date_iso.as_bytes()[7] != b'-' {
-        return Err("dateIso must be YYYY-MM-DD".into());
-    }
-    let year: i32 = date_iso[0..4]
-        .parse()
-        .map_err(|_| "dateIso must be YYYY-MM-DD".to_string())?;
-    let month: u32 = date_iso[5..7]
-        .parse()
-        .map_err(|_| "dateIso must be YYYY-MM-DD".to_string())?;
-    let day: u32 = date_iso[8..10]
-        .parse()
-        .map_err(|_| "dateIso must be YYYY-MM-DD".to_string())?;
-    if year < 1970 || !(1..=12).contains(&month) || !(1..=31).contains(&day) {
-        return Err("dateIso must be YYYY-MM-DD".into());
-    }
-    Ok(())
-}
-
-pub fn cluster_year_summary(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    year: i32,
-) -> Result<PlaySessionYearSummaryDto, String> {
-    let (server_sql, mut params) = server_filter_sql(servers_ordered)?;
-    let year_str = year.to_string();
-    let unique = unique_track_expr();
-
-    store
-        .with_read_conn(|conn| {
-            let sql = format!(
-                "SELECT \
-                   COALESCE(SUM(ps.listened_sec), 0.0), \
-                   COUNT(*), \
-                   COUNT(DISTINCT {unique}), \
-                   COUNT(DISTINCT date(ps.started_at_ms / 1000, 'unixepoch', 'localtime')), \
-                   COALESCE(SUM(CASE WHEN ps.completion = 'full' THEN 1 ELSE 0 END), 0), \
-                   COALESCE(SUM(CASE WHEN ps.completion = 'partial' THEN 1 ELSE 0 END), 0) \
-                 FROM play_session ps \
-                 LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k \
-                   ON k.server_id = ps.server_id AND k.track_id = ps.track_id \
-                 WHERE {server_sql} \
-                   AND strftime('%Y', ps.started_at_ms / 1000, 'unixepoch', 'localtime') = ?",
-            );
-            params.push(SqlValue::Text(year_str.clone()));
-
-            let totals = conn.query_row(
-                &sql,
-                rusqlite::params_from_iter(params.iter()),
-                |row| {
-                    Ok((
-                        row.get::<_, f64>(0)?,
-                        row.get::<_, i64>(1)? as u32,
-                        row.get::<_, i64>(2)? as u32,
-                        row.get::<_, i64>(3)? as u32,
-                        row.get::<_, i64>(4)? as u32,
-                        row.get::<_, i64>(5)? as u32,
-                    ))
-                },
-            )?;
-
-            let plays_sql = format!(
-                "SELECT ps.started_at_ms, ps.listened_sec \
-                 FROM play_session ps \
-                 WHERE {server_sql} \
-                   AND strftime('%Y', ps.started_at_ms / 1000, 'unixepoch', 'localtime') = ? \
-                 ORDER BY ps.started_at_ms ASC",
-            );
-            let mut play_params = params[..params.len() - 1].to_vec();
-            play_params.push(SqlValue::Text(year_str));
-
-            let mut stmt = conn.prepare(&plays_sql)?;
-            let plays = stmt
-                .query_map(rusqlite::params_from_iter(play_params.iter()), |row| {
-                    Ok((row.get::<_, i64>(0)?, row.get::<_, f64>(1)?))
-                })?
-                .collect::<rusqlite::Result<Vec<_>>>()?;
-
-            let (
-                total_listened_sec,
-                track_play_count,
-                unique_track_count,
-                listening_day_count,
-                full_count,
-                partial_count,
-            ) = totals;
-            Ok(PlaySessionYearSummaryDto {
-                total_listened_sec,
-                session_count: count_listening_sessions(&plays),
-                track_play_count,
-                unique_track_count,
-                listening_day_count,
-                full_count,
-                partial_count,
-            })
-        })
-        .map_err(|e| e.to_string())
-}
-
-pub fn cluster_heatmap(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    year: i32,
-) -> Result<Vec<PlaySessionHeatmapDayDto>, String> {
-    let (server_sql, mut params) = server_filter_sql(servers_ordered)?;
-    params.push(SqlValue::Text(year.to_string()));
-
-    store
-        .with_read_conn(|conn| {
-            let sql = format!(
-                "SELECT \
-                   date(ps.started_at_ms / 1000, 'unixepoch', 'localtime') AS d, \
-                   COUNT(*) AS n \
-                 FROM play_session ps \
-                 WHERE {server_sql} \
-                   AND strftime('%Y', ps.started_at_ms / 1000, 'unixepoch', 'localtime') = ? \
-                 GROUP BY d \
-                 ORDER BY d ASC",
-            );
-            let mut stmt = conn.prepare(&sql)?;
-            let rows = stmt
-                .query_map(rusqlite::params_from_iter(params.iter()), |row| {
-                    Ok(PlaySessionHeatmapDayDto {
-                        date: row.get(0)?,
-                        track_play_count: row.get::<_, i64>(1)? as u32,
-                    })
-                })?
-                .collect::<rusqlite::Result<Vec<_>>>()?;
-            Ok(rows)
-        })
-        .map_err(|e| e.to_string())
-}
-
-pub fn cluster_day_detail(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    date_iso: &str,
-) -> Result<PlaySessionDayDetailDto, String> {
-    validate_date_iso(date_iso)?;
-    let (server_sql, mut params) = server_filter_sql(servers_ordered)?;
-    params.push(SqlValue::Text(date_iso.to_string()));
-
-    store
-        .with_read_conn(|conn| {
-            let totals_sql = format!(
-                "SELECT \
-                   COALESCE(SUM(ps.listened_sec), 0.0), \
-                   COUNT(*), \
-                   COALESCE(SUM(CASE WHEN ps.completion = 'full' THEN 1 ELSE 0 END), 0), \
-                   COALESCE(SUM(CASE WHEN ps.completion = 'partial' THEN 1 ELSE 0 END), 0) \
-                 FROM play_session ps \
-                 WHERE {server_sql} \
-                   AND date(ps.started_at_ms / 1000, 'unixepoch', 'localtime') = ?",
-            );
-            let (total_listened_sec, track_play_count, full_count, partial_count) = conn.query_row(
-                &totals_sql,
-                rusqlite::params_from_iter(params.iter()),
-                |row| {
-                    Ok((
-                        row.get::<_, f64>(0)?,
-                        row.get::<_, i64>(1)? as u32,
-                        row.get::<_, i64>(2)? as u32,
-                        row.get::<_, i64>(3)? as u32,
-                    ))
-                },
-            )?;
-
-            let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-            let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-            let cols = aliased_track_columns("t");
-            let rows_sql = format!(
-                "WITH sessions AS (
-                   SELECT
-                     ps.started_at_ms,
-                     ps.listened_sec,
-                     ps.completion,
-                     COALESCE(k.cluster_key, 'solo:' || ps.server_id || ':' || ps.track_id) AS merge_key
-                   FROM play_session ps
-                   LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-                     ON k.server_id = ps.server_id AND k.track_id = ps.track_id
-                   WHERE {server_sql}
-                     AND date(ps.started_at_ms / 1000, 'unixepoch', 'localtime') = ?
-                 ),
-                 candidates AS (
-                   SELECT
-                     t.rowid AS tid,
-                     t.server_id,
-                     t.id AS track_id,
-                     k.cluster_key,
-                     COALESCE(k.duration_sec, t.duration_sec) AS dur,
-                     ({priority_sql}) AS priority_rank
-                   FROM track t
-                   LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-                     ON k.server_id = t.server_id AND k.track_id = t.id
-                   WHERE t.deleted = 0 AND t.server_id IN ({in_placeholders})
-                 ),
-                 refs AS (
-                   SELECT cluster_key, MIN(priority_rank) AS best_rank
-                     FROM candidates
-                    WHERE cluster_key IS NOT NULL
-                    GROUP BY cluster_key
-                 ),
-                 ref_dur AS (
-                   SELECT c.cluster_key, c.dur AS ref_dur
-                     FROM candidates c
-                     JOIN refs r ON c.cluster_key = r.cluster_key AND c.priority_rank = r.best_rank
-                 ),
-                 partitioned AS (
-                   SELECT c.tid,
-                     CASE
-                       WHEN c.cluster_key IS NULL THEN 'solo:' || c.server_id || ':' || c.track_id
-                       WHEN ABS(c.dur - rd.ref_dur) <= {tol} THEN c.cluster_key
-                       ELSE 'solo:' || c.server_id || ':' || c.track_id
-                     END AS merge_key,
-                     c.priority_rank
-                   FROM candidates c
-                   LEFT JOIN ref_dur rd ON c.cluster_key = rd.cluster_key
-                 ),
-                 winners AS (
-                   SELECT merge_key, tid,
-                     ROW_NUMBER() OVER (PARTITION BY merge_key ORDER BY priority_rank) AS rn
-                   FROM partitioned
-                 )
-                 SELECT {cols}, s.listened_sec, s.completion, s.started_at_ms
-                   FROM sessions s
-                   JOIN winners w ON w.merge_key = s.merge_key AND w.rn = 1
-                   JOIN track t ON t.rowid = w.tid
-                  ORDER BY s.started_at_ms DESC",
-                tol = DURATION_TOLERANCE_SEC,
-            );
-
-            let mut rows_params = params.clone();
-            rows_params.append(&mut priority_params);
-            rows_params.append(&mut in_params);
-
-            let track_col_count = repos::track_columns().split(',').count();
-            let mut stmt = conn.prepare(&rows_sql)?;
-            let tracks = stmt
-                .query_map(rusqlite::params_from_iter(rows_params.iter()), |row| {
-                    let track = repos::row_to_track_row(row).map(|r| crate::dto::LibraryTrackDto::from_row(&r))?;
-                    Ok(PlaySessionDayTrackDto {
-                        server_id: track.server_id,
-                        track_id: track.id,
-                        title: track.title,
-                        artist: track.artist,
-                        listened_sec: row.get(track_col_count)?,
-                        completion: row.get(track_col_count + 1)?,
-                        started_at_ms: row.get(track_col_count + 2)?,
-                    })
-                })?
-                .collect::<rusqlite::Result<Vec<_>>>()?;
-
-            let plays: Vec<(i64, f64)> = tracks
-                .iter()
-                .map(|t| (t.started_at_ms, t.listened_sec))
-                .collect();
-            Ok(PlaySessionDayDetailDto {
-                totals: PlaySessionDayTotalsDto {
-                    total_listened_sec,
-                    session_count: count_listening_sessions(&plays),
-                    track_play_count,
-                    full_count,
-                    partial_count,
-                },
-                tracks,
-            })
-        })
-        .map_err(|e| e.to_string())
-}
-
-pub fn cluster_recent_days(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-) -> Result<Vec<PlaySessionRecentDayDto>, String> {
-    let limit = limit.clamp(1, RECENT_DAYS_LIMIT_MAX);
-    let (server_sql, params) = server_filter_sql(servers_ordered)?;
-
-    store
-        .with_read_conn(|conn| {
-            let sql = format!(
-                "SELECT
-                   date(ps.started_at_ms / 1000, 'unixepoch', 'localtime') AS d,
-                   ps.started_at_ms,
-                   ps.listened_sec,
-                   ps.completion
-                 FROM play_session ps
-                 WHERE {server_sql}
-                 ORDER BY d DESC, ps.started_at_ms ASC",
-            );
-            let mut stmt = conn.prepare(&sql)?;
-            let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), |row| {
-                Ok((
-                    row.get::<_, String>(0)?,
-                    row.get::<_, i64>(1)?,
-                    row.get::<_, f64>(2)?,
-                    row.get::<_, String>(3)?,
-                ))
-            })?;
-
-            let mut by_day: HashMap<String, DayAgg> = HashMap::new();
-            for row in rows {
-                let (date, started_at_ms, listened_sec, completion) = row?;
-                let agg = by_day.entry(date).or_default();
-                agg.total_listened_sec += listened_sec;
-                agg.track_play_count += 1;
-                if completion == "full" {
-                    agg.full_count += 1;
-                } else {
-                    agg.partial_count += 1;
-                }
-                agg.plays.push((started_at_ms, listened_sec));
-            }
-
-            let mut out: Vec<PlaySessionRecentDayDto> = by_day
-                .into_iter()
-                .map(|(date, agg)| PlaySessionRecentDayDto {
-                    date,
-                    total_listened_sec: agg.total_listened_sec,
-                    session_count: count_listening_sessions(&agg.plays),
-                    track_play_count: agg.track_play_count,
-                    full_count: agg.full_count,
-                    partial_count: agg.partial_count,
-                })
-                .collect();
-            out.sort_by(|a, b| b.date.cmp(&a.date));
-            out.truncate(limit as usize);
-            Ok(out)
-        })
-        .map_err(|e| e.to_string())
-}
-
-pub fn cluster_most_played(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    limit: u32,
-) -> Result<Vec<PlaySessionMostPlayedDto>, String> {
-    let limit = limit.clamp(1, MOST_PLAYED_LIMIT_MAX);
-    let (server_sql, mut stats_params) = server_filter_sql(servers_ordered)?;
-    let (in_placeholders, mut in_params) = in_list_sql(servers_ordered);
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-    let cols = aliased_track_columns("t");
-    let col_count = repos::track_columns().split(',').count();
-
-    let sql = format!(
-        "WITH session_counts AS (
-           SELECT
-             COALESCE(k.cluster_key, 'solo:' || ps.server_id || ':' || ps.track_id) AS merge_key,
-             COUNT(*) AS track_play_count,
-             COALESCE(SUM(ps.listened_sec), 0.0) AS total_listened_sec
-           FROM play_session ps
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = ps.server_id AND k.track_id = ps.track_id
-           WHERE {server_sql}
-           GROUP BY merge_key
-         ),
-         candidates AS (
-           SELECT
-             t.rowid AS tid,
-             t.server_id,
-             t.id AS track_id,
-             k.cluster_key,
-             COALESCE(k.duration_sec, t.duration_sec) AS dur,
-             ({priority_sql}) AS priority_rank
-           FROM track t
-           LEFT JOIN {ATTACH_ALIAS}.track_cluster_key k
-             ON k.server_id = t.server_id AND k.track_id = t.id
-           WHERE t.deleted = 0 AND t.server_id IN ({in_placeholders})
-         ),
-         refs AS (
-           SELECT cluster_key, MIN(priority_rank) AS best_rank
-             FROM candidates
-            WHERE cluster_key IS NOT NULL
-            GROUP BY cluster_key
-         ),
-         ref_dur AS (
-           SELECT c.cluster_key, c.dur AS ref_dur
-             FROM candidates c
-             JOIN refs r ON c.cluster_key = r.cluster_key AND c.priority_rank = r.best_rank
-         ),
-         partitioned AS (
-           SELECT c.tid,
-             CASE
-               WHEN c.cluster_key IS NULL THEN 'solo:' || c.server_id || ':' || c.track_id
-               WHEN ABS(c.dur - rd.ref_dur) <= {tol} THEN c.cluster_key
-               ELSE 'solo:' || c.server_id || ':' || c.track_id
-             END AS merge_key,
-             c.priority_rank
-           FROM candidates c
-           LEFT JOIN ref_dur rd ON c.cluster_key = rd.cluster_key
-         ),
-         winners AS (
-           SELECT merge_key, tid,
-             ROW_NUMBER() OVER (PARTITION BY merge_key ORDER BY priority_rank) AS rn
-           FROM partitioned
-         )
-         SELECT {cols}, sc.track_play_count, sc.total_listened_sec
-           FROM session_counts sc
-           JOIN winners w ON w.merge_key = sc.merge_key AND w.rn = 1
-           JOIN track t ON t.rowid = w.tid
-          ORDER BY sc.track_play_count DESC, sc.total_listened_sec DESC, t.title COLLATE NOCASE ASC
-          LIMIT ?",
-        tol = DURATION_TOLERANCE_SEC,
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut stats_params);
-    params.append(&mut priority_params);
-    params.append(&mut in_params);
-    params.push(SqlValue::Integer(limit as i64));
-
-    store
-        .with_read_conn(|conn| {
-            let mut stmt = conn.prepare(&sql)?;
-            let rows = stmt.query_map(rusqlite::params_from_iter(params.iter()), |row| {
-                let track =
-                    repos::row_to_track_row(row).map(|r| crate::dto::LibraryTrackDto::from_row(&r))?;
-                Ok(PlaySessionMostPlayedDto {
-                    track,
-                    track_play_count: row.get::<_, i64>(col_count)? as u32,
-                    total_listened_sec: row.get(col_count + 1)?,
-                })
-            })?;
-            rows.collect::<rusqlite::Result<Vec<_>>>()
-        })
-        .map_err(|e| e.to_string())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    fn track(server: &str, id: &str, title: &str, artist: &str, album: &str) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: title.into(),
-            title_sort: None,
-            artist: Some(artist.into()),
-            artist_id: Some(format!("art-{server}")),
-            album: album.into(),
-            album_id: Some(format!("alb-{server}")),
-            album_artist: Some(artist.into()),
-            duration_sec: 200,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: None,
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn day_detail_merges_track_identity_to_cluster_winner() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Song", "Band", "LP"),
-                track("s2", "t2", "Song", "Band", "LP"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        store
-            .with_conn_mut("test", |conn| {
-                conn.execute(
-                    "INSERT INTO play_session (server_id, track_id, started_at_ms, listened_sec, position_max_sec, completion, end_reason)
-                     VALUES (?1, ?2, ?3, 120.0, 120.0, 'full', 'ended')",
-                    rusqlite::params!["s2", "t2", 1_000i64],
-                )?;
-                Ok(())
-            })
-            .unwrap();
-
-        let detail = cluster_day_detail(&store, &["s1".into(), "s2".into()], "1970-01-01").unwrap();
-        assert_eq!(detail.tracks.len(), 1);
-        assert_eq!(detail.tracks[0].server_id, "s1");
-        assert_eq!(detail.tracks[0].track_id, "t1");
-        assert_eq!(detail.totals.track_play_count, 1);
-    }
-
-    #[test]
-    fn most_played_aggregates_cluster_members() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[
-                track("s1", "t1", "Song", "Band", "LP"),
-                track("s2", "t2", "Song", "Band", "LP"),
-            ])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        store
-            .with_conn_mut("test", |conn| {
-                conn.execute(
-                    "INSERT INTO play_session (server_id, track_id, started_at_ms, listened_sec, position_max_sec, completion, end_reason)
-                     VALUES
-                     ('s1', 't1', 1700000000000, 60.0, 60.0, 'partial', 'ended'),
-                     ('s2', 't2', 1700000100000, 90.0, 90.0, 'full', 'ended')",
-                    [],
-                )?;
-                Ok(())
-            })
-            .unwrap();
-
-        let rows = cluster_most_played(&store, &["s1".into(), "s2".into()], 10).unwrap();
-        assert_eq!(rows.len(), 1);
-        assert_eq!(rows[0].track.server_id, "s1");
-        assert_eq!(rows[0].track_play_count, 2);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/priority.rs

@@ -1,44 +0,0 @@
-//! Priority rank SQL from an ordered server list (index 0 = highest).
-
-use rusqlite::types::Value as SqlValue;
-
-/// Build `CASE server_col WHEN ? THEN 0 … ELSE 9999 END` plus bind values.
-pub fn priority_case_sql(server_col: &str, servers_ordered: &[String]) -> (String, Vec<SqlValue>) {
-    if servers_ordered.is_empty() {
-        return ("9999".to_string(), Vec::new());
-    }
-    let mut sql = format!("CASE {server_col}");
-    let mut params = Vec::with_capacity(servers_ordered.len());
-    for (rank, sid) in servers_ordered.iter().enumerate() {
-        sql.push_str(&format!(" WHEN ? THEN {rank}"));
-        params.push(SqlValue::Text(sid.clone()));
-    }
-    sql.push_str(" ELSE 9999 END");
-    (sql, params)
-}
-
-/// `server_id IN (?,?,…)` placeholders and bind values.
-pub fn in_list_sql(servers: &[String]) -> (String, Vec<SqlValue>) {
-    if servers.is_empty() {
-        return ("0".to_string(), Vec::new());
-    }
-    let placeholders = vec!["?"; servers.len()].join(", ");
-    let params = servers
-        .iter()
-        .map(|s| SqlValue::Text(s.clone()))
-        .collect();
-    (placeholders, params)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn priority_case_orders_servers() {
-        let (sql, params) = priority_case_sql("t.server_id", &["a".into(), "b".into()]);
-        assert!(sql.contains("WHEN ? THEN 0"));
-        assert!(sql.contains("WHEN ? THEN 1"));
-        assert_eq!(params.len(), 2);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/rebuild.rs

@@ -1,362 +0,0 @@
-//! Batch rebuild of `track_cluster_key` — source of truth for cluster identity.
-
-use rusqlite::{params, Transaction};
-
-use crate::store::LibraryStore;
-
-use super::db::{self, ATTACH_ALIAS, NORM_VERSION};
-use super::keys::compute_track_cluster_keys;
-
-const REBUILD_BATCH_SIZE: usize = 5_000;
-
-struct TrackRow {
-    server_id: String,
-    track_id: String,
-    artist: Option<String>,
-    album_artist: Option<String>,
-    title: String,
-    album: String,
-    duration_sec: i64,
-}
-
-fn fetch_live_tracks(
-    tx: &Transaction<'_>,
-    server_id: Option<&str>,
-) -> rusqlite::Result<Vec<TrackRow>> {
-    let (sql, bind): (&str, Option<&str>) = match server_id {
-        Some(_) => (
-            "SELECT server_id, id, artist, album_artist, title, album, duration_sec \
-             FROM track WHERE deleted = 0 AND server_id = ?1",
-            server_id,
-        ),
-        None => (
-            "SELECT server_id, id, artist, album_artist, title, album, duration_sec \
-             FROM track WHERE deleted = 0",
-            None,
-        ),
-    };
-    let mut stmt = tx.prepare(sql)?;
-    let rows = match bind {
-        Some(sid) => stmt.query_map(params![sid], map_track_row)?.collect(),
-        None => stmt.query_map([], map_track_row)?.collect(),
-    };
-    rows
-}
-
-fn map_track_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<TrackRow> {
-    Ok(TrackRow {
-        server_id: row.get(0)?,
-        track_id: row.get(1)?,
-        artist: row.get(2)?,
-        album_artist: row.get(3)?,
-        title: row.get(4)?,
-        album: row.get(5)?,
-        duration_sec: row.get(6)?,
-    })
-}
-
-fn upsert_batch(tx: &Transaction<'_>, batch: &[(TrackRow, super::keys::TrackClusterKeys)]) -> rusqlite::Result<()> {
-    let mut stmt = tx.prepare(&format!(
-        "INSERT INTO {ATTACH_ALIAS}.track_cluster_key \
-         (server_id, track_id, cluster_key, album_key, artist_key, duration_sec) \
-         VALUES (?1, ?2, ?3, ?4, ?5, ?6) \
-         ON CONFLICT(server_id, track_id) DO UPDATE SET \
-           cluster_key = excluded.cluster_key, \
-           album_key = excluded.album_key, \
-           artist_key = excluded.artist_key, \
-           duration_sec = excluded.duration_sec"
-    ))?;
-    for (row, keys) in batch {
-        stmt.execute(params![
-            row.server_id,
-            row.track_id,
-            keys.cluster_key,
-            keys.album_key,
-            keys.artist_key,
-            row.duration_sec,
-        ])?;
-    }
-    Ok(())
-}
-
-fn rebuild_in_tx(
-    tx: &Transaction<'_>,
-    server_id: Option<&str>,
-    clear_scope: bool,
-) -> rusqlite::Result<u32> {
-    if clear_scope {
-        match server_id {
-            Some(sid) => {
-                tx.execute(
-                    &format!("DELETE FROM {ATTACH_ALIAS}.track_cluster_key WHERE server_id = ?1"),
-                    params![sid],
-                )?;
-            }
-            None => {
-                tx.execute(
-                    &format!("DELETE FROM {ATTACH_ALIAS}.track_cluster_key"),
-                    [],
-                )?;
-            }
-        }
-    }
-
-    let tracks = fetch_live_tracks(tx, server_id)?;
-    let mut written = 0u32;
-    let mut batch: Vec<(TrackRow, super::keys::TrackClusterKeys)> = Vec::new();
-
-    for row in tracks {
-        let Some(keys) = compute_track_cluster_keys(
-            row.artist.as_deref(),
-            row.album_artist.as_deref(),
-            &row.title,
-            &row.album,
-        ) else {
-            continue;
-        };
-        batch.push((row, keys));
-        if batch.len() >= REBUILD_BATCH_SIZE {
-            upsert_batch(tx, &batch)?;
-            written = written.saturating_add(batch.len() as u32);
-            batch.clear();
-        }
-    }
-    if !batch.is_empty() {
-        upsert_batch(tx, &batch)?;
-        written = written.saturating_add(batch.len() as u32);
-    }
-
-    tx.execute(
-        &format!(
-            "INSERT INTO {ATTACH_ALIAS}.cluster_meta (key, value) VALUES ('norm_version', ?1) \
-             ON CONFLICT(key) DO UPDATE SET value = excluded.value"
-        ),
-        params![NORM_VERSION],
-    )?;
-
-    Ok(written)
-}
-
-/// Rebuild cluster keys for every live track in the library index.
-pub fn rebuild_all_cluster_keys(store: &LibraryStore) -> Result<u32, String> {
-    store.with_conn_mut("cluster_rebuild_all", |conn| {
-        let tx = conn.transaction()?;
-        let count = rebuild_in_tx(&tx, None, true)?;
-        tx.commit()?;
-        Ok(count)
-    })
-}
-
-/// Rebuild cluster keys for one server's live tracks (deletes stale rows first).
-pub fn rebuild_cluster_keys_for_server(
-    store: &LibraryStore,
-    server_id: &str,
-) -> Result<u32, String> {
-    store.with_conn_mut("cluster_rebuild_server", |conn| {
-        let tx = conn.transaction()?;
-        let count = rebuild_in_tx(&tx, Some(server_id), true)?;
-        tx.commit()?;
-        Ok(count)
-    })
-}
-
-/// Rebuild when `cluster_meta.norm_version` lags the compiled rules.
-pub fn rebuild_if_norm_version_stale(store: &LibraryStore) -> Result<Option<u32>, String> {
-    let stale = store.with_conn("cluster_norm_check", db::needs_norm_rebuild)?;
-    if !stale {
-        return Ok(None);
-    }
-    rebuild_all_cluster_keys(store).map(Some)
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::store::LibraryStore;
-    use rusqlite::params;
-
-    fn seed_track(
-        store: &LibraryStore,
-        server: &str,
-        id: &str,
-        artist: &str,
-        title: &str,
-        album: &str,
-        duration: i64,
-    ) {
-        store
-            .with_conn_mut("misc", |conn| {
-                conn.execute(
-                    "INSERT INTO track (server_id, id, title, artist, album, duration_sec, synced_at, raw_json) \
-                     VALUES (?1, ?2, ?3, ?4, ?5, ?6, 1, '{}')",
-                    params![server, id, title, artist, album, duration],
-                )
-            })
-            .unwrap();
-    }
-
-    #[test]
-    fn rebuild_is_idempotent() {
-        let store = LibraryStore::open_in_memory();
-        seed_track(&store, "s1", "t1", "Artist", "Song", "Album", 200);
-        seed_track(&store, "s2", "t2", "Artist", "Song", "Album", 205);
-
-        let first = rebuild_all_cluster_keys(&store).unwrap();
-        assert_eq!(first, 2);
-
-        let count_after: i64 = store
-            .with_conn("misc", |c| {
-                c.query_row(
-                    &format!("SELECT COUNT(*) FROM {ATTACH_ALIAS}.track_cluster_key"),
-                    [],
-                    |r| r.get(0),
-                )
-            })
-            .unwrap();
-        assert_eq!(count_after, 2);
-
-        let second = rebuild_all_cluster_keys(&store).unwrap();
-        assert_eq!(second, 2);
-        let count_again: i64 = store
-            .with_conn("misc", |c| {
-                c.query_row(
-                    &format!("SELECT COUNT(*) FROM {ATTACH_ALIAS}.track_cluster_key"),
-                    [],
-                    |r| r.get(0),
-                )
-            })
-            .unwrap();
-        assert_eq!(count_again, 2);
-    }
-
-    #[test]
-    fn tracks_with_empty_fields_get_no_row() {
-        let store = LibraryStore::open_in_memory();
-        seed_track(&store, "s1", "t1", "", "Song", "Album", 100);
-        seed_track(&store, "s1", "t2", "Artist", "Song", "Album", 100);
-
-        let written = rebuild_all_cluster_keys(&store).unwrap();
-        assert_eq!(written, 1);
-
-        let count: i64 = store
-            .with_conn("misc", |c| {
-                c.query_row(
-                    &format!("SELECT COUNT(*) FROM {ATTACH_ALIAS}.track_cluster_key"),
-                    [],
-                    |r| r.get(0),
-                )
-            })
-            .unwrap();
-        assert_eq!(count, 1);
-    }
-
-    #[test]
-    fn same_cluster_key_across_servers_after_rebuild() {
-        let store = LibraryStore::open_in_memory();
-        seed_track(&store, "s1", "t1", "Band", "Hit", "LP", 180);
-        seed_track(&store, "s2", "t9", "Band", "Hit", "LP", 182);
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        let keys: Vec<String> = store
-            .with_conn("misc", |c| {
-                let mut stmt = c.prepare(&format!(
-                    "SELECT cluster_key FROM {ATTACH_ALIAS}.track_cluster_key ORDER BY server_id"
-                ))?;
-                let rows: rusqlite::Result<Vec<String>> =
-                    stmt.query_map([], |r| r.get(0))?.collect();
-                rows
-            })
-            .unwrap();
-        assert_eq!(keys.len(), 2);
-        assert_eq!(keys[0], keys[1]);
-    }
-
-    #[test]
-    fn per_server_rebuild_replaces_stale_rows() {
-        let store = LibraryStore::open_in_memory();
-        seed_track(&store, "s1", "t1", "A", "One", "X", 1);
-        seed_track(&store, "s2", "t1", "B", "Two", "Y", 2);
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        store
-            .with_conn_mut("misc", |conn| {
-                conn.execute(
-                    "UPDATE track SET title = 'Updated' WHERE server_id = 's1' AND id = 't1'",
-                    [],
-                )
-            })
-            .unwrap();
-
-        rebuild_cluster_keys_for_server(&store, "s1").unwrap();
-
-        let title_norm_row: Option<String> = store
-            .with_conn("misc", |c| {
-                use rusqlite::OptionalExtension;
-                c.query_row(
-                    &format!(
-                        "SELECT k.cluster_key FROM {ATTACH_ALIAS}.track_cluster_key k \
-                         JOIN track t ON t.server_id = k.server_id AND t.id = k.track_id \
-                         WHERE k.server_id = 's1' AND k.track_id = 't1'"
-                    ),
-                    [],
-                    |r| r.get(0),
-                )
-                .optional()
-            })
-            .unwrap();
-        assert!(title_norm_row.is_some());
-
-        let s2_count: i64 = store
-            .with_conn("misc", |c| {
-                c.query_row(
-                    &format!(
-                        "SELECT COUNT(*) FROM {ATTACH_ALIAS}.track_cluster_key WHERE server_id = 's2'"
-                    ),
-                    [],
-                    |r| r.get(0),
-                )
-            })
-            .unwrap();
-        assert_eq!(s2_count, 1);
-    }
-
-    #[test]
-    fn norm_version_bump_triggers_full_rebuild() {
-        let store = LibraryStore::open_in_memory();
-        seed_track(&store, "s1", "t1", "Artist", "Old", "Album", 1);
-        rebuild_all_cluster_keys(&store).unwrap();
-
-        store
-            .with_conn_mut("misc", |conn| {
-                conn.execute(
-                    &format!(
-                        "UPDATE {ATTACH_ALIAS}.cluster_meta SET value = '0' WHERE key = 'norm_version'"
-                    ),
-                    [],
-                )
-            })
-            .unwrap();
-
-        assert!(
-            store
-                .with_conn("misc", db::needs_norm_rebuild)
-                .unwrap()
-        );
-
-        let rebuilt = rebuild_if_norm_version_stale(&store).unwrap();
-        assert_eq!(rebuilt, Some(1));
-
-        let version: String = store
-            .with_conn("misc", |c| {
-                c.query_row(
-                    &format!(
-                        "SELECT value FROM {ATTACH_ALIAS}.cluster_meta WHERE key = 'norm_version'"
-                    ),
-                    [],
-                    |r| r.get(0),
-                )
-            })
-            .unwrap();
-        assert_eq!(version, NORM_VERSION);
-    }
-}

src-tauri/crates/psysonic-library/src/server_cluster/resolve.rs

@@ -1,198 +0,0 @@
-//! Resolve cluster candidates for playback / writes (spec §5–6).
-
-use rusqlite::types::Value as SqlValue;
-use rusqlite::OptionalExtension;
-
-use crate::dto::LibraryClusterCandidateDto;
-use crate::store::LibraryStore;
-
-use super::db::ATTACH_ALIAS;
-use super::merge::duration_partitions;
-use super::priority::priority_case_sql;
-
-/// All `(server_id, track_id)` rows sharing a `cluster_key`, ordered by priority.
-pub fn resolve_candidates_by_cluster_key(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    cluster_key: &str,
-) -> Result<Vec<LibraryClusterCandidateDto>, String> {
-    if servers_ordered.is_empty() || cluster_key.is_empty() {
-        return Ok(Vec::new());
-    }
-    let (priority_sql, mut priority_params) = priority_case_sql("t.server_id", servers_ordered);
-    let in_placeholders = vec!["?"; servers_ordered.len()].join(", ");
-    let mut in_params: Vec<SqlValue> = servers_ordered
-        .iter()
-        .map(|s| SqlValue::Text(s.clone()))
-        .collect();
-
-    let sql = format!(
-        "SELECT t.server_id, t.id, COALESCE(k.duration_sec, t.duration_sec), ({priority_sql})
-           FROM {ATTACH_ALIAS}.track_cluster_key k
-           JOIN track t ON t.server_id = k.server_id AND t.id = k.track_id
-          WHERE k.cluster_key = ? AND t.deleted = 0 AND t.server_id IN ({in_placeholders})
-          ORDER BY 4, t.server_id, t.id"
-    );
-
-    let mut params: Vec<SqlValue> = Vec::new();
-    params.append(&mut priority_params);
-    params.push(SqlValue::Text(cluster_key.to_string()));
-    params.append(&mut in_params);
-
-    let rows: Vec<(String, String, i64, u32)> = store.with_read_conn(|conn| {
-        let mut stmt = conn.prepare(&sql)?;
-        let collected = stmt.query_map(rusqlite::params_from_iter(params.iter()), |r| {
-            Ok((r.get(0)?, r.get(1)?, r.get(2)?, r.get::<_, i64>(3)? as u32))
-        })?;
-        collected.collect::<rusqlite::Result<Vec<_>>>()
-    })?;
-
-    let with_rank = rows;
-
-    let partitions = duration_partitions(cluster_key, &with_rank);
-    let winner = partitions.first();
-    Ok(with_rank
-        .into_iter()
-        .map(|(server_id, track_id, duration_sec, priority_rank)| {
-            let is_winner = winner
-                .map(|(_, ws, wt)| ws == &server_id && wt == &track_id)
-                .unwrap_or(false);
-            LibraryClusterCandidateDto {
-                server_id,
-                track_id,
-                duration_sec,
-                priority_rank,
-                is_winner,
-            }
-        })
-        .collect())
-}
-
-/// Resolve `cluster_key` from a seed track, then return candidates.
-pub fn resolve_candidates_for_track(
-    store: &LibraryStore,
-    servers_ordered: &[String],
-    server_id: &str,
-    track_id: &str,
-) -> Result<Vec<LibraryClusterCandidateDto>, String> {
-    let cluster_key: Option<String> = store.with_read_conn(|conn| {
-        conn.query_row(
-            &format!(
-                "SELECT cluster_key FROM {ATTACH_ALIAS}.track_cluster_key \
-                 WHERE server_id = ?1 AND track_id = ?2"
-            ),
-            rusqlite::params![server_id, track_id],
-            |r| r.get(0),
-        )
-        .optional()
-    })?;
-
-    let Some(cluster_key) = cluster_key else {
-        return Ok(vec![LibraryClusterCandidateDto {
-            server_id: server_id.to_string(),
-            track_id: track_id.to_string(),
-            duration_sec: track_duration(store, server_id, track_id)?,
-            priority_rank: servers_ordered
-                .iter()
-                .position(|s| s == server_id)
-                .unwrap_or(9999) as u32,
-            is_winner: true,
-        }]);
-    };
-
-    resolve_candidates_by_cluster_key(store, servers_ordered, &cluster_key)
-}
-
-fn track_duration(store: &LibraryStore, server_id: &str, track_id: &str) -> Result<i64, String> {
-    store
-        .with_read_conn(|conn| {
-            conn.query_row(
-                "SELECT duration_sec FROM track WHERE server_id = ?1 AND id = ?2 AND deleted = 0",
-                rusqlite::params![server_id, track_id],
-                |r| r.get(0),
-            )
-        })
-        .map_err(|e| e.to_string())
-}
-
-/// Lookup cluster key for a track (for search/seed mapping).
-pub fn cluster_key_for_track(
-    store: &LibraryStore,
-    server_id: &str,
-    track_id: &str,
-) -> Result<Option<String>, String> {
-    store
-        .with_read_conn(|conn| {
-            conn.query_row(
-                &format!(
-                    "SELECT cluster_key FROM {ATTACH_ALIAS}.track_cluster_key \
-                     WHERE server_id = ?1 AND track_id = ?2"
-                ),
-                rusqlite::params![server_id, track_id],
-                |r| r.get(0),
-            )
-            .optional()
-        })
-        .map_err(|e| e.to_string())
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::repos::{TrackRepository, TrackRow};
-    use crate::server_cluster::rebuild::rebuild_all_cluster_keys;
-
-    fn tr(server: &str, id: &str) -> TrackRow {
-        TrackRow {
-            server_id: server.into(),
-            id: id.into(),
-            title: "Song".into(),
-            title_sort: None,
-            artist: Some("Band".into()),
-            artist_id: None,
-            album: "LP".into(),
-            album_id: None,
-            album_artist: Some("Band".into()),
-            duration_sec: 180,
-            track_number: Some(1),
-            disc_number: Some(1),
-            year: None,
-            genre: None,
-            suffix: None,
-            bit_rate: None,
-            size_bytes: None,
-            cover_art_id: None,
-            starred_at: None,
-            user_rating: None,
-            play_count: None,
-            played_at: None,
-            server_path: None,
-            library_id: None,
-            isrc: None,
-            mbid_recording: None,
-            bpm: None,
-            replay_gain_track_db: None,
-            replay_gain_album_db: None,
-            content_hash: None,
-            server_updated_at: None,
-            server_created_at: None,
-            deleted: false,
-            synced_at: 1,
-            raw_json: "{}".into(),
-        }
-    }
-
-    #[test]
-    fn resolve_orders_by_priority() {
-        let store = LibraryStore::open_in_memory();
-        TrackRepository::new(&store)
-            .upsert_batch(&[tr("s1", "t1"), tr("s2", "t2")])
-            .unwrap();
-        rebuild_all_cluster_keys(&store).unwrap();
-        let key = cluster_key_for_track(&store, "s1", "t1").unwrap().unwrap();
-        let cands = resolve_candidates_by_cluster_key(&store, &["s1".into(), "s2".into()], &key).unwrap();
-        assert_eq!(cands.len(), 2);
-        assert!(cands[0].is_winner);
-        assert_eq!(cands[0].server_id, "s1");
-    }
-}