refactor(queue): thin-state refs as canonical, full Track via resolver (#872)

* refactor(queue): wire queue UI to the track resolver (thin-state phase 3) cucadmuh's phase-3 steps: - Selectors (useQueueTracks) read resolver-first: getCachedTrack → queue: Track[] fallback (until phase 4), F4 star/rating overrides merged on read. - QueueList rows source their track from the resolver (queue fallback); rows show title/artist/duration only, so no override merge there. - pendingStarSync star/rating success → invalidateQueueResolver so the cache reflects the synced value. - queueResolverBridge re-seeds on queueIndex change too — the prefetch window travels with the playing track. Additive: queue: Track[] stays canonical and behaviour is unchanged (rows resolve to the same data). Phase 4 drops queue: Track[] and the fallbacks. * docs(changelog): queue panel reads through track cache (#860) * fix(queue): stop a render loop that froze the UI on long queues A long virtualized queue + a track change could lock the WebView for ~2 min: - useVirtualizer was handed a fresh `initialRect` object literal every render, so it kept re-initializing in a loop. Hoisted it to a stable module constant. - getCachedTrack did an LRU bump (Map delete+set) during render — a render-time side effect. Made it a pure read; recency is set at write time in cacheSet. * perf(mobile): virtualize the mobile player queue drawer The mobile now-playing queue drawer rendered the full queue with .map; a multi-thousand-track queue meant thousands of DOM nodes. Virtualize it with @tanstack/react-virtual (uniform rows, stable initialRect) so the DOM stays at O(visible rows), matching the desktop QueuePanel. Active track is centred on open via scrollToIndex. * perf(mini): virtualize the mini-player queue list The mini-player queue rendered the full MiniSyncPayload queue with .map. Virtualize it against the OverlayScrollArea viewport (stable initialRect) so the mini window's DOM stays at O(visible rows). Drag-reorder is preserved: rows keep data-mq-idx alongside the virtualizer's measureElement. * refactor(queue): add resolveQueueTrack/getQueueTracksView helper (thin-state phase 4) Render-safe ref→Track view for the phase-4 consumer migration off queue: Track[]. Resolver cache → caller fallback (legacy queue[idx] during dual-write) → placeholder; ref queue-only flags carried, F4 overrides merged. Pure synchronous read, no cache mutation (the freeze landmine), so it is safe in render. * refactor(queue): keep queueItems as the canonical in-memory mirror (thin-state phase 4) Step 1b: dual-write the thin queueItems ref list at every queue write site (the 11 mutations, next/radio top-up, playTrack, undo/redo restore, instant-mix, radio, server-queue init, lucky-mix rollback, and hydrate) so it tracks queue: Track[] in memory, not only at persist time. Identity-preserving maps (star/rating overrides) keep the same refs and are intentionally left untouched. Resolves the restore double-role flagged for 1b: queueItemsIndex is now the restore-pending sentinel that gates hydrateQueueFromIndex, while queueItems stays canonical -- rebuilt from the whole queue after a full hydrate instead of cleared. Normal mutations never set the sentinel, so it only fires on a fresh cold-start restore, not on later server switches. No behaviour change; queue: Track[] stays the source consumers read until phase 3. tsc + full vitest suite (1119 tests) green. * refactor(queue): mobile queue drawer reads through the track resolver (thin-state phase 4) Step 2: the mobile now-playing queue drawer resolves each row's track from the resolver cache (→ queue: Track[] fallback until phase 4), matching the desktop QueueList wired in the phase-3 commit. Subscribes to the resolver version so rows re-render as the cache fills. Structure (count, order, keys, the playTrack arg) still comes from queue: Track[] until it is dropped in the final step. The mobile drawer was the last queue display surface still reading track metadata straight off the fat queue. tsc + full vitest suite green. * refactor(queue): ref-native queue mutations + dual-write bridge (thin-state phase 4) Step 3a: the 11 queueMutationActions now splice/filter/reorder QueueItemRef[] (matching by trackId + the ref's queue-only flags) instead of Track[]. `bridgeQueueFromItems` rebuilds the dual-written queue: Track[] from the new refs by id — purely structural (no resolver/override merge), so behaviour is byte-identical and playerStore.queue.test.ts stays unchanged green. The working ref list comes from `itemsOf(state)` (derived from queue: Track[] for now); the final step swaps that one line to state.queueItems once the fat queue is gone. enqueue / enqueueAt / enqueueRadio seed the resolver cache with incoming tracks (seed-before-splice) so they resolve without a network round-trip after the fat queue is dropped. Adds a DEV-only id-parity guardrail (queue vs queueItems); dev-runtime only, silent in vitest and prod. tsc + full vitest suite (1119) green; contract test unchanged. * refactor(queue): ref-native radio/infinite top-ups (thin-state phase 4) Step 3b: nextAction's proactive infinite-queue and radio top-ups build the new queue as QueueItemRef[] and bridge back to queue: Track[] (same as the queue mutations), and seed the resolver cache with the freshly fetched tracks so they resolve without a network round-trip after the fat queue is dropped. The radio top-up keeps its HISTORY_KEEP front-trim, now expressed on refs. The exhausted-queue refill paths hand their new queue to playTrack, which keeps its fat-queue handling until the final step (its no-arg case needs the resolver- derived queue that lands with the queue: Track[] removal). tsc + full vitest (1119) green; contract test unchanged. * refactor(queue): undo snapshots store thin refs, not Track[] (thin-state phase 4) Step 4: QueueUndoSnapshot.queue: Track[] becomes queueItems: QueueItemRef[], killing the undo "hidden multiplier" — 32 snapshots of a 50k queue now cost refs, not 32×50k full tracks. applyQueueHistorySnapshot rebuilds the display queue from the refs via resolveQueueTrack: resolver cache → the live queue by id (covers tracks the edit didn't remove) → placeholder. currentTrack stays a full track in the snapshot and is restored to the engine unchanged. The snapshot refs derive from queue: Track[] for now (so the undo/redo contract cases, which seed only `queue`, stay green); the final step swaps that to [...s.queueItems]. tsc + full vitest suite (1119) green. * perf(mini): cap the mini-player queue snapshot to ±100 around the current track (thin-state phase 4) Step 5: the mini bridge no longer serializes the full queue over IPC on every push — a 50k Artist-Radio queue would otherwise re-encode in full on every track advance. snapshot() sends a window of 100 tracks before/after the playing song; queueIndex is made slice-relative. The mini component stays unchanged (slice- relative); jump/reorder/remove control events are translated back to absolute queue indices via the window offset captured on the last push. tsc + full vitest suite (1119) green. Mini bridge has no unit tests — needs a quick mini-player smoke (queue shows ±100, jump/reorder/remove land correctly). * refactor(queue): make queueItems a required PlayerState field (thin-state phase 4) Foundation for the final consumer migration off queue: Track[]: queueItems has been written at every queue write site since phase 1b, so promoting it from optional to required is a no-op at runtime (tsc confirms zero new errors) and lets the upcoming reader migrations read state.queueItems without `?? []` noise. * refactor(queue): migrate structural queue readers off queue: Track[] (thin-state phase 4) First reader batch toward dropping queue: Track[]: the queue-length selectors (usePlaybackServerId, usePlaybackCoverArt, useQueuePanelDrag, useMiniQueueDrag) now read state.queueItems.length, and FullscreenPlayer's next-track cover prefetch resolves through useQueueTrackAt instead of indexing the fat queue. All behaviour- identical during dual-write (queueItems is in lockstep with queue). tsc + full vitest suite (1119) green. Note: getPlaybackServerId() (playbackServer.ts) deliberately stays on queue for now — it is called from many partially-mocked test stores, so it migrates with the final field removal where the seedQueue helper covers those tests. * refactor(queue): QueuePanel save/share/playlist read queueItems (thin-state phase 4) The id/length reads (save to playlist, share link, create playlist, empty-queue guards, next-tracks divider) now read state.queueItems instead of the fat queue. Behaviour-identical during dual-write; queue: Track[] stays for the rendered QueueList + auto-scroll until the field is dropped. tsc + full suite (1119) green. * refactor(queue): drop queue: Track[] — thin queueItems is the only queue (thin-state phase 4) The store no longer holds the fat queue. `queueItems: QueueItemRef[]` is the sole canonical queue; full `Track`s resolve on demand via the resolver (index batch → getSong fallback, bounded LRU cache); only `currentTrack` stays a full Track. At 50k tracks the store holds ~hundreds of resolved tracks + the refs, not 50k Track objects. - **Persist:** partialize is refs-only (no windowed slice / PERSIST_QUEUE_HALF). A `merge` migrates every historical blob shape → `queueItems` (existing `queueItems` → legacy `queueRefs` → pre-ref windowed `queue: Track[]`) and drops the obsolete `queue` key, so saved queues survive the upgrade. - **Restore (decision B):** `hydrateQueueFromIndex` eager-resolves the whole ref list into the cache on cold start (index → getSong, so an index-off queue still plays), clears the restore sentinel. - **Resolver bridge:** keeps `[idx-50, idx+200]` warm via `resolveVisibleRange`. - **Mutations / actions / playback:** operate on refs; the playing track is `currentTrack`, the next/neighbour tracks resolve from the cache. Navigation (next/previous/row-jump) keeps `queueItems` and only moves the index — no full resolve or queue rebuild per track change. - **Persist tests** cover the three old-blob migrations; `seedQueue` test helper replaces the `setState({ queue })` seeds. tsc + full vitest suite (1115) green. Behaviour-preserving by the test contract; the gapless track change + cold-start restore + mini cap still want a live smoke before merge. * fix(queue): star/rating keeps the queue row resolved instead of blanking to "…" (thin-state) Rating/starring a queue song flashed the row's title to the "…" placeholder until the next track change. Root cause: on sync success pendingStarSync called invalidateQueueResolver, which DROPPED the cached track — and with queue: Track[] gone there's no fat fallback, so the row resolved to a placeholder until the resolver bridge re-fetched the window. Fix: add patchCachedTrack(trackId, patch) and use it on star/rating success to update the cached entry in place (title kept, synced starred/userRating applied) instead of dropping it. No placeholder flash, no re-fetch. tsc + full vitest suite (1115) green. * fix(player): quota-safe persist so a full localStorage can't kill playback A very large queue (~50k refs) overflows the localStorage quota; the persist write then threw QuotaExceededError from inside set(), which aborted playTrack before audio_play — no audio output at all. Back the player persist with a quota-safe storage wrapper so a failed write degrades to a no-op instead of throwing. Restoring the full ref list at that ceiling (vs a windowed cap) is left as a follow-up. * polish(player): throttle the quota-skip persist warning to once per key The quota-safe persist logs a skip on every failed write; on a huge queue that floods the dev console once per mutation. Warn once per key per quota-exceeded streak, re-armed when a write to that key next succeeds. * fix(queue): port new cover-pipeline readers to thin-state Main's cover pipeline (#870) reads s.queue.length and seeds the player store with queue: [track] in its tests. Under thin-state, queue: Track[] no longer exists — the canonical queue is queueItems: QueueItemRef[]. These four files were brought across in the merge but still spoke the old shape; this commit aligns them with the thin-state contract. - src/cover/usePlaybackCoverArt: queueLength = queueItems.length - src/cover/usePlaybackCoverArt.test: seed via toQueueItemRefs - src/api/coverCache.test: same - src/hooks/useNowPlayingPrewarm.test: same (two test cases) * fix(queue): canonicalize thin-state server identity for mixed-server queues `QueueItemRef.serverId` and `PlayerState.queueServerId` are now written as the URL-derived index key on every writer path, matching the library index direction. Mixed-server queues with duplicate `trackId` across servers stay unambiguous because the resolver cache, persistence, and playback bindings all share one key shape. - new `canonicalQueueServerKey()` helper (idempotent UUID-or-key normalizer) - `toQueueItemRefs`, `bindQueueServerForPlayback`, `seedQueueResolver`, and `hydrateQueueFromIndex` emit canonical keys - `getCachedTrack` falls back to the canonical lookup so refs persisted in the legacy UUID shape still resolve through the migration window - persist `merge` rewrites `queueServerId` and every ref `serverId` on rehydrate, so the live store never holds mixed shapes - `removeServer` compares against the resolved id so a profile delete still clears the matching queue binding - the two `playbackServer.test.ts` asserts that hard-coded the UUID shape are updated to the canonical key (existing reader-tolerance is unchanged) * fix(queue-undo): bind snapshot prepend to snapshot-canonical server identity When `applyQueueHistorySnapshot` has to prepend the still-playing track (the snapshot's queue does not contain it), the new ref must follow the snapshot's playback server, not the live `queueServerId`. A server switch racing the undo would otherwise stamp the prepended ref with the new server, mis-resolving the playing track on the very next render. - `QueueUndoSnapshot` now carries `queueServerId` (captured by `queueUndoSnapshotFromState`); older in-memory entries fall back through the snapshot's own refs and finally the live store value - the prepend in `applyQueueHistorySnapshot` plus the post-restore `seedQueueResolver` both source the server identity from this snapshot context, run through `canonicalQueueServerKey` so cache bucket and ref shape stay in lockstep * test(queue): regression cluster for mixed-server queues with duplicate trackId Covers the four invariants the thin-state review called out: - resolver correctness: same `trackId` on two servers maps to two distinct cache entries via canonical keys, and legacy UUID-shaped refs still read the same entries through the compat lookup path - restore/hydrate: persist `merge` forward-migrates UUID-form blobs in three shapes (canonical `queueItems`, legacy `queueRefs`, mixed-server `queueItems`) to canonical keys - undo snapshot application: prepended ref follows the snapshot's playback server even when the live queue has been rebound to a different one, with fallback to snapshot refs and live state for legacy entries - queue sync id emission: `flushPlayQueuePosition` -> `savePlayQueue` passes plain track ids and the playback server out of band, no per-ref `serverId` ever leaks into the request body Also asserts the write helpers (`toQueueItemRefs`, `bindQueueServerForPlayback`) emit canonical keys directly. * perf(queue-header): coalesce resolver burst updates and aggregate in one pass `QueueHeader` recomputed total and remaining queue durations on every resolver cache version bump via two separate full-queue reduces. A mass resolve burst (queue restore, prefetch window slide) bumps the version dozens of times in one frame, and very long queues turned that into visible main-thread stutter. - one pass: a single for-loop produces both total and future-tracks duration; a 50k-track queue costs one walk per recompute, not two - `useDeferredValue(version)` coalesces the burst into a single low-priority commit so the cache version is only sampled once per React frame instead of once per cache write * fix(queue): use stable artist seed for radio top-up The proactive radio top-up in `runNext` seeded `getSimilarSongs2` and `getTopSongs` from `resolveQueueTrack(nextRef)` metadata. When the next ref is still cold in the resolver cache, the placeholder track has empty artist fields, and the top-up would fire `getSimilarSongs2('')` -- silently returning nothing and leaving the queue dry just before the radio rail would have refilled. - prefer the just-played `currentTrack` (always fully resolved in the player store) and the stored radio seed artist id - fall back to the next-track metadata only when those are missing - skip the top-up entirely when no stable seed is available, instead of emitting a non-deterministic empty request * docs(changelog): queue mixed-server routing and quota-safe persist (#872)
2026-07-22 07:15:47 +00:00 · 2026-05-27 00:10:34 +02:00
parent a8cfff0b62
commit 45b9229ceb
88 changed files with 1965 additions and 944 deletions
@@ -1,15 +1,20 @@
 import type { QueueItemRef, Track } from '../../store/playerStoreTypes';
+import { canonicalQueueServerKey } from '../server/serverIndexKey';

 /**
 * Derive thin `QueueItemRef`s from a `Track[]` queue (thin-state). Per-item
- * `serverId` is the single playback server in v1; queue-only flags are carried
- * through, others omitted to keep the persisted/derived list small. Pure — no
- * store import, so both `playerStore` (persist) and the resolver bridge can use
- * it without a circular dependency.
+ * `serverId` is the canonical server index key — every writer normalizes here
+ * so refs are unambiguous across mixed-server queues (same `trackId` on two
+ * servers must collide on nothing, since the resolver uses `serverId:trackId`).
+ * Queue-only flags are carried through, others omitted to keep the persisted /
+ * derived list small. Pure — no store import beyond the canonicalizer, so both
+ * `playerStore` (persist) and the resolver bridge can use it without a
+ * circular dependency.
 */
 export function toQueueItemRefs(serverId: string, queue: Track[]): QueueItemRef[] {
+  const canonicalId = canonicalQueueServerKey(serverId);
  return queue.map(t => {
-    const ref: QueueItemRef = { serverId, trackId: t.id };
+    const ref: QueueItemRef = { serverId: canonicalId, trackId: t.id };
    if (t.autoAdded) ref.autoAdded = true;
    if (t.radioAdded) ref.radioAdded = true;
    if (t.playNextAdded) ref.playNextAdded = true;
@@ -4,6 +4,10 @@ import { useLibraryIndexStore } from '@/store/libraryIndexStore';
 import { usePlayerStore } from '@/store/playerStore';
 import type { TrackRefDto } from '@/api/library';
 import type { Track } from '@/store/playerStoreTypes';
+import {
+  getCachedTrack,
+  _resetQueueResolverForTest,
+} from './queueTrackResolver';
 import { hydrateQueueFromIndex } from './queueRestore';

 const ready = () =>
@@ -34,72 +38,39 @@ const track = (id: string): Track => ({ id, title: id, artist: '', album: 'A', a

 function seedStore(over: Partial<ReturnType<typeof usePlayerStore.getState>> = {}) {
  usePlayerStore.setState({
-    queue: [track('w1')],
    queueServerId: 's1',
    queueIndex: 0,
    currentTrack: null,
+    queueItems: [],
+    queueItemsIndex: undefined,
    queueRefs: undefined,
    queueRefsIndex: undefined,
    ...over,
  });
 }

+/**
+ * Thin-state `hydrateQueueFromIndex`: the store is refs-canonical, so cold
+ * restore eagerly resolves the whole `queueItems` ref list into the resolver
+ * cache (index batch → getSong fallback) and clears the restore-pending
+ * sentinel. It no longer swaps a fat `Track[]` into the store — `queueItems`
+ * stays the source of truth.
+ */
 describe('hydrateQueueFromIndex', () => {
  beforeEach(() => {
    useLibraryIndexStore.setState({ masterEnabled: true });
+    _resetQueueResolverForTest();
    seedStore();
  });

-  it('does nothing without persisted refs', async () => {
-    seedStore({ queueRefs: undefined });
+  it('does nothing without a restore-pending sentinel', async () => {
+    seedStore({ queueItems: [{ serverId: 's1', trackId: 'w1' }], queueItemsIndex: undefined });
    await hydrateQueueFromIndex();
-    expect(usePlayerStore.getState().queue.map(t => t.id)).toEqual(['w1']);
+    // No resolve dispatched (no sentinel) → nothing cached.
+    expect(getCachedTrack({ serverId: 's1', trackId: 'w1' })).toBeUndefined();
  });

-  it('keeps the windowed fallback when the index is not ready', async () => {
-    onInvoke('library_get_status', () => ({ serverId: 's1', libraryScope: '', syncPhase: 'initial_sync' }));
-    seedStore({ queueRefs: ['t1', 't2', 't3'], queueRefsIndex: 1 });
-    await hydrateQueueFromIndex();
-    expect(usePlayerStore.getState().queue.map(t => t.id)).toEqual(['w1']);
-    expect(usePlayerStore.getState().queueRefs).toEqual(['t1', 't2', 't3']); // not cleared
-  });
-
-  it('restores the full queue and re-locates the current track when ready', async () => {
-    ready();
-    echoBatch();
-    seedStore({
-      queueRefs: ['t1', 't2', 't3'],
-      queueRefsIndex: 1,
-      currentTrack: track('t2'),
-    });
-    await hydrateQueueFromIndex();
-    const s = usePlayerStore.getState();
-    expect(s.queue.map(t => t.id)).toEqual(['t1', 't2', 't3']);
-    expect(s.queueIndex).toBe(1); // re-located to current track t2
-    expect(s.queueRefs).toBeUndefined(); // cleared after success
-  });
-
-  it('batches refs in chunks of 100', async () => {
-    ready();
-    echoBatch();
-    const refs = Array.from({ length: 150 }, (_, i) => `t${i}`);
-    seedStore({ queueRefs: refs, queueRefsIndex: 0 });
-    await hydrateQueueFromIndex();
-    expect(usePlayerStore.getState().queue).toHaveLength(150);
-  });
-
-  it('keeps the fallback when the current track is not in the hydrated list', async () => {
-    ready();
-    echoBatch();
-    seedStore({
-      queueRefs: ['t1', 't2'],
-      currentTrack: track('gone'),
-    });
-    await hydrateQueueFromIndex();
-    expect(usePlayerStore.getState().queue.map(t => t.id)).toEqual(['w1']); // unchanged
-  });
-
-  it('hydrates from queueItems (preferred) and clears the ref lists', async () => {
+  it('resolves the whole queueItems ref list into the resolver cache and clears the sentinel', async () => {
    ready();
    echoBatch();
    seedStore({
@@ -113,17 +84,31 @@ describe('hydrateQueueFromIndex', () => {
    });
    await hydrateQueueFromIndex();
    const s = usePlayerStore.getState();
-    expect(s.queue.map(t => t.id)).toEqual(['t1', 't2', 't3']);
-    expect(s.queueIndex).toBe(1); // re-located to current track t2
-    expect(s.queueItems).toBeUndefined();
-    expect(s.queueRefs).toBeUndefined();
+    // queueItems stays canonical (no fat-array swap).
+    expect(s.queueItems.map(r => r.trackId)).toEqual(['t1', 't2', 't3']);
+    // Restore-pending sentinel cleared so it runs at most once.
+    expect(s.queueItemsIndex).toBeUndefined();
+    // Every ref was resolved into the cache.
+    expect(getCachedTrack({ serverId: 's1', trackId: 't1' })?.id).toBe('t1');
+    expect(getCachedTrack({ serverId: 's1', trackId: 't3' })?.id).toBe('t3');
  });

-  it('upgrades a legacy queueRefs-only store (no queueItems) via queueServerId', async () => {
+  it('batches refs in chunks of 100', async () => {
+    ready();
+    echoBatch();
+    const items = Array.from({ length: 150 }, (_, i) => ({ serverId: 's1', trackId: `t${i}` }));
+    seedStore({ queueItems: items, queueItemsIndex: 0 });
+    await hydrateQueueFromIndex();
+    // All 150 resolved into the cache (the resolver chunks ≤100/call internally).
+    expect(getCachedTrack({ serverId: 's1', trackId: 't0' })?.id).toBe('t0');
+    expect(getCachedTrack({ serverId: 's1', trackId: 't149' })?.id).toBe('t149');
+  });
+
+  it('upgrades a legacy queueRefs-only blob via queueServerId, then clears it', async () => {
    ready();
    echoBatch();
    seedStore({
-      queueItems: undefined, // pre-Phase-1 persist shape
+      queueItems: [], // pre-thin-state in-memory shape
      queueRefs: ['t1', 't2', 't3'],
      queueRefsIndex: 1,
      queueServerId: 's1',
@@ -131,28 +116,23 @@ describe('hydrateQueueFromIndex', () => {
    });
    await hydrateQueueFromIndex();
    const s = usePlayerStore.getState();
-    expect(s.queue.map(t => t.id)).toEqual(['t1', 't2', 't3']);
-    expect(s.queueIndex).toBe(1);
-    expect(s.queueRefs).toBeUndefined(); // both ref lists cleared after success
-    expect(s.queueItems).toBeUndefined();
+    // Legacy refs resolved into the cache and the legacy fields cleared.
+    expect(getCachedTrack({ serverId: 's1', trackId: 't1' })?.id).toBe('t1');
+    expect(getCachedTrack({ serverId: 's1', trackId: 't3' })?.id).toBe('t3');
+    expect(s.queueItemsIndex).toBeUndefined();
+    expect(s.queueRefs).toBeUndefined();
  });

-  it('carries queue-only flags from queueItems onto hydrated tracks', async () => {
-    ready();
-    echoBatch();
+  it('clears the sentinel even when the index is not ready (best-effort getSong fallback runs)', async () => {
+    onInvoke('library_get_status', () => ({ serverId: 's1', libraryScope: '', syncPhase: 'initial_sync' }));
+    onInvoke('library_get_tracks_batch', () => []);
    seedStore({
-      queueItems: [
-        { serverId: 's1', trackId: 't1' },
-        { serverId: 's1', trackId: 't2', radioAdded: true },
-        { serverId: 's1', trackId: 't3', autoAdded: true, playNextAdded: true },
-      ],
+      queueItems: [{ serverId: 's1', trackId: 't1' }],
      queueItemsIndex: 0,
    });
    await hydrateQueueFromIndex();
-    const q = usePlayerStore.getState().queue;
-    expect(q.find(t => t.id === 't1')?.radioAdded).toBeUndefined();
-    expect(q.find(t => t.id === 't2')?.radioAdded).toBe(true);
-    expect(q.find(t => t.id === 't3')?.autoAdded).toBe(true);
-    expect(q.find(t => t.id === 't3')?.playNextAdded).toBe(true);
+    // Sentinel cleared up front so the eager resolve runs at most once; refs stay.
+    expect(usePlayerStore.getState().queueItemsIndex).toBeUndefined();
+    expect(usePlayerStore.getState().queueItems.map(r => r.trackId)).toEqual(['t1']);
  });
 });
@@ -1,89 +1,60 @@
-import { libraryGetTracksBatch, type LibraryTrackDto, type TrackRefDto } from '../../api/library';
 import { useAuthStore } from '../../store/authStore';
 import { usePlayerStore } from '../../store/playerStore';
-import type { Track } from '../../store/playerStoreTypes';
-import { songToTrack } from '../playback/songToTrack';
-import { trackToSong } from './advancedSearchLocal';
-import { libraryIsReady } from './libraryReady';
-
-/** `library_get_tracks_batch` cap (spec §8.6 — max 100 refs/call). */
-const BATCH = 100;
+import type { QueueItemRef } from '../../store/playerStoreTypes';
+import { canonicalQueueServerKey } from '../server/serverIndexKey';
+import { resolveBatch } from './queueTrackResolver';

 /**
- * Full-queue restore. The player store rehydrates a *windowed* `queue` plus a
- * full thin-ref list. When the library index is ready for the queue's server,
- * hydrate the entire queue from the index (`library_get_tracks_batch`, ≤100
- * refs/call) and swap it in, re-locating the current track so the playback
- * position stays correct even if some refs were dropped (unknown to the index).
+ * Full-queue restore (thin-state, decision B). The player store rehydrates the
+ * whole thin `queueItems` ref list from localStorage on startup; this eagerly
+ * resolves every ref into the resolver cache so the queue UI / playback paths
+ * have real `Track` metadata. `resolveBatch` does the index batch
+ * (`library_get_tracks_batch`, ≤100 refs/call) → `getSong` network fallback (P8)
+ * internally, so the queue is never empty even with the index off (the P6
+ * default — every ref still resolves via getSong).
 *
- * Phase 1: prefers `queueItems` (per-item serverId + queue-only flags) and
- * carries those flags onto the hydrated tracks; falls back to the legacy
- * `queueRefs` string list for stores persisted before Phase 1.
- *
- * Best-effort: missing refs / index not ready / any failure leave the windowed
- * `queue` untouched — no regression when the index is off (the P6 default).
- * Clears the ref lists once a full hydrate succeeds so it runs at most once.
+ * Clears the restore-pending sentinel (`queueItemsIndex`) once the eager resolve
+ * is dispatched so it runs at most once; `queueItems` stays canonical. Legacy
+ * pre-thin-state blobs that only carried `queueRefs` were normalised into
+ * `queueItems` by the store's persist `merge`, so this reads `queueItems` only.
 */
 export async function hydrateQueueFromIndex(): Promise<void> {
  const player = usePlayerStore.getState();

-  const items = player.queueItems;
-  let refs: TrackRefDto[] | null = null;
-  if (items?.length) {
-    refs = items.map(it => ({ serverId: it.serverId, trackId: it.trackId }));
-  } else if (player.queueRefs?.length) {
-    const sid = player.queueServerId ?? useAuthStore.getState().activeServerId;
-    if (sid) refs = player.queueRefs.map(trackId => ({ serverId: sid, trackId }));
+  // Restore-pending sentinel: `partialize` writes `queueItemsIndex` alongside
+  // the full `queueItems` on every persist, so a fresh rehydrate carries it
+  // back. Normal in-memory mutations keep `queueItems` canonical but never set
+  // the index, so its presence — not a non-empty `queueItems` — marks "this
+  // restored queue still needs an eager resolve". Without it (steady state /
+  // later server switch) there is nothing to do.
+  const restorePending =
+    player.queueItemsIndex !== undefined || (player.queueRefs?.length ?? 0) > 0;
+  if (!restorePending) return;
+
+  let refs: QueueItemRef[] = player.queueItems ?? [];
+  if (refs.length === 0 && player.queueRefs?.length) {
+    const rawSid = player.queueServerId ?? useAuthStore.getState().activeServerId ?? '';
+    const sid = canonicalQueueServerKey(rawSid);
+    refs = player.queueRefs.map(trackId => ({ serverId: sid, trackId }));
  }
-  if (!refs || refs.length === 0) return;

-  const clearRefs = () =>
-    usePlayerStore.setState({
-      queueItems: undefined, queueItemsIndex: undefined,
-      queueRefs: undefined, queueRefsIndex: undefined,
-    });
+  // Clear the restore-pending sentinel + any legacy refs; `queueItems` stays the
+  // canonical mirror. Done up front so a later resolve never re-triggers.
+  usePlayerStore.setState({
+    queueItemsIndex: undefined,
+    queueRefs: undefined,
+    queueRefsIndex: undefined,
+  });

-  // v1 is single-server; gate readiness on the queue's server.
-  const serverId = refs[0].serverId || player.queueServerId || useAuthStore.getState().activeServerId;
-  if (!serverId) {
-    clearRefs();
-    return;
-  }
-  // Keep the windowed fallback (and the refs, for a later ready startup) when
-  // the index can't serve the queue yet.
-  if (!(await libraryIsReady(serverId))) return;
+  if (refs.length === 0) return;

+  // Eager resolve of the whole queue into the resolver cache (best-effort —
+  // index batch when ready, else getSong window fallback so the queue plays
+  // even with the index off). Failures leave refs as placeholders until a row
+  // scrolls into view and the resolver bridge fetches them.
  try {
-    const dtos: LibraryTrackDto[] = [];
-    for (let i = 0; i < refs.length; i += BATCH) {
-      dtos.push(...(await libraryGetTracksBatch(refs.slice(i, i + BATCH))));
-    }
-    if (dtos.length === 0) return; // index has none of them → keep fallback
-
-    // The index doesn't store queue-only flags (radio/auto/play-next dividers),
-    // so carry them from the refs onto the hydrated tracks.
-    const flags = new Map(items?.map(it => [it.trackId, it]));
-    const hydrated: Track[] = dtos.map(d => {
-      const t = songToTrack(trackToSong(d));
-      const f = flags.get(t.id);
-      if (f?.autoAdded) t.autoAdded = true;
-      if (f?.radioAdded) t.radioAdded = true;
-      if (f?.playNextAdded) t.playNextAdded = true;
-      return t;
-    });
-
-    // Re-locate the current track so queueIndex stays aligned with playback.
-    const cur = usePlayerStore.getState().currentTrack;
-    const idx = cur ? hydrated.findIndex(t => t.id === cur.id) : -1;
-    if (cur && idx < 0) return; // can't align playback → keep windowed fallback
-
-    usePlayerStore.setState({
-      queue: hydrated,
-      queueIndex: idx >= 0 ? idx : 0,
-      queueItems: undefined, queueItemsIndex: undefined,
-      queueRefs: undefined, queueRefsIndex: undefined,
-    });
+    await resolveBatch(refs);
  } catch {
-    // best-effort; the windowed fallback stays in place
+    /* best-effort */
  }
 }
@@ -3,6 +3,7 @@ import { getSong } from '../../api/subsonicLibrary';
 import { usePlayerStore } from '../../store/playerStore';
 import type { QueueItemRef, Track } from '../../store/playerStoreTypes';
 import { songToTrack } from '../playback/songToTrack';
+import { canonicalQueueServerKey } from '../server/serverIndexKey';
 import { trackToSong } from './advancedSearchLocal';
 import { libraryIsReady } from './libraryReady';

@@ -30,26 +31,24 @@ const refKey = (r: { serverId: string; trackId: string }) => `${r.serverId}:${r.
 const cache = new Map<string, Track>();
 const inFlight = new Set<string>();
 const listeners = new Set<() => void>();
+let cacheVersion = 0;

 function notify(): void {
+  cacheVersion++;
  for (const l of listeners) l();
 }

+/** Monotonic version, bumped on every cache change (for `useSyncExternalStore`). */
+export function getQueueResolverVersion(): number {
+  return cacheVersion;
+}
+
 /** Subscribe to cache changes (for `useSyncExternalStore` selectors). */
 export function subscribeQueueResolver(cb: () => void): () => void {
  listeners.add(cb);
  return () => { listeners.delete(cb); };
 }

-function cacheTouch(key: string): Track | undefined {
-  const t = cache.get(key);
-  if (t !== undefined) {
-    cache.delete(key);
-    cache.set(key, t); // move to most-recent
-  }
-  return t;
-}
-
 function cacheSet(key: string, track: Track): void {
  if (cache.has(key)) cache.delete(key);
  cache.set(key, track);
@@ -69,7 +68,20 @@ function carryFlags(track: Track, ref: QueueItemRef | undefined): Track {

 /** Synchronous cache read (no fetch); undefined on miss. */
 export function getCachedTrack(ref: QueueItemRef): Track | undefined {
-  return cacheTouch(refKey(ref));
+  // Pure read — no LRU bump. Called from component render (QueueList rows), where
+  // a Map mutation (delete+set) is a render side-effect. Recency is set at write
+  // time in cacheSet instead; this cache is effectively insertion-order/FIFO.
+  const direct = cache.get(refKey(ref));
+  if (direct) return direct;
+  // Compat: refs persisted before B1 (queue server identity canonicalization)
+  // may still carry a UUID. Writes are canonical now, so the live cache key
+  // is `${indexKey}:${trackId}`; map UUID → indexKey on read to bridge the
+  // migration window.
+  const canonical = canonicalQueueServerKey(ref.serverId);
+  if (canonical && canonical !== ref.serverId) {
+    return cache.get(refKey({ serverId: canonical, trackId: ref.trackId }));
+  }
+  return undefined;
 }

 /** Lightweight placeholder shown until a ref resolves. */
@@ -101,10 +113,13 @@ export function applyQueueOverrides(track: Track): Track {
  return next;
 }

-/** Seed the cache with already-known tracks (e.g. on enqueue) — no fetch. */
+/** Seed the cache with already-known tracks (e.g. on enqueue) — no fetch.
+ *  Canonicalizes the caller-supplied server id so seed and refs always agree
+ *  on a single key shape. */
 export function seedQueueResolver(serverId: string, tracks: Track[]): void {
  if (tracks.length === 0) return;
-  for (const t of tracks) cacheSet(refKey({ serverId, trackId: t.id }), t);
+  const canonicalId = canonicalQueueServerKey(serverId);
+  for (const t of tracks) cacheSet(refKey({ serverId: canonicalId, trackId: t.id }), t);
  notify();
 }

@@ -177,8 +192,7 @@ export function resolveVisibleRange(refs: QueueItemRef[], fromIdx: number, toIdx
  if (end > start) void resolveBatch(refs.slice(start, end));
 }

-/** Drop cached entries for a track id (e.g. after a star/rating sync succeeds,
- *  so the next read re-fetches the server truth). */
+/** Drop cached entries for a track id, forcing the next resolve to re-fetch. */
 export function invalidateQueueResolver(trackId: string): void {
  let changed = false;
  for (const key of [...cache.keys()]) {
@@ -190,6 +204,21 @@ export function invalidateQueueResolver(trackId: string): void {
  if (changed) notify();
 }

+/** Patch cached entries for a track id in place (e.g. after a star/rating sync
+ *  succeeds). Unlike {@link invalidateQueueResolver}, this keeps the entry so a
+ *  visible queue row never blanks to a placeholder — the row stays resolved and
+ *  just reflects the synced value. No-op for refs not currently cached. */
+export function patchCachedTrack(trackId: string, patch: Partial<Track>): void {
+  let changed = false;
+  for (const [key, track] of cache) {
+    if (key.endsWith(`:${trackId}`)) {
+      cache.set(key, { ...track, ...patch });
+      changed = true;
+    }
+  }
+  if (changed) notify();
+}
+
 /** Test-only: clear cache + in-flight set. */
 export function _resetQueueResolverForTest(): void {
  cache.clear();
@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { usePlayerStore } from '@/store/playerStore';
+import type { QueueItemRef, Track } from '@/store/playerStoreTypes';
+import { seedQueueResolver, _resetQueueResolverForTest } from '@/utils/library/queueTrackResolver';
+import { resolveQueueTrack, getQueueTracksView } from './queueTrackView';
+
+const track = (id: string, over: Partial<Track> = {}): Track =>
+  ({ id, title: id, artist: 'A', album: 'Al', albumId: 'Al', duration: 1, ...over });
+const ref = (trackId: string, over: Partial<QueueItemRef> = {}): QueueItemRef =>
+  ({ serverId: 's1', trackId, ...over });
+
+describe('queueTrackView', () => {
+  beforeEach(() => {
+    _resetQueueResolverForTest();
+    usePlayerStore.setState({ starredOverrides: {}, userRatingOverrides: {} });
+  });
+
+  it('resolves from the resolver cache when present', () => {
+    seedQueueResolver('s1', [track('t1', { title: 'Cached' })]);
+    expect(resolveQueueTrack(ref('t1')).title).toBe('Cached');
+  });
+
+  it('falls back to the provided Track on cache miss', () => {
+    expect(resolveQueueTrack(ref('t2'), track('t2', { title: 'Fallback' })).title).toBe('Fallback');
+  });
+
+  it('returns a placeholder on miss with no fallback', () => {
+    const r = resolveQueueTrack(ref('t3'));
+    expect(r.id).toBe('t3');
+    expect(r.title).toBe('…');
+  });
+
+  it('carries the ref queue-only flags onto the resolved track', () => {
+    seedQueueResolver('s1', [track('t4')]);
+    const r = resolveQueueTrack(ref('t4', { radioAdded: true }));
+    expect(r.radioAdded).toBe(true);
+  });
+
+  it('merges session star/rating overrides', () => {
+    seedQueueResolver('s1', [track('t5')]);
+    usePlayerStore.setState({ starredOverrides: { t5: true }, userRatingOverrides: { t5: 4 } });
+    const r = resolveQueueTrack(ref('t5'));
+    expect(!!r.starred).toBe(true);
+    expect(r.userRating).toBe(4);
+  });
+
+  it('getQueueTracksView resolves each ref, preferring cache then fallback', () => {
+    seedQueueResolver('s1', [track('a', { title: 'CachedA' })]);
+    const out = getQueueTracksView([ref('a'), ref('b')], [track('a'), track('b', { title: 'FbB' })]);
+    expect(out.map(t => t.title)).toEqual(['CachedA', 'FbB']);
+  });
+});
@@ -0,0 +1,66 @@
+import type { QueueItemRef, Track } from '../../store/playerStoreTypes';
+import { getCachedTrack, placeholderTrack, applyQueueOverrides } from './queueTrackResolver';
+
+/**
+ * Dual-write bridge (thin-state phase 4): rebuild the legacy `queue: Track[]`
+ * from the canonical `QueueItemRef[]` after a ref-native mutation. Each ref's
+ * track is sourced from the supplied `pools` (the previous queue + any tracks
+ * just handed to the mutation) by id — **purely structural**: no resolver cache
+ * read and no F4 override merge (display still applies those), so the derived
+ * array is byte-identical to the old fat-array mutation result. The ref is the
+ * source of truth for the queue-only flags. A ref with no pooled track falls
+ * back to a placeholder (does not happen during dual-write, where every ref's
+ * track is in hand). Removed in the final step together with `queue: Track[]`.
+ */
+export function bridgeQueueFromItems(items: QueueItemRef[], pools: Track[][]): Track[] {
+  const byId = new Map<string, Track>();
+  for (const pool of pools) {
+    for (const t of pool) if (!byId.has(t.id)) byId.set(t.id, t);
+  }
+  return items.map(ref => {
+    const base = byId.get(ref.trackId);
+    if (!base) return placeholderTrack(ref);
+    if (
+      base.autoAdded === ref.autoAdded &&
+      base.radioAdded === ref.radioAdded &&
+      base.playNextAdded === ref.playNextAdded
+    ) {
+      return base;
+    }
+    return { ...base, autoAdded: ref.autoAdded, radioAdded: ref.radioAdded, playNextAdded: ref.playNextAdded };
+  });
+}
+
+/**
+ * Queue thin-state phase 4: turn a `QueueItemRef` into a display `Track` for the
+ * upcoming consumer migration off `queue: Track[]`.
+ *
+ * Resolver-first: cache → caller fallback (the legacy `queue[idx]` Track during
+ * the dual-write transition) → placeholder. Queue-only flags come from the ref
+ * (they are not in the index/cache); session star/rating overrides (F4) are
+ * merged last. Pure synchronous read — **no fetch, no cache mutation** — so it is
+ * safe to call from render (the resolver's `getCachedTrack` is a plain `cache.get`
+ * for exactly this reason; see the freeze fix in queueTrackResolver).
+ */
+export function resolveQueueTrack(ref: QueueItemRef, fallback?: Track): Track {
+  const base = getCachedTrack(ref) ?? fallback ?? placeholderTrack(ref);
+  // Carry the ref's queue-only flags onto the resolved track without mutating the
+  // cached object (a render-time mutation is what caused the earlier render loop).
+  const needsFlags =
+    base.autoAdded !== ref.autoAdded ||
+    base.radioAdded !== ref.radioAdded ||
+    base.playNextAdded !== ref.playNextAdded;
+  const flagged = needsFlags
+    ? { ...base, autoAdded: ref.autoAdded, radioAdded: ref.radioAdded, playNextAdded: ref.playNextAdded }
+    : base;
+  return applyQueueOverrides(flagged);
+}
+
+/**
+ * Resolve a whole ref list to display `Track`s (non-React call sites: snapshots,
+ * hot-cache planning, sync). Same per-item rules as {@link resolveQueueTrack};
+ * `fallbacks[i]` is the legacy `queue[i]` during the dual-write transition.
+ */
+export function getQueueTracksView(refs: QueueItemRef[], fallbacks?: Track[]): Track[] {
+  return refs.map((ref, i) => resolveQueueTrack(ref, fallbacks?.[i]));
+}