From 02e1c583e9494f2f484631b3e85c872608fa6c23 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Sat, 5 Sep 2026 01:12:39 +0200
Subject: [PATCH 1/5] fix(554): mute the preview player so autoplay is never
 blocked
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

HlsPlayer's manifest GET can block until segments exist (unbounded
maxTimeToFirstByteMs), so MANIFEST_PARSED can arrive past the
browser's transient user-activation window and video.play() gets
rejected as blocked autoplay — the channel preview panel then sat at
"starting" over a black frame with no hint the operator just needed
to press play.

Render the <video> element muted (browsers permit autoplay of muted
media without user activation) so the common case starts on its own,
and add an optional onAutoplayBlocked callback for the residual case
(stricter policy/extension) that the channel preview panel wires to a
"press play" hint shown only while still starting.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QqCpYFsKgnAnx6jVwrKiV
---
 docs/spa-conventions.md                       | 15 ++++
 web/src/media/HlsPlayer.test.tsx              | 63 ++++++++++++++++
 web/src/media/HlsPlayer.tsx                   | 32 ++++++--
 .../channels/ChannelPreviewPanel.test.tsx     | 75 +++++++++++++++++++
 .../screens/channels/ChannelPreviewPanel.tsx  | 18 +++++
 5 files changed, 198 insertions(+), 5 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index 10d7b9935..f7014ab4b 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -643,6 +643,21 @@ safe) and mirrors `onError`'s requirements exactly: pass a **stable** `onPlaying
 since it too sits in the attach effect's dependency array and an unstable identity would restart the
 stream every render.
 
