From cde74b596539c9a12e0ef00485e2dbc5510bbd17 Mon Sep 17 00:00:00 2001
From: Bryan Van Deusen <bryan.vandeusen@fabledsword.com>
Date: Wed, 22 Jul 2026 22:57:23 -0400
Subject: [PATCH] =?UTF-8?q?feat(player):=20web=20queue=20auto-follow=20+?=
 =?UTF-8?q?=20jump-to-current=20pill=20+=20clear-queue=20=E2=80=94=20#1944?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 web/src/lib/components/QueueDrawer.test.ts |   6 +-
 web/src/lib/components/QueueList.svelte    | 117 ++++++++++++++++-----
 web/src/lib/player/store.svelte.ts         |  15 +++
 3 files changed, 107 insertions(+), 31 deletions(-)

diff --git a/web/src/lib/components/QueueDrawer.test.ts b/web/src/lib/components/QueueDrawer.test.ts
index ec82c755..c9b81cfa 100644
--- a/web/src/lib/components/QueueDrawer.test.ts
+++ b/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';
diff --git a/web/src/lib/components/QueueList.svelte b/web/src/lib/components/QueueList.svelte
index 1fb2dd48..cc223183 100644
--- a/web/src/lib/components/QueueList.svelte
+++ b/web/src/lib/components/QueueList.svelte
@@ -1,7 +1,7 @@
 <script lang="ts">
   import { untrack } from 'svelte';
-  import { X } from 'lucide-svelte';
-  import { player } from '$lib/player/store.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
@@ -10,9 +10,7 @@
   // 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). Flipping it true scrolls the now-playing
-  //   row into view — parity with the Android queue, which opens positioned
-  //   on the current track.
+  //   visible now-playing panel). Gates the scroll-to-current behavior.
   type Props = {
     onClose?: () => void;
     closeButtonRef?: HTMLButtonElement;
@@ -22,19 +20,54 @@
   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;
 
-  // When the queue becomes visible, center the now-playing row in view. The
-  // index/length are read untracked so this fires once per open (matching the
-  // Android queue's open-positioned behavior) rather than following the track
-  // as it auto-advances. Deferred a frame so the drawer's slide-in has settled.
-  $effect(() => {
-    if (!active || !scrollBody) return;
-    const body = scrollBody;
-    const index = untrack(() => player.index);
-    if (untrack(() => player.queue.length) === 0) return;
-    requestAnimationFrame(() => {
-      (body.children[index] as HTMLElement | undefined)?.scrollIntoView({ block: 'center' });
+  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 {
@@ -45,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>
@@ -54,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 bind:this={scrollBody} 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}
@@ -76,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>
diff --git a/web/src/lib/player/store.svelte.ts b/web/src/lib/player/store.svelte.ts
index 1e41432b..031f8c70 100644
--- a/web/src/lib/player/store.svelte.ts
+++ b/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;