From 8d2981313890b303a1d05ba518bbc8075772a642 Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sat, 11 Jul 2026 15:17:36 +0200
Subject: [PATCH 1/2] fix(player): show an error state when media fails to load

isLoading was cleared only by loadedmetadata, and the media elements had
no error handler - a blocked, dead, or unreachable stream URL left the
player spinning forever. Both media elements now handle error by
replacing the spinner with a visible error overlay; the state resets on
the next episode switch. Found while gating all outbound requests (#290):
a refused stream URL looked identical to a slow one.
---
 src/ui/PodcastView/EpisodePlayer.svelte  | 41 ++++++++++++++++++++++++
 src/ui/PodcastView/EpisodePlayer.test.ts | 33 +++++++++++++++++++
 2 files changed, 74 insertions(+)

diff --git a/src/ui/PodcastView/EpisodePlayer.svelte b/src/ui/PodcastView/EpisodePlayer.svelte
index f7d5793..a99c1d2 100644
--- a/src/ui/PodcastView/EpisodePlayer.svelte
+++ b/src/ui/PodcastView/EpisodePlayer.svelte
@@ -62,6 +62,7 @@
 
 	let isHoveringArtwork: boolean = false;
 	let isLoading: boolean = true;
+	let loadError: string | null = null;
 	let playerVolume: number = 1;
 	let mediaElement: HTMLMediaElement | null = null;
 	// The currentEpisode subscription fires synchronously on subscribe with the
@@ -177,10 +178,19 @@
 
 	function onMetadataLoaded() {
 		isLoading = false;
+		loadError = null;
 
 		restorePlaybackTime();
 	}
 
+	// A blocked, dead, or unreachable media URL never fires loadedmetadata, so
+	// without this the loading overlay spins forever (found while gating all
+	// outbound requests: a refused stream URL looked identical to a slow one).
+	function onMediaError() {
+		isLoading = false;
+		loadError = "Could not load this episode's media.";
+	}
+
 	function restorePlaybackTime() {
 		const playedEps = $playedEpisodes;
 		const currentEp = $currentEpisode;
@@ -339,6 +349,7 @@
 			// the src swap persist the new episode under its key with the old/zero
 			// time and clobber its saved resume position (issue #33).
 			isLoading = true;
+			loadError = null;
 			lastPositionSaveMs = Number.NEGATIVE_INFINITY;
 			segmentStopTimeWithoutProgressSave = null;
 
@@ -504,6 +515,7 @@
 				bind:volume={playerVolume}
 				on:ended={onEpisodeEnded}
 				on:loadedmetadata={onMetadataLoaded}
+				on:error={onMediaError}
 				on:timeupdate={onTimeUpdate}
 				on:pause={onPause}
 				on:play|preventDefault
@@ -516,6 +528,11 @@
 				<div class="podcast-artwork-isloading-overlay">
 					<Loading />
 				</div>
+			{:else if loadError}
+				<div class="podcast-artwork-load-error" role="alert">
+					<Icon icon="alert-triangle" clickable={false} />
+					<span>{loadError}</span>
+				</div>
 			{:else}
 				<button
 					type="button"
@@ -569,6 +586,11 @@
 					<div class="podcast-artwork-isloading-overlay">
 						<Loading />
 					</div>
+				{:else if loadError}
+					<div class="podcast-artwork-load-error" role="alert">
+						<Icon icon="alert-triangle" clickable={false} />
+						<span>{loadError}</span>
+					</div>
 				{:else}
 					<div
 						class="podcast-artwork-overlay"
@@ -595,6 +617,7 @@
 			bind:volume={playerVolume}
 			on:ended={onEpisodeEnded}
 			on:loadedmetadata={onMetadataLoaded}
+			on:error={onMediaError}
 			on:timeupdate={onTimeUpdate}
 			on:pause={onPause}
 			on:play|preventDefault
@@ -820,6 +843,24 @@
 		outline-offset: 2px;
 	}
 
+	.podcast-artwork-load-error {
+		position: absolute;
+		top: 0;
+		left: 0;
+		width: 100%;
+		height: 100%;
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		justify-content: center;
+		gap: 0.5rem;
+		text-align: center;
+		padding: 0.5rem;
+		background-color: rgba(0, 0, 0, 0.6);
+		color: var(--text-error);
+		font-size: 0.85rem;
+	}
+
 	.podcast-artwork-isloading-overlay {
 		position: absolute;
 		inset: 0;
diff --git a/src/ui/PodcastView/EpisodePlayer.test.ts b/src/ui/PodcastView/EpisodePlayer.test.ts
index 2046395..8b78a47 100644
--- a/src/ui/PodcastView/EpisodePlayer.test.ts
+++ b/src/ui/PodcastView/EpisodePlayer.test.ts
@@ -115,6 +115,39 @@ describe("EpisodePlayer", () => {
 		expect(get(requestedPlaybackTime)).toBeNull();
 	});
 
+	test("shows an error state instead of a permanent spinner when media fails to load", async () => {
+		const { container } = render(EpisodePlayer);
+		await waitFor(() => {
+			expect(container.querySelector("audio")).not.toBeNull();
+		});
+		const audio = container.querySelector("audio") as HTMLAudioElement;
+
+		// A blocked/dead stream URL fires error, never loadedmetadata.
+		await fireEvent.error(audio);
+
+		expect(container.querySelector(".podcast-artwork-isloading-overlay")).toBeNull();
+		const error = container.querySelector(".podcast-artwork-load-error");
+		expect(error).not.toBeNull();
+		expect(error?.textContent).toContain("Could not load");
+	});
+
+	test("clears the error state when the next episode loads", async () => {
+		const { container } = render(EpisodePlayer);
+		await waitFor(() => {
+			expect(container.querySelector("audio")).not.toBeNull();
+		});
+		const audio = container.querySelector("audio") as HTMLAudioElement;
+		await fireEvent.error(audio);
+		expect(container.querySelector(".podcast-artwork-load-error")).not.toBeNull();
+
+		currentEpisode.set({ ...testEpisode, title: "Next Episode" });
+		await waitFor(() => {
+			expect(container.querySelector(".podcast-artwork-isloading-overlay")).not.toBeNull();
+		});
+		await fireEvent.loadedMetadata(container.querySelector("audio") as HTMLAudioElement);
+		expect(container.querySelector(".podcast-artwork-load-error")).toBeNull();
+	});
+
 	test("arms a requested segment after metadata loads", async () => {
 		requestedPlaybackTime.set({
 			episodeKey: `${testEpisode.podcastName}::${testEpisode.title}`,

From 0f2574b4db469501909aab71236de8cf6e09d6bb Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sat, 11 Jul 2026 15:25:33 +0200
Subject: [PATCH 2/2] fix(player): guard persistence separately from the
 loading spinner

Addressing review: onMediaError cleared isLoading, but isLoading also
gated persistPlaybackPosition, so a failed load (which never restores the
saved position) could let a later pause/destroy write the pre-restore 0
over the stored resume point. Split the concerns: isLoading stays a pure
display flag; a dedicated playbackRestored guard, set only by a real
metadata load, gates persistence. Regression test: a failed load followed
by unmount keeps the saved position intact.
---
 src/ui/PodcastView/EpisodePlayer.svelte  | 15 +++++++++++----
 src/ui/PodcastView/EpisodePlayer.test.ts | 17 +++++++++++++++++
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/src/ui/PodcastView/EpisodePlayer.svelte b/src/ui/PodcastView/EpisodePlayer.svelte
index a99c1d2..93c78e3 100644
--- a/src/ui/PodcastView/EpisodePlayer.svelte
+++ b/src/ui/PodcastView/EpisodePlayer.svelte
@@ -63,6 +63,10 @@
 	let isHoveringArtwork: boolean = false;
 	let isLoading: boolean = true;
 	let loadError: string | null = null;
+	// Distinct from isLoading (a display flag): gates persistence so it stays
+	// closed when media fails to load, since a failed load clears the spinner
+	// without restoring the saved position. Only a real metadata load opens it.
+	let playbackRestored: boolean = false;
 	let playerVolume: number = 1;
 	let mediaElement: HTMLMediaElement | null = null;
 	// The currentEpisode subscription fires synchronously on subscribe with the
@@ -179,6 +183,7 @@
 	function onMetadataLoaded() {
 		isLoading = false;
 		loadError = null;
+		playbackRestored = true;
 
 		restorePlaybackTime();
 	}
@@ -273,9 +278,10 @@
 
 	function persistPlaybackPosition() {
 		// Never persist before metadata has loaded and the saved position has been
-		// restored (onMetadataLoaded) — writing the pre-restore 0 would clobber the
-		// stored position we are about to resume from.
-		if (isLoading || !$currentEpisode) return;
+		// restored (onMetadataLoaded), including the failed-load path where the
+		// spinner clears but no restore ran — writing the pre-restore 0 would
+		// clobber the stored position we resume from.
+		if (!playbackRestored || !$currentEpisode) return;
 		if (shouldSuppressSegmentProgressPersistence()) return;
 
 		playedEpisodes.setEpisodeTime(
@@ -350,6 +356,7 @@
 			// time and clobber its saved resume position (issue #33).
 			isLoading = true;
 			loadError = null;
+			playbackRestored = false;
 			lastPositionSaveMs = Number.NEGATIVE_INFINITY;
 			segmentStopTimeWithoutProgressSave = null;
 
@@ -363,7 +370,7 @@
 			// progress bar stays pinned at 100% and the timestamps show the
 			// previous episode's end for the whole (network-bound) metadata fetch.
 			// onMetadataLoaded → restorePlaybackTime sets the real position, and
-			// the isLoading guard above keeps this reset from being persisted.
+			// the playbackRestored guard keeps this reset from being persisted.
 			if (hasSeenFirstEpisodeFire) {
 				currentTime.set(0);
 				duration.set(0);
diff --git a/src/ui/PodcastView/EpisodePlayer.test.ts b/src/ui/PodcastView/EpisodePlayer.test.ts
index 8b78a47..7de6e3d 100644
--- a/src/ui/PodcastView/EpisodePlayer.test.ts
+++ b/src/ui/PodcastView/EpisodePlayer.test.ts
@@ -131,6 +131,23 @@ describe("EpisodePlayer", () => {
 		expect(error?.textContent).toContain("Could not load");
 	});
 
+	test("does not persist a pre-restore position when media fails to load", async () => {
+		// Seed a saved resume point; a failed load must not overwrite it with 0.
+		playedEpisodes.setEpisodeTime(testEpisode, 1234, 3600, false);
+		const { container, unmount } = render(EpisodePlayer);
+		await waitFor(() => {
+			expect(container.querySelector("audio")).not.toBeNull();
+		});
+		const audio = container.querySelector("audio") as HTMLAudioElement;
+
+		await fireEvent.error(audio);
+		// Destroy fires persistPlaybackPosition; the guard must keep it closed.
+		unmount();
+
+		const saved = get(playedEpisodes)[`${testEpisode.podcastName}::${testEpisode.title}`];
+		expect(saved?.time).toBe(1234);
+	});
+
 	test("clears the error state when the next episode loads", async () => {
 		const { container } = render(EpisodePlayer);
 		await waitFor(() => {