web/src/lib/api/types.ts

@@ -41,6 +41,10 @@ export type TrackRef = {
   disc_number?: number;
   duration_sec: number;
   stream_url: string;
+  // #5418: the file is gone from the library (missing_since is set). Sent on
+  // direct lookups such as album detail and search; lists that pick tracks
+  // for playback leave missing files out instead.
+  unavailable?: boolean;
 };
 
 export type ArtistDetail = ArtistRef & {

web/src/lib/components/TrackRow.svelte

@@ -25,6 +25,9 @@
   } = $props();
 
   const track = $derived(tracks[index]);
+  // #5418: the file is gone. The row stays, greyed, so an album still reads
+  // in order, but there is nothing to play, like or queue.
+  const missing = $derived(!!track.unavailable);
 
   const isSelected = $derived(selection.isSelected(track.id));
   const selectMode = $derived(selection.active);
@@ -61,9 +64,13 @@
   title={track.title}
   {subtitle}
   durationSec={track.duration_sec}
-  {track}
+  track={missing ? null : track}
   ariaLabel={track.title}
+  rowTitle={missing
+    ? 'This track’s file is missing from the library, so it can’t be played. It returns automatically if the file comes back.'
+    : undefined}
   {isSelected}
+  disabled={missing}
   onActivate={activate}
 >
   {#snippet lead()}
@@ -88,4 +95,10 @@
       <Check size={14} strokeWidth={2} />
     </button>
   {/snippet}
+
+  {#snippet note()}
+    {#if missing}
+      <span class="text-error-fg"> · File missing</span>
+    {/if}
+  {/snippet}
 </TrackListRow>

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

@@ -89,6 +89,20 @@ describe('TrackRow', () => {
     ).toBeInTheDocument();
   });
 
+  // #5418: a missing file stays in the list, greyed, with nothing to act on.
+  test('a missing file is marked, does not play, and offers no actions', async () => {
+    const withMissing = [{ ...tracks[0], unavailable: true }, tracks[1]];
+    render(TrackRow, { props: { tracks: withMissing, index: 0 } });
+    const row = screen.getByRole('button', { name: 'So What' });
+    expect(row).toHaveAttribute('aria-disabled', 'true');
+    expect(screen.getByText(/file missing/i)).toBeInTheDocument();
+    await fireEvent.click(row);
+    expect(playQueue).not.toHaveBeenCalled();
+    expect(screen.queryByRole('button', { name: /add .* to queue/i })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /play radio/i })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: /track actions for/i })).not.toBeInTheDocument();
+  });
+
   describe('selection mode', () => {
     test('clicking the checkbox toggles selection without playing', async () => {
       render(TrackRow, { props: { tracks, index: 0 } });

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

@@ -123,6 +123,12 @@ export function registerAudioEl(el: HTMLAudioElement | null): void {
   _audioEl = el;
 }
 
+// #5418: a missing file can't stream, so it never enters the queue. Returns
+// the same array when nothing is missing.
+function playable(tracks: TrackRef[]): TrackRef[] {
+  return tracks.some((t) => t.unavailable) ? tracks.filter((t) => !t.unavailable) : tracks;
+}
+
 export function playQueue(
   tracks: TrackRef[],
   startIndex = 0,
@@ -138,8 +144,16 @@ export function playQueue(
   // rotation-aware order, so no client shuffle in that path).
   _queueSource = opts.source ?? null;
   // #968: a fresh play replaces the self-heal closure + resets its budget.
-  _queueRefetch = opts.refetch ?? null;
+  const refetch = opts.refetch;
+  _queueRefetch = refetch ? () => refetch().then(playable) : null;
   _selfHealAttempts = 0;
+  // Start on the chosen track's place in the playable list; if the chosen
+  // one is missing, that place holds the next playable track after it.
+  const all = tracks;
+  tracks = playable(all);
+  if (tracks !== all) {
+    startIndex = all.slice(0, startIndex).filter((t) => !t.unavailable).length;
+  }
   if (opts.shuffle && tracks.length > 1) {
     // Fisher-Yates over the whole list. startIndex is ignored — the
     // caller is asking for "random play from this pool," so the first
@@ -391,6 +405,7 @@ function trySelfHeal(): boolean {
 
 export function enqueueTrack(t: TrackRef): void {
   _radioSeedId = null;  // M4c
+  if (t.unavailable) return;
   _queue = [..._queue, t];
   if (_state === 'idle') _index = 0;
 }
@@ -402,6 +417,7 @@ export function enqueueTrack(t: TrackRef): void {
  */
 export function playNext(t: TrackRef): void {
   _radioSeedId = null; // M4c: any user-driven enqueue clears the radio refresh state
+  if (t.unavailable) return;
   if (_queue.length === 0) {
     _queue = [t];
     _index = 0;
@@ -413,6 +429,7 @@ export function playNext(t: TrackRef): void {
 
 export function enqueueTracks(ts: TrackRef[]): void {
   _radioSeedId = null;  // M4c
+  ts = playable(ts);
   if (ts.length === 0) return;
   _queue = [..._queue, ...ts];
   if (_state === 'idle') _index = 0;
@@ -423,6 +440,7 @@ export function enqueueTracks(ts: TrackRef[]): void {
 // with the batch at index 0 (mirrors playNext's single-track shape).
 export function playNextMany(ts: TrackRef[]): void {
   _radioSeedId = null;
+  ts = playable(ts);
   if (ts.length === 0) return;
   if (_queue.length === 0) {
     _queue = [...ts];

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

@@ -338,6 +338,7 @@ import {
   enqueueTrack,
   enqueueTracks,
   playNext,
+  playNextMany,
   playRadio,
   moveQueueItem,
   removeFromQueue,
@@ -398,6 +399,42 @@ describe('player store — enqueue + playRadio', () => {
   });
 });
 
+// #5418: a missing file can't stream, so no entry point lets one into the queue.
+describe('missing files stay out of the queue', () => {
+  const gone = (id: string) => ({ ...track(id), unavailable: true });
+
+  test('playQueue drops them and starts on the chosen track', () => {
+    playQueue([track('1'), gone('2'), track('3'), track('4')], 2);
+    expect(player.queue.map((t) => t.id)).toEqual(['1', '3', '4']);
+    expect(player.current?.id).toBe('3');
+  });
+
+  test('playQueue on a missing track starts on the next playable one', () => {
+    playQueue([track('1'), gone('2'), track('3')], 1);
+    expect(player.current?.id).toBe('3');
+  });
+
+  test('playQueue with a missing tail starts on the last playable one', () => {
+    playQueue([track('1'), gone('2')], 1);
+    expect(player.current?.id).toBe('1');
+  });
+
+  test('playQueue of only missing files leaves the player idle', () => {
+    playQueue([gone('1'), gone('2')], 0);
+    expect(player.queue).toEqual([]);
+    expect(player.state).toBe('idle');
+  });
+
+  test('enqueue and play-next skip them', () => {
+    playQueue([track('a')], 0);
+    enqueueTrack(gone('b'));
+    playNext(gone('c'));
+    enqueueTracks([gone('d'), track('e')]);
+    playNextMany([track('f'), gone('g')]);
+    expect(player.queue.map((t) => t.id)).toEqual(['a', 'f', 'e']);
+  });
+});
+
 describe('playNext', () => {
   test('splices at _index + 1, leaving _index unchanged', () => {
     playQueue([track('a'), track('b')], 0);