+**Autoplay (#554).** The `<video>` element is rendered `muted` unconditionally: browsers permit
+autoplay of muted media without user activation, so the `video.play()` kick above succeeds even when
+`MANIFEST_PARSED` arrives past the browser's transient user-activation window (~5s in Chrome) — the
+failure mode a slow-starting channel (unbounded manifest `maxTimeToFirstByteMs`, see above) used to
+hit, leaving the channel-preview panel sitting at "starting" over a black frame with no indication the
+operator just needs to press play. `controls` stays on so the operator can unmute to verify audio.
+For the residual case where autoplay is still rejected (a stricter browser policy or extension),
+`HlsPlayer` also takes an optional `onAutoplayBlocked()`, called when the `video.play()` promise
+rejects on either path; it is purely additive and does **not** need a stable identity requirement
+beyond what the attach effect's dependency array already requires (same rule as `onError`/`onPlaying`
+— pass a `useCallback`). The channel-preview panel (`ChannelPreviewPanel.tsx`) wires it to a
+"press play" hint shown only while `state` is still `starting`, and clears it the moment `onPlaying`
+actually fires — the panel never claims the fault fixed itself; the hint mirrors an honest, still-not-
+playing state.
+
 **Resolving a `/iptv/*` src under JWT auth (#552).** Before feeding an `/iptv/*` manifest URL to
 `HlsPlayer`, pass it through `withIptvToken(url)` (`web/src/media/iptvToken.ts`): under a JWT-enabled
 deployment it appends the short-lived `?access_token=` the `/iptv/*` scheme requires (the `ctv-session`
diff --git a/web/src/media/HlsPlayer.test.tsx b/web/src/media/HlsPlayer.test.tsx
index 1337d4841..d4122249e 100644
--- a/web/src/media/HlsPlayer.test.tsx
+++ b/web/src/media/HlsPlayer.test.tsx
@@ -105,4 +105,67 @@ describe('HlsPlayer', () => {
     const video = container.querySelector('video');
     expect(() => video?.dispatchEvent(new Event('playing'))).not.toThrow();
   });
+
+  // #554: the panel used to sit at "starting" over a black frame with no hint when the browser
+  // rejected the manifest-parsed play() kick as blocked autoplay. Rendering the video muted lets
+  // browsers autoplay it without user activation in the common case.
+  it('renders the video element muted', () => {
+    const { container } = render(<HlsPlayer src="/iptv/channel/12.1.m3u8" />);
+
+    const video = container.querySelector('video');
+    expect(video?.muted).toBe(true);
+  });
+
+  it('reports onAutoplayBlocked when the manifest-parsed play() kick is rejected', async () => {
+    const onAutoplayBlocked = vi.fn();
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('blocked'));
+
+    try {
+      render(<HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />);
+
+      const manifestHandler = hlsMock.on.mock.calls.find((call) => call[0] === 'hlsManifestParsed')?.[1];
+      manifestHandler();
+
+      // The rejection settles on a microtask; flush it before asserting.
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onAutoplayBlocked).toHaveBeenCalledTimes(1);
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
+  it('does not report onAutoplayBlocked when the play() kick succeeds', async () => {
+    const onAutoplayBlocked = vi.fn();
+    render(<HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />);
+
+    const manifestHandler = hlsMock.on.mock.calls.find((call) => call[0] === 'hlsManifestParsed')?.[1];
+    manifestHandler();
+
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(onAutoplayBlocked).not.toHaveBeenCalled();
+  });
+
+  it('is safe with no onAutoplayBlocked provided', async () => {
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('blocked'));
+
+    try {
+      render(<HlsPlayer src="/iptv/channel/12.1.m3u8" />);
+
+      const manifestHandler = hlsMock.on.mock.calls.find((call) => call[0] === 'hlsManifestParsed')?.[1];
+      expect(() => manifestHandler()).not.toThrow();
+
+      await Promise.resolve();
+      await Promise.resolve();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
 });
diff --git a/web/src/media/HlsPlayer.tsx b/web/src/media/HlsPlayer.tsx
index 96c3cdce4..591989ac8 100644
--- a/web/src/media/HlsPlayer.tsx
+++ b/web/src/media/HlsPlayer.tsx
@@ -20,6 +20,13 @@ export interface HlsPlayerProps {
   // before any media has decoded (an HttpLiveStreamingDirect manifest always parses even over a
   // black video). Optional and purely additive — omitting it is safe.
   onPlaying?: () => void;
+  // Called when the browser rejects the player's own `video.play()` kick (autoplay blocked). The
+  // element is rendered `muted`, which lets Chromium/Firefox autoplay without user activation in
+  // the common case (#554), but a stricter policy (e.g. an extension, or a browser configured to
+  // block all autoplay) can still reject it — this is the fallback so a caller can tell the operator
+  // to press play rather than let the panel sit at "starting" with no explanation. Optional and
+  // purely additive.
+  onAutoplayBlocked?: () => void;
 }
 
 // A small HLS video player. Uses hls.js when Media Source Extensions are available (config mirrors
@@ -27,7 +34,15 @@ export interface HlsPlayerProps {
 // segments exist, so the manifest request must tolerate an unbounded time-to-first-byte), and falls
 // back to the browser's native HLS support (Safari) otherwise. Reusable across any screen that needs
 // to preview an ErsatzTV HLS stream.
-export function HlsPlayer({ src, playToken = 0, className, style, onError, onPlaying }: HlsPlayerProps) {
+export function HlsPlayer({
+  src,
+  playToken = 0,
+  className,
+  style,
+  onError,
+  onPlaying,
+  onAutoplayBlocked
+}: HlsPlayerProps) {
   const videoRef = useRef<HTMLVideoElement | null>(null);
   const hlsRef = useRef<Hls | null>(null);
 
@@ -64,7 +79,8 @@ export function HlsPlayer({ src, playToken = 0, className, style, onError, onPla
       hls.attachMedia(video);
       hls.on(Hls.Events.MANIFEST_PARSED, () => {
         void video.play().catch(() => {
-          // Autoplay may be blocked; the user can press play manually.
+          // Autoplay may be blocked despite `muted` (#554); the user can press play manually.
+          onAutoplayBlocked?.();
         });
       });
       hls.on(Hls.Events.ERROR, (_event, data) => {
@@ -87,7 +103,8 @@ export function HlsPlayer({ src, playToken = 0, className, style, onError, onPla
       video.src = src;
       const onCanPlay = () => {
         void video.play().catch(() => {
-          // Autoplay may be blocked; the user can press play manually.
+          // Autoplay may be blocked despite `muted` (#554); the user can press play manually.
+          onAutoplayBlocked?.();
         });
       };
       video.addEventListener('canplay', onCanPlay);
@@ -110,7 +127,7 @@ export function HlsPlayer({ src, playToken = 0, className, style, onError, onPla
 
     return undefined;
     // playToken forces re-attachment for repeat plays of an identical src (see HlsPlayerProps).
-  }, [src, playToken, onError, onPlaying]);
+  }, [src, playToken, onError, onPlaying, onAutoplayBlocked]);
 
   // Final unmount safety net (covers the hls.js instance in every path).
   useEffect(
@@ -120,5 +137,10 @@ export function HlsPlayer({ src, playToken = 0, className, style, onError, onPla
     []
   );
 
-  return <video className={className} controls ref={videoRef} style={style} />;
+  // muted: browsers permit autoplay of muted media without user activation (#554) — without it,
+  // MANIFEST_PARSED can arrive past the ~5s transient-activation window on a slow-starting channel
+  // and video.play() is rejected as blocked autoplay, leaving the panel at "starting" over a black
+  // frame with no indication the operator just needs to press play. `controls` still lets the
+  // operator unmute to verify audio.
+  return <video className={className} controls muted ref={videoRef} style={style} />;
 }
diff --git a/web/src/screens/channels/ChannelPreviewPanel.test.tsx b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
index ce46e11e3..bca173d44 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.test.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
@@ -211,6 +211,81 @@ describe('ChannelPreviewPanel', () => {
     expect(screen.getByText(/networkError: manifestLoadError/)).toBeInTheDocument();
   });
 
+  // #554: on a slow-starting channel MANIFEST_PARSED can arrive past the browser's transient
+  // user-activation window, so HlsPlayer's own play() kick is rejected as blocked autoplay. The
+  // panel must tell the operator to press play rather than sit silently at "starting".
+  it('shows a hint when autoplay is blocked', async () => {
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('blocked'));
+
+    try {
+      await renderPanel(
+        <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
+      );
+
+      const manifestHandler = getManifestHandler();
+      await act(async () => {
+        manifestHandler();
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(screen.getByText(/autoplay was blocked/i)).toBeInTheDocument();
+      // Still honest: playback has not actually started, so the State fact stays "starting".
+      expect(screen.getByText('starting')).toBeInTheDocument();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
+  it('does not show the autoplay-blocked hint once playback actually starts', async () => {
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('blocked'));
+
+    try {
+      await renderPanel(
+        <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
+      );
+
+      const manifestHandler = getManifestHandler();
+      await act(async () => {
+        manifestHandler();
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(screen.getByText(/autoplay was blocked/i)).toBeInTheDocument();
+
+      // SlideOver portals its content, so query the whole document rather than the render container.
+      const video = document.querySelector('video');
+      await act(async () => {
+        video?.dispatchEvent(new Event('playing'));
+        await Promise.resolve();
+      });
+
+      expect(screen.queryByText(/autoplay was blocked/i)).not.toBeInTheDocument();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
+  it('does not show the autoplay-blocked hint when play() succeeds', async () => {
+    await renderPanel(
+      <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
+    );
+
+    const manifestHandler = getManifestHandler();
+    await act(async () => {
+      manifestHandler();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+
+    expect(screen.queryByText(/autoplay was blocked/i)).not.toBeInTheDocument();
+  });
+
   it('shows the manifest url so a failure can be reproduced with curl', async () => {
     await renderPanel(
       <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
diff --git a/web/src/screens/channels/ChannelPreviewPanel.tsx b/web/src/screens/channels/ChannelPreviewPanel.tsx
index dcc4b5fc8..3222228e7 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.tsx
@@ -45,6 +45,10 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
   const [started, setStarted] = useState(availability === 'Available');
   const [state, setState] = useState<PlaybackState>(availability === 'Available' ? 'starting' : 'idle');
   const [error, setError] = useState<null | string>(null);
+  // Set when the browser rejects HlsPlayer's own play() kick despite the player being muted (#554).
+  // Purely informational — `state` stays 'starting' (still honest: playback has not actually begun)
+  // — so the operator knows to press the native play button instead of assuming a stall.
+  const [autoplayBlocked, setAutoplayBlocked] = useState(false);
   // Bumped on every (re)play. The manifest GET itself starts a server-side session, so a repeat play
   // of an identical URL — e.g. Retry after a failure — must re-issue the request rather than be a
   // no-op; HlsPlayer tears down and re-attaches whenever this changes, even with the same src.
@@ -74,6 +78,7 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
     setStarted(availability === 'Available');
     setState(availability === 'Available' ? 'starting' : 'idle');
     setError(null);
+    setAutoplayBlocked(false);
     setPlayToken(0);
     setResolvedSrc(null);
   }
@@ -102,9 +107,15 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
       return;
     }
     setError(null);
+    setAutoplayBlocked(false);
     setState('playing');
   }, []);
 
+  // Stable identity for the same reason as onError/onPlaying above.
+  const onAutoplayBlocked = useCallback(() => {
+    setAutoplayBlocked(true);
+  }, []);
+
   const onOptIn = useCallback(() => {
     setStarted(true);
     setState('starting');
@@ -125,6 +136,7 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
     setResolvedSrc(null);
     failedRef.current = false;
     setError(null);
+    setAutoplayBlocked(false);
     setState('starting');
     setPlayToken((current) => current + 1);
   }, []);
@@ -181,12 +193,18 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
             <>
               <HlsPlayer
                 className="ctv-preview-video"
+                onAutoplayBlocked={onAutoplayBlocked}
                 onError={onError}
                 onPlaying={onPlaying}
                 playToken={playToken}
                 src={resolvedSrc}
                 style={{ aspectRatio: '16 / 9', background: '#000' }}
               />
+              {autoplayBlocked && state === 'starting' && (
+                <p className="ctv-settings-warn-callout ctv-preview-caveat" role="status">
+                  Autoplay was blocked — press play on the video to start the preview.
+                </p>
+              )}
               <div className="ctv-detail-actions">
                 <Button onClick={onRetry} size="sm" variant="secondary">
                   Retry
-- 
2.47.3


From 4e042fb7de16309d4f2d4aa04f13f270a664de73 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Sat, 5 Sep 2026 01:46:37 +0200
Subject: [PATCH 2/5] fix(554): the hint's cause must be measured, and muting
 is the consumer's call
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round one measured three defects in the first commit.

onAutoplayBlocked fired on ANY rejected video.play(), so the panel could
say "autoplay was blocked" when it was not. A play() interrupted by
teardown rejects with AbortError — which is exactly what the panel's own
Retry produces while the MANIFEST_PARSED play() is still pending — and
because the element was muted, a genuine NotAllowedError is the rare
case, so the realistic firings were the mislabelled ones. Report only a
DOMException named NotAllowedError, on both the MSE and native paths.

`muted` was applied to the shared player unconditionally, which silently
muted the playback-troubleshooting screen — the tool whose job includes
verifying the audio side of an FFmpeg profile, and which the legacy
Blazor player never muted. Make it an opt-in `muted` prop defaulting to
false; the channel preview passes it, troubleshooting does not, and a
test on each side pins its own value.

The two clauses hiding the hint once playback starts masked each other:
removing either alone left the panel suite green. Every path back to
'starting' (Retry, a channel change) already clears the flag itself, so
the clear in onPlaying could never be the load-bearing guard — drop it
and let the `state === 'starting'` render guard be the single pinned one.

Also cover the native-HLS (Safari) branch, which no test had ever
executed: its play() kick, its playing/error wiring, and both autoplay
rejection names.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QqCpYFsKgnAnx6jVwrKiV
---
 docs/spa-conventions.md                       |  38 ++++--
 web/src/media/HlsPlayer.test.tsx              | 125 +++++++++++++++++-
 web/src/media/HlsPlayer.tsx                   |  56 +++++---
 .../PlaybackTroubleshootingScreen.test.tsx    |  25 ++++
 .../channels/ChannelPreviewPanel.test.tsx     |  43 +++++-
 .../screens/channels/ChannelPreviewPanel.tsx  |  11 +-
 6 files changed, 252 insertions(+), 46 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index f7014ab4b..7f1963496 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -643,20 +643,30 @@ safe) and mirrors `onError`'s requirements exactly: pass a **stable** `onPlaying
 since it too sits in the attach effect's dependency array and an unstable identity would restart the
 stream every render.
 
-**Autoplay (#554).** The `<video>` element is rendered `muted` unconditionally: browsers permit
-autoplay of muted media without user activation, so the `video.play()` kick above succeeds even when
-`MANIFEST_PARSED` arrives past the browser's transient user-activation window (~5s in Chrome) — the
-failure mode a slow-starting channel (unbounded manifest `maxTimeToFirstByteMs`, see above) used to
-hit, leaving the channel-preview panel sitting at "starting" over a black frame with no indication the
-operator just needs to press play. `controls` stays on so the operator can unmute to verify audio.
-For the residual case where autoplay is still rejected (a stricter browser policy or extension),
-`HlsPlayer` also takes an optional `onAutoplayBlocked()`, called when the `video.play()` promise
-rejects on either path; it is purely additive and does **not** need a stable identity requirement
-beyond what the attach effect's dependency array already requires (same rule as `onError`/`onPlaying`
-— pass a `useCallback`). The channel-preview panel (`ChannelPreviewPanel.tsx`) wires it to a
-"press play" hint shown only while `state` is still `starting`, and clears it the moment `onPlaying`
-actually fires — the panel never claims the fault fixed itself; the hint mirrors an honest, still-not-
-playing state.
+**Autoplay (#554).** `HlsPlayer` takes an optional `muted` prop, **defaulting to `false`**. Muted
+media is the one thing browsers autoplay without user activation, so passing it makes the
+`video.play()` kick above succeed even when `MANIFEST_PARSED` arrives past the browser's transient
+user-activation window (~5s in Chrome) — the failure mode a slow-starting channel (unbounded manifest
+`maxTimeToFirstByteMs`, see above) hits, leaving a player sitting at "starting" over a black frame
+with no indication the operator just needs to press play. It is a **per-consumer** choice rather than
+a player-wide default because muting costs audio-by-default: the channel-preview panel
+(`ChannelPreviewPanel.tsx`) opts in — it answers "does this channel work right now", and starting
+beats being audible — while the playback-troubleshooting screen
+(`PlaybackTroubleshootingScreen.tsx`) must stay unmuted, since verifying the audio side of an FFmpeg
+profile is part of its job. `controls` is always on either way, so a muted player can be unmuted by
+hand.
+
+For the residual case where autoplay is rejected anyway (a stricter browser policy or an extension),
+`HlsPlayer` also takes an optional `onAutoplayBlocked()`. It fires **only** on an autoplay-policy
+rejection — a `DOMException` named `NotAllowedError`; a `play()` promise rejected under any other
+name (notably `AbortError`, which is what a pending `play()` interrupted by a teardown produces, and
+a consumer's own Retry does exactly that) is not reported, or the caller would put a cause in front
+of the operator that did not happen. Like `onError`/`onPlaying` it sits in the attach effect's
+dependency array, so pass a `useCallback`; it is purely additive and omitting it is safe. The
+channel-preview panel wires it to a "press play" hint whose visibility is the render guard
+`state === 'starting'` **alone** — every path back to `starting` (Retry, a channel change) clears the
+flag itself, so a second clear in `onPlaying` would be a guard no test could distinguish. The panel
+never claims the fault fixed itself; the hint mirrors an honest, still-not-playing state.
 
 **Resolving a `/iptv/*` src under JWT auth (#552).** Before feeding an `/iptv/*` manifest URL to
 `HlsPlayer`, pass it through `withIptvToken(url)` (`web/src/media/iptvToken.ts`): under a JWT-enabled
diff --git a/web/src/media/HlsPlayer.test.tsx b/web/src/media/HlsPlayer.test.tsx
index d4122249e..c8ed7fd16 100644
--- a/web/src/media/HlsPlayer.test.tsx
+++ b/web/src/media/HlsPlayer.test.tsx
@@ -1,5 +1,5 @@
 import { render } from '@testing-library/react';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { HlsPlayer } from './HlsPlayer';
 
 const hlsMock = {
@@ -107,20 +107,27 @@ describe('HlsPlayer', () => {
   });
 
   // #554: the panel used to sit at "starting" over a black frame with no hint when the browser
-  // rejected the manifest-parsed play() kick as blocked autoplay. Rendering the video muted lets
-  // browsers autoplay it without user activation in the common case.
-  it('renders the video element muted', () => {
+  // rejected the manifest-parsed play() kick as blocked autoplay. Muted media autoplays without user
+  // activation, but muting costs audio-by-default, so it is the caller's decision, not the player's.
+  it('renders the video element unmuted by default', () => {
     const { container } = render(<HlsPlayer src="/iptv/channel/12.1.m3u8" />);
 
+    const video = container.querySelector('video');
+    expect(video?.muted).toBe(false);
+  });
+
+  it('renders the video element muted when the caller opts in', () => {
+    const { container } = render(<HlsPlayer muted src="/iptv/channel/12.1.m3u8" />);
+
     const video = container.querySelector('video');
     expect(video?.muted).toBe(true);
   });
 
-  it('reports onAutoplayBlocked when the manifest-parsed play() kick is rejected', async () => {
+  it('reports onAutoplayBlocked when the manifest-parsed play() kick is rejected by autoplay policy', async () => {
     const onAutoplayBlocked = vi.fn();
     const playSpy = vi
       .spyOn(HTMLMediaElement.prototype, 'play')
-      .mockRejectedValue(new DOMException('blocked'));
+      .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
 
     try {
       render(<HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />);
@@ -138,6 +145,30 @@ describe('HlsPlayer', () => {
     }
   });
 
+  // A play() interrupted by teardown rejects with AbortError — which is what a caller's own Retry
+  // produces while the manifest-parsed play() is still pending. Reporting that as blocked autoplay
+  // would put a false cause in front of the operator.
+  it('does not report onAutoplayBlocked when play() is rejected for another reason', async () => {
+    const onAutoplayBlocked = vi.fn();
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('The play() request was interrupted', 'AbortError'));
+
+    try {
+      render(<HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />);
+
+      const manifestHandler = hlsMock.on.mock.calls.find((call) => call[0] === 'hlsManifestParsed')?.[1];
+      manifestHandler();
+
+      await Promise.resolve();
+      await Promise.resolve();
+
+      expect(onAutoplayBlocked).not.toHaveBeenCalled();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
   it('does not report onAutoplayBlocked when the play() kick succeeds', async () => {
     const onAutoplayBlocked = vi.fn();
     render(<HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />);
@@ -154,7 +185,7 @@ describe('HlsPlayer', () => {
   it('is safe with no onAutoplayBlocked provided', async () => {
     const playSpy = vi
       .spyOn(HTMLMediaElement.prototype, 'play')
-      .mockRejectedValue(new DOMException('blocked'));
+      .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
 
     try {
       render(<HlsPlayer src="/iptv/channel/12.1.m3u8" />);
@@ -168,4 +199,84 @@ describe('HlsPlayer', () => {
       playSpy.mockRestore();
     }
   });
+
+  // The native-HLS (Safari) branch carries its own copies of the play() kick and of the playing/error
+  // wiring; without MediaSource in jsdom nothing else in this file executes it, so it is exercised
+  // here explicitly rather than assumed to mirror the MSE path.
+  describe('native HLS (Safari) path', () => {
+    let canPlayTypeSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+      hlsMock.isSupported = false;
+      canPlayTypeSpy = vi.spyOn(HTMLMediaElement.prototype, 'canPlayType').mockReturnValue('maybe');
+    });
+
+    afterEach(() => {
+      canPlayTypeSpy.mockRestore();
+    });
+
+    it('reports onAutoplayBlocked when the canplay play() kick is rejected by autoplay policy', async () => {
+      const onAutoplayBlocked = vi.fn();
+      const playSpy = vi
+        .spyOn(HTMLMediaElement.prototype, 'play')
+        .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
+
+      try {
+        const { container } = render(
+          <HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />
+        );
+
+        // Confirm this really is the native branch: hls.js was never constructed.
+        expect(hlsMock.loadSource).not.toHaveBeenCalled();
+
+        const video = container.querySelector('video');
+        video?.dispatchEvent(new Event('canplay'));
+
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(onAutoplayBlocked).toHaveBeenCalledTimes(1);
+      } finally {
+        playSpy.mockRestore();
+      }
+    });
+
+    it('does not report onAutoplayBlocked when the canplay play() kick is rejected for another reason', async () => {
+      const onAutoplayBlocked = vi.fn();
+      const playSpy = vi
+        .spyOn(HTMLMediaElement.prototype, 'play')
+        .mockRejectedValue(new DOMException('The play() request was interrupted', 'AbortError'));
+
+      try {
+        const { container } = render(
+          <HlsPlayer onAutoplayBlocked={onAutoplayBlocked} src="/iptv/channel/12.1.m3u8" />
+        );
+
+        const video = container.querySelector('video');
+        video?.dispatchEvent(new Event('canplay'));
+
+        await Promise.resolve();
+        await Promise.resolve();
+
+        expect(onAutoplayBlocked).not.toHaveBeenCalled();
+      } finally {
+        playSpy.mockRestore();
+      }
+    });
+
+    it('reports onPlaying and onError from the element\'s own events', () => {
+      const onError = vi.fn();
+      const onPlaying = vi.fn();
+      const { container } = render(
+        <HlsPlayer onError={onError} onPlaying={onPlaying} src="/iptv/channel/12.1.m3u8" />
+      );
+
+      const video = container.querySelector('video');
+      video?.dispatchEvent(new Event('playing'));
+      expect(onPlaying).toHaveBeenCalledTimes(1);
+
+      video?.dispatchEvent(new Event('error'));
+      expect(onError).toHaveBeenCalledWith('The browser could not play this stream');
+    });
+  });
 });
diff --git a/web/src/media/HlsPlayer.tsx b/web/src/media/HlsPlayer.tsx
index 591989ac8..25fdcc874 100644
--- a/web/src/media/HlsPlayer.tsx
+++ b/web/src/media/HlsPlayer.tsx
@@ -20,13 +20,29 @@ export interface HlsPlayerProps {
   // before any media has decoded (an HttpLiveStreamingDirect manifest always parses even over a
   // black video). Optional and purely additive — omitting it is safe.
   onPlaying?: () => void;
-  // Called when the browser rejects the player's own `video.play()` kick (autoplay blocked). The
-  // element is rendered `muted`, which lets Chromium/Firefox autoplay without user activation in
-  // the common case (#554), but a stricter policy (e.g. an extension, or a browser configured to
-  // block all autoplay) can still reject it — this is the fallback so a caller can tell the operator
-  // to press play rather than let the panel sit at "starting" with no explanation. Optional and
-  // purely additive.
+  // Called when the browser rejects the player's own `video.play()` kick under its autoplay policy
+  // — and only then: the promise is rejected with a `NotAllowedError` DOMException in that case, and
+  // with a different name (e.g. `AbortError`) when a pending play() is merely interrupted by
+  // teardown, which must not be reported as blocked autoplay or the caller names a cause that did
+  // not happen. Passing `muted` lets Chromium/Firefox autoplay without user activation in the common
+  // case (#554), but a stricter policy (an extension, or a browser configured to block all autoplay)
+  // can still reject it — this is the fallback so a caller can tell the operator to press play rather
+  // than let the panel sit at "starting" with no explanation. Optional and purely additive.
   onAutoplayBlocked?: () => void;
+  // Render the element muted. Off by default: the playback-troubleshooting screen exists partly to
+  // verify the audio side of an FFmpeg profile, so it must stay audible. The channel preview opts in
+  // (#554) because browsers permit autoplay of muted media without user activation, which is what
+  // keeps a slow-starting preview from sitting at "starting" over a black frame. `controls` is always
+  // on, so a muted player can still be unmuted by hand.
+  muted?: boolean;
+}
+
+// A rejected video.play() says why in the DOMException's name. Only NotAllowedError is the autoplay
+// policy refusing to start unprompted; AbortError (a pending play() interrupted by a teardown — what
+// the preview panel's own Retry does while MANIFEST_PARSED's play() is still pending) and
+// NotSupportedError are different faults and must not be reported as blocked autoplay.
+function isAutoplayPolicyRejection(error: unknown): boolean {
+  return error instanceof DOMException && error.name === 'NotAllowedError';
 }
 
 // A small HLS video player. Uses hls.js when Media Source Extensions are available (config mirrors
@@ -41,7 +57,8 @@ export function HlsPlayer({
   style,
   onError,
   onPlaying,
-  onAutoplayBlocked
+  onAutoplayBlocked,
+  muted = false
 }: HlsPlayerProps) {
   const videoRef = useRef<HTMLVideoElement | null>(null);
   const hlsRef = useRef<Hls | null>(null);
@@ -78,9 +95,11 @@ export function HlsPlayer({
       hls.loadSource(src);
       hls.attachMedia(video);
       hls.on(Hls.Events.MANIFEST_PARSED, () => {
-        void video.play().catch(() => {
-          // Autoplay may be blocked despite `muted` (#554); the user can press play manually.
-          onAutoplayBlocked?.();
+        void video.play().catch((error: unknown) => {
+          // Autoplay can be blocked even when muted (#554); the user can press play manually.
+          if (isAutoplayPolicyRejection(error)) {
+            onAutoplayBlocked?.();
+          }
         });
       });
       hls.on(Hls.Events.ERROR, (_event, data) => {
@@ -102,9 +121,11 @@ export function HlsPlayer({
     if (video.canPlayType('application/vnd.apple.mpegurl')) {
       video.src = src;
       const onCanPlay = () => {
-        void video.play().catch(() => {
-          // Autoplay may be blocked despite `muted` (#554); the user can press play manually.
-          onAutoplayBlocked?.();
+        void video.play().catch((error: unknown) => {
+          // Autoplay can be blocked even when muted (#554); the user can press play manually.
+          if (isAutoplayPolicyRejection(error)) {
+            onAutoplayBlocked?.();
+          }
         });
       };
       video.addEventListener('canplay', onCanPlay);
@@ -137,10 +158,7 @@ export function HlsPlayer({
     []
   );
 
-  // muted: browsers permit autoplay of muted media without user activation (#554) — without it,
-  // MANIFEST_PARSED can arrive past the ~5s transient-activation window on a slow-starting channel
-  // and video.play() is rejected as blocked autoplay, leaving the panel at "starting" over a black
-  // frame with no indication the operator just needs to press play. `controls` still lets the
-  // operator unmute to verify audio.
-  return <video className={className} controls muted ref={videoRef} style={style} />;
+  // `muted` is the caller's call (see HlsPlayerProps): muted media autoplays without user activation
+  // (#554), but that trades away audio-by-default, which the troubleshooting screen needs.
+  return <video className={className} controls muted={muted} ref={videoRef} style={style} />;
 }
diff --git a/web/src/screens/PlaybackTroubleshootingScreen.test.tsx b/web/src/screens/PlaybackTroubleshootingScreen.test.tsx
index cdd720e52..dfaf9cfbe 100644
--- a/web/src/screens/PlaybackTroubleshootingScreen.test.tsx
+++ b/web/src/screens/PlaybackTroubleshootingScreen.test.tsx
@@ -277,6 +277,31 @@ describe('PlaybackTroubleshootingScreen', () => {
     }
   });
 
+  // This screen exists partly to verify the audio side of an FFmpeg profile, so its player must stay
+  // audible. HlsPlayer's `muted` is opt-in for that reason (#554) — the channel preview opts in, this
+  // one must not, and a default flipped to muted here would be silent in both senses.
+  it('leaves the troubleshooting player unmuted', async () => {
+    setLocation('/app/troubleshooting/playback?mediaItem=5');
+    const statusRef = { current: IDLE };
+    installFetch(statusRef);
+    vi.useFakeTimers();
+
+    try {
+      render(<PlaybackTroubleshootingScreen />);
+      await vi.waitFor(() => expect(screen.getByText(/Movie Settings/i)).toBeTruthy());
+
+      statusRef.current = { state: 'running', exitCode: null, speed: null, logs: null };
+      fireEvent.click(screen.getByRole('button', { name: 'Play' }));
+      await vi.waitFor(() => expect(hlsMock.loadSource).toHaveBeenCalledWith(LIVE_MANIFEST));
+
+      const video = document.querySelector('video');
+      expect(video).not.toBeNull();
+      expect(video?.muted).toBe(false);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it('surfaces the ProblemDetails detail and returns to idle when start fails (409)', async () => {
     setLocation('/app/troubleshooting/playback?mediaItem=5');
     const statusRef = { current: IDLE };
diff --git a/web/src/screens/channels/ChannelPreviewPanel.test.tsx b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
index bca173d44..72e66ccc0 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.test.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
@@ -217,7 +217,7 @@ describe('ChannelPreviewPanel', () => {
   it('shows a hint when autoplay is blocked', async () => {
     const playSpy = vi
       .spyOn(HTMLMediaElement.prototype, 'play')
-      .mockRejectedValue(new DOMException('blocked'));
+      .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
 
     try {
       await renderPanel(
@@ -239,10 +239,12 @@ describe('ChannelPreviewPanel', () => {
     }
   });
 
+  // The hint is hidden by the `state === 'starting'` render guard alone — removing that guard must
+  // redden this test, which it can only do because nothing else clears the flag on this path.
   it('does not show the autoplay-blocked hint once playback actually starts', async () => {
     const playSpy = vi
       .spyOn(HTMLMediaElement.prototype, 'play')
-      .mockRejectedValue(new DOMException('blocked'));
+      .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
 
     try {
       await renderPanel(
@@ -271,6 +273,43 @@ describe('ChannelPreviewPanel', () => {
     }
   });
 
+  // A play() interrupted by teardown rejects with AbortError, which is exactly what Retry produces
+  // while the manifest-parsed play() is still pending. The hint names blocked autoplay as the cause,
+  // so it must not appear for a rejection that was not the autoplay policy.
+  it('does not show the autoplay-blocked hint when play() is rejected for another reason', async () => {
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('The play() request was interrupted', 'AbortError'));
+
+    try {
+      await renderPanel(
+        <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
+      );
+
+      const manifestHandler = getManifestHandler();
+      await act(async () => {
+        manifestHandler();
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(screen.queryByText(/autoplay was blocked/i)).not.toBeInTheDocument();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
+  // The preview is the consumer that opts into a muted player (#554): muted media autoplays without
+  // user activation, which is what stops a slow-starting preview from sitting at "starting".
+  it('mutes the preview player', async () => {
+    await renderPanel(
+      <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
+    );
+
+    // SlideOver portals its content, so query the whole document rather than the render container.
+    expect(document.querySelector('video')?.muted).toBe(true);
+  });
+
   it('does not show the autoplay-blocked hint when play() succeeds', async () => {
     await renderPanel(
       <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
diff --git a/web/src/screens/channels/ChannelPreviewPanel.tsx b/web/src/screens/channels/ChannelPreviewPanel.tsx
index 3222228e7..67de3b5aa 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.tsx
@@ -45,9 +45,12 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
   const [started, setStarted] = useState(availability === 'Available');
   const [state, setState] = useState<PlaybackState>(availability === 'Available' ? 'starting' : 'idle');
   const [error, setError] = useState<null | string>(null);
-  // Set when the browser rejects HlsPlayer's own play() kick despite the player being muted (#554).
-  // Purely informational — `state` stays 'starting' (still honest: playback has not actually begun)
-  // — so the operator knows to press the native play button instead of assuming a stall.
+  // Set when the browser's autoplay policy rejects HlsPlayer's own play() kick despite the player
+  // being muted (#554). Purely informational — `state` stays 'starting' (still honest: playback has
+  // not actually begun) — so the operator knows to press the native play button instead of assuming
+  // a stall. The hint's visibility is the render guard on `state === 'starting'` alone: every path
+  // back to 'starting' (Retry, a channel change) clears this flag itself, so a second clear in
+  // onPlaying would be unreachable as a guard and could not be pinned by a test.
   const [autoplayBlocked, setAutoplayBlocked] = useState(false);
   // Bumped on every (re)play. The manifest GET itself starts a server-side session, so a repeat play
   // of an identical URL — e.g. Retry after a failure — must re-issue the request rather than be a
@@ -107,7 +110,6 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
       return;
     }
     setError(null);
-    setAutoplayBlocked(false);
     setState('playing');
   }, []);
 
@@ -193,6 +195,7 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
             <>
               <HlsPlayer
                 className="ctv-preview-video"
+                muted
                 onAutoplayBlocked={onAutoplayBlocked}
                 onError={onError}
                 onPlaying={onPlaying}
-- 
2.47.3


From b6b4fb6619d7b7d8364682a22e4c9f9cf9b42493 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Sat, 5 Sep 2026 02:08:36 +0200
Subject: [PATCH 3/5] test(554): pin both clears the hint's single guard
 depends on
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Dropping the onPlaying clear made the `state === 'starting'` render guard the
hint's only guard, which moves the burden onto the two paths back to
`starting`: each has to clear `autoplayBlocked` itself. Both were assertable
but unasserted — either `setAutoplayBlocked(false)` could be deleted with the
whole panel suite green, so the invariant the code comment and
docs/spa-conventions.md §5b both state was unpinned in both of its named paths.

Add one test per path (Retry; a channel switch), each asserting the hint is
gone while the panel is back at `starting` — so the render guard cannot be
what hid it. Each also asserts the player really re-mounted (loadSource count
/ last URL, plus a non-null <video>), so the hint cannot be absent merely
because the `resolvedSrc` block is unrendered.

Measured on this tree, each mutation caught by exactly one test:
deleting the onRetry clear reds only 'clicking Retry clears the
autoplay-blocked hint' (Tests 1 failed | 25 passed); deleting the
render-phase reset clear reds only 'clears the autoplay-blocked hint when
switching to a different channel' (1 failed | 25 passed); replacing
`autoplayBlocked && state === 'starting' &&` with `autoplayBlocked &&` reds
one test too. Unmutated: 26 passed.

Refs #554

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QqCpYFsKgnAnx6jVwrKiV
---
 .../channels/ChannelPreviewPanel.test.tsx     | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/web/src/screens/channels/ChannelPreviewPanel.test.tsx b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
index 72e66ccc0..c40831ad9 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.test.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
@@ -273,6 +273,45 @@ describe('ChannelPreviewPanel', () => {
     }
   });
 
+  // The `state === 'starting'` guard is the hint's ONLY guard, so every path back to `starting` has
+  // to clear the flag itself. Retry is one: it is a fresh attempt that was never blocked, and a hint
+  // carried over from the previous attempt would name a cause that did not happen this time.
+  it('clicking Retry clears the autoplay-blocked hint', async () => {
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
+
+    try {
+      await renderPanel(
+        <ChannelPreviewPanel channel={channel(available)} nowPlaying={null} onClose={vi.fn()} open />
+      );
+
+      const manifestHandler = getManifestHandler();
+      await act(async () => {
+        manifestHandler();
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(screen.getByText(/autoplay was blocked/i)).toBeInTheDocument();
+
+      // The retried attempt is not blocked.
+      playSpy.mockResolvedValue(undefined);
+      fireEvent.click(screen.getByRole('button', { name: /retry/i }));
+      await flush();
+
+      // The player really did re-mount, so the hint is absent because the flag was cleared — not
+      // because the whole `resolvedSrc` block is still unrendered.
+      expect(hlsMock.loadSource).toHaveBeenCalledTimes(2);
+      expect(document.querySelector('video')).not.toBeNull();
+      expect(screen.queryByText(/autoplay was blocked/i)).not.toBeInTheDocument();
+      // Retry returns to `starting`, so the render guard is not what hid the hint here.
+      expect(screen.getByText('starting')).toBeInTheDocument();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
   // A play() interrupted by teardown rejects with AbortError, which is exactly what Retry produces
   // while the manifest-parsed play() is still pending. The hint names blocked autoplay as the cause,
   // so it must not appear for a rejection that was not the autoplay policy.
@@ -495,6 +534,47 @@ describe('ChannelPreviewPanel', () => {
       expect(screen.getByText('playing')).toBeInTheDocument();
     });
 
+    // The other path back to `starting`, and the other half of the hint's single-guard invariant: a
+    // switch must not leave the previous channel's hint standing over a new channel that was never
+    // blocked. The render-phase reset owns this clear — the guard cannot help, since the new channel
+    // starts in `starting` too.
+    it('clears the autoplay-blocked hint when switching to a different channel', async () => {
+      const playSpy = vi
+        .spyOn(HTMLMediaElement.prototype, 'play')
+        .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
+
+      try {
+        const { rerender } = await renderPanel(
+          <ChannelPreviewPanel channel={channel(available, undefined, 1)} nowPlaying={null} onClose={vi.fn()} open />
+        );
+
+        const manifestHandler = getManifestHandler();
+        await act(async () => {
+          manifestHandler();
+          await Promise.resolve();
+          await Promise.resolve();
+        });
+
+        expect(screen.getByText(/autoplay was blocked/i)).toBeInTheDocument();
+
+        // The new channel's attempt is not blocked.
+        playSpy.mockResolvedValue(undefined);
+        rerender(
+          <ChannelPreviewPanel channel={channel(available2, undefined, 2)} nowPlaying={null} onClose={vi.fn()} open />
+        );
+        await flush();
+
+        // The new channel's player really is mounted, so the hint is absent because the flag was
+        // cleared — not because the `resolvedSrc` block is still unrendered.
+        expect(hlsMock.loadSource).toHaveBeenLastCalledWith('/iptv/channel/34.1.m3u8');
+        expect(document.querySelector('video')).not.toBeNull();
+        expect(screen.queryByText(/autoplay was blocked/i)).not.toBeInTheDocument();
+        expect(screen.getByText('starting')).toBeInTheDocument();
+      } finally {
+        playSpy.mockRestore();
+      }
+    });
+
     it('does not carry the retry play token over to the next channel', async () => {
       // Both channels share a manifest URL so the only thing that could re-trigger the attach
       // effect across the switch is playToken. If the reset failed to zero it out, the token
-- 
2.47.3


From f119bfcb297a28048cff2db7ba1a3471059069e0 Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Sat, 5 Sep 2026 02:42:39 +0200
Subject: [PATCH 4/5] docs(554): the opt-in is a third path back to starting,
 and the invariant must say so
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hint's single-guard invariant was stated as "every path back to `starting` clears
the flag itself", enumerating Retry and a channel change. `onOptIn` is a third such
path and clears nothing, so the sentence was false as written — in the code comment,
in the Retry test's comment, and in docs/spa-conventions.md §5b.

Adding a clear to `onOptIn` would be dead code no test could distinguish, which is the
exact shape this branch removed from `onPlaying`. The omission is correct for a reason
none of the three places stated: the opt-in button renders only while `started` is
false, `started` only goes false in the render-phase reset that clears the flag two
lines later, and no player exists to set the flag while `started` is false. State that
exception, and pin the reachability premise it rests on with a test that fails if the
opt-in button outlives the mounted player.

Refs #554

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QqCpYFsKgnAnx6jVwrKiV
---
 docs/spa-conventions.md                       |  9 ++--
 .../channels/ChannelPreviewPanel.test.tsx     | 43 ++++++++++++++++++-
 .../screens/channels/ChannelPreviewPanel.tsx  | 10 +++--
 3 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index 7f1963496..d70e663aa 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -664,9 +664,12 @@ a consumer's own Retry does exactly that) is not reported, or the caller would p
 of the operator that did not happen. Like `onError`/`onPlaying` it sits in the attach effect's
 dependency array, so pass a `useCallback`; it is purely additive and omitting it is safe. The
 channel-preview panel wires it to a "press play" hint whose visibility is the render guard
-`state === 'starting'` **alone** — every path back to `starting` (Retry, a channel change) clears the
-flag itself, so a second clear in `onPlaying` would be a guard no test could distinguish. The panel
-never claims the fault fixed itself; the hint mirrors an honest, still-not-playing state.
+`state === 'starting'` **alone**, so a second clear in `onPlaying` would be a guard no test could
+distinguish. That holds because the panel's paths back to `starting` either clear the flag themselves
+(Retry, a channel change) or cannot be reached while it is set — the forced-preview opt-in re-enters
+`starting` without clearing, but its button renders only before the player has ever mounted, so the
+flag is necessarily false there. The panel never claims the fault fixed itself; the hint mirrors an
+honest, still-not-playing state.
 
 **Resolving a `/iptv/*` src under JWT auth (#552).** Before feeding an `/iptv/*` manifest URL to
 `HlsPlayer`, pass it through `withIptvToken(url)` (`web/src/media/iptvToken.ts`): under a JWT-enabled
diff --git a/web/src/screens/channels/ChannelPreviewPanel.test.tsx b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
index c40831ad9..c44b64ab4 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.test.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.test.tsx
@@ -274,8 +274,9 @@ describe('ChannelPreviewPanel', () => {
   });
 
   // The `state === 'starting'` guard is the hint's ONLY guard, so every path back to `starting` has
-  // to clear the flag itself. Retry is one: it is a fresh attempt that was never blocked, and a hint
-  // carried over from the previous attempt would name a cause that did not happen this time.
+  // to clear the flag itself or be unreachable while it is set. Retry is one of the clearing ones:
+  // it is a fresh attempt that was never blocked, and a hint carried over from the previous attempt
+  // would name a cause that did not happen this time.
   it('clicking Retry clears the autoplay-blocked hint', async () => {
     const playSpy = vi
       .spyOn(HTMLMediaElement.prototype, 'play')
@@ -312,6 +313,44 @@ describe('ChannelPreviewPanel', () => {
     }
   });
 
+  // The forced-preview opt-in is the third path back to `starting`, and the one that does NOT clear
+  // the flag. It does not have to: its button is gone the moment `started` flips true, which is
+  // before any player — the only thing that can set the flag — has mounted. Pin that unreachability,
+  // since it is what makes the missing clear correct rather than an oversight.
+  it('retires the forced-preview opt-in once the player is up, so it cannot re-enter starting with the hint set', async () => {
+    const playSpy = vi
+      .spyOn(HTMLMediaElement.prototype, 'play')
+      .mockRejectedValue(new DOMException('blocked', 'NotAllowedError'));
+
+    try {
+      await renderPanel(
+        <ChannelPreviewPanel
+          channel={channel(forced, 'MPEG-TS')}
+          nowPlaying={null}
+          onClose={vi.fn()}
+          open
+        />
+      );
+
+      fireEvent.click(screen.getByRole('button', { name: /preview via hls anyway/i }));
+      await flush();
+
+      const manifestHandler = getManifestHandler();
+      await act(async () => {
+        manifestHandler();
+        await Promise.resolve();
+        await Promise.resolve();
+      });
+
+      expect(screen.getByText(/autoplay was blocked/i)).toBeInTheDocument();
+      expect(
+        screen.queryByRole('button', { name: /preview via hls anyway/i })
+      ).not.toBeInTheDocument();
+    } finally {
+      playSpy.mockRestore();
+    }
+  });
+
   // A play() interrupted by teardown rejects with AbortError, which is exactly what Retry produces
   // while the manifest-parsed play() is still pending. The hint names blocked autoplay as the cause,
   // so it must not appear for a rejection that was not the autoplay policy.
diff --git a/web/src/screens/channels/ChannelPreviewPanel.tsx b/web/src/screens/channels/ChannelPreviewPanel.tsx
index 67de3b5aa..0180fc79b 100644
--- a/web/src/screens/channels/ChannelPreviewPanel.tsx
+++ b/web/src/screens/channels/ChannelPreviewPanel.tsx
@@ -48,9 +48,13 @@ export function ChannelPreviewPanel({ channel, nowPlaying, onClose, open }: Chan
   // Set when the browser's autoplay policy rejects HlsPlayer's own play() kick despite the player
   // being muted (#554). Purely informational — `state` stays 'starting' (still honest: playback has
   // not actually begun) — so the operator knows to press the native play button instead of assuming
-  // a stall. The hint's visibility is the render guard on `state === 'starting'` alone: every path
-  // back to 'starting' (Retry, a channel change) clears this flag itself, so a second clear in
-  // onPlaying would be unreachable as a guard and could not be pinned by a test.
+  // a stall. The hint's visibility is the render guard on `state === 'starting'` alone, so a second
+  // clear in onPlaying would be unreachable as a guard and could not be pinned by a test. Of the
+  // three paths back to 'starting', two clear this flag themselves (Retry, and the render-phase
+  // channel reset below). The third — onOptIn — deliberately does not, because it cannot be reached
+  // while the flag is set: its button renders only while `started` is false, `started` only goes
+  // false in that same reset (two lines above the reset's own clear), and no player exists to set
+  // the flag in between. A clear there would be dead code no test could distinguish either.
   const [autoplayBlocked, setAutoplayBlocked] = useState(false);
   // Bumped on every (re)play. The manifest GET itself starts a server-side session, so a repeat play
   // of an identical URL — e.g. Retry after a failure — must re-issue the request rather than be a
-- 
2.47.3


From 350509f8bb7c514a07bb2dc8e85d0e028a19380c Mon Sep 17 00:00:00 2001
From: Timothy <timothy@noreply.gitea.tblindustries.be>
Date: Sat, 5 Sep 2026 02:45:42 +0200
Subject: [PATCH 5/5] docs(554): the opt-in's unreachability is about
 `started`, not about mount order
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"its button renders only before the player has ever mounted" is loose: a channel
switch to a forced channel re-renders the button after a player has mounted for the
previous channel. The load-bearing fact is the one the code comment states — the
button renders only while `started` is false, and the only thing that un-starts the
panel is the channel reset that clears the flag in the same batch.

Refs #554

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QqCpYFsKgnAnx6jVwrKiV
---
 docs/spa-conventions.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/spa-conventions.md b/docs/spa-conventions.md
index d70e663aa..9ce223c0e 100644
--- a/docs/spa-conventions.md
+++ b/docs/spa-conventions.md
@@ -667,9 +667,9 @@ channel-preview panel wires it to a "press play" hint whose visibility is the re
 `state === 'starting'` **alone**, so a second clear in `onPlaying` would be a guard no test could
 distinguish. That holds because the panel's paths back to `starting` either clear the flag themselves
 (Retry, a channel change) or cannot be reached while it is set — the forced-preview opt-in re-enters
-`starting` without clearing, but its button renders only before the player has ever mounted, so the
-flag is necessarily false there. The panel never claims the fault fixed itself; the hint mirrors an
-honest, still-not-playing state.
+`starting` without clearing, but its button renders only while the panel has not started, and the
+only thing that un-starts it is the channel reset that clears the flag. The panel never claims the
+fault fixed itself; the hint mirrors an honest, still-not-playing state.
 
 **Resolving a `/iptv/*` src under JWT auth (#552).** Before feeding an `/iptv/*` manifest URL to
 `HlsPlayer`, pass it through `withIptvToken(url)` (`web/src/media/iptvToken.ts`): under a JWT-enabled
-- 
2.47.3