feat(player): web queue auto-follow + jump-to-current pill + clear-queue — #1944

QueueList now follows the now-playing row as the track auto-advances (only
while it's in view), centers it on open, and surfaces a 'Jump to current' pill
once the user scrolls it off-screen. Header gains a clear-queue action backed
by a new store clearQueue() that empties the queue and stops playback.

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

android/app/src/main/java/com/fabledsword/minstrel/player/ui/QueueScreen.kt

@@ -11,6 +11,7 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.itemsIndexed
+import androidx.compose.foundation.lazy.rememberLazyListState
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.Icon
@@ -86,7 +87,14 @@ private fun QueueList(
     onJumpTo: (Int) -> Unit,
     onToggleLike: (String) -> Unit,
 ) {
-    LazyColumn(modifier = Modifier.fillMaxSize()) {
+    // Open scrolled to the now-playing track so it's in view immediately.
+    // Seeding the initial index (rather than animating post-layout) avoids a
+    // flash of the list top; it's captured once per entry, so the view stays
+    // put as the track later auto-advances — matching "show me where I am now."
+    val listState = rememberLazyListState(
+        initialFirstVisibleItemIndex = currentIndex.coerceIn(0, tracks.lastIndex),
+    )
+    LazyColumn(state = listState, modifier = Modifier.fillMaxSize()) {
         itemsIndexed(items = tracks, key = { _, track -> track.id }) { index, track ->
             QueueRow(
                 track = track,

web/src/lib/components/QueueDrawer.svelte

@@ -35,5 +35,9 @@
          transition-transform duration-200
          {player.queueDrawerOpen ? 'translate-x-0' : 'translate-x-full'}"
 >
-  <QueueList onClose={() => closeQueueDrawer()} bind:closeButtonRef={closeButton} />
+  <QueueList
+    onClose={() => closeQueueDrawer()}
+    active={player.queueDrawerOpen}
+    bind:closeButtonRef={closeButton}
+  />
 </aside>

web/src/lib/components/QueueDrawer.test.ts

@@ -25,10 +25,12 @@ vi.mock('$lib/player/store.svelte', () => ({
     get queueDrawerOpen() { return openValue; }
   },
   // QueueTrackRow imports these from the store; provide stubs so its
-  // module-load doesn't break when QueueDrawer renders rows.
+  // module-load doesn't break when QueueDrawer renders rows. QueueList
+  // imports clearQueue for its header action.
   playFromQueueIndex: vi.fn(),
   removeFromQueue: vi.fn(),
-  moveQueueItem: vi.fn()
+  moveQueueItem: vi.fn(),
+  clearQueue: vi.fn()
 }));
 
 import QueueDrawer from './QueueDrawer.svelte';

web/src/lib/components/QueueList.svelte

@@ -1,6 +1,7 @@
 <script lang="ts">
-  import { X } from 'lucide-svelte';
-  import { player } from '$lib/player/store.svelte';
+  import { untrack } from 'svelte';
+  import { X, Trash2, ArrowDown } from 'lucide-svelte';
+  import { player, clearQueue } from '$lib/player/store.svelte';
   import QueueTrackRow from './QueueTrackRow.svelte';
 
   // onClose: when provided, renders an X button in the header so the
@@ -8,12 +9,66 @@
   //   now-playing route (visible at lg+ widths) omits it.
   // closeButtonRef: bind:this hook so the drawer can focus the X for
   //   keyboard users on open.
+  // active: true when the queue is on-screen (drawer open, or the always-
+  //   visible now-playing panel). Gates the scroll-to-current behavior.
   type Props = {
     onClose?: () => void;
     closeButtonRef?: HTMLButtonElement;
+    active?: boolean;
   };
 
-  let { onClose, closeButtonRef = $bindable() }: Props = $props();
+  let { onClose, closeButtonRef = $bindable(), active = true }: Props = $props();
+
+  let scrollBody: HTMLElement | undefined = $state();
+  // Whether the now-playing row is (at least partly) within the scroll
+  // viewport. Drives auto-follow (only follow while the user is watching the
+  // current track) and the "Jump to current" pill (shown when it's off-screen).
+  let currentInView = $state(true);
+  let sawFirstIndex = false;
+
+  function scrollToCurrent(block: ScrollLogicalPosition, behavior: ScrollBehavior = 'auto') {
+    (scrollBody?.children[player.index] as HTMLElement | undefined)?.scrollIntoView({
+      block,
+      behavior,
+    });
+    currentInView = true;
+  }
+
+  function recomputeInView() {
+    const row = scrollBody?.children[player.index] as HTMLElement | undefined;
+    if (!scrollBody || !row) {
+      currentInView = true;
+      return;
+    }
+    const b = scrollBody.getBoundingClientRect();
+    const r = row.getBoundingClientRect();
+    currentInView = r.bottom > b.top && r.top < b.bottom;
+  }
+
+  // On open (active flips true, or on mount for the always-visible panel),
+  // center the now-playing row — parity with the Android queue.
+  $effect(() => {
+    if (!active) return;
+    if (untrack(() => player.queue.length) === 0) return;
+    requestAnimationFrame(() => scrollToCurrent('center'));
+  });
+
+  // Follow the current track as it auto-advances, but only while the user is
+  // still watching it — if they've scrolled away, leave them there (the pill
+  // offers the way back). block:'nearest' keeps it minimal (no yank when the
+  // row is already visible). Index is tracked; currentInView is read untracked
+  // so a scroll that hides the row doesn't itself re-trigger a scroll.
+  $effect(() => {
+    player.index; // subscribe: follow on advance
+    if (!sawFirstIndex) {
+      sawFirstIndex = true;
+      return; // the open effect already handled the initial position
+    }
+    if (!active) return;
+    if (untrack(() => player.queue.length) === 0) return;
+    if (!untrack(() => currentInView)) return;
+    requestAnimationFrame(() => scrollToCurrent('nearest'));
+  });
 
   function totalDurationLabel(tracks: { duration_sec: number }[]): string {
     const totalSec = tracks.reduce((s, tr) => s + (tr.duration_sec ?? 0), 0);
@@ -23,7 +78,7 @@
   }
 </script>
 
-<div class="flex h-full flex-col">
+<div class="relative flex h-full flex-col">
   <div class="flex items-center justify-between border-b border-border px-4 py-3">
     <div>
       <h2 class="text-lg font-semibold">Queue</h2>
@@ -32,20 +87,33 @@
         {#if player.queue.length > 0} · {totalDurationLabel(player.queue)}{/if}
       </p>
     </div>
-    {#if onClose}
-      <button
-        type="button"
-        bind:this={closeButtonRef}
-        aria-label="Close queue"
-        onclick={onClose}
-        class="text-text-secondary hover:text-text-primary"
-      >
-        <X size={20} />
-      </button>
-    {/if}
+    <div class="flex items-center gap-1">
+      {#if player.queue.length > 0}
+        <button
+          type="button"
+          aria-label="Clear queue"
+          title="Clear queue"
+          onclick={() => clearQueue()}
+          class="rounded p-1 text-text-secondary hover:text-text-primary"
+        >
+          <Trash2 size={18} />
+        </button>
+      {/if}
+      {#if onClose}
+        <button
+          type="button"
+          bind:this={closeButtonRef}
+          aria-label="Close queue"
+          onclick={onClose}
+          class="rounded p-1 text-text-secondary hover:text-text-primary"
+        >
+          <X size={20} />
+        </button>
+      {/if}
+    </div>
   </div>
 
-  <div class="flex-1 overflow-y-auto">
+  <div bind:this={scrollBody} onscroll={recomputeInView} class="flex-1 overflow-y-auto">
     {#if player.queue.length === 0}
       <p class="text-text-secondary text-center p-8">No tracks queued.</p>
     {:else}
@@ -54,4 +122,17 @@
       {/each}
     {/if}
   </div>
+
+  {#if active && player.queue.length > 0 && !currentInView}
+    <button
+      type="button"
+      onclick={() => scrollToCurrent('center', 'smooth')}
+      class="absolute bottom-4 left-1/2 flex -translate-x-1/2 items-center gap-1.5
+             rounded-full bg-action-secondary px-3 py-1.5 text-xs font-medium
+             text-action-fg shadow-lg"
+    >
+      <ArrowDown size={14} />
+      Jump to current
+    </button>
+  {/if}
 </div>

web/src/lib/components/QueueTrackRow.svelte

@@ -3,6 +3,7 @@
   import { draggable, type DragEventData } from '@neodrag/svelte';
   import type { TrackRef } from '$lib/api/types';
   import { playFromQueueIndex, removeFromQueue, moveQueueItem } from '$lib/player/store.svelte';
+  import { coverUrl, FALLBACK_COVER } from '$lib/media/covers';
   import { offsetToDelta } from './queue-row-math';
   import LikeButton from './LikeButton.svelte';
 
@@ -66,6 +67,13 @@
     <GripVertical size={16} />
   </button>
 
+  <img
+    src={coverUrl(track.album_id)}
+    alt=""
+    onerror={(e) => ((e.currentTarget as HTMLImageElement).src = FALLBACK_COVER)}
+    class="h-10 w-10 flex-shrink-0 rounded object-cover"
+  />
+
   <button
     type="button"
     onclick={handleBodyClick}

web/src/lib/player/store.svelte.ts

@@ -505,6 +505,21 @@ export function removeFromQueue(idx: number): void {
   _error = null;
 }
 
+// Clear the whole queue and stop playback — mirrors removeFromQueue's
+// empty-queue branch. Also drops the radio/system source + self-heal closure
+// so the emptied player doesn't try to refill from a now-irrelevant source.
+export function clearQueue(): void {
+  _queue = [];
+  _index = 0;
+  _state = 'idle';
+  _position = 0;
+  _duration = 0;
+  _error = null;
+  _radioSeedId = null;
+  _queueSource = null;
+  _queueRefetch = null;
+}
+
 export function playFromQueueIndex(idx: number): void {
   if (idx < 0 || idx >= _queue.length) return;
   _radioSeedId = null;

web/src/routes/+layout.svelte

@@ -168,9 +168,14 @@
   style="display: none"
 ></audio>
 
-<QueueDrawer />
-
 <QueryClientProvider client={queryClient}>
+  <!-- QueueDrawer must be inside the provider: its rows render LikeButton,
+       which calls useQueryClient() at init. The drawer's <aside> is always
+       mounted, so the moment the queue is populated (on first play) those
+       LikeButtons instantiate — outside the provider they throw
+       "No QueryClient was found" and abort the play flush. -->
+  <QueueDrawer />
+
   {#if user.value !== null && page.url.pathname !== '/login' && page.url.pathname !== '/now-playing'}
     <Shell>{@render children()}</Shell>
   {:else}

web/vitest.setup.ts

@@ -37,6 +37,14 @@ if (typeof window !== 'undefined') {
   Object.defineProperty(window, 'sessionStorage', { configurable: true, value: memSession });
 }
 
+// jsdom doesn't implement Element.prototype.scrollIntoView. Components that
+// call it (queue auto-scroll to the now-playing row, the alphabetical rail)
+// would throw an unhandled TypeError in tests — which fails the run even when
+// every assertion passes. No-op it; tests never assert on scroll position.
+if (typeof Element !== 'undefined' && !Element.prototype.scrollIntoView) {
+  Element.prototype.scrollIntoView = () => {};
+}
+
 // W-T3 moved toast rendering out of per-page markup into a single
 // <ToastHost /> mounted in +layout.svelte. Tests render individual pages
 // without the layout, so we mount ToastHost here so `pushToast()` calls