bump VERSION to 0.7.1

Terminals answer OSC 10/11/12 color queries but never push changes, so
detect theme flips with a 60 s poll (legacy-tmux fallback for servers
< 3.6). Re-queries palette + default fg/bg, updates the system palette
and re-detects dark/light mode.

README.md

@@ -16,6 +16,8 @@ external player with full transport control — all from your terminal.
 - **Search** across your subscribed shows.
 - **Audio playback** through an external player with full transport control:
   play/pause, next/previous, seek, speed, and per-episode resume progress.
+  When an episode finishes, the next one plays automatically, continuing
+  down the list you started it from (search results, a show, or the Feed).
 - **Themeable** and **remappable keybindings**.
 - Ships as a **standalone compiled binary** — no runtime or install step beyond
   a system audio player.
@@ -208,7 +210,9 @@ entry. Releases are compiled with bunfig autoload disabled
 entirely. If you still hit it, you're on an old release — upgrade.
 
 **No audio — playback is a silent no-op** — PodTui needs **mpv** on your
-`PATH`. Install it (`brew install mpv`, `pacman -S mpv`, …) and relaunch.
+`PATH`. Homebrew and AUR installs pull it in automatically; if you used the
+standalone tarball, install it yourself (`brew install mpv`, `pacman -S mpv`,
+…) and relaunch.
 
 **Homebrew prints a dylib warning** — “load commands do not fit in the header
 … needs `-headerpad`” is benign: the app loads its libraries by path, the

src/context/ThemeContext.tsx

@@ -120,6 +120,14 @@ const EMPTY_TERMINAL_COLORS: TerminalColors = {
 /** Cached macOS appearance (dark/light), independent of the terminal. */
 let cachedOsMode: "dark" | "light" | null = null;
 
+/**
+ * How often to re-query the terminal for theme changes (OSC 10/11/12).
+ * Terminals only answer these queries — they never push a color change —
+ * so detection is a slow poll. 60 s keeps CPU cost unmeasurable while
+ * still tracking theme flips within a reasonable delay.
+ */
+const SYSTEM_THEME_POLL_MS = 60_000;
+
 /**
  * Detect the terminal's dark/light mode.
  *
@@ -215,7 +223,12 @@ export const { use: useTheme, provider: ThemeProvider } = createSimpleContext({
       });
     }
 
-    async function resolveSystemTheme() {
+    /**
+     * Query the terminal's colors via OSC (palette + default fg/bg), with a
+     * legacy-tmux fallback for servers < 3.6 that don't forward OSC replies.
+     * Returns null when the terminal cannot answer.
+     */
+    async function queryTerminalColors(): Promise<TerminalColors | null> {
       if (process.env.TMUX) {
         await waitForCapabilities();
       }
@@ -254,6 +267,12 @@ export const { use: useTheme, provider: ThemeProvider } = createSimpleContext({
         }
       }
 
+      return colors;
+    }
+
+    async function resolveSystemTheme() {
+      const colors = await queryTerminalColors();
+
       // ── dark/light mode detection ─────────────────────────────────────────
       // The provider starts with a hardcoded mode (e.g. "dark"); detect the
       // real one from the terminal's background color (OSC 11) or, when that
@@ -299,8 +318,55 @@ export const { use: useTheme, provider: ThemeProvider } = createSimpleContext({
       }
     }
 
+    /**
+     * Poll for terminal theme changes: re-query OSC colors, update the
+     * system palette when it differs, and re-detect dark/light mode.
+     * Runs on a slow timer (see SYSTEM_THEME_POLL_MS); most polls change
+     * nothing and only pay the idle query round-trip.
+     */
+    async function pollSystemTheme() {
+      if (!store.ready) return;
+      const colors = await queryTerminalColors();
+      if (!colors) return;
+
+      const current = store.system;
+      const changed =
+        !current ||
+        current.defaultBackground !== colors.defaultBackground ||
+        current.defaultForeground !== colors.defaultForeground ||
+        current.palette.join(",") !== colors.palette.join(",");
+
+      if (changed) {
+        setStore(
+          produce((draft) => {
+            draft.system = colors;
+          }),
+        );
+      }
+
+      // Refresh the OS-appearance fallback only when the terminal cannot
+      // report a background (e.g. tmux without OSC forwarding), so the
+      // common path never spawns a subprocess.
+      if (process.platform === "darwin" && !colors.defaultBackground) {
+        cachedOsMode = null;
+      }
+      const detectedMode = detectSystemMode(colors);
+      if (detectedMode && detectedMode !== store.mode) {
+        setStore("mode", detectedMode);
+        emitThemeModeChanged(detectedMode);
+      }
+    }
+
     onMount(init);
 
+    // Poll the terminal for theme changes (see pollSystemTheme). Registered
+    // once per provider init — SIGUSR2 re-runs the inner `init`, not this
+    // closure, so the timer cannot stack.
+    const pollTimer = setInterval(() => {
+      void pollSystemTheme();
+    }, SYSTEM_THEME_POLL_MS);
+    onCleanup(() => clearInterval(pollTimer));
+
     // Setup SIGUSR2 signal handler for dynamic theme reload
     // This allows external tools to trigger a theme refresh by sending:
     // `kill -USR2 <pid>`

src/hooks/useAudio.ts

@@ -55,10 +55,15 @@ import {
 	saveLastPlayerSync,
 } from "../utils/app-persistence";
 import type { Episode, Progress } from "../types/episode";
-import type { Feed } from "../types/feed";
-import { useAudioNavStore, AudioSource } from "../stores/audio-nav";
+import { useAudioNavStore } from "../stores/audio-nav";
 import { useDownloadStore } from "../stores/download";
 import { useFeedStore } from "../stores/feed";
+import { useSearchStore } from "../stores/search";
+import {
+	nextStep,
+	prevStep,
+	queueForSource,
+} from "../utils/audio-queue";
 
 export interface AudioControls {
 	// Signals (reactive getters)
@@ -180,8 +185,10 @@ const PAUSE_WATCH_TICKS = 7;
 
 /** The player process died while we believed playback was live — track
  *  ended (mpv quits at EOF) or the process crashed. Persist the final
- *  position and stop polling. */
-function finalizeTrackEnd(): void {
+ *  position and stop polling. `autoAdvance` is true only when the track
+ *  reached its natural end with the player still alive and no stream error
+ *  — the signal to keep the queue going. */
+function finalizeTrackEnd(autoAdvance: boolean): void {
 	setIsPlaying(false);
 	stopPolling();
 	const ep = currentEpisode();
@@ -189,6 +196,12 @@ function finalizeTrackEnd(): void {
 		const progressStore = useProgressStore();
 		progressStore.update(ep.id, position(), duration(), speed());
 	}
+	if (autoAdvance) {
+		// The episode finished: play the next one from the source that
+		// started it (search results / show / feed). No-op at the end of
+		// the list or when the episode isn't in the source list anymore.
+		void next().catch(() => {});
+	}
 }
 
 /** mpv paused itself OUTSIDE PodTUI — system sleep/lock, AirPod removal,
@@ -235,7 +248,12 @@ function startPolling(): void {
 				// and reports pause=true there, which would otherwise be
 				// mistaken for an external pause and never finalize.
 				if (!backend.isPlaying()) {
-					finalizeTrackEnd();
+					// Natural EOF (player alive, no stream error) auto-advances
+					// to the next episode; a crashed/killed daemon or a failed
+					// stream must not start the next episode on its own.
+					finalizeTrackEnd(
+						backend.isAlive() && !backend.getPlaybackError(),
+					);
 					return;
 				}
 
@@ -270,7 +288,7 @@ function startPolling(): void {
 				// still alive: a dead player while we thought we were paused
 				// means the track ended (mpv quits at EOF) or it crashed.
 				if (!backend.isAlive()) {
-					finalizeTrackEnd();
+					finalizeTrackEnd(false);
 					return;
 				}
 				const paused = await backend.getPauseState();
@@ -335,21 +353,52 @@ async function play(episode: Episode): Promise<void> {
 		return;
 	}
 
-	try {
-		const appStore = useAppStore();
-		const progressStore = useProgressStore();
-		const storeSpeed = appStore.state().settings.playbackSpeed;
-		const vol = volume();
-		const spd = storeSpeed || speed();
+	const appStore = useAppStore();
+	const progressStore = useProgressStore();
+	const storeSpeed = appStore.state().settings.playbackSpeed;
+	const vol = volume();
+	const spd = storeSpeed || speed();
 
-		const feedStore = useFeedStore();
-		const feed = feedStore.feeds().find((f) => f.podcast.id === episode.podcastId);
-		const podcastTitle = feed?.customName || feed?.podcast.title || "";
-		// Play the downloaded file when present (offline + no network stalls);
-		// otherwise stream. Cover resolves to the feed art, falling back to the
-		// episode's own image (feeds added by URL may lack a channel cover).
-		const downloadStore = useDownloadStore();
-		const url = downloadStore.getDownloadedFilePath(episode.id) ?? episode.audioUrl;
+	const feedStore = useFeedStore();
+	const feed = feedStore.feeds().find((f) => f.podcast.id === episode.podcastId);
+	const podcastTitle = feed?.customName || feed?.podcast.title || "";
+	// Play the downloaded file when present (offline + no network stalls);
+	// otherwise stream. Cover resolves to the feed art, falling back to the
+	// episode's own image (feeds added by URL may lack a channel cover).
+	const downloadStore = useDownloadStore();
+	const url = downloadStore.getDownloadedFilePath(episode.id) ?? episode.audioUrl;
+
+	// Resume from saved progress if available and not completed
+	const savedProgress = progressStore.get(episode.id);
+	let startPos = 0;
+	if (savedProgress && !progressStore.isCompleted(episode.id)) {
+		startPos = savedProgress.position;
+	}
+
+	// Present the new episode in the UI IMMEDIATELY, before the backend load
+	// (cover fetch + loadfile can take a few hundred ms): the player tab,
+	// status bar, and OS Now Playing must not keep showing the previous
+	// episode during the swap. The previous track's poll is stopped so it
+	// can't attribute its position/progress to the new episode; polling
+	// restarts once the backend is actually playing. Mirrors load()'s
+	// synchronous presentation.
+	stopPolling();
+	setCurrentEpisode(episode);
+	setIsPlaying(false);
+	startedPlayback = false;
+	setPosition(startPos);
+	setSpeed(spd);
+	if (episode.duration) setDuration(episode.duration);
+	const media = useMediaRegistry();
+	media.setNowPlaying({
+		title: episode.title,
+		artist: podcastTitle || episode.podcastId,
+		duration: episode.duration,
+	});
+	media.setPlaybackState(false);
+	if (startPos > 0) media.setPosition(startPos);
+
+	try {
 		// Cover art only applies at file LOAD (the runtime video-add fallback
 		// never becomes an albumart track), so a cold-cache play must wait for
 		// the fetch or play artless. Serve the disk cache synchronously; on a
@@ -360,13 +409,6 @@ async function play(episode: Episode): Promise<void> {
 			"bounded",
 		);
 
-		// Resume from saved progress if available and not completed
-		const savedProgress = progressStore.get(episode.id);
-		let startPos = 0;
-		if (savedProgress && !progressStore.isCompleted(episode.id)) {
-			startPos = savedProgress.position;
-		}
-
 		await b.play(url, {
 			volume: vol,
 			speed: spd,
@@ -375,10 +417,8 @@ async function play(episode: Episode): Promise<void> {
 			coverArtPath: coverArtPath ?? undefined,
 		});
 
-		setCurrentEpisode(episode);
 		setIsPlaying(true);
 		setPosition(startPos);
-		setSpeed(spd);
 		if (episode.duration) setDuration(episode.duration);
 		startedPlayback = true;
 
@@ -387,12 +427,6 @@ async function play(episode: Episode): Promise<void> {
 		saveLastPlayerToFile({ episodeId: episode.id, timestamp: new Date() });
 
 		// Register with platform media controls
-		const media = useMediaRegistry();
-		media.setNowPlaying({
-			title: episode.title,
-			artist: podcastTitle || episode.podcastId,
-			duration: episode.duration,
-		});
 		media.setPlaybackState(true);
 		if (startPos > 0) media.setPosition(startPos);
 
@@ -728,6 +762,60 @@ export async function restoreLastSession(): Promise<void> {
  * Returns a singleton — all components share the same playback state.
  * Registers event bus listeners and cleans them up with onCleanup.
  */
+
+// ── Episode queue navigation ──────────────────────────────────────────────
+// `next`/`prev` (and the end-of-episode auto-advance in finalizeTrackEnd)
+// move within the ordered list of the source that STARTED the current
+// episode: the Feed's chronological list, the current show's episodes, or
+// the search results (see utils/audio-queue). Module-level so
+// finalizeTrackEnd can auto-advance without a mounted hook owner.
+
+const audioNav = useAudioNavStore();
+
+/** The ordered playable episodes for the source that started playback. */
+function queueForCurrentSource(): Episode[] {
+	const feedStore = useFeedStore();
+	return queueForSource(
+		audioNav.getSource(),
+		audioNav.getPodcastId(),
+		feedStore.feeds(),
+		feedStore.getAllEpisodesChronological(),
+		useSearchStore().results(),
+	);
+}
+
+async function next(): Promise<void> {
+	const current = currentEpisode();
+	if (!current) return;
+	const step = nextStep(queueForCurrentSource(), current.id);
+	// A duplicated queue entry (same episode id twice) must not make
+	// "next" replay the CURRENT episode — that would reload it from
+	// saved progress and audibly repeat already-played audio.
+	if (!step || step.episode.id === current.id) return;
+	await play(step.episode);
+	audioNav.next(step.index);
+}
+
+async function prev(): Promise<void> {
+	const current = currentEpisode();
+	if (!current) return;
+
+	// Standard transport behavior: past 30s in, "prev" restarts the current
+	// episode; before that it steps back within the source queue.
+	const NAV_START_THRESHOLD = 30;
+	const currentPos = position();
+	const currentDur = duration();
+	if (currentPos > NAV_START_THRESHOLD && currentDur > 0) {
+		await seek(NAV_START_THRESHOLD);
+		return;
+	}
+
+	const step = prevStep(queueForCurrentSource(), current.id);
+	if (!step) return;
+	await play(step.episode);
+	audioNav.prev(step.index);
+}
+
 export function useAudio(): AudioControls {
 	// Initialize backend on first use
 	ensureBackend();
@@ -793,80 +881,6 @@ export function useAudio(): AudioControls {
 		await doSetSpeed(next);
 	});
 
-	const audioNav = useAudioNavStore();
-	const feedStore = useFeedStore();
-
-	async function prev(): Promise<void> {
-		const current = currentEpisode();
-		if (!current) return;
-
-		const currentPos = position();
-		const currentDur = duration();
-
-		const NAV_START_THRESHOLD = 30;
-
-		if (currentPos > NAV_START_THRESHOLD && currentDur > 0) {
-			await seek(NAV_START_THRESHOLD);
-		} else {
-			const source = audioNav.getSource();
-			let episodes: Array<{ episode: Episode; feed: Feed }> = [];
-
-			if (source === AudioSource.FEED) {
-				episodes = feedStore.getAllEpisodesChronological();
-			} else if (source === AudioSource.MY_SHOWS) {
-				const podcastId = audioNav.getPodcastId();
-				if (!podcastId) return;
-
-				const feed = feedStore
-					.getFilteredFeeds()
-					.find((f) => f.podcast.id === podcastId);
-				if (!feed) return;
-
-				episodes = feed.episodes.map((ep) => ({ episode: ep, feed }));
-			}
-
-			const currentIndex = audioNav.getCurrentIndex();
-			const newIndex = Math.max(0, currentIndex - 1);
-
-			if (newIndex < episodes.length && episodes[newIndex]) {
-				const { episode } = episodes[newIndex];
-				await play(episode);
-				audioNav.prev(newIndex);
-			}
-		}
-	}
-
-	async function next(): Promise<void> {
-		const current = currentEpisode();
-		if (!current) return;
-
-		const source = audioNav.getSource();
-		let episodes: Array<{ episode: Episode; feed: Feed }> = [];
-
-		if (source === AudioSource.FEED) {
-			episodes = feedStore.getAllEpisodesChronological();
-		} else if (source === AudioSource.MY_SHOWS) {
-			const podcastId = audioNav.getPodcastId();
-			if (!podcastId) return;
-
-			const feed = feedStore
-				.getFilteredFeeds()
-				.find((f) => f.podcast.id === podcastId);
-			if (!feed) return;
-
-			episodes = feed.episodes.map((ep) => ({ episode: ep, feed }));
-		}
-
-		const currentIndex = audioNav.getCurrentIndex();
-		const newIndex = Math.min(episodes.length - 1, currentIndex + 1);
-
-		if (newIndex >= 0 && episodes[newIndex]) {
-			const { episode } = episodes[newIndex];
-			await play(episode);
-			audioNav.next(newIndex);
-		}
-	}
-
 	onCleanup(() => {
 		refCount--;
 		unsubPlay();

src/index.tsx

@@ -1,7 +1,7 @@
 import type { Feed } from "./types/feed"
 import type { Episode } from "./types/episode"
 
-const VERSION = "0.7.0";
+const VERSION = "0.7.1";
 
 interface CliArgs {
 	version: boolean;

src/pages/Player/RealtimeWaveform.tsx

@@ -8,8 +8,9 @@
  *
  * This component only subscribes to store state, reports the width-derived
  * bar count (terminal resize re-inits the running pipeline), and renders:
- * a braille spinner while the pipeline is loading its first frames, the
- * frequency bars once frames arrive, and a dotted placeholder when idle.
+ * a braille spinner while the pipeline is loading its first frames or the
+ * player is stalled (re-buffering), the frequency bars once frames arrive,
+ * and a dotted placeholder when idle.
  */
 
 import { createEffect, on } from "solid-js";
@@ -53,12 +54,13 @@ export function RealtimeWaveform() {
 		const bars = viz.barData();
 		const count = numBars();
 
-		// Loading state: the braille spinner shows while the pipeline warms
-		// up — but only when there are no bars to render yet (first play /
-		// after an unload). On resume/seek the last bars stay on screen
-		// until fresh frames arrive, so the waveform never blanks out for
-		// the (multi-second, network-bound) cold start.
-		if (bars.length === 0 && viz.isLoading()) {
+		// Loading state: the braille spinner shows while the pipeline is
+		// warming up — cold start (first play / after an unload), resume
+		// into undecoded audio, or a stalled position clock (mpv
+		// re-buffering after a long pause on a network stream). The store
+		// clears it the moment the first fresh frame renders, so stale
+		// bars never masquerade as live data while the pipeline re-arms.
+		if (viz.isLoading() || viz.isStalled()) {
 			return <LoadingIndicator />;
 		}
 

src/stores/visualizer.ts

@@ -25,6 +25,12 @@
  * after the Player tab stops being focused it tears down. Reads outside
  * decoded coverage return empty — the renderer simply holds the last frame
  * until the decode frontier arrives.
+ *
+ * Loading semantics: `isLoading` is true from any pipeline start (cold
+ * start, resume into undecoded audio) until the first complete FFT frame,
+ * and `isStalled` while playback claims to be live but the position clock
+ * is frozen (player re-buffering). The component renders the spinner for
+ * either; bars replace it the moment fresh frames arrive.
  */
 
 import {
@@ -55,6 +61,14 @@ const FRAME_INTERVAL = 33;
 /** Number of PCM samples to read per frame (512 is a good FFT window) */
 const SAMPLES_PER_FRAME = 512;
 
+/**
+ * How long the position clock may stay frozen while the UI believes
+ * playback is live before the waveform reports a stall (loading state).
+ * mpv polls time-pos every ~150ms, so a frozen clock means the player is
+ * re-buffering — the long-pause-then-resume case on network streams.
+ */
+const STALL_DETECT_MS = 2000;
+
 /** Timer handle as returned by setTimeout/setInterval in this runtime. */
 type TimerHandle = ReturnType<typeof setTimeout>;
 
@@ -65,6 +79,10 @@ export interface VisualizerStore {
 	barData: () => number[];
 	/** True from pipeline start until the first complete FFT frame renders. */
 	isLoading: () => boolean;
+	/** True while playback claims to be live but the position clock has
+	 *  been frozen past STALL_DETECT_MS (player re-buffering, e.g. after a
+	 *  long pause on a network stream). */
+	isStalled: () => boolean;
 	/** True while the ~30fps render loop is armed. */
 	isRunning: () => boolean;
 	/** Report whether the Player tab is the visible tab. */
@@ -82,6 +100,10 @@ function createVisualizerStore(): VisualizerStore {
 	// True from pipeline start until the first complete FFT frame renders.
 	const [isLoading, setIsLoading] = createSignal(false);
 
+	// True while playback is live but the position clock is frozen
+	// (player re-buffering) — see STALL_DETECT_MS.
+	const [isStalled, setIsStalled] = createSignal(false);
+
 	// Whether the Player tab is the visible tab (fed by PlayerPage).
 	const [focused, setFocused] = createSignal(false);
 
@@ -103,6 +125,20 @@ function createVisualizerStore(): VisualizerStore {
 	let sampleBuffer: Float64Array | null = null;
 	let unloadTimer: TimerHandle | null = null;
 
+	// Stall tracker: last observed position-signal value and when it moved.
+	// Any change (forward, backward, seek) re-arms the clock; a frozen
+	// signal while playing trips isStalled after STALL_DETECT_MS.
+	let lastRenderPos = -1;
+	let lastPosMoveAt = 0;
+
+	// Resume point: the position a paused pipeline was re-armed at. The
+	// loading state set by resume only clears once the position clock has
+	// advanced PAST this — while the player is still re-buffering, the
+	// cache can serve the same window forever and the stale pre-pause bars
+	// must not masquerade as live data. -1 = cold start (clear on the
+	// first produced frame, regardless of the clock).
+	let resumePos = -1;
+
 	// What the running pipeline was started with — lets the playback effect
 	// tell "nothing changed, stay warm" from "must restart".
 	let activeUrl = "";
@@ -200,9 +236,19 @@ function createVisualizerStore(): VisualizerStore {
 		lastPolledPosition = position;
 		lastPolledAt = performance.now();
 
+		// Seed the stall tracker: a fresh pipeline should not report a
+		// stall just because the first position poll hasn't landed.
+		lastRenderPos = position;
+		lastPosMoveAt = performance.now();
+
+		// Cold start: the loading state clears on the first produced frame
+		// (see renderFrame) — no resume-position gating.
+		resumePos = -1;
+
 		activeUrl = url;
 		activeBars = barCount();
 		setIsLoading(true);
+		setIsStalled(false);
 		frameTimer = setInterval(renderFrame, FRAME_INTERVAL);
 	};
 
@@ -224,6 +270,14 @@ function createVisualizerStore(): VisualizerStore {
 		}
 		sampleBuffer = null;
 		setIsLoading(false);
+		setIsStalled(false);
+		// Drop the last rendered frame: after a stop the bars are stale (a
+		// different episode, a different position) and would masquerade as
+		// live data while the next cold start warms up — and, because the
+		// component only shows the spinner while bars are empty, they'd
+		// also suppress the loading state. Cold restarts re-render fresh
+		// bars within the first frame.
+		setBarData([]);
 	};
 
 	// ── Pause: freeze the loop, keep the cache ──────────────────────────
@@ -248,6 +302,7 @@ function createVisualizerStore(): VisualizerStore {
 		// (still cold-starting when paused), the component should fall back
 		// to the placeholder, not freeze on a spinner.
 		setIsLoading(false);
+		setIsStalled(false);
 	};
 
 	// ── Resume: re-arm the render loop, top up the cache ───────────────
@@ -269,6 +324,20 @@ function createVisualizerStore(): VisualizerStore {
 
 		lastPolledPosition = pos;
 		lastPolledAt = performance.now();
+		// Re-arm the stall tracker from the resume position (a long pause
+		// left the old timestamps stale — they'd trip the stall detector on
+		// the very first frame otherwise).
+		lastRenderPos = pos;
+		lastPosMoveAt = performance.now();
+
+		// Resume re-arms a pipeline whose ffmpeg pass was killed at pause:
+		// the pre-pause bars are stale until fresh frames flow, so show the
+		// loading state IN THEIR PLACE. It clears only once the position
+		// clock has advanced past the resume point (see renderFrame) — a
+		// player still re-buffering after a long pause keeps the spinner
+		// instead of serving static cached bars.
+		resumePos = pos;
+		setIsLoading(true);
 		frameTimer = setInterval(renderFrame, FRAME_INTERVAL);
 		return true;
 	};
@@ -282,6 +351,26 @@ function createVisualizerStore(): VisualizerStore {
 		// coverage (decode cold start, seek into a hole) the read is empty
 		// and the LAST FRAME simply holds — never clamped/repeated junk.
 		const target = smoothPosition();
+
+		// Stall detection: while the UI believes playback is live, the
+		// position signal must keep advancing (useAudio polls it every
+		// ~150ms). A frozen clock with a warm pipeline means the player is
+		// re-buffering — the classic long-pause-then-resume on a network
+		// stream — and without this the waveform shows dead-looking static
+		// bars for the whole stall. Report it as loading; the first frame
+		// after the clock moves again clears it.
+		const rawPos = audioPlaybackSignals.position();
+		if (rawPos !== lastRenderPos) {
+			lastRenderPos = rawPos;
+			lastPosMoveAt = performance.now();
+			if (isStalled()) setIsStalled(false);
+		} else if (
+			audioPlaybackSignals.isPlaying() &&
+			performance.now() - lastPosMoveAt > STALL_DETECT_MS
+		) {
+			setIsStalled(true);
+		}
+
 		const count = pcm.readWindow(sampleBuffer, target);
 		// Never feed a partial FFT window to cava.
 		if (count < sampleBuffer.length) return;
@@ -290,7 +379,14 @@ function createVisualizerStore(): VisualizerStore {
 
 		// Normalize against the running peak and copy to a new array
 		setBarData(scaler(output));
-		if (isLoading()) setIsLoading(false);
+		// Fresh frames only count once the position clock has moved past
+		// the resume point: while the player is still re-buffering after a
+		// long pause, the cache serves the same window and the spinner must
+		// stay in place of the stale bars. Cold starts (resumePos < 0)
+		// clear on the first frame as before.
+		if (isLoading() && (resumePos < 0 || rawPos > resumePos)) {
+			setIsLoading(false);
+		}
 	};
 
 	// ── Playback subscription ──────────────────────────────────────────
@@ -425,6 +521,7 @@ function createVisualizerStore(): VisualizerStore {
 		// state
 		barData,
 		isLoading,
+		isStalled,
 		isRunning: () => frameTimer !== null,
 		// inputs
 		setFocused,

src/utils/audio-player.ts

@@ -82,6 +82,11 @@ export interface AudioBackend {
 	getPauseState(): Promise<boolean | undefined>;
 	/** True while the player process is running (regardless of pause). */
 	isAlive(): boolean;
+	/** Last playback error (end-file reason "error"), or null when the last
+	 *  track ended cleanly (or nothing has failed yet). Lets callers
+	 *  distinguish a natural end-of-file from a stream failure — a failed
+	 *  episode must not auto-advance the queue. */
+	getPlaybackError(): string | null;
 	dispose(): void;
 }
 
@@ -591,13 +596,22 @@ export class MpvBackend implements AudioBackend {
 		// play checks it and skips its own stale paused-load.
 		this._intentPlaying = true;
 		await this.runLoadExclusive(async () => {
-			// Fast path: this exact URL was PRELOADED paused (boot restore) —
-			// mpv has been buffering it since boot, so flipping pause off starts
-			// audio ~instantly. Re-acquire the start position only when it
-			// moved meaningfully since the preload (progress saved meanwhile).
-			if (this._loadedUrl === url && this._loadedPaused && !this._ended) {
+			// Same episode re-selected (Enter in a list, key-repeat, a
+			// second tap on the playing row): the file is ALREADY in the
+			// player. Reloading with start=<saved progress> would audibly
+			// skip BACK and repeat already-played audio (saved progress
+			// lags the live position by up to the 5s persist interval), so
+			// align in place instead:
+			//   - preload park (loaded paused at boot restore): seek only
+			//     when the caller's target moved materially since load;
+			//   - user-paused: unpause at the CURRENT position (saved
+			//     progress is stale and must not become a backward seek);
+			//   - already playing: unpause is a no-op — nothing to do.
+			// A genuinely finished episode (_ended) still falls through to
+			// a fresh load, which replays from the top via isCompleted.
+			if (this._loadedUrl === url && !this._ended) {
 				const target = opts?.startPosition ?? this._position;
-				if (Math.abs(target - this._position) > 2) {
+				if (this._loadedPaused && Math.abs(target - this._position) > 2) {
 					await this.send(["set_property", "time-pos", target]);
 					this._position = target;
 				}
@@ -782,6 +796,9 @@ class NoopBackend implements AudioBackend {
 	isAlive(): boolean {
 		return false;
 	}
+	getPlaybackError(): string | null {
+		return null;
+	}
 	dispose(): void {}
 }
 

src/utils/audio-queue.ts

@@ -0,0 +1,88 @@
+/**
+ * audio-queue — ordered episode queue for "what plays next" navigation.
+ *
+ * Pure selection logic for source-based auto-advance (and manual next/prev):
+ * given the navigation source that STARTED the current episode, which
+ * episodes come after it?
+ *
+ *   FEED      — the global chronological Feed list (newest first), so "next"
+ *               walks toward older episodes — further down the list.
+ *   MY_SHOWS  — the current show's episode list (newest first), scoped to the
+ *               podcast that started playback.
+ *   SEARCH    — the current search results, in display order (episode-kind
+ *               results only — a show result has nothing to play).
+ *
+ * Kept dependency-light (pure functions over plain data) so the ordering and
+ * bounds contract is unit-testable without stores or audio.
+ */
+
+import type { Episode } from "../types/episode";
+import type { Feed } from "../types/feed";
+import type { SearchResult } from "../types/source";
+import { AudioSource } from "../stores/audio-nav";
+
+/** The ordered playable queue for a navigation source. Empty when the
+ *  source's context is missing (no podcastId, no search results, no feeds). */
+export function queueForSource(
+	source: AudioSource,
+	podcastId: string | undefined,
+	feeds: Feed[],
+	allEpisodes: Array<{ episode: Episode; feed: Feed }>,
+	searchResults: SearchResult[],
+): Episode[] {
+	if (source === AudioSource.FEED) {
+		// Dedupe by episode id: the same episode can appear twice after a
+		// refresh merge or when two feeds list it — a duplicate would make
+		// next/auto-advance step onto the CURRENT episode and replay it.
+		const seen = new Set<string>();
+		const unique: Episode[] = [];
+		for (const e of allEpisodes) {
+			if (seen.has(e.episode.id)) continue;
+			seen.add(e.episode.id);
+			unique.push(e.episode);
+		}
+		return unique;
+	}
+	if (source === AudioSource.MY_SHOWS) {
+		const feed = feeds.find((f) => f.podcast.id === podcastId);
+		return feed ? feed.episodes : [];
+	}
+	if (source === AudioSource.SEARCH) {
+		return searchResults
+			.filter((r) => r.kind === "episode")
+			.map((r) => r.episode);
+	}
+	return [];
+}
+
+/** Index of an episode in the queue, or -1 when the episode isn't in it. */
+export function queueIndex(queue: Episode[], episodeId: string): number {
+	return queue.findIndex((e) => e.id === episodeId);
+}
+
+export interface QueueStep {
+	episode: Episode;
+	index: number;
+}
+
+/** The episode after `episodeId` in the queue, with its index. Null when
+ *  the episode isn't in the queue or is already the last one. */
+export function nextStep(
+	queue: Episode[],
+	episodeId: string,
+): QueueStep | null {
+	const idx = queueIndex(queue, episodeId);
+	if (idx < 0 || idx + 1 >= queue.length) return null;
+	return { episode: queue[idx + 1], index: idx + 1 };
+}
+
+/** The episode before `episodeId` in the queue, with its index. Null when
+ *  the episode isn't in the queue or is already the first one. */
+export function prevStep(
+	queue: Episode[],
+	episodeId: string,
+): QueueStep | null {
+	const idx = queueIndex(queue, episodeId);
+	if (idx <= 0) return null;
+	return { episode: queue[idx - 1], index: idx - 1 };
+}

tests/audio-backend.test.ts

@@ -172,6 +172,76 @@ test.skipIf(!hasMpv)(
 	{ timeout: 20000 },
 );
 
+test.skipIf(!hasMpv)(
+	"play() of the already-playing url does NOT reload (no audible skip-back)",
+	async () => {
+		fixtureWavs();
+		const backend = new MpvBackend();
+		try {
+			// Start mid-episode (as a resume would) and let it advance.
+			await backend.play(wavA, { volume: 0, speed: 1, startPosition: 1 });
+			await waitFor(
+				"position advances past the start offset",
+				async () => (await backend.getPosition()) > 1.8,
+			);
+			const before = await backend.getPosition();
+
+			// Re-selecting the SAME episode (Enter in a list, key-repeat)
+			// calls play() with the STALE saved progress. The file is
+			// already loaded — this must not reload from that earlier
+			// position, or the listener hears already-played audio again.
+			await backend.play(wavA, { volume: 0, speed: 1, startPosition: 1 });
+
+			// A reload would drop the position back to ~1; a correct no-op
+			// keeps advancing from where it was.
+			await waitFor(
+				"playback continues past the pre-play position",
+				async () => (await backend.getPosition()) > before + 0.3,
+			);
+			expect(backend.isPlaying()).toBe(true);
+			// And the position never fell back toward the stale offset.
+			expect(await backend.getPosition()).toBeGreaterThan(1.8);
+		} finally {
+			await cleanup(backend);
+		}
+	},
+	{ timeout: 20000 },
+);
+
+test.skipIf(!hasMpv)(
+	"play() of the same url while user-paused resumes at the current position",
+	async () => {
+		fixtureWavs();
+		const backend = new MpvBackend();
+		try {
+			await backend.play(wavB, { volume: 0, speed: 1, startPosition: 1 });
+			await waitFor(
+				"position advances",
+				async () => (await backend.getPosition()) > 2,
+			);
+			await backend.pause();
+			await waitFor(
+				"paused observed",
+				async () => (await backend.getPauseState()) === true,
+			);
+			const pausedAt = await backend.getPosition();
+
+			// Re-selecting the paused episode resumes where it PAUSED — the
+			// stale saved progress must not become a backward seek target.
+			await backend.play(wavB, { volume: 0, speed: 1, startPosition: 1 });
+			expect(backend.isPlaying()).toBe(true);
+			await waitFor(
+				"resumed at the paused position",
+				async () => (await backend.getPosition()) > pausedAt + 0.3,
+			);
+			expect(await backend.getPosition()).toBeGreaterThan(1.5);
+		} finally {
+			await cleanup(backend);
+		}
+	},
+	{ timeout: 20000 },
+);
+
 test.skipIf(!hasMpv)(
 	"daemon killed mid-play: resume() rejects on the fresh idle daemon; play() recovers a new one",
 	async () => {

tests/audio-queue.test.ts

@@ -0,0 +1,155 @@
+/**
+ * audio-queue unit tests — pure selection logic for next/prev navigation
+ * and source-based auto-advance. Covers ordering, bounds, and the
+ * deduplication that prevents "next" from replaying the current episode.
+ */
+import { test, expect } from "bun:test";
+import {
+	queueForSource,
+	queueIndex,
+	nextStep,
+	prevStep,
+} from "../src/utils/audio-queue";
+import { AudioSource } from "../src/stores/audio-nav";
+import type { Episode } from "../src/types/episode";
+import type { Feed } from "../src/types/feed";
+import { FeedVisibility } from "../src/types/feed";
+import type { SearchResult } from "../src/types/source";
+
+function ep(id: string, n: number): Episode {
+	return {
+		id,
+		podcastId: "pod-" + id,
+		title: `Episode ${n}`,
+		description: "",
+		audioUrl: `https://example.com/${id}.mp3`,
+		duration: 600,
+		pubDate: new Date(2026, 0, n),
+	};
+}
+
+function feed(id: string, episodes: Episode[]): Feed {
+	return {
+		id,
+		podcast: {
+			id,
+			title: "Feed " + id,
+			description: "",
+			feedUrl: `https://example.com/${id}.xml`,
+			lastUpdated: new Date(),
+			isSubscribed: true,
+		},
+		episodes,
+		visibility: FeedVisibility.PUBLIC,
+		sourceId: "rss",
+		lastUpdated: new Date(),
+		isPinned: false,
+	};
+}
+
+function episodeResult(episode: Episode): SearchResult {
+	return {
+		sourceId: "itunes",
+		kind: "episode",
+		podcast: {
+			id: episode.podcastId,
+			title: "Show " + episode.podcastId,
+			description: "",
+			feedUrl: `https://example.com/${episode.podcastId}.xml`,
+			lastUpdated: new Date(),
+			isSubscribed: false,
+		},
+		episode,
+	};
+}
+
+const e1 = ep("e1", 1);
+const e2 = ep("e2", 2);
+const e3 = ep("e3", 3);
+
+test("FEED queue is the chronological global list, newest first", () => {
+	const f1 = feed("f1", [e3, e2]);
+	const f2 = feed("f2", [e1]);
+	const queue = queueForSource(
+		AudioSource.FEED,
+		undefined,
+		[f1, f2],
+		[
+			{ episode: e3, feed: f1 },
+			{ episode: e2, feed: f1 },
+			{ episode: e1, feed: f2 },
+		],
+		[],
+	);
+	expect(queue.map((e) => e.id)).toEqual(["e3", "e2", "e1"]);
+	expect(queueIndex(queue, "e2")).toBe(1);
+	expect(nextStep(queue, "e2")?.episode.id).toBe("e1");
+	expect(prevStep(queue, "e2")?.episode.id).toBe("e3");
+	expect(nextStep(queue, "e1")).toBeNull();
+	expect(prevStep(queue, "e3")).toBeNull();
+});
+
+test("FEED queue dedupes repeated episode ids (same episode listed twice)", () => {
+	// The same episode appears twice in the global list (e.g. a refresh
+	// merge duplicated a feed's entries). Without dedupe, nextStep after
+	// e2 would step onto e2 AGAIN — replaying the current episode.
+	const f1 = feed("f1", [e3, e2, e2, e1]);
+	const queue = queueForSource(
+		AudioSource.FEED,
+		undefined,
+		[f1],
+		[
+			{ episode: e3, feed: f1 },
+			{ episode: e2, feed: f1 },
+			{ episode: e2, feed: f1 },
+			{ episode: e1, feed: f1 },
+		],
+		[],
+	);
+	expect(queue.map((e) => e.id)).toEqual(["e3", "e2", "e1"]);
+	// Distinct objects sharing an id dedupe too.
+	const e2clone = { ...e2 };
+	const queue2 = queueForSource(
+		AudioSource.FEED,
+		undefined,
+		[f1],
+		[
+			{ episode: e3, feed: f1 },
+			{ episode: e2, feed: f1 },
+			{ episode: e2clone, feed: f1 },
+		],
+		[],
+	);
+	expect(queue2.map((e) => e.id)).toEqual(["e3", "e2"]);
+	expect(nextStep(queue2, "e2")).toBeNull(); // no self-step
+});
+
+test("MY_SHOWS queue scopes to the podcast that started playback", () => {
+	const fA = feed("podA", [e3, e2]);
+	const fB = feed("podB", [e1]);
+	const queue = queueForSource(
+		AudioSource.MY_SHOWS,
+		"podA",
+		[fA, fB],
+		[],
+		[],
+	);
+	expect(queue.map((e) => e.id)).toEqual(["e3", "e2"]);
+	// Unknown podcastId → empty queue (nothing to play next).
+	expect(
+		queueForSource(AudioSource.MY_SHOWS, "podX", [fA, fB], [], []),
+	).toEqual([]);
+});
+
+test("SEARCH queue filters to episode-kind results in display order", () => {
+	const queue = queueForSource(
+		AudioSource.SEARCH,
+		undefined,
+		[],
+		[],
+		[episodeResult(e1), episodeResult(e2)],
+	);
+	expect(queue.map((e) => e.id)).toEqual(["e1", "e2"]);
+	expect(queueIndex(queue, "e1")).toBe(0);
+	expect(queueIndex(queue, "e3")).toBe(-1);
+});

tests/auto-advance.test.ts

@@ -0,0 +1,197 @@
+/**
+ * auto-advance.test.ts — "at the end of episodes play the next one, from
+ * the source that started it" feature.
+ *
+ * When a track reaches its natural end (mpv eof-reached), useAudio must
+ * advance to the next episode in the source queue — the current show's
+ * episode list (MY_SHOWS), the Feed's chronological list, or the search
+ * results — and must STOP at the end of the list (no wrap-around). A
+ * crashed/killed daemon must NOT auto-advance (that path is pinned by
+ * external-pause-reconcile.test.ts).
+ *
+ * Integration style (like external-pause-reconcile.test.ts): real stores,
+ * real persistence sandbox, and the REAL mpv backend driven by real audio
+ * files — two short local WAVs served over HTTP, so EOF happens on a
+ * deterministic timer. The show is subscribed through the real feed store's
+ * addFeed() API (no config seeding — works on whatever singleton state this
+ * worker holds), and the audio-nav source is pinned to MY_SHOWS for that
+ * podcast so the queue is scoped and deterministic. Skipped when mpv isn't
+ * installed.
+ */
+import { test, expect, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const hasMpv = !!Bun.which("mpv");
+
+// ── Sandbox BEFORE any app module evaluates ───────────────────────────────
+const CONFIG = mkdtempSync(join(tmpdir(), "podtui-autoadv-"));
+const DATA = mkdtempSync(join(tmpdir(), "podtui-autoadv-data-"));
+process.env.XDG_CONFIG_HOME = CONFIG;
+process.env.XDG_DATA_HOME = DATA;
+process.env.PODTUI_AUDIO_BACKEND = "mpv"; // real backend; EOF is the signal under test
+
+/** 2s mono 16-bit WAV with a sine tone — short enough to EOF fast,
+ *  distinct per episode so playback is unambiguous. */
+function makeWav(freq: number): Buffer {
+	const SAMPLE_RATE = 44100;
+	const DURATION = 2;
+	const dataLen = SAMPLE_RATE * DURATION;
+	const buf = Buffer.alloc(44 + dataLen * 2);
+	buf.write("RIFF", 0);
+	buf.writeUInt32LE(36 + dataLen * 2, 4);
+	buf.write("WAVE", 8);
+	buf.write("fmt ", 12);
+	buf.writeUInt32LE(16, 16); // fmt chunk size
+	buf.writeUInt16LE(1, 20); // PCM
+	buf.writeUInt16LE(1, 22); // mono
+	buf.writeUInt32LE(SAMPLE_RATE, 24);
+	buf.writeUInt32LE(SAMPLE_RATE * 2, 28); // byte rate
+	buf.writeUInt16LE(2, 32); // block align
+	buf.writeUInt16LE(16, 34); // bits per sample
+	buf.write("data", 36);
+	buf.writeUInt32LE(dataLen * 2, 40);
+	for (let i = 0; i < dataLen; i++) {
+		const sample = Math.round(
+			Math.sin((2 * Math.PI * freq * i) / SAMPLE_RATE) * 8000,
+		);
+		buf.writeInt16LE(sample, 44 + i * 2);
+	}
+	return buf;
+}
+const wav1 = makeWav(440);
+const wav2 = makeWav(880);
+
+// ── Local HTTP server: the RSS feed + both audio files ────────────────────
+let server: ReturnType<typeof Bun.serve> | null = null;
+function feedXml(origin: string): string {
+	// Distinct pubDates so ep1 (newest) is episodes[0], ep2 older — "next"
+	// must step DOWN the list toward the older episode.
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0"><channel>
+<title>Auto Advance Show</title>
+<description>auto-advance test feed</description>
+<item>
+<title>Episode One</title>
+<pubDate>2026-08-10T00:00:00Z</pubDate>
+<enclosure url="${origin}/e1.wav" length="${wav1.length}" type="audio/wav"/>
+</item>
+<item>
+<title>Episode Two</title>
+<pubDate>2026-08-01T00:00:00Z</pubDate>
+<enclosure url="${origin}/e2.wav" length="${wav2.length}" type="audio/wav"/>
+</item>
+</channel></rss>`;
+}
+server = Bun.serve({
+	port: 0,
+	fetch(req) {
+		const url = new URL(req.url);
+		if (url.pathname.endsWith(".xml")) {
+			return new Response(feedXml(url.origin), {
+				headers: { "Content-Type": "application/rss+xml" },
+			});
+		}
+		if (url.pathname.endsWith("e1.wav")) {
+			return new Response(wav1.buffer as ArrayBuffer, {
+				headers: { "Content-Type": "audio/wav" },
+			});
+		}
+		if (url.pathname.endsWith("e2.wav")) {
+			return new Response(wav2.buffer as ArrayBuffer, {
+				headers: { "Content-Type": "audio/wav" },
+			});
+		}
+		return new Response("not found", { status: 404 });
+	},
+});
+
+// ── Real modules (loaded after env + server are up) ───────────────────────
+// @ts-expect-error — bun-only query suffix: distinct module identity that
+// loads the real file instead of a leaked mock.module from another test file.
+const { useAudio } = await import("../src/hooks/useAudio?auto-advance-test");
+const { useFeedStore } = await import("../src/stores/feed");
+const { useAudioNavStore, AudioSource } = await import(
+	"../src/stores/audio-nav"
+);
+
+const feedStore = useFeedStore();
+const audioNav = useAudioNavStore();
+
+/** Poll `check` every 25ms until truthy; throw after `timeoutMs`. */
+async function waitFor(
+	check: () => boolean,
+	timeoutMs = 15000,
+): Promise<void> {
+	const start = Date.now();
+	while (!check()) {
+		if (Date.now() - start > timeoutMs) {
+			throw new Error("condition not met in time");
+		}
+		await Bun.sleep(25);
+	}
+}
+
+// Subscribe to the local feed through the real store API; unique podcast id
+// so the MY_SHOWS queue lookup is deterministic whatever else this worker's
+// shared feed store holds.
+const feedUrl = `http://127.0.0.1:${server!.port}/show.xml`;
+const PODCAST_ID = `auto-advance-pod-${process.pid}`;
+const feed = await feedStore.addFeed(
+	{
+		id: PODCAST_ID,
+		title: "Auto Advance Show",
+		description: "auto-advance test feed",
+		feedUrl,
+		lastUpdated: new Date(),
+		isSubscribed: true,
+	},
+	"test-source",
+);
+if (!feed || feed.episodes.length < 2) {
+	throw new Error("test feed did not load two episodes");
+}
+const ep1 = feed.episodes[0]; // newest — plays first
+const ep2 = feed.episodes[1]; // older — must follow automatically
+if (ep1.title !== "Episode One") {
+	throw new Error("episode order unexpected — ep1 is not the newest");
+}
+
+afterAll(() => {
+	audioNav.reset(); // don't leak nav state into shared-worker tests
+	server?.stop(true);
+	rmSync(CONFIG, { recursive: true, force: true });
+	rmSync(DATA, { recursive: true, force: true });
+});
+
+test.skipIf(!hasMpv)(
+	"episode ending auto-plays the next in the show; the last episode stops",
+	async () => {
+		const audio = useAudio();
+		audioNav.setSource(AudioSource.MY_SHOWS, PODCAST_ID);
+
+		// Start the newest episode.
+		await audio.play(ep1);
+		expect(audio.isPlaying()).toBe(true);
+		expect(audio.currentEpisode()?.id).toBe(ep1.id);
+
+		// EOF → the next (older) episode starts automatically, and the nav
+		// index moves with it.
+		await waitFor(
+			() =>
+				audio.currentEpisode()?.id === ep2.id && audio.isPlaying(),
+		);
+		expect(audioNav.getCurrentIndex()).toBe(1);
+
+		// The last episode ends → playback stops; no wrap-around to ep1.
+		await waitFor(() => !audio.isPlaying());
+		expect(audio.currentEpisode()?.id).toBe(ep2.id);
+		await Bun.sleep(600); // give any (wrong) auto-advance time to fire
+		expect(audio.currentEpisode()?.id).toBe(ep2.id);
+		expect(audio.isPlaying()).toBe(false);
+
+		await audio.stop();
+	},
+	{ timeout: 45000 },
+);

tests/visualizer-store.test.ts

@@ -230,15 +230,118 @@ test.skipIf(skip)(
 		app.updateVisualizer({ enabled: false });
 		await waitFor(() => !viz.isRunning(), 10000);
 		expect(viz.isLoading()).toBe(false);
+		// Stopping the pipeline must drop the last rendered frame — a cold
+		// restart (re-enable, unload, episode change) would otherwise show
+		// stale bars from the previous run and never reach the loading
+		// state (the spinner only shows while bars are empty).
+		expect(viz.barData().length).toBe(0);
 
 		app.updateVisualizer({ enabled: true });
-		await waitFor(() => viz.isRunning(), 10000);
+		// The restart surfaces the loading state before the first frame.
+		await waitFor(() => viz.isLoading(), 5000);
 		await waitFor(() => !viz.isLoading() && viz.barData().length > 0, 10000);
 		expect(viz.barData().length).toBe(64);
 	},
 	{ timeout: 20000 },
 );
 
+// A pause followed by a seek while paused, then resume, lands OUTSIDE the
+// decoded sliding window: the cache can't serve bars instantly, so the
+// store must surface the warm-up as a loading state instead of silently
+// holding the stale pre-pause frame. Regression: resumeVisualization never
+// set isLoading, so the last frame froze with no feedback until the
+// re-decode's first frame landed.
+test.skipIf(skip)(
+	"resume into undecoded audio shows the loading state until bars land",
+	async () => {
+		const viz = useVisualizer();
+		await startPlaying();
+		expect(viz.barData().length).toBe(64);
+
+		// Pause, then seek far ahead while paused (outside the ~10s of
+		// decoded coverage), then resume.
+		setIsPlaying(false);
+		await waitFor(() => !viz.isRunning(), 10000);
+		setPosition(30);
+		setIsPlaying(true);
+
+		// The resume position isn't decoded yet — loading, not frozen bars.
+		await waitFor(() => viz.isLoading(), 5000);
+		expect(viz.isRunning()).toBe(true);
+
+		// Playback advances past the resume point (mpv moves the clock);
+		// once the re-decode covers it, fresh bars replace the stale
+		// pre-pause frame (chirp spectrum at 30s ≠ 2s) and the loading
+		// state clears.
+		setPosition(31);
+		const barsBefore = viz.barData();
+		await waitFor(
+			() => !viz.isLoading() && viz.barData() !== barsBefore,
+			15000,
+		);
+		expect(viz.barData().length).toBe(64);
+	},
+	{ timeout: 30000 },
+);
+
+// After a long pause on a network stream, the player (mpv) re-buffers:
+// `isPlaying` stays true but the position clock freezes. Without
+// detection the waveform rendered the same cached window forever — static
+// bars and no feedback. The render loop must report the stall as a
+// loading state and clear it the moment the clock moves again.
+test.skipIf(skip)(
+	"a frozen position clock while playing surfaces a stall; recovery clears it",
+	async () => {
+		const viz = useVisualizer();
+		await startPlaying();
+		expect(viz.isStalled()).toBe(false);
+
+		// Freeze the position: isPlaying stays true, the clock never moves.
+		await waitFor(() => viz.isStalled(), 10000);
+
+		// Player recovers — the clock advances again.
+		setPosition(4);
+		await waitFor(() => !viz.isStalled(), 3000);
+		expect(viz.isRunning()).toBe(true);
+	},
+	{ timeout: 20000 },
+);
+
+// Resume re-arms a pipeline whose ffmpeg pass was killed at pause: the
+// stale pre-pause bars must not masquerade as live data while the player
+// recovers. The spinner shows IN THEIR PLACE until the position clock
+// advances past the resume point — a frozen clock (mpv re-buffering after
+// a long pause) keeps the spinner even though the cache can serve the
+// same window.
+test.skipIf(skip)(
+	"resume shows the loading state in place of stale bars until the position clock advances",
+	async () => {
+		const viz = useVisualizer();
+		await startPlaying();
+		expect(viz.isLoading()).toBe(false);
+
+		// Pause, then resume against the still-covered position.
+		setIsPlaying(false);
+		await waitFor(() => !viz.isRunning(), 10000);
+		setIsPlaying(true);
+
+		// The spinner replaces the bars immediately on resume.
+		await waitFor(() => viz.isLoading(), 5000);
+		expect(viz.isRunning()).toBe(true);
+
+		// Position clock stays frozen at the resume point (re-buffering):
+		// the loading state must persist, not yield to static cached bars.
+		await Bun.sleep(250);
+		expect(viz.isLoading()).toBe(true);
+
+		// Player recovers — the clock advances → fresh bars, spinner gone.
+		setPosition(3);
+		await waitFor(() => !viz.isLoading(), 3000);
+		expect(viz.barData().length).toBe(64);
+	},
+	{ timeout: 20000 },
+);
+
 // ── Teardown ─────────────────────────────────────────────────────────────
 
 afterAll(() => {