From 1630a3df3c6ff7da0abbc0fad65b2ba21a4d4b03 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Wed, 9 Sep 2026 23:55:51 +0200
Subject: [PATCH 01/52] fix(player): the YT progress checkpoint reaches the
 cache, so a reopen cannot rewind it

The player checkpointed every 5s and the server stored it, but nothing wrote the new
position back into react-query: the close path only marked qk.feed() stale with
refetchType "none", and nothing refetches the feed until it remounts (staleTime 30s,
refetchOnWindowFocus off). So the resume read the position the cache had been FETCHED
with, and the next checkpoint then persisted that older value over the newer one.

Measured on localdev: played to 830s, closed (server had 830), reopened the same card
without a reload -> the row was back to 751s. 79 seconds of progress destroyed by a
reopen, and the card's progress bar never moved either.

The Plex player already solved this for its detail query, with a comment describing the
identical failure; this is the feed-side twin that was missed in that sweep. patchCachedProgress
writes the position the SERVER stored (the endpoint clears trivially-early and near-finished
checkpoints to 0, so mirroring our own reading would disagree with the row) into every cached
feed page and playlist detail, keeping array identity where nothing changed. A session map
covers the second half: the launch queue is frozen at mount, so stepping next->prev back to an
item played earlier in the same session resumed from that snapshot.

Verified in the browser: 811 -> close 816 -> reopen 825, and the card now shows Continue/Restart.
---
 frontend/src/components/PlayerModal.tsx       |  13 +-
 frontend/src/lib/api/feed.ts                  |  18 +-
 .../playerModalHooks.progress.dom.test.tsx    | 164 ++++++++++++++++++
 frontend/src/lib/playerModalHooks.ts          |  20 ++-
 frontend/src/lib/progressCache.ts             |  67 +++++++
 5 files changed, 277 insertions(+), 5 deletions(-)
 create mode 100644 frontend/src/lib/playerModalHooks.progress.dom.test.tsx
 create mode 100644 frontend/src/lib/progressCache.ts

diff --git a/frontend/src/components/PlayerModal.tsx b/frontend/src/components/PlayerModal.tsx
index c9666d11..fbce8674 100644
--- a/frontend/src/components/PlayerModal.tsx
+++ b/frontend/src/components/PlayerModal.tsx
@@ -129,9 +129,17 @@ export default function PlayerModal({
   if (index < 0) index = 0;
   const active = queue?.[index] ?? video; // the queue item at index, else the opened video (never undefined)
   const hasQueue = !!queue && queue.length > 1;
-  // startAt only applies to the item we opened with; advanced items resume their own pos.
+  // Positions this session has checkpointed (server-confirmed), per video id — see useYtProgress.
+  // The launch queue is frozen at mount, so its items keep the position they were snapshotted with;
+  // without this map, stepping next→prev back to an item played earlier in the SAME session would
+  // resume at that snapshot and then persist it over the newer position.
+  const sessionPosRef = useRef<Map<string, number>>(new Map());
+  const sessionPos = sessionPosRef.current.get(active.id);
+  // startAt only applies to the item we opened with; advanced items resume their own pos. A
+  // position this session already stored wins over both — it is the freshest truth we have.
   const resumeAt =
-    startAt != null && active.id === video.id ? startAt : active.position_seconds || 0;
+    sessionPos ??
+    (startAt != null && active.id === video.id ? startAt : active.position_seconds || 0);
   const mountRef = useRef<HTMLDivElement | null>(null);
   const playerRef = useRef<YTPlayer | null>(null);
   // Keyboard/wheel controls. We keep focus on the modal card (not the cross-origin player
@@ -429,6 +437,7 @@ export default function PlayerModal({
     reapplyStored,
     focusModal,
     advanceOnEnd,
+    sessionPosRef,
     qc,
   });
 
diff --git a/frontend/src/lib/api/feed.ts b/frontend/src/lib/api/feed.ts
index 8ff19306..0d19b24a 100644
--- a/frontend/src/lib/api/feed.ts
+++ b/frontend/src/lib/api/feed.ts
@@ -40,6 +40,12 @@ export interface VideoDetail {
   duration_seconds: number | null;
 }
 
+/** The stored answer of `POST /api/videos/{id}/progress` — the row as it now stands. */
+export interface StoredProgress {
+  video_id: string;
+  position_seconds: number;
+}
+
 export interface FeedResponse {
   items: Video[];
   has_more: boolean;
@@ -179,8 +185,16 @@ export const feedApi = {
     ),
   clearState: (id: string) =>
     req(`/api/videos/${id}/state`, { method: "DELETE" }, { idempotent: true }),
-  saveProgress: (id: string, positionSeconds: number, durationSeconds: number) =>
-    req(
+  // Returns the position the server actually STORED — which is not always what we sent: a
+  // trivially-early or near-finished checkpoint is cleared to 0 (see set_video_progress). Callers
+  // that mirror the position into a cache must write this answer, never their own reading, so the
+  // client can never disagree with the row.
+  saveProgress: (
+    id: string,
+    positionSeconds: number,
+    durationSeconds: number,
+  ): Promise<StoredProgress> =>
+    req<StoredProgress>(
       `/api/videos/${id}/progress`,
       {
         method: "POST",
diff --git a/frontend/src/lib/playerModalHooks.progress.dom.test.tsx b/frontend/src/lib/playerModalHooks.progress.dom.test.tsx
new file mode 100644
index 00000000..69745c07
--- /dev/null
+++ b/frontend/src/lib/playerModalHooks.progress.dom.test.tsx
@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+//
+// The YT player's progress checkpoint must reach the CACHE, not just the server. Before this, the
+// modal's cleanup only marked `qk.feed()` stale with `refetchType: "none"` — and nothing refetches
+// the feed until it remounts (staleTime 30s, refetchOnWindowFocus off), so reopening the same card
+// in the same session resumed from the position the cache had been fetched with, and the next
+// checkpoint then persisted THAT older value over the newer one. Measured on localdev before the
+// fix: played to 830s → closed (server had 830) → reopened → the row was back to 751s.
+//
+// Its own file on purpose: `loadYouTubeApi` memoises the API promise in a module-level singleton,
+// so a test that installs `window.YT` cannot share a module instance with tests that do not.
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { QueryClient } from "@tanstack/react-query";
+import { createRef, type MutableRefObject } from "react";
+import { useYtProgress } from "./playerModalHooks";
+import { patchCachedProgress } from "./progressCache";
+import { qk } from "./queryKeys";
+import { api, type Video } from "./api";
+import type { YTPlayer } from "./youtube";
+
+const VID = "EC5oFYy9z9g";
+
+const video = (over: Partial<Video> = {}): Video =>
+  ({ id: VID, title: "Melyik szállás a Drágább?", position_seconds: 748, ...over }) as Video;
+
+/** A feed cache shaped like the real infinite query: pages of `{ items }`. */
+const seedFeed = (qc: QueryClient, v: Video) =>
+  qc.setQueryData(qk.feed({ q: "" } as never), { pages: [{ items: [v] }], pageParams: [null] });
+
+const cachedPos = (qc: QueryClient): number | undefined => {
+  const data = qc.getQueryData(qk.feed({ q: "" } as never)) as
+    | { pages: { items: Video[] }[] }
+    | undefined;
+  return data?.pages[0]?.items[0]?.position_seconds;
+};
+
+// ONE fake namespace with a MUTABLE clock, installed once. `loadYouTubeApi` memoises the API
+// promise in a module-level singleton, so the namespace the first mount resolves is the one every
+// later mount gets — re-installing a fresh `window.YT` per test would silently have no effect (an
+// earlier draft of this file did exactly that, and its "near the end" case was really still
+// reading the first test's clock).
+const clock = { current: 0, duration: 0 };
+const fakePlayer = {
+  getCurrentTime: () => clock.current,
+  getDuration: () => clock.duration,
+  destroy: () => {},
+} as unknown as YTPlayer;
+window.YT = {
+  Player: function () {
+    return fakePlayer;
+  } as never,
+};
+
+/** Point the shared fake player at a position. */
+function atPosition(currentTime: number, duration: number) {
+  clock.current = currentTime;
+  clock.duration = duration;
+}
+
+/** Let the API promise, the player construction and the checkpoint POST all settle. */
+const settle = async () => {
+  for (let i = 0; i < 6; i++) await Promise.resolve();
+  await new Promise((r) => setTimeout(r, 0));
+  for (let i = 0; i < 6; i++) await Promise.resolve();
+};
+
+function mountPlayer(qc: QueryClient, sessionPos: Map<string, number>) {
+  const mount = document.createElement("div");
+  document.body.appendChild(mount);
+  return renderHook(() =>
+    useYtProgress({
+      activeId: VID,
+      resumeAt: 748,
+      mountRef: { current: mount },
+      playerRef: createRef<YTPlayer>() as MutableRefObject<YTPlayer | null>,
+      currentIdRef: { current: VID },
+      navRef: { current: { queue: undefined, index: 0 } },
+      modeRef: { current: { autoMode: "off", loopMode: "off" } },
+      setWatched: () => {},
+      setPlayerError: () => {},
+      setLiveData: () => {},
+      reapplyStored: () => {},
+      focusModal: () => {},
+      advanceOnEnd: () => {},
+      sessionPosRef: { current: sessionPos },
+      qc,
+    }),
+  );
+}
+
+describe("useYtProgress — the checkpoint reaches the cache", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("writes the position the player reached into the cached feed on close", async () => {
+    const qc = new QueryClient();
+    seedFeed(qc, video());
+    atPosition(830, 3118);
+    const save = vi
+      .spyOn(api, "saveProgress")
+      .mockResolvedValue({ video_id: VID, position_seconds: 830 });
+
+    const { unmount } = mountPlayer(qc, new Map());
+    await settle();
+    unmount();
+    await settle();
+
+    expect(save).toHaveBeenCalled();
+    // Without the patch this stays 748 — the value a reopen would resume from, and then persist
+    // back over the 830 the server already holds.
+    expect(cachedPos(qc)).toBe(830);
+  });
+
+  it("mirrors what the SERVER stored, not what the player read", async () => {
+    const qc = new QueryClient();
+    seedFeed(qc, video({ position_seconds: 748 }));
+    // 3s in — under the endpoint's 5s floor, so it stores 0 and answers 0. (The OTHER clearing
+    // rule, near-the-end, is unreachable from here on purpose: the player auto-marks watched and
+    // deliberately skips that checkpoint, so it never asks the server at all.)
+    atPosition(3, 3118);
+    vi.spyOn(api, "saveProgress").mockResolvedValue({ video_id: VID, position_seconds: 0 });
+    const sessionPos = new Map<string, number>();
+
+    const { unmount } = mountPlayer(qc, sessionPos);
+    await settle();
+    unmount();
+    await settle();
+
+    // Mirroring `getCurrentTime()` would put 3 here — a resume bar and a resume point the server
+    // does not have, which the next checkpoint would then keep re-asserting.
+    expect(sessionPos.get(VID)).toBe(0);
+    expect(cachedPos(qc)).toBe(0);
+  });
+});
+
+describe("patchCachedProgress", () => {
+  it("patches a playlist detail and leaves untouched lists identical", () => {
+    const qc = new QueryClient();
+    const other = video({ id: "other", position_seconds: 12 });
+    qc.setQueryData(qk.playlist(3), { id: 3, items: [video(), other] });
+    const before = qc.getQueryData(qk.playlist(3)) as { items: Video[] };
+
+    patchCachedProgress(qc, new Map([[VID, 830]]));
+
+    const after = qc.getQueryData(qk.playlist(3)) as { items: Video[] };
+    expect(after.items[0]?.position_seconds).toBe(830);
+    // Same object identity for the row that did not change — so an open player's checkpoint does
+    // not re-render every card in the list behind it.
+    expect(after.items[1]).toBe(before.items[1]);
+    expect(after.items[1]?.position_seconds).toBe(12);
+  });
+
+  it("is a no-op when nothing was stored", () => {
+    const qc = new QueryClient();
+    seedFeed(qc, video());
+    const before = qc.getQueryData(qk.feed({ q: "" } as never));
+
+    patchCachedProgress(qc, new Map());
+
+    expect(qc.getQueryData(qk.feed({ q: "" } as never))).toBe(before);
+  });
+});
diff --git a/frontend/src/lib/playerModalHooks.ts b/frontend/src/lib/playerModalHooks.ts
index 2a64cca2..ab0a47f8 100644
--- a/frontend/src/lib/playerModalHooks.ts
+++ b/frontend/src/lib/playerModalHooks.ts
@@ -19,6 +19,7 @@ import {
 import { useBackToExit } from "./history";
 import { api, type Video } from "./api";
 import { qk } from "./queryKeys";
+import { patchCachedProgress } from "./progressCache";
 import type { YTNamespace, YTPlayer, YTPlayerEvent } from "./youtube";
 import type { AutoMode, LoopMode } from "../components/playerModalControls";
 
@@ -308,6 +309,7 @@ export function useYtProgress({
   reapplyStored,
   focusModal,
   advanceOnEnd,
+  sessionPosRef,
   qc,
 }: {
   activeId: string;
@@ -323,6 +325,10 @@ export function useYtProgress({
   reapplyStored: () => void;
   focusModal: () => void;
   advanceOnEnd: () => void;
+  // Positions this player session has actually STORED, per video id. Written from the server's
+  // answer, read back by the modal's resume so stepping next→prev inside one session does not
+  // rewind to the value the frozen launch queue was snapshotted with.
+  sessionPosRef: MutableRefObject<Map<string, number>>;
   qc: QueryClient;
 }): void {
   const autoMarkedRef = useRef(false);
@@ -359,7 +365,14 @@ export function useYtProgress({
         // Only checkpoint the library item we opened with — a navigated-to video may not be in this
         // user's library, so the server would 404 on it.
         if (currentIdRef.current === id) {
-          return api.saveProgress(id, cur, dur).catch(() => {});
+          return (
+            api
+              .saveProgress(id, cur, dur)
+              // Record what the server STORED, not `cur`: a near-end or under-5s checkpoint is
+              // cleared to 0 there, and the resume must agree with the row, not with our reading.
+              .then((res) => void sessionPosRef.current.set(id, res.position_seconds))
+              .catch(() => {})
+          );
         }
       } catch {
         /* player may be tearing down */
@@ -445,6 +458,11 @@ export function useYtProgress({
       // Final flush, then mark the feed + playlists stale so resume bars reflect this session on the next
       // natural refetch — WITHOUT refetching every loaded feed page on each player close (PERF-2).
       Promise.resolve(persist()).finally(() => {
+        // Write this session's stored positions INTO the cached lists first. Marking them stale is
+        // not enough on its own: nothing refetches the feed until it remounts (staleTime 30s,
+        // refetchOnWindowFocus off), so a reopen used to resume from the position the cache was
+        // fetched with — and the next checkpoint then persisted that older value over this one.
+        patchCachedProgress(qc, sessionPosRef.current);
         qc.invalidateQueries({ queryKey: qk.feed(), refetchType: "none" });
         qc.invalidateQueries({ queryKey: qk.playlist(), refetchType: "none" });
       });
diff --git a/frontend/src/lib/progressCache.ts b/frontend/src/lib/progressCache.ts
new file mode 100644
index 00000000..087c2523
--- /dev/null
+++ b/frontend/src/lib/progressCache.ts
@@ -0,0 +1,67 @@
+import type { QueryClient } from "@tanstack/react-query";
+import { qk } from "./queryKeys";
+import type { Video } from "./api";
+
+// Every cached list that carries feed videos is one of two shapes: a single object with `items`
+// (a playlist detail) or an infinite query's `{ pages: [...] }` over those objects. Narrow
+// structurally rather than by type name so a new list surface is covered the day it is added.
+type ItemList = { items: Video[] };
+type Cached = Partial<ItemList> & { pages?: unknown[] };
+
+const isItemList = (v: unknown): v is ItemList =>
+  !!v && typeof v === "object" && Array.isArray((v as ItemList).items);
+
+/**
+ * Write server-stored resume positions into every cached list holding those videos.
+ *
+ * The player checkpoints progress every few seconds, but until this ran, nothing wrote the new
+ * position back into react-query — so the feed cache kept the value it was fetched with, a reopen
+ * of the same card resumed from THAT stale value, and the next checkpoint then persisted the older
+ * position over the newer one (measured: 830s → reopen → 751s). The Plex player already solved the
+ * same problem for its detail query (`plexPlayerHooks`, "reopening the same item in the SAME
+ * session read react-query's CACHED detail"); this is the feed-side twin.
+ *
+ * `positions` must hold what the SERVER stored (`api.saveProgress`'s answer), not what the player
+ * read: the endpoint clears trivially-early and near-finished checkpoints to 0, and mirroring our
+ * own reading would re-introduce that disagreement on the client.
+ */
+export function patchCachedProgress(qc: QueryClient, positions: Map<string, number>): void {
+  if (positions.size === 0) return;
+
+  const patchList = (items: Video[]): Video[] => {
+    let changed = false;
+    const next = items.map((v) => {
+      const pos = positions.get(v.id);
+      if (pos === undefined || v.position_seconds === pos) return v;
+      changed = true;
+      return { ...v, position_seconds: pos };
+    });
+    // Keep the previous array identity when nothing moved, so an untouched list does not
+    // re-render every card behind the open player.
+    return changed ? next : items;
+  };
+
+  const patch = (old: Cached | undefined): Cached | undefined => {
+    if (!old) return old;
+    if (Array.isArray(old.pages)) {
+      let changed = false;
+      const pages = old.pages.map((page) => {
+        if (!isItemList(page)) return page;
+        const items = patchList(page.items);
+        if (items === page.items) return page;
+        changed = true;
+        return { ...page, items };
+      });
+      return changed ? { ...old, pages } : old;
+    }
+    if (isItemList(old)) {
+      const items = patchList(old.items);
+      return items === old.items ? old : { ...old, items };
+    }
+    return old;
+  };
+
+  // Prefix keys: every filter combination of the feed, and every playlist detail.
+  qc.setQueriesData<Cached>({ queryKey: qk.feed() }, patch);
+  qc.setQueriesData<Cached>({ queryKey: qk.playlist() }, patch);
+}

From b8bff504d81c1a5a1d703f8e59650b1f446d13f7 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Wed, 9 Sep 2026 23:55:51 +0200
Subject: [PATCH 02/52] fix(plex): "Clear resume point" now tells Plex about an
 in-progress item
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The button deletes the local row and mirrors the un-mark to Plex, but it decided whether
to push from the previous STATUS alone (prev_status != "new") — and an in-progress item's
row is status="new" carrying a position, which is exactly how the importer maps a bare
viewOffset. So for the single case the button exists for, nothing was ever sent to Plex:
the offset stayed, and the next pull imported it straight back. The user cleared Protector
twice and it returned to Continue watching at 92s both times.

Push now when Plex holds anything to clear — a view count, or a resume point. "hidden"
stays Siftlode-only and pushes nothing, which is what this endpoint's docstring always
claimed and the status-only guard contradicted.

One unscrobble clears BOTH viewCount and viewOffset — measured against the live server from
a watched+offset state and an offset-only one, so the push itself needed no change. The
client docstring that claimed "clears viewCount" is what sent the first diagnosis down a
wrong path (a timeline write with time=0, which does not clear an offset at all); it now
records what the server actually does.

Verified end to end on the real Plex server: the button leaves viewCount=None viewOffset=None,
and a full 44,885-item re-import brings back no row for it.
---
 backend/app/plex/client.py                   |  7 +-
 backend/app/routes/plex/playback.py          | 12 ++-
 backend/tests/test_plex_clear_resume_push.py | 83 ++++++++++++++++++++
 3 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 backend/tests/test_plex_clear_resume_push.py

diff --git a/backend/app/plex/client.py b/backend/app/plex/client.py
index a8a92dde..d3313323 100644
--- a/backend/app/plex/client.py
+++ b/backend/app/plex/client.py
@@ -197,7 +197,12 @@ class PlexClient:
         )
 
     def unscrobble(self, rating_key: str) -> None:
-        """Mark the item *unwatched* on the token's Plex account (clears viewCount)."""
+        """Mark the item *unwatched* on the token's Plex account.
+
+        Clears the view count AND the resume point (`viewOffset`) — measured against the live server
+        on 2026-09-09, from both a watched+offset state and an offset-only one. This one call is the
+        whole un-mark; `/:/timeline?time=0` and `/:/progress?time=0` were both tried there and do
+        NOT clear an offset, so do not reach for them."""
         self._write(
             "GET",
             f"/:/unscrobble?identifier={self._LIBRARY_IDENTIFIER}"
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index d77eb462..1a25750c 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -406,10 +406,20 @@ def item_state(
     )
     prev_status = st.status if st is not None else "new"
     if status == "new":
+        # Does Plex hold anything for this item that the un-mark has to clear? Two things qualify: a
+        # view count, and a resume point. An IN-PROGRESS item carries status "new" WITH a position —
+        # that is how the importer maps a bare `viewOffset` (`_plex_watch_to_state`) — so keying the
+        # push on the status alone silently skipped the single case "Clear resume point" exists for:
+        # the un-mark never reached Plex, the offset stayed, and the next pull imported it straight
+        # back (Protector, cleared twice by the user and back at 92s both times). `hidden` is
+        # Siftlode-only and still pushes nothing, exactly as this endpoint's docstring says.
+        mirrored_on_plex = st is not None and (
+            st.status == "watched" or (st.position_seconds or 0) > 0
+        )
         if st is not None:
             db.delete(st)
             db.commit()
-        if prev_status != "new":  # something → unwatched: mirror the un-mark to Plex
+        if mirrored_on_plex:
             _push_watch(background, db, user.id, it.id, rating_key, "unwatched")
         return {"status": "new"}
     if st is None:
diff --git a/backend/tests/test_plex_clear_resume_push.py b/backend/tests/test_plex_clear_resume_push.py
new file mode 100644
index 00000000..b088a84d
--- /dev/null
+++ b/backend/tests/test_plex_clear_resume_push.py
@@ -0,0 +1,83 @@
+""" "Clear resume point" has to reach Plex — the case the status-only guard skipped.
+
+`POST /api/plex/item/{rk}/state {"status": "new"}` backs the *Clear resume point* / *Mark unwatched*
+buttons. It deletes the local row and mirrors the un-mark to Plex — but it used to decide whether to
+push from the PREVIOUS STATUS alone (`prev_status != "new"`), and an in-progress item's row is
+`status="new"` carrying a position: that is how the importer maps a bare `viewOffset`
+(`_plex_watch_to_state`). So for the one case the button exists for, nothing was ever sent to Plex,
+Plex kept the offset, and the next pull imported it straight back — the user cleared *Protector*
+twice and it returned to Continue watching at 92s both times (2026-09-09).
+
+One `unscrobble` clears the view count AND the offset (measured against the live server), so the
+push itself needed no change; what needed fixing is WHEN it is scheduled.
+
+DB lane (`db` fixture) — skipped when no Postgres is reachable.
+"""
+
+from types import SimpleNamespace
+
+from fastapi.testclient import TestClient
+
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
+from app.main import app
+from app.models import PlexItem, PlexLibrary, PlexState, User
+from app.plex import watch_sync as plex_watch
+
+
+def _seed(db, *, status: str, position: int):
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    it = PlexItem(
+        rating_key="98614", library_id=lib.id, kind="movie", title="Protector", duration_s=5495
+    )
+    db.add(it)
+    user = User(email="clear@example.com")
+    db.add(user)
+    db.flush()
+    db.add(PlexState(user_id=user.id, item_id=it.id, status=status, position_seconds=position))
+    db.commit()
+    return it, user
+
+
+def _clear(db, user, it, monkeypatch) -> list[tuple]:
+    """Drive the endpoint with the Plex link satisfied and the background push recorded."""
+    pushes: list[tuple] = []
+    monkeypatch.setattr(state, "_configured_cache", True)  # pass the instance-setup request gate
+    monkeypatch.setattr(plex_watch, "link_for_push", lambda db_, uid: SimpleNamespace(id=1))
+    monkeypatch.setattr(
+        plex_watch,
+        "push_state_to_plex",
+        lambda user_id, item_id, rating_key, action, *rest: pushes.append((rating_key, action)),
+    )
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: user
+    try:
+        resp = TestClient(app).post(f"/api/plex/item/{it.rating_key}/state", json={"status": "new"})
+        assert resp.status_code == 200, resp.text
+    finally:
+        app.dependency_overrides.clear()
+    return pushes
+
+
+def test_clearing_an_in_progress_item_tells_plex(db, monkeypatch):
+    # The regression: status "new" + a position IS the in-progress shape, and it must push.
+    it, user = _seed(db, status="new", position=92)
+    assert _clear(db, user, it, monkeypatch) == [("98614", "unwatched")]
+    assert db.query(PlexState).count() == 0
+
+
+def test_clearing_a_watched_item_still_tells_plex(db, monkeypatch):
+    # The case the old guard did cover — kept, so the fix cannot narrow into a new hole.
+    it, user = _seed(db, status="watched", position=0)
+    assert _clear(db, user, it, monkeypatch) == [("98614", "unwatched")]
+
+
+def test_unhiding_touches_plex_not_at_all(db, monkeypatch):
+    # `hidden` is a Siftlode-only concept "with no Plex analogue, so it never touches Plex" — the
+    # endpoint's own docstring. The old status-only guard pushed here anyway, un-marking an item on
+    # Plex that the user had merely hidden.
+    it, user = _seed(db, status="hidden", position=0)
+    assert _clear(db, user, it, monkeypatch) == []

From ed4ab4e13cdd6803e1492b270b1da11e980a766d Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Thu, 10 Sep 2026 19:31:05 +0200
Subject: [PATCH 03/52] fix(plex): subtitles stop blocking the request, and
 stop re-reading the file
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug hunt 2026-09, items 8 and 12 — the two things the Plex player was measurably
lying about.

Item 8: picking a subtitle track showed nothing for a long time, and the reported
workaround was to stop/start until it suddenly worked. Measured on prod against a
17.06 GB MKV with two embedded SubRip tracks:

  full pass, one track                154 s
  full pass, both tracks in ONE run   111 s
  -c:s copy (no WebVTT conversion)    143 s
  from 1:00:00 to the end of file      66 s
  a 630 s window at 1:00:00, both       8 s

So the conversion was never the cost: ffmpeg streams every byte of the container
between its seek point and its stop point, and the array delivers ~140 MB/s. The
only lever is reading less. Three changes follow from that:

  * a window around the playhead is extracted and published FIRST (seconds), and
    the full pass completes behind it;
  * every embedded text track rides that same single read — picking Hungarian used
    to cost a full pass and then switching to English cost another one;
  * none of it happens inside a request any more. The endpoint answers 202 while a
    background worker extracts, the player polls /status (carrying its position, so
    the window follows the viewer), and one ffmpeg run finally has a timeout.

-copyts is deliberately absent from a windowed pass: with it ffmpeg ignores -t and
reads the whole container anyway (measured — a [0, 600 s] window still took the
full 145 s), so a window comes back on a zero-based clock and is shifted to
absolute time here. Cached tracks written by older builds have no coverage sidecar
and count as complete, so nothing is re-extracted after the upgrade.

The <track> is no longer mounted before the server has something to put in it; a
"Preparing subtitles: …" notice stands in, and a track that can never be shown says
why instead of leaving the viewer to conclude the picker does nothing.

Item 12: "Bitrate" read a constant 211 kbps on every remux, because it was the
master playlist's BANDWIDTH — which ffmpeg derives from the one stream whose rate
it knows, the -b:a 192k AAC track, plus 10%. It is a measurement now: bytes per
second of MEDIA from hls.js FRAG_LOADED, accumulated per fragment type and summed
(a multi-audio session's video and audio renditions cover the same media seconds,
so pooling them would report half the truth), and an honest dash until the first
fragment lands. The panel also finally names the audio and subtitle track in play.

Verified in the browser against the real Plex library, and every new test
mutation-checked.
---
 backend/app/plex/subtitles.py                 | 374 +++++++++++++++++-
 backend/app/routes/plex/playback.py           |  87 ++--
 backend/tests/test_plex_subtitle_prepare.py   | 263 ++++++++++++
 frontend/src/components/PlexPlayer.tsx        |  62 ++-
 frontend/src/components/PlexStatsOverlay.tsx  |  27 +-
 frontend/src/i18n/locales/en/plex.json        |   8 +
 frontend/src/i18n/locales/hu/plex.json        |   8 +
 frontend/src/lib/api/plex.ts                  |  28 +-
 .../lib/plexPlayerHooks.subtitle.dom.test.tsx | 140 +++++++
 frontend/src/lib/plexPlayerHooks.ts           |  68 +++-
 frontend/src/lib/plexStats.test.ts            |  96 +++++
 frontend/src/lib/plexStats.ts                 |  60 ++-
 frontend/src/lib/queryKeys.ts                 |   3 +
 13 files changed, 1158 insertions(+), 66 deletions(-)
 create mode 100644 backend/tests/test_plex_subtitle_prepare.py
 create mode 100644 frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx

diff --git a/backend/app/plex/subtitles.py b/backend/app/plex/subtitles.py
index 770c10b0..ea685cfd 100644
--- a/backend/app/plex/subtitles.py
+++ b/backend/app/plex/subtitles.py
@@ -1,15 +1,57 @@
-"""WebVTT conversion, HLS-clock time-shift, and on-disk cache for Plex subtitle streams.
+"""WebVTT conversion, HLS-clock time-shift, and the on-disk cache + background extractor for Plex
+subtitle streams.
 
 Text subtitles (embedded or external) are turned into WebVTT so the browser <track> can render them;
 bitmap subtitles (Blu-ray/DVD) can't be (would need burn-in). Converted VTTs are cached on the shared
 Plex on-disk cache root (``cache.CACHE_DIR``).
+
+WHY THERE IS A BACKGROUND EXTRACTOR HERE — measured on prod, 2026-09-10, against a 17.06 GB 1080p
+MKV with two embedded SubRip tracks on the 81 TB array:
+
+===========================================================  ========
+  full pass, ONE track (what this module used to do)           154 s
+  full pass, BOTH text tracks in a SINGLE ffmpeg run           111 s
+  `-c:s copy` instead of converting to WebVTT                  143 s
+  from 1:00:00 to the end of the file                           66 s
+  a 630 s WINDOW at 1:00:00, both tracks                          8 s
+===========================================================  ========
+
+The conversion is not the cost (dropping it saved 7%): ffmpeg has to stream every byte of the
+container between its seek point and its stop point, and the array delivers ~140 MB/s — so the time
+is (bytes read) / 140 MB/s, and the ONLY lever is reading less. Hence:
+
+* extract a WINDOW around the playhead first — the viewer sees subtitles in seconds — then complete
+  the whole track in the background so every later seek is instant and the next session is free;
+* extract EVERY embedded text track in ONE pass, because the read is shared: picking Hungarian used
+  to cost a full read and then switching to English cost another one (the "hektikus" report);
+* never do any of it inside a request (it froze the <track> with no feedback AND held an API worker
+  thread for the whole read).
+
+`-copyts` CANNOT be used for a window: it makes ffmpeg ignore `-t`/`-to` (measured — a [0, 600 s]
+window still took the full 145 s and emitted the whole track), so windows are extracted on a
+zero-based clock and shifted back to absolute time here with `shift_vtt`.
 """
 
+import json
+import logging
 import re
 import subprocess
+import tempfile
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from pathlib import Path
 
+from sqlalchemy.orm import Session
+
+from app.db import SessionLocal
+from app.models import PlexItem
+from app.plex import paths as plex_paths
 from app.plex.cache import CACHE_DIR
-from app.plex.client import PlexError
+from app.plex.client import PlexClient, PlexError
+from app.plex.lookups import by_rating_key
+
+log = logging.getLogger("siftlode.plex")
 
 # Image-based subtitle codecs (Blu-ray/DVD) — can't be turned into text WebVTT (would need burn-in).
 BITMAP_SUBS = {
@@ -109,7 +151,7 @@ def ffmpeg_to_vtt(src: str, sub_ord: int | None) -> str:
         "webvtt",
         "pipe:1",
     ]
-    r = subprocess.run(cmd, capture_output=True)
+    r = subprocess.run(cmd, capture_output=True, timeout=EXTRACT_TIMEOUT_S)
     if r.returncode != 0 or not r.stdout:
         raise PlexError(
             (r.stderr or b"").decode("utf-8", "replace")[:200] or "ffmpeg subtitle convert failed"
@@ -133,3 +175,329 @@ def cache_write(key: str, vtt: str) -> None:
         tmp.replace(CACHE_DIR / f"{key}.vtt")  # atomic publish
     except OSError:
         pass
+
+
+# --- cache identity -----------------------------------------------------------------------------
+
+# The cached VTT holds ABSOLUTE cue times (per rating_key + subtitle ordinal); the per-session shift
+# is applied on the way out, so a resume/seek to any offset reuses the same file. Beside it, a small
+# JSON sidecar records WHICH absolute-time ranges the file actually covers — a windowed extraction
+# publishes a usable but incomplete track, and "incomplete" must never be mistaken for "all there is".
+_FULL_END_S = 1_000_000_000.0  # stand-in for "to the end of the file" (JSON can't hold infinity)
+
+
+def cache_key(rating_key: str, sub_ord: int) -> str:
+    return f"sub_{rating_key}_{sub_ord}"
+
+
+def _vtt_path(key: str) -> Path:
+    return CACHE_DIR / f"{key}.vtt"
+
+
+def _meta_path(key: str) -> Path:
+    return CACHE_DIR / f"{key}.json"
+
+
+def read_meta(key: str) -> tuple[list[list[float]], bool]:
+    """Covered absolute-time ranges + whether the track is fully extracted. A VTT with no sidecar
+    (written by an older build, which only ever cached complete tracks) counts as complete."""
+    try:
+        raw = json.loads(_meta_path(key).read_text(encoding="utf-8"))
+        return [[float(a), float(b)] for a, b in raw.get("ranges", [])], bool(raw.get("complete"))
+    except (OSError, ValueError, TypeError):
+        return ([[0.0, _FULL_END_S]], True) if _vtt_path(key).exists() else ([], False)
+
+
+def _write_meta(key: str, ranges: list[list[float]], complete: bool) -> None:
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        tmp = CACHE_DIR / f"{key}.json.tmp"
+        tmp.write_text(json.dumps({"ranges": ranges, "complete": complete}), encoding="utf-8")
+        tmp.replace(_meta_path(key))
+    except OSError:
+        pass
+
+
+def generation(key: str) -> int:
+    """Monotonic id of the cached file's current content. It goes into the <track> URL so that when a
+    window is superseded by a wider one the browser refetches instead of keeping the short VTT."""
+    try:
+        return _vtt_path(key).stat().st_mtime_ns
+    except OSError:
+        return 0
+
+
+def merge_ranges(ranges: list[list[float]]) -> list[list[float]]:
+    """Sort + coalesce touching/overlapping covered ranges."""
+    out: list[list[float]] = []
+    for a, b in sorted((r for r in ranges if r[1] > r[0]), key=lambda r: r[0]):
+        if out and a <= out[-1][1]:
+            out[-1][1] = max(out[-1][1], b)
+        else:
+            out.append([a, b])
+    return out
+
+
+def covers(ranges: list[list[float]], at: float) -> bool:
+    return any(a <= at <= b for a, b in ranges)
+
+
+def merge_vtt(*sources: str) -> str:
+    """Union of the cue blocks of several absolute-time VTTs, ordered by start time.
+
+    Two extraction passes over the same file emit identical cues for the region they share, so
+    de-duplication keys off the TIMING line — the one part of a cue that identifies it uniquely and
+    that neither pass can renumber (ffmpeg's webvtt muxer writes no cue identifiers)."""
+    seen: set[str] = set()
+    cues: list[tuple[float, str]] = []
+    for src in sources:
+        for block in re.split(r"\n[ \t]*\n", src or ""):
+            b = block.strip()
+            if not b or "-->" not in b:
+                continue  # header / NOTE / STYLE — the merged file gets its own single header
+            timing = next(ln for ln in b.split("\n") if "-->" in ln)
+            if timing in seen:
+                continue
+            seen.add(timing)
+            try:
+                start = _vtt_ts_to_s(timing.partition("-->")[0].strip())
+            except (ValueError, IndexError):
+                continue
+            cues.append((start, b))
+    cues.sort(key=lambda c: c[0])
+    return "WEBVTT\n\n" + "\n\n".join(b for _, b in cues) + "\n"
+
+
+def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) -> None:
+    """Merge a freshly extracted region into the cached track and widen its covered ranges."""
+    old = cache_read(key)
+    old_ranges, was_complete = read_meta(key)
+    cache_write(key, merge_vtt(old or "", vtt))
+    _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
+
+
+# --- background extraction ----------------------------------------------------------------------
+
+# How much of the track to extract before the viewer sees anything. WINDOW_PRE_S starts a little
+# before the playhead so a cue that is already on screen is not missed; WINDOW_LEN_S is the span
+# published as the first, provisional VTT (~4 s of work on the measured file). It only has to hold
+# until the full pass lands behind it — 111 s for that file — so it is deliberately much longer than
+# any realistic full pass.
+WINDOW_PRE_S = 30.0
+WINDOW_LEN_S = 300.0
+# Ceiling on one ffmpeg run so a wedged extraction can't hold a pool thread forever (the old
+# in-request extraction had no timeout at all).
+EXTRACT_TIMEOUT_S = 900.0
+# A failed track is remembered briefly so a 1 s status poll doesn't respawn ffmpeg every second, and
+# forgotten again soon after so fixing the file (or Plex coming back) doesn't need a restart.
+FAIL_TTL_S = 60.0
+# Two items' full passes plus a window for a third: enough that a seek into an un-extracted region is
+# served while a full pass runs, bounded so a burst can't thrash the array.
+_POOL = ThreadPoolExecutor(max_workers=3, thread_name_prefix="plex-subs")
+
+_LOCK = threading.Lock()
+_INFLIGHT: set[tuple] = set()
+_FAILURES: dict[str, tuple[str, float]] = {}
+
+
+class SubtitleUnavailable(Exception):
+    """A track that cannot be served as text, carrying the stable code the route maps to a status."""
+
+    def __init__(self, code: str):
+        super().__init__(code)
+        self.code = code
+
+
+# code -> HTTP status. An extraction/upstream failure is 422 with a structured detail (502 is
+# reserved for the raw byte proxies); the rest are genuine "no such thing" / "not text".
+UNAVAILABLE_STATUS = {
+    "no_item": 404,
+    "no_track": 404,
+    "no_file": 404,
+    "not_fetchable": 404,
+    "bitmap": 415,
+    "extract_failed": 422,
+    "plex_error": 422,
+}
+
+
+def reset_state() -> None:
+    """Drop the in-flight/failure registries (tests; nothing in the app needs it)."""
+    with _LOCK:
+        _INFLIGHT.clear()
+        _FAILURES.clear()
+
+
+def _fail(key: str, code: str) -> None:
+    with _LOCK:
+        _FAILURES[key] = (code, time.monotonic())
+
+
+def _recent_failure(key: str) -> str | None:
+    with _LOCK:
+        hit = _FAILURES.get(key)
+        if hit and time.monotonic() - hit[1] < FAIL_TTL_S:
+            return hit[0]
+        _FAILURES.pop(key, None)
+        return None
+
+
+def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
+    """State of one subtitle track, scheduling whatever extraction is still missing. NEVER blocks.
+
+    ``ready`` = fully extracted · ``partial`` = usable, covers ``at``, still growing · ``preparing``
+    = nothing to show for ``at`` yet · ``failed`` = ``code`` says why. ``gen`` changes whenever the
+    cached file grows, so the client can refetch a window that has been superseded."""
+    key = cache_key(rating_key, sub_ord)
+    ranges, complete = read_meta(key)
+    have = cache_read(key) is not None
+    covered = have and covers(ranges, at)
+    if complete and have:
+        return {"state": "ready", "code": None, "gen": generation(key)}
+    code = _recent_failure(key)
+    if code and not covered:
+        return {"state": "failed", "code": code, "gen": generation(key)}
+    if not code:
+        _schedule(rating_key, sub_ord, at, want_window=not covered)
+    return {"state": "partial" if covered else "preparing", "code": None, "gen": generation(key)}
+
+
+def _schedule(rating_key: str, sub_ord: int, at: float, want_window: bool) -> None:
+    """Kick off the jobs this track still needs: the window that makes it watchable now, and the one
+    full pass that makes it complete. Each is deduplicated by identity, so a 1 s status poll (or a
+    second viewer) joins the running job instead of starting another ffmpeg."""
+    jobs: list[tuple[tuple, float | None]] = []
+    if want_window:
+        w_start = max(0.0, at - WINDOW_PRE_S)
+        jobs.append((("win", rating_key, round(w_start)), w_start))
+    jobs.append((("full", rating_key), None))
+    for ident, window_start in jobs:
+        with _LOCK:
+            if ident in _INFLIGHT:
+                continue
+            _INFLIGHT.add(ident)
+        _POOL.submit(_run, ident, rating_key, sub_ord, window_start)
+
+
+def _run(ident: tuple, rating_key: str, sub_ord: int, window_start: float | None) -> None:
+    try:
+        _extract_and_publish(rating_key, sub_ord, window_start)
+    except SubtitleUnavailable as e:
+        _fail(cache_key(rating_key, sub_ord), e.code)
+    except PlexError as e:
+        log.warning("subtitle extraction failed for %s/%s: %s", rating_key, sub_ord, e)
+        _fail(cache_key(rating_key, sub_ord), "plex_error")
+    except (
+        Exception
+    ):  # a worker thread has nobody to raise to — record it, let the next poll see it
+        log.exception("subtitle extraction crashed for %s/%s", rating_key, sub_ord)
+        _fail(cache_key(rating_key, sub_ord), "extract_failed")
+    finally:
+        with _LOCK:
+            _INFLIGHT.discard(ident)
+
+
+def _text_streams(db: Session, rating_key: str) -> tuple[PlexItem, list[dict]]:
+    """The item plus its subtitle streams, in the ordinal order the API and the UI both use."""
+    it = by_rating_key(db, PlexItem, rating_key)
+    if it is None:
+        raise SubtitleUnavailable("no_item")
+    with PlexClient(db) as plex:
+        part = ((plex.metadata(it.rating_key) or {}).get("Media") or [{}])[0].get("Part") or [{}]
+        return it, [s for s in (part[0].get("Stream") or []) if s.get("streamType") == 3]
+
+
+def _is_bitmap(stream: dict) -> bool:
+    return (stream.get("codec") or stream.get("format") or "").lower() in BITMAP_SUBS
+
+
+def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | None) -> None:
+    """One extraction job. A sidecar track is fetched whole from Plex (cheap, no ffmpeg); an embedded
+    one is extracted together with EVERY other embedded text track in the file, because they all ride
+    on the same single read — the whole point of the measurement at the top of this module."""
+    with SessionLocal() as db:
+        it, subs = _text_streams(db, rating_key)
+        if sub_ord < 0 or sub_ord >= len(subs):
+            raise SubtitleUnavailable("no_track")
+        want = subs[sub_ord]
+        if _is_bitmap(want):
+            raise SubtitleUnavailable("bitmap")
+        if want.get("key"):  # external sidecar → one fetch, always the complete track
+            if window_start is not None:
+                return  # nothing to window — the full job serves it in a single fetch
+            vtt = _sidecar_vtt(db, want)
+            publish(cache_key(rating_key, sub_ord), vtt, (0.0, _FULL_END_S), True)
+            return
+        if want.get("index") is None:
+            raise SubtitleUnavailable("not_fetchable")
+        src = plex_paths.local_media_path(db, it.file_path)
+        if src is None:
+            raise SubtitleUnavailable("no_file")
+        # Ordinal among the file's EMBEDDED subtitle streams — what `-map 0:s:N` counts. Sidecars sit
+        # in the same list but not in the file, so they must not shift the mapping.
+        targets = {
+            sum(1 for x in subs[:i] if x.get("index") is not None): i
+            for i, s in enumerate(subs)
+            if s.get("index") is not None and not _is_bitmap(s)
+        }
+    start = window_start or 0.0
+    length = (WINDOW_LEN_S + WINDOW_PRE_S) if window_start is not None else None
+    end = _FULL_END_S if length is None else start + length
+    for emb_ord, vtt in _ffmpeg_extract(str(src), sorted(targets), window_start, length).items():
+        publish(
+            cache_key(rating_key, targets[emb_ord]),
+            shift_vtt(vtt, -start),  # zero-based window clock → absolute cue times
+            (start, end),
+            length is None,
+        )
+
+
+def _sidecar_vtt(db: Session, stream: dict) -> str:
+    """An external subtitle file, fetched through Plex and converted to WebVTT."""
+    with PlexClient(db) as plex:
+        raw = plex.raw_get(stream["key"])
+    codec = (stream.get("codec") or stream.get("format") or "").lower()
+    if codec in ("srt", "subrip", ""):
+        return srt_to_vtt(raw.decode("utf-8", "replace"))
+    with tempfile.NamedTemporaryFile(suffix="." + (codec or "sub"), delete=False) as fh:
+        fh.write(raw)
+        tmp = fh.name
+    try:
+        return ffmpeg_to_vtt(tmp, None)
+    finally:
+        Path(tmp).unlink(missing_ok=True)
+
+
+def _ffmpeg_extract(
+    src: str, emb_ords: list[int], start: float | None, length: float | None
+) -> dict[int, str]:
+    """Extract several embedded subtitle streams to WebVTT in ONE ffmpeg run (= one read of the file).
+
+    `start`/`length` bound the read to a window. Without `-copyts` the cues come out on a zero-based
+    clock (the caller shifts them back) — which is exactly why `-copyts` is absent: with it ffmpeg
+    ignores `-t` and reads the whole container anyway (measured)."""
+    if not emb_ords:
+        return {}
+    with tempfile.TemporaryDirectory(prefix="plexsub-") as tmpdir:
+        cmd = ["ffmpeg", "-nostdin", "-loglevel", "error"]
+        if start:
+            cmd += ["-ss", f"{start:.3f}"]
+        cmd += ["-i", src]
+        outs = {o: Path(tmpdir) / f"{o}.vtt" for o in emb_ords}
+        for emb_ord, out in outs.items():
+            cmd += ["-map", f"0:s:{emb_ord}"]
+            if length is not None:
+                cmd += ["-t", f"{length:.3f}"]
+            cmd += ["-f", "webvtt", "-y", str(out)]
+        r = subprocess.run(cmd, capture_output=True, timeout=EXTRACT_TIMEOUT_S)
+        got = {
+            o: p.read_text(encoding="utf-8", errors="replace")
+            for o, p in outs.items()
+            if p.exists()
+        }
+    if not got:
+        raise SubtitleUnavailable("extract_failed")
+    if r.returncode != 0:
+        # Partial output with a non-zero exit still beats nothing (a later pass widens it) — say so.
+        log.warning("ffmpeg subtitle pass exited %s: %s", r.returncode, (r.stderr or b"")[:200])
+    return got
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 1a25750c..c6e6d1dd 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -1,8 +1,6 @@
 """Plex playback: image/subtitle proxies, HLS streaming, and watch-state writes."""
 
 import hashlib
-import os
-import tempfile
 import threading
 from datetime import datetime, timedelta, timezone
 
@@ -89,62 +87,45 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
     return imgcache.response(data, ct)
 
 
+@router.get("/subtitle/{rating_key}/{sub_ord}/status")
+def subtitle_status(rating_key: str, sub_ord: int, request: Request, at: float = 0.0) -> dict:
+    """Is this subtitle track showable yet — and if not, get it moving. Extraction runs in the
+    background (see plex/subtitles.py for the measurements that forced it there), so the player polls
+    this while it waits instead of hanging on a <track> that will not load for a minute or more.
+
+    `at` is the viewer's absolute position: the extractor windows around it, so what gets read first
+    is the part actually about to be watched."""
+    _require_session(request)
+    return subtitles.ensure(rating_key, sub_ord, at)
+
+
 @router.get("/subtitle/{rating_key}/{sub_ord}")
-def subtitle(rating_key: str, sub_ord: int, request: Request, offset: float = 0.0) -> Response:
+def subtitle(
+    rating_key: str, sub_ord: int, request: Request, offset: float = 0.0, at: float = 0.0
+) -> Response:
     """Serve the ord-th subtitle track as WebVTT for the browser's <track> — so choosing a subtitle
     overlays it directly (no HLS re-mux / session restart). Handles EXTERNAL sidecar subs (fetched
     from Plex via the stream `key` — the old `-map 0:s` broke on these since they're not in the file)
-    AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached."""
+    AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached.
+
+    NEVER extracts inline. A cold track answers 202 and the extraction proceeds in the background; the
+    player mounts the <track> only once /status says there is something to show, so in practice this
+    is only ever hit warm (or on a cache eviction race, which the 202 sends back to polling)."""
     _require_session(request)
-    # Cache the ABSOLUTE-time VTT once (per rk+ord); the per-session cue-shift is applied on the way
-    # out, so a resume/seek to any offset reuses the same cached track (no cache-per-offset explosion).
-    cache_key = f"sub_{rating_key}_{sub_ord}"
-    hit = subtitles.cache_read(cache_key)
-    if hit is not None:
-        return Response(subtitles.shift_vtt(hit, offset), media_type="text/vtt")
-    try:
-        with SessionLocal() as db:
-            it = item_or_404(db, rating_key)
-            with PlexClient(db) as plex:
-                part = ((plex.metadata(it.rating_key) or {}).get("Media") or [{}])[0].get(
-                    "Part"
-                ) or [{}]
-                subs = [s for s in (part[0].get("Stream") or []) if s.get("streamType") == 3]
-                if sub_ord < 0 or sub_ord >= len(subs):
-                    raise HTTPException(status_code=404, detail="No such subtitle")
-                s = subs[sub_ord]
-                codec = (s.get("codec") or s.get("format") or "").lower()
-                if codec in subtitles.BITMAP_SUBS:
-                    raise HTTPException(
-                        status_code=415,
-                        detail="Image-based subtitle can't be shown as text",
-                    )
-                if s.get("key"):  # external sidecar → fetch from Plex, convert to VTT
-                    raw = plex.raw_get(s["key"])
-                    if codec in ("srt", "subrip", ""):
-                        vtt = subtitles.srt_to_vtt(raw.decode("utf-8", "replace"))
-                    else:
-                        fd, tmp = tempfile.mkstemp(suffix="." + (codec or "sub"))
-                        try:
-                            os.write(fd, raw)
-                            os.close(fd)
-                            vtt = subtitles.ffmpeg_to_vtt(tmp, None)
-                        finally:
-                            os.unlink(tmp)
-                elif s.get("index") is not None:  # embedded → extract from the local file
-                    src = plex_paths.local_media_path(db, it.file_path)
-                    if src is None:
-                        raise HTTPException(status_code=404, detail="Media file not found on disk")
-                    emb_ord = sum(1 for x in subs[:sub_ord] if x.get("index") is not None)
-                    vtt = subtitles.ffmpeg_to_vtt(str(src), emb_ord)
-                else:
-                    raise HTTPException(status_code=404, detail="Subtitle not fetchable")
-    except PlexNotConfigured as e:
-        raise HTTPException(status_code=400, detail=str(e))
-    except PlexError as e:
-        raise HTTPException(status_code=502, detail=f"Subtitle fetch failed: {e}")
-    subtitles.cache_write(cache_key, vtt)
-    return Response(subtitles.shift_vtt(vtt, offset), media_type="text/vtt")
+    # The cached VTT holds ABSOLUTE cue times (per rk+ord); the per-session cue-shift is applied on
+    # the way out, so a resume/seek to any offset reuses the same track (no cache-per-offset explosion).
+    st = subtitles.ensure(rating_key, sub_ord, at)
+    if st["state"] == "failed":
+        raise HTTPException(
+            status_code=subtitles.UNAVAILABLE_STATUS.get(st["code"], 422),
+            detail={"code": "subtitle", "reason": st["code"]},
+        )
+    hit = subtitles.cache_read(subtitles.cache_key(rating_key, sub_ord))
+    if hit is None:
+        return Response(
+            status_code=202, media_type="application/json", content='{"state":"preparing"}'
+        )
+    return Response(subtitles.shift_vtt(hit, offset), media_type="text/vtt")
 
 
 # Resume/watched thresholds. _PROGRESS_MIN_S matches the feed's PROGRESS_MIN_SECONDS (5), but
diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
new file mode 100644
index 00000000..128a84eb
--- /dev/null
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -0,0 +1,263 @@
+"""Subtitle extraction must not happen inside the request, and must read as little as possible.
+
+Bug hunt 2026-09, item 8 — "switching the subtitle track shows nothing; after a few stop/starts it
+suddenly works". Measured on prod against a 17.06 GB MKV with two embedded SubRip tracks:
+
+    full pass, one track  154 s | both tracks in ONE run  111 s | a 630 s window at 1:00:00  8 s
+
+The cost is not the WebVTT conversion, it is that ffmpeg streams every byte of the container between
+its seek point and its stop point. The old endpoint did that pass INSIDE the <track>'s request, once
+per track, with no timeout — so the browser sat on an empty track for minutes (and an API worker
+thread sat with it), and picking the second language cost the whole read again.
+
+These tests pin the three things that fixes it: the request never waits for ffmpeg, the extraction
+publishes a window around the playhead before the whole track, and one ffmpeg run covers every
+embedded text track. Pure — no Postgres, no ffmpeg.
+"""
+
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+import pytest
+from fastapi.testclient import TestClient
+
+import app.state as app_state
+from app.main import app
+from app.plex import subtitles
+from app.routes.plex import playback
+
+
+@pytest.fixture(autouse=True)
+def _isolated_cache(tmp_path, monkeypatch):
+    """A throwaway cache root + empty registries: this module's state is process-global."""
+    monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path)
+    subtitles.reset_state()
+    yield
+    subtitles.reset_state()
+
+
+@pytest.fixture
+def client(monkeypatch) -> TestClient:
+    # The subtitle endpoints authenticate off the signed session cookie directly (not a FastAPI
+    # dependency), so there is no dependency_overrides hook to use.
+    monkeypatch.setattr(playback, "resolved_user_id", lambda request: (1, None))
+    monkeypatch.setattr(app_state, "_configured_cache", True)  # pass the instance-setup gate, no DB
+    return TestClient(app)
+
+
+class _ManualPool:
+    """Deterministic stand-in for the extraction thread pool: jobs run when the test says so."""
+
+    def __init__(self) -> None:
+        self.jobs: list[tuple] = []
+
+    def submit(self, fn, *args) -> None:
+        self.jobs.append((fn, args))
+
+    def run_next(self) -> None:
+        fn, args = self.jobs.pop(0)
+        fn(*args)
+
+    def run_all(self) -> int:
+        jobs, self.jobs = self.jobs, []
+        for fn, args in jobs:
+            fn(*args)
+        return len(jobs)
+
+
+def _cue(start: str, end: str, text: str) -> str:
+    return f"{start} --> {end}\n{text}"
+
+
+def _vtt(*cues: str) -> str:
+    return "WEBVTT\n\n" + "\n\n".join(cues) + "\n"
+
+
+# --- the request must never wait for the extraction ---------------------------------------------
+
+
+def test_a_cold_track_answers_at_once_instead_of_waiting_for_ffmpeg(client, monkeypatch):
+    """THE regression. A cold track used to block the request for the length of a full file read;
+    now it answers 202 and the extraction runs behind it. Timed, because "does it block?" is the
+    whole question — the fake extraction holds a worker for 5 s, which the request must not feel."""
+    started = threading.Event()
+    release = threading.Event()
+
+    def _slow(rating_key, sub_ord, window_start):
+        started.set()
+        release.wait(timeout=5)
+
+    monkeypatch.setattr(subtitles, "_extract_and_publish", _slow)
+    try:
+        t0 = time.monotonic()
+        resp = client.get("/api/plex/subtitle/98614/0")
+        elapsed = time.monotonic() - t0
+        assert resp.status_code == 202, resp.text
+        assert elapsed < 2.0, f"the request waited {elapsed:.1f}s on the extraction"
+        assert started.wait(timeout=5), "the extraction never started in the background"
+        # …and the status endpoint answers just as fast while that extraction is still running.
+        t0 = time.monotonic()
+        st = client.get("/api/plex/subtitle/98614/0/status")
+        assert st.status_code == 200 and st.json()["state"] == "preparing"
+        assert time.monotonic() - t0 < 2.0
+    finally:
+        release.set()
+
+
+def test_a_burst_of_polls_starts_one_window_and_one_full_pass(monkeypatch):
+    """The player polls once a second while it waits. Each poll must JOIN the running jobs, not
+    start another ffmpeg over the same 17 GB."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    for _ in range(5):
+        subtitles.ensure("98614", 0, at=600.0)
+    assert len(pool.jobs) == 2  # one window (at 600 s) + the one full pass
+    # submit(_run, ident, rating_key, sub_ord, window_start) — the last arg is what distinguishes them
+    assert [a[3] for _, a in pool.jobs] == [570.0, None]  # the window first, then the full pass
+
+
+# --- window first, whole track after ------------------------------------------------------------
+
+
+def test_status_walks_preparing_to_partial_to_ready(client, monkeypatch):
+    """A window around the playhead makes the track showable long before it is complete, and the
+    generation changes when it grows so the browser refetches instead of keeping the short VTT."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    key = subtitles.cache_key("98614", 0)
+
+    def _publish(rating_key, sub_ord, window_start):
+        if window_start is not None:
+            subtitles.publish(
+                key, _vtt(_cue("59:54.187", "59:58.650", "window")), (3570.0, 3900.0), False
+            )
+        else:
+            subtitles.publish(key, _vtt(_cue("01:12.000", "01:15.000", "whole")), (0.0, 1e9), True)
+
+    monkeypatch.setattr(subtitles, "_extract_and_publish", _publish)
+
+    first = client.get("/api/plex/subtitle/98614/0/status?at=3600").json()
+    assert first["state"] == "preparing" and first["gen"] == 0
+
+    pool.run_next()  # the window job, submitted first — the full pass stays queued behind it
+    windowed = client.get("/api/plex/subtitle/98614/0/status?at=3600").json()
+    assert windowed["state"] == "partial", "a window around the playhead is showable"
+    assert windowed["gen"] > 0
+    # …and the <track> request now gets real WebVTT rather than another 202.
+    served = client.get("/api/plex/subtitle/98614/0?at=3600")
+    assert served.status_code == 200 and "window" in served.text
+
+    pool.run_next()  # the full pass, scheduled by that same first poll
+    done = client.get("/api/plex/subtitle/98614/0/status?at=3600").json()
+    assert done["state"] == "ready"
+    assert done["gen"] != windowed["gen"], "a widened track must not reuse the window's generation"
+    assert "whole" in client.get("/api/plex/subtitle/98614/0").text
+
+
+def test_a_position_outside_the_extracted_window_is_not_called_showable(client, monkeypatch):
+    """Honest states: cues exist, but none for where the viewer just seeked to. Saying "ready" there
+    would put an empty track on screen with no explanation — the original complaint."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    subtitles.publish(
+        subtitles.cache_key("98614", 0),
+        _vtt(_cue("00:10.000", "00:12.000", "x")),
+        (0.0, 330.0),
+        False,
+    )
+    assert client.get("/api/plex/subtitle/98614/0/status?at=100").json()["state"] == "partial"
+    assert client.get("/api/plex/subtitle/98614/0/status?at=5000").json()["state"] == "preparing"
+
+
+def test_an_unshowable_track_says_why_and_maps_to_a_status(client, monkeypatch):
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+
+    def _bitmap(rating_key, sub_ord, window_start):
+        raise subtitles.SubtitleUnavailable("bitmap")
+
+    monkeypatch.setattr(subtitles, "_extract_and_publish", _bitmap)
+    client.get("/api/plex/subtitle/98614/0/status")
+    pool.run_all()
+    st = client.get("/api/plex/subtitle/98614/0/status").json()
+    assert st["state"] == "failed" and st["code"] == "bitmap"
+    resp = client.get("/api/plex/subtitle/98614/0")
+    assert resp.status_code == 415  # a structured detail, so the UI can translate it
+    assert resp.json()["detail"] == {"code": "subtitle", "reason": "bitmap"}
+
+
+# --- the ffmpeg pass itself ---------------------------------------------------------------------
+
+
+def _capture_ffmpeg(monkeypatch) -> list[list[str]]:
+    """Record the argv of each ffmpeg run and satisfy it by writing the outputs it asked for."""
+    runs: list[list[str]] = []
+
+    def _fake_run(cmd, **kwargs):
+        runs.append(cmd)
+        for i, arg in enumerate(cmd):
+            if arg == "-y":
+                Path(cmd[i + 1]).write_text(_vtt(_cue("00:01.000", "00:02.000", "hi")), "utf-8")
+        return subprocess.CompletedProcess(cmd, 0, b"", b"")
+
+    monkeypatch.setattr(subtitles.subprocess, "run", _fake_run)
+    return runs
+
+
+def test_one_ffmpeg_run_extracts_every_embedded_text_track(monkeypatch):
+    """The read is the cost and it is SHARED. Extracting one track at a time is what made picking
+    Hungarian cost a full pass and then switching to English cost another one."""
+    runs = _capture_ffmpeg(monkeypatch)
+    out = subtitles._ffmpeg_extract("/plex-media/f.mkv", [0, 1], None, None)
+    assert len(runs) == 1, "each extra ffmpeg run is another full read of the file"
+    assert set(out) == {0, 1}
+    assert runs[0].count("-map") == 2
+
+
+def test_a_windowed_pass_bounds_the_read_and_never_uses_copyts(monkeypatch):
+    """`-copyts` is the trap: with it ffmpeg IGNORES -t and reads the whole container anyway
+    (measured — a [0, 600 s] window still took the full 145 s). So the window is extracted on a
+    zero-based clock and shifted back to absolute time by the caller."""
+    runs = _capture_ffmpeg(monkeypatch)
+    subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], 3570.0, 330.0)
+    cmd = runs[0]
+    assert "-copyts" not in cmd
+    assert cmd[cmd.index("-ss") + 1].startswith(
+        "3570"
+    )  # input seek — before -i, so it is a real seek
+    assert cmd.index("-ss") < cmd.index("-i")
+    assert cmd[cmd.index("-t") + 1].startswith("330")
+
+
+def test_the_full_pass_is_not_bounded(monkeypatch):
+    runs = _capture_ffmpeg(monkeypatch)
+    subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], None, None)
+    assert "-t" not in runs[0] and "-ss" not in runs[0]
+
+
+# --- the pure pieces the above rests on ---------------------------------------------------------
+
+
+def test_merge_vtt_unions_windows_in_time_order():
+    late = _vtt(_cue("59:54.187", "59:58.650", "late"))
+    early = _vtt(_cue("01:12.000", "01:15.000", "early"), _cue("59:54.187", "59:58.650", "late"))
+    merged = subtitles.merge_vtt(late, early)
+    assert merged.startswith("WEBVTT\n\n")
+    assert merged.count("-->") == 2, "the shared region must not be duplicated"
+    assert merged.index("early") < merged.index("late")
+
+
+def test_covered_ranges_coalesce_and_answer_membership():
+    ranges = subtitles.merge_ranges([[300.0, 600.0], [0.0, 330.0], [900.0, 1200.0]])
+    assert ranges == [[0.0, 600.0], [900.0, 1200.0]]
+    assert subtitles.covers(ranges, 450.0)
+    assert not subtitles.covers(ranges, 700.0)
+
+
+def test_a_cached_vtt_from_an_older_build_counts_as_complete(tmp_path):
+    """Before this change the cache only ever held whole tracks, and none of them has a sidecar.
+    Reading one as "covers nothing" would re-extract every already-cached track after the upgrade."""
+    (tmp_path / "sub_98614_0.vtt").write_text(_vtt(_cue("00:01.000", "00:02.000", "x")), "utf-8")
+    assert subtitles.read_meta("sub_98614_0") == ([[0.0, 1_000_000_000.0]], True)
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index ff076f6e..43c7a747 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -41,6 +41,7 @@ import {
 import { Ctrl, PanelHead, Skip10 } from "./plexPlayerControls";
 import { PlexPlayerSettings } from "./PlexPlayerSettings";
 import { PlexStatsOverlay } from "./PlexStatsOverlay";
+import { createFragMeter } from "../lib/plexStats";
 import { UpNextCard } from "./UpNextCard";
 import {
   useAutoSkip,
@@ -114,6 +115,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   // stats mode row's "· HDR→SDR" tag; null/false for an 8-bit HW, software, or non-transcode session.
   const tonemapRef = useRef<boolean | null>(null);
   const durationRef = useRef(0);
+  // Rolling per-fragment bitrate meter for the stats overlay. Fed from hls.js FRAG_LOADED below and
+  // reset with each session, because the master playlist's own BANDWIDTH is not a measurement — for a
+  // remux it is the AAC track's nominal 192k + 10%, i.e. a constant 211 kbps (see plexStats.ts).
+  const fragMeterRef = useRef(createFragMeter());
   // ≥2 audio tracks → multi-rendition HLS: all tracks ship in one session and hls.js switches audio
   // client-side (no restart). Ref so the stable loadSession/changeAudio callbacks read it fresh.
   const multiAudioRef = useRef(false);
@@ -303,6 +308,17 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         // buffer forward up to maxBufferLength. Applies to remux + transcode alike (both use copyts).
         const hls = new Hls({ maxBufferLength: 30, enableWorker: true, startPosition: 0 });
         hlsRef.current = hls;
+        // Measure the real delivered bitrate: bytes per second of MEDIA, per fragment. A new session
+        // is a new stream (different start offset, possibly a different audio rendition), so the
+        // rolling window starts empty rather than carrying the previous session's numbers over.
+        fragMeterRef.current.reset();
+        hls.on(Hls.Events.FRAG_LOADED, (_e, data) => {
+          fragMeterRef.current.add({
+            type: data.frag.type,
+            bytes: data.frag.stats?.total || data.frag.stats?.loaded || 0,
+            durationS: data.frag.duration,
+          });
+        });
         hls.loadSource(`${sess.url}?t=${Math.floor(startAt)}`);
         hls.attachMedia(video);
         // Subtitles are native <track>s (not muxed into the HLS), so nothing subtitle-related here.
@@ -361,6 +377,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     textSubs,
     selectedSub,
     subTrackOffset,
+    subShowable,
+    subFail,
+    subGen,
+    onSubTrackError,
   } = usePlexTracks({
     id,
     detail,
@@ -851,15 +871,17 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       >
         {/* Text subtitles as native tracks (same-origin → sent with the session cookie). The effect
             above flips modes; the browser fetches a track's VTT the first time it's shown. */}
-        {selectedSub && (
+        {selectedSub && subShowable && (
           <track
             // One track = the selected sub only (no multi-track overlap). Key by the shifted-offset so
-            // a seek-restart or a (debounced) sub-offset change remounts → fresh VTT fetch.
-            key={`${id}-${selectedSub.ord}-${subTrackOffset.toFixed(2)}`}
+            // a seek-restart or a (debounced) sub-offset change remounts → fresh VTT fetch, and by the
+            // extraction generation so a widened track replaces the first short window.
+            key={`${id}-${selectedSub.ord}-${subTrackOffset.toFixed(2)}-${subGen}`}
             kind="subtitles"
-            src={api.plexSubtitleUrl(id, selectedSub.ord, subTrackOffset)}
+            src={api.plexSubtitleUrl(id, selectedSub.ord, subTrackOffset, subGen)}
             srcLang={selectedSub.language ?? undefined}
             label={selectedSub.label}
+            onError={onSubTrackError}
             default
           />
         )}
@@ -894,6 +916,29 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         </div>
       )}
 
+      {/* Subtitle-extraction notice. Pulling a track out of a big MKV is a full read of the container
+          (154 s for a 17 GB film, measured), so it happens in the background — around the playhead
+          first. Until then the <track> is deliberately NOT mounted, and this says why instead of
+          leaving the viewer to conclude that switching subtitles "does nothing" (bug hunt 2026-09,
+          item 8). It sits one rung above the track-switch OSD so the two never overlap. */}
+      <div
+        className="pointer-events-none absolute inset-x-0 bottom-36 z-menu flex justify-center px-4"
+        aria-live="polite"
+      >
+        {selectedSub && !subShowable && (
+          <div className="flex max-w-full items-center gap-2 truncate rounded-full border border-white/15 bg-black/75 px-4 py-2 text-sm text-white shadow-2xl">
+            {subFail ? (
+              <span className="text-danger">{t(`plex.player.subUnavailable.${subFail}`)}</span>
+            ) : (
+              <>
+                <Loader2 className="h-4 w-4 shrink-0 animate-spin" aria-hidden />
+                <span>{t("plex.player.subPreparing", { label: selectedSub.label })}</span>
+              </>
+            )}
+          </div>
+        )}
+      </div>
+
       {/* Keyboard track-switch OSD. Sits ABOVE the control bar's own space so it reads even while the
           bar is showing, and inside the player element so it survives fullscreen. `aria-live` because
           the whole point is confirming something you cannot otherwise see.
@@ -1279,6 +1324,15 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         <PlexStatsOverlay
           videoRef={videoRef}
           hlsRef={hlsRef}
+          fragMeterRef={fragMeterRef}
+          audioLabel={
+            detail?.audio_streams.find((a) => a.ord === (audioOrd ?? 0))?.label ?? undefined
+          }
+          subLabel={
+            subOrd == null
+              ? t("plex.player.subOff")
+              : (detail?.subtitle_streams.find((x) => x.ord === subOrd)?.label ?? undefined)
+          }
           playable={detail?.playable ?? ""}
           hwRef={hwRef}
           tonemapRef={tonemapRef}
diff --git a/frontend/src/components/PlexStatsOverlay.tsx b/frontend/src/components/PlexStatsOverlay.tsx
index 5fdd1029..0cadd95f 100644
--- a/frontend/src/components/PlexStatsOverlay.tsx
+++ b/frontend/src/components/PlexStatsOverlay.tsx
@@ -2,7 +2,7 @@ import { type RefObject, useEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import type Hls from "hls.js";
 import { X } from "lucide-react";
-import { buildStatRows, type HlsLevelInfo, type StatRow } from "../lib/plexStats";
+import { buildStatRows, type FragMeter, type HlsLevelInfo, type StatRow } from "../lib/plexStats";
 
 // "Stats for nerds" debug overlay (E6 S2). Samples the live HTML5 <video> + hls.js state once a second
 // and renders the active mode, resolution, codec/bitrate, dropped frames, buffer, hls level and session
@@ -11,6 +11,9 @@ import { buildStatRows, type HlsLevelInfo, type StatRow } from "../lib/plexStats
 export function PlexStatsOverlay({
   videoRef,
   hlsRef,
+  fragMeterRef,
+  audioLabel,
+  subLabel,
   playable,
   hwRef,
   tonemapRef,
@@ -21,6 +24,11 @@ export function PlexStatsOverlay({
 }: {
   videoRef: RefObject<HTMLVideoElement | null>;
   hlsRef: RefObject<Hls | null>;
+  // Rolling FRAG_LOADED meter owned by the player (it lives as long as the hls.js instance, not as
+  // long as this panel) — the source of the MEASURED bitrate row.
+  fragMeterRef: RefObject<FragMeter>;
+  audioLabel?: string; // selected audio track label, as the tracks menu names it
+  subLabel?: string; // selected subtitle track label (or the menu's "Off" entry)
   playable: string;
   hwRef: RefObject<boolean | null>; // active transcode encoder: true=GPU, false=CPU, null=not transcode
   tonemapRef: RefObject<boolean | null>; // HW HDR→SDR tonemap engaged (adds a "· HDR→SDR" mode tag)
@@ -88,6 +96,9 @@ export function PlexStatsOverlay({
           totalFrames: total,
           bufferAheadS: bufferAhead,
           hlsLevel: level,
+          measuredBps: fragMeterRef.current?.bitrate(),
+          audioLabel,
+          subLabel,
           sessionStartS: sessionStartRef.current ?? 0,
           abs: absRef.current ?? 0,
           duration: durationRef.current ?? 0,
@@ -97,7 +108,19 @@ export function PlexStatsOverlay({
     sample();
     const iv = setInterval(sample, 1000);
     return () => clearInterval(iv);
-  }, [videoRef, hlsRef, playable, hwRef, tonemapRef, sessionStartRef, absRef, durationRef]);
+  }, [
+    videoRef,
+    hlsRef,
+    fragMeterRef,
+    audioLabel,
+    subLabel,
+    playable,
+    hwRef,
+    tonemapRef,
+    sessionStartRef,
+    absRef,
+    durationRef,
+  ]);
 
   return (
     <div
diff --git a/frontend/src/i18n/locales/en/plex.json b/frontend/src/i18n/locales/en/plex.json
index 5e8d4b04..12136fb0 100644
--- a/frontend/src/i18n/locales/en/plex.json
+++ b/frontend/src/i18n/locales/en/plex.json
@@ -200,6 +200,8 @@
       "codec": "Codec",
       "bitrate": "Bitrate",
       "level": "HLS level",
+      "audio": "Audio track",
+      "subtitle": "Subtitle track",
       "frames": "Dropped frames",
       "buffer": "Buffer ahead",
       "offset": "Session offset",
@@ -214,6 +216,12 @@
     "fineSeek": "Fine seek (Ctrl)",
     "autoHide": "Auto-hide controls",
     "subStyle": "Subtitles",
+    "subPreparing": "Preparing subtitles: {{label}}…",
+    "subUnavailable": {
+      "bitmap": "This subtitle is image-based and can't be shown as text.",
+      "missing": "This subtitle track isn't available.",
+      "failed": "This subtitle couldn't be loaded."
+    },
     "subSize": "Text size",
     "subPos": "Position",
     "subColor": "Text color",
diff --git a/frontend/src/i18n/locales/hu/plex.json b/frontend/src/i18n/locales/hu/plex.json
index e4d555f5..4edd3cde 100644
--- a/frontend/src/i18n/locales/hu/plex.json
+++ b/frontend/src/i18n/locales/hu/plex.json
@@ -200,6 +200,8 @@
       "codec": "Kodek",
       "bitrate": "Bitráta",
       "level": "HLS szint",
+      "audio": "Hangsáv",
+      "subtitle": "Feliratsáv",
       "frames": "Eldobott képkockák",
       "buffer": "Puffer előre",
       "offset": "Munkamenet-eltolás",
@@ -214,6 +216,12 @@
     "fineSeek": "Finom léptetés (Ctrl)",
     "autoHide": "Vezérlők elrejtése",
     "subStyle": "Feliratok",
+    "subPreparing": "Felirat előkészítése: {{label}}…",
+    "subUnavailable": {
+      "bitmap": "Ez a felirat képalapú, szövegként nem jeleníthető meg.",
+      "missing": "Ez a feliratsáv nem érhető el.",
+      "failed": "Ezt a feliratot nem sikerült betölteni."
+    },
     "subSize": "Szövegméret",
     "subPos": "Pozíció",
     "subColor": "Szövegszín",
diff --git a/frontend/src/lib/api/plex.ts b/frontend/src/lib/api/plex.ts
index 808cfde1..647d5333 100644
--- a/frontend/src/lib/api/plex.ts
+++ b/frontend/src/lib/api/plex.ts
@@ -633,8 +633,32 @@ export const plexApi = {
   // WebVTT URL for a text subtitle track (used directly as a <track src>). Same-origin → cookie-authed.
   // `offset` = the session's real media start (0 for direct-play); the backend shifts the absolute
   // cue times onto the HLS session's zero-based clock so subtitles line up with speech after a seek.
-  plexSubtitleUrl: (id: string, ord: number, offset = 0): string =>
-    `/api/plex/subtitle/${encodeURIComponent(id)}/${ord}${offset ? `?offset=${offset}` : ""}`,
+  // `gen` is the cached track's generation: extraction publishes a window around the playhead first
+  // and widens it in the background, so the URL has to change when it grows or the browser would keep
+  // serving the first, short VTT from its own cache.
+  plexSubtitleUrl: (id: string, ord: number, offset = 0, gen = 0): string => {
+    const p = new URLSearchParams();
+    if (offset) p.set("offset", String(offset));
+    if (gen) p.set("gen", String(gen));
+    const q = p.toString();
+    return `/api/plex/subtitle/${encodeURIComponent(id)}/${ord}${q ? `?${q}` : ""}`;
+  },
+  // Whether a subtitle track can be shown yet. Extracting one out of a big MKV costs a full read of
+  // the container (measured: 154 s for a 17 GB film), so the server does it in the background — around
+  // `at`, the viewer's position, first — and the player polls this instead of mounting a <track> that
+  // would sit empty for minutes. `partial` = a window around `at` is ready and still growing.
+  plexSubtitleStatus: (
+    id: string,
+    ord: number,
+    at = 0,
+  ): Promise<{
+    state: "ready" | "partial" | "preparing" | "failed";
+    code: string | null;
+    gen: number;
+  }> =>
+    req(
+      `/api/plex/subtitle/${encodeURIComponent(id)}/${ord}/status?at=${Math.max(0, Math.floor(at))}`,
+    ),
   // `final` marks a settled checkpoint (pause / page-hide / leaving the player) as opposed to the
   // periodic 10s tick — the backend mirrors the resume position to a linked Plex account only on a
   // final checkpoint, so a single watch doesn't spray Plex with timeline updates.
diff --git a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
new file mode 100644
index 00000000..6dc61625
--- /dev/null
+++ b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
@@ -0,0 +1,140 @@
+// @vitest-environment jsdom
+//
+// A subtitle <track> must not be mounted before the server has something to put in it.
+//
+// Bug hunt 2026-09, item 8: extracting one track out of a big MKV is a full read of the container
+// (154 s for a 17 GB film, measured on prod), and it used to happen inside the <track>'s own
+// request. The browser gives a <track> no visible state, so the player showed nothing at all —
+// which reads as "switching subtitles does nothing", and the reported workaround was to stop/start
+// until the cache happened to be warm. The extraction now runs in the background, publishing a
+// window around the playhead first, and this hook's poll is what decides when there is something to
+// mount and what to say while there isn't.
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createRef, type ReactNode, type MutableRefObject } from "react";
+import { usePlexTracks } from "./plexPlayerHooks";
+import { api, type PlexItemDetail } from "./api";
+import type Hls from "hls.js";
+
+const RK = "98614";
+
+const detail = (): PlexItemDetail =>
+  ({
+    id: RK,
+    duration_seconds: 8580,
+    audio_streams: [{ ord: 0, label: "Magyar AC3 5.1", language: "hu", default: true }],
+    subtitle_streams: [
+      { ord: 0, label: "Magyar", language: "hu", text: true },
+      { ord: 1, label: "English", language: "en", text: true },
+    ],
+    markers: [],
+  }) as unknown as PlexItemDetail;
+
+function mount(qc: QueryClient) {
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+  );
+  return renderHook(
+    () =>
+      usePlexTracks({
+        id: RK,
+        detail: detail(),
+        sessionK: 0,
+        subOffset: 0,
+        subPos: 88,
+        loadSession: async () => {},
+        patchPrefs: () => {},
+        videoRef: createRef<HTMLVideoElement>(),
+        hlsRef: createRef<Hls>(),
+        multiAudioRef: { current: false },
+        audioRef: { current: 0 } as MutableRefObject<number | null>,
+        aoffRef: { current: 0 },
+        absRef: { current: 3600 },
+      }),
+    { wrapper },
+  );
+}
+
+const client = () => new QueryClient({ defaultOptions: { queries: { retry: false, gcTime: 0 } } });
+
+describe("usePlexTracks — the <track> waits for the extraction", () => {
+  // vitest runs with globals off, so testing-library's auto-cleanup never registers: unmount by
+  // hand or the hook's 250 ms sub-offset debounce fires into a torn-down environment.
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  it("is not showable while the track is still being extracted", async () => {
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
+      state: "preparing",
+      code: null,
+      gen: 0,
+    });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(api.plexSubtitleStatus).toHaveBeenCalled());
+    await waitFor(() => expect(result.current.selectedSub?.ord).toBe(0));
+    // The selected track exists and is offered in the picker — it just cannot be rendered yet, and
+    // the caller must be told so rather than mounting an empty <track>.
+    expect(result.current.subShowable).toBe(false);
+    expect(result.current.subFail).toBeNull();
+  });
+
+  it("sends the viewer's position, so the extraction windows around where they are", async () => {
+    const status = vi
+      .spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValue({ state: "preparing", code: null, gen: 0 });
+    const { result } = mount(client());
+    result.current.setSubOrd(1);
+    await waitFor(() => expect(status).toHaveBeenCalledWith(RK, 1, 3600));
+  });
+
+  it("becomes showable on a PARTIAL track — a window around the playhead is what is needed now", async () => {
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
+      state: "partial",
+      code: null,
+      gen: 1757500000000000000,
+    });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subShowable).toBe(true));
+    // The generation goes into the <track> key/URL: without it the browser would keep serving the
+    // first, short window from its own cache once the background pass widens the track.
+    expect(result.current.subGen).toBe(1757500000000000000);
+  });
+
+  it("reports a track that can never be shown, in the bucket the player has a sentence for", async () => {
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
+      state: "failed",
+      code: "bitmap",
+      gen: 0,
+    });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subFail).toBe("bitmap"));
+    expect(result.current.subShowable).toBe(false);
+  });
+
+  it("folds the server's finer failure codes into 'missing'", async () => {
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
+      state: "failed",
+      code: "no_file",
+      gen: 0,
+    });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subFail).toBe("missing"));
+  });
+
+  it("asks nothing at all while subtitles are off", async () => {
+    const status = vi
+      .spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValue({ state: "ready", code: null, gen: 1 });
+    const { result } = mount(client());
+    await waitFor(() => expect(result.current.textSubs).toHaveLength(2));
+    expect(status).not.toHaveBeenCalled();
+    expect(result.current.subShowable).toBe(false);
+  });
+});
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index e7146a9a..e6700d43 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -7,7 +7,7 @@ import {
   type RefObject,
   type WheelEvent as ReactWheelEvent,
 } from "react";
-import type { QueryClient } from "@tanstack/react-query";
+import { useQuery, useQueryClient, type QueryClient } from "@tanstack/react-query";
 import Hls from "hls.js";
 import {
   exitFullscreen,
@@ -344,6 +344,18 @@ export function useAutoSkip(opts: {
 // stream) or client-side via hls.js (multi-rendition), while subtitle switches just flip the single
 // mounted <track>. The shared media refs (video/hls/audio/aoff/abs/multiAudio) are owned by the
 // component and passed in so this hook and the media session read/write the same substrate.
+/** Why a subtitle track can't be shown, in the three buckets the player has a sentence for. The
+ *  server's codes are finer-grained than that on purpose (they drive the HTTP status too), so the
+ *  fold happens here rather than multiplying near-identical translations. */
+export type SubFailReason = "bitmap" | "missing" | "failed";
+
+function subFailReason(code: string | null | undefined): SubFailReason {
+  if (code === "bitmap") return "bitmap";
+  if (code === "no_item" || code === "no_track" || code === "no_file" || code === "not_fetchable")
+    return "missing";
+  return "failed";
+}
+
 export function usePlexTracks(opts: {
   id: string;
   detail: PlexItemDetail | undefined;
@@ -374,9 +386,19 @@ export function usePlexTracks(opts: {
   textSubs: PlexItemDetail["subtitle_streams"];
   selectedSub: PlexItemDetail["subtitle_streams"][number] | null;
   subTrackOffset: number;
+  /** The selected track has something to render (a window around the playhead, or the whole thing).
+   *  False means "not yet" — the caller must NOT mount a <track>, it would just sit blank. */
+  subShowable: boolean;
+  /** The selected track can never be shown, bucketed for the message the player puts on screen. */
+  subFail: SubFailReason | null;
+  /** The cached VTT's generation — it grows as the background extraction widens the track, so it
+   *  belongs in the <track> key/URL or the browser keeps serving the first, short window. */
+  subGen: number;
+  onSubTrackError: () => void;
 } {
   const { id, detail, sessionK, subOffset, subPos, loadSession, patchPrefs } = opts;
   const { videoRef, hlsRef, multiAudioRef, audioRef, aoffRef, absRef } = opts;
+  const qc = useQueryClient();
   // Selected audio / subtitle stream ordinals (null audio = default first; null subtitle = off).
   const [audioOrd, setAudioOrd] = useState<number | null>(null);
   const [subOrd, setSubOrd] = useState<number | null>(null);
@@ -455,6 +477,46 @@ export function usePlexTracks(opts: {
     [patchPrefs, loadSession, aoffRef, absRef],
   );
 
+  // --- is the selected track actually extractable yet? -------------------------------------------
+  // Pulling one subtitle track out of a big MKV means ffmpeg streams the whole container: measured on
+  // prod at 154 s for a 17 GB film (and the same again for the second track). That used to happen
+  // INSIDE the <track>'s own request, so the browser sat on an empty track with no spinner, no retry
+  // and no error — the "switch the track, nothing happens, stop/start a few times and eventually it
+  // works" report (bug hunt 2026-09, item 8). The server now extracts in the background, a window
+  // around the playhead first, and this poll is what tells us when there is something to mount.
+  const subStatusQ = useQuery({
+    queryKey: qk.plexSubtitle(id, subOrd ?? -1),
+    queryFn: () => api.plexSubtitleStatus(id, subOrd as number, absRef.current ?? 0),
+    enabled: subOrd != null,
+    // Keep polling until the track is COMPLETE, not just showable: each poll carries the current
+    // position, so seeking past the extracted window is what asks for the next one. A settled
+    // answer — the whole track, or a reason it can never be shown — stops the poll; without that
+    // stop, a bitmap track would poll for the length of the film AND keep re-arming the extraction
+    // every time the server's short failure memo expired.
+    refetchInterval: (q) => {
+      const st = q.state.data?.state;
+      if (st === "ready" || st === "failed") return false;
+      return st === "partial" ? 2000 : 1000;
+    },
+    staleTime: 0,
+    retry: false,
+  });
+  const subStatus = subOrd == null ? null : (subStatusQ.data ?? null);
+  // Mount the <track> for a `partial` track too: a window around the playhead is exactly what the
+  // viewer needs right now, and the poll widens it underneath them.
+  const subShowable = subStatus?.state === "ready" || subStatus?.state === "partial";
+  const subFail: SubFailReason | null =
+    subStatusQ.isError && subOrd != null
+      ? "failed"
+      : subStatus?.state === "failed"
+        ? subFailReason(subStatus.code)
+        : null;
+  // A <track> that errors anyway (the cached VTT was evicted between the poll and the fetch) goes
+  // back to polling rather than staying silently blank.
+  const onSubTrackError = useCallback(() => {
+    if (subOrd != null) qc.invalidateQueries({ queryKey: qk.plexSubtitle(id, subOrd) });
+  }, [qc, id, subOrd]);
+
   // Text subtitles offered in the picker; image subs (PGS/VobSub) can't be shown as text.
   const textSubs = (detail?.subtitle_streams ?? []).filter((s) => s.text);
   // Render ONLY the selected sub as a single <track> (below) — rendering all of them and flipping
@@ -521,5 +583,9 @@ export function usePlexTracks(opts: {
     textSubs,
     selectedSub,
     subTrackOffset,
+    subShowable,
+    subFail,
+    subGen: subStatus?.gen ?? 0,
+    onSubTrackError,
   };
 }
diff --git a/frontend/src/lib/plexStats.test.ts b/frontend/src/lib/plexStats.test.ts
index 985d1deb..8455134c 100644
--- a/frontend/src/lib/plexStats.test.ts
+++ b/frontend/src/lib/plexStats.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 import {
   buildStatRows,
+  createFragMeter,
   fmtBitrate,
   fmtBufferSecs,
   fmtClock,
@@ -89,6 +90,8 @@ describe("buildStatRows", () => {
       "codec",
       "bitrate",
       "level",
+      "audio",
+      "subtitle",
       "frames",
       "buffer",
       "offset",
@@ -144,3 +147,96 @@ describe("fmtMode", () => {
     expect(fmtMode("transcode", null, true)).toBe("transcode"); // no encoder → no tag either
   });
 });
+
+// --- item 12 of the 2026-09 bug hunt ------------------------------------------------------------
+//
+// The panel reported "Bitrate: 211 kbps" on EVERY remux, which the viewer rightly refused to
+// believe. It was reading the master playlist's BANDWIDTH, and for a remux ffmpeg computes that from
+// the only stream whose rate it knows — the `-b:a 192k` AAC track — plus 10%: 192000 × 1.1 = 211200,
+// a constant that has nothing to do with the video. And the panel never said which audio or subtitle
+// track was playing, though the player has switched both since E5.
+
+describe("measured bitrate", () => {
+  it("reports bytes per second of MEDIA, not of wall clock", () => {
+    const m = createFragMeter();
+    // A 6 s remux segment of 6 MB is 8 Mbps, however fast it happened to download.
+    m.add({ type: "main", bytes: 6_000_000, durationS: 6 });
+    expect(m.bitrate()).toBe(8_000_000);
+  });
+
+  it("adds the audio rendition's rate instead of averaging it away", () => {
+    // Multi-audio sessions ship audio as its own rendition, so both fragment types cover the SAME
+    // media seconds. Pooling bytes over pooled durations would report half the real bitrate.
+    const m = createFragMeter();
+    m.add({ type: "main", bytes: 6_000_000, durationS: 6 });
+    m.add({ type: "audio", bytes: 150_000, durationS: 6 });
+    expect(m.bitrate()).toBe(8_000_000 + 200_000);
+  });
+
+  it("has nothing to say before the first fragment, and after a reset", () => {
+    const m = createFragMeter();
+    expect(m.bitrate()).toBeUndefined(); // an honest dash — never the manifest's stand-in number
+    m.add({ type: "main", bytes: 6_000_000, durationS: 6 });
+    m.reset();
+    expect(m.bitrate()).toBeUndefined();
+  });
+
+  it("ignores init segments and anything with no media duration", () => {
+    const m = createFragMeter();
+    m.add({ type: "main", bytes: 900, durationS: 0 });
+    m.add({ type: "main", bytes: 0, durationS: 6 });
+    expect(m.bitrate()).toBeUndefined();
+  });
+
+  it("follows the stream: old fragments fall out of the rolling window", () => {
+    const m = createFragMeter(2);
+    m.add({ type: "main", bytes: 60_000_000, durationS: 6 }); // a dense scene
+    m.add({ type: "main", bytes: 3_000_000, durationS: 6 });
+    m.add({ type: "main", bytes: 3_000_000, durationS: 6 });
+    expect(m.bitrate()).toBe(4_000_000); // the 80 Mbps sample is gone, not still weighing it down
+  });
+});
+
+describe("buildStatRows — what is actually playing", () => {
+  const hls = (over: Partial<PlexStatsInput> = {}): PlexStatsInput => ({
+    playable: "remux",
+    transport: "hls",
+    videoWidth: 1920,
+    videoHeight: 1080,
+    droppedFrames: 6,
+    totalFrames: 1458,
+    bufferAheadS: 12,
+    hlsLevel: { index: 0, total: 1, bitrate: 211_200 },
+    sessionStartS: 0,
+    abs: 10,
+    duration: 8580,
+    ...over,
+  });
+  const value = (rows: { key: string; value: string }[], key: string) =>
+    rows.find((r) => r.key === key)?.value;
+
+  it("shows the MEASURED bitrate and never the manifest's 211 kbps stand-in", () => {
+    const rows = buildStatRows(hls({ measuredBps: 7_900_000 }));
+    expect(value(rows, "bitrate")).toBe("7.9 Mbps");
+  });
+
+  it("dashes the bitrate until something has been measured", () => {
+    // The level still carries its 211200 BANDWIDTH here — using it would be the old bug.
+    expect(value(buildStatRows(hls()), "bitrate")).toBe(DASH);
+  });
+
+  it("names the selected audio and subtitle track", () => {
+    const rows = buildStatRows(hls({ audioLabel: "Magyar AC3 5.1", subLabel: "Magyar" }));
+    expect(value(rows, "audio")).toBe("Magyar AC3 5.1");
+    expect(value(rows, "subtitle")).toBe("Magyar");
+  });
+
+  it("keeps the track rows for direct play too, where there is no HLS level at all", () => {
+    const rows = buildStatRows(
+      hls({ transport: "direct", hlsLevel: null, audioLabel: "English", subLabel: "Off" }),
+    );
+    expect(rows.some((r) => r.key === "bitrate")).toBe(false); // HLS-only, as before
+    expect(value(rows, "audio")).toBe("English");
+    expect(value(rows, "subtitle")).toBe("Off");
+  });
+});
diff --git a/frontend/src/lib/plexStats.ts b/frontend/src/lib/plexStats.ts
index 53f5f1ea..6a59705e 100644
--- a/frontend/src/lib/plexStats.ts
+++ b/frontend/src/lib/plexStats.ts
@@ -21,6 +21,14 @@ export interface PlexStatsInput {
   totalFrames: number; // getVideoPlaybackQuality().totalVideoFrames
   bufferAheadS: number; // seconds buffered ahead of the playhead
   hlsLevel: HlsLevelInfo | null; // null for direct play / Safari-native HLS
+  // MEASURED stream bitrate: bytes actually delivered per second of media, from hls.js's per-fragment
+  // load stats. Undefined until the first fragment lands (an honest dash — never a stand-in number).
+  // This row used to read the master playlist's BANDWIDTH, which for a remux session ffmpeg derives
+  // from the one thing it knows, the `-b:a 192k` AAC track, plus 10%: a constant 211 kbps on every
+  // remux regardless of the actual video. That is what the viewer correctly refused to believe.
+  measuredBps?: number;
+  audioLabel?: string; // the selected audio track, as the tracks menu names it
+  subLabel?: string; // the selected subtitle track (or the menu's "Off" entry)
   sessionStartS: number; // media-clock offset the current session was opened at
   abs: number; // current media time (absolute, session offset already folded in)
   duration: number;
@@ -138,12 +146,16 @@ export function buildStatRows(s: PlexStatsInput): StatRow[] {
       {
         key: "bitrate",
         labelKey: "plex.player.stats.bitrate",
-        value: fmtBitrate(s.hlsLevel?.bitrate),
+        value: fmtBitrate(s.measuredBps),
       },
       { key: "level", labelKey: "plex.player.stats.level", value: fmtLevel(s.hlsLevel) },
     );
   }
   rows.push(
+    // Which audio/subtitle track is actually playing. The player has switched both since E5 and the
+    // panel never said which one you landed on — the one question "stats for nerds" was being asked.
+    { key: "audio", labelKey: "plex.player.stats.audio", value: s.audioLabel || DASH },
+    { key: "subtitle", labelKey: "plex.player.stats.subtitle", value: s.subLabel || DASH },
     {
       key: "frames",
       labelKey: "plex.player.stats.frames",
@@ -159,3 +171,49 @@ export function buildStatRows(s: PlexStatsInput): StatRow[] {
   );
   return rows;
 }
+
+// --- measured bitrate ---------------------------------------------------------------------------
+
+interface FragSample {
+  type: string; // hls.js fragment type: "main" (video, and muxed audio) / "audio" / "subtitle"
+  bytes: number;
+  durationS: number; // MEDIA seconds the fragment carries (not how long it took to download)
+}
+
+export interface FragMeter {
+  add(sample: FragSample): void;
+  /** Bits per second of media, or undefined while nothing has been measured yet. */
+  bitrate(): number | undefined;
+  reset(): void;
+}
+
+/** Rolling meter over hls.js FRAG_LOADED stats: bytes delivered per second of MEDIA, which is the
+ *  stream's real bitrate — as opposed to download throughput, which only measures the network.
+ *
+ *  Kept per fragment TYPE and summed: in a multi-audio session the audio ships as its own rendition,
+ *  so video and audio fragments cover the SAME media seconds. Pooling their bytes over the pooled
+ *  durations would report half the truth; per-type rates add up to the whole. */
+export function createFragMeter(window = 10): FragMeter {
+  const byType = new Map<string, FragSample[]>();
+  return {
+    add(sample) {
+      if (!(sample.bytes > 0) || !(sample.durationS > 0)) return; // pre-roll / init segments
+      const list = byType.get(sample.type) ?? [];
+      list.push(sample);
+      if (list.length > window) list.shift();
+      byType.set(sample.type, list);
+    },
+    bitrate() {
+      let total = 0;
+      for (const list of byType.values()) {
+        const bytes = list.reduce((n, f) => n + f.bytes, 0);
+        const secs = list.reduce((n, f) => n + f.durationS, 0);
+        if (secs > 0) total += (bytes * 8) / secs;
+      }
+      return total > 0 ? total : undefined;
+    },
+    reset() {
+      byType.clear();
+    },
+  };
+}
diff --git a/frontend/src/lib/queryKeys.ts b/frontend/src/lib/queryKeys.ts
index 6bb7bbae..423f9743 100644
--- a/frontend/src/lib/queryKeys.ts
+++ b/frontend/src/lib/queryKeys.ts
@@ -128,6 +128,9 @@ export const qk = {
       ? (["plex-show", showId, ...(lang ? [lang] : [])] as const)
       : (["plex-show"] as const),
   plexItem: (id: string, lang?: string) => ["plex-item", id, ...(lang ? [lang] : [])] as const,
+  // Extraction state of one subtitle track. Not keyed by the playhead: the position is an argument
+  // that steers the background extraction, not part of the track's identity.
+  plexSubtitle: (id: string, ord: number) => ["plex-subtitle", id, ord] as const,
   plexPlaylists: (...rest: unknown[]) => ["plex-playlists", ...rest],
   plexPlaylist: (playlistId: number) => ["plex-playlist", playlistId] as const,
   plexCollections: (...rest: unknown[]) => ["plex-collections", ...rest],

From 5a42d76e8a2204c3befccfc275026d9587e170ea Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Thu, 10 Sep 2026 20:02:06 +0200
Subject: [PATCH 04/52] feat(plex): an off-by-default loudness normalisation
 toggle for playback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bug hunt 2026-09, item 14 — "how does the multichannel downmix work, and is it
normalised?" It isn't: `plex/stream.py` has always encoded `-c:a aac -ac 2 -b:a
192k`, i.e. fixed stereo with ffmpeg's default downmix matrix and no loudness
handling at all, which is why a film mastered for a cinema arrives with whispered
dialogue and deafening action.

New admin knob `plex_audio_loudnorm` (Configuration → Plex), DEFAULT OFF: it makes
a film markedly louder and narrows its dynamic range, which is a taste call rather
than a fix. It sits at the end of the Plex group, after the software-transcode
knobs — it is an audio concern, not one of the libx264 ones.

  -af aformat=channel_layouts=stereo,loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000

Three things about that chain are load-bearing and each has a test:

  * the downmix is FORCED FIRST rather than left to `-ac 2` — measuring 5.1 and
    folding it down afterwards would normalise something other than what is heard;
  * the trailing resample is not decoration: `loudnorm` runs its own resampler at
    192 kHz internally, which the AAC encoder will not take;
  * one `-af`, no stream index, so EVERY audio rendition of a multi-audio file is
    normalised — not just the first.

The knob is also part of the session directory name (`…_multi-ln_+0.00`), because
it changes the audio the segments contain, and a session left over from before the
admin flipped it must not be mistaken for one that honours it. The suffix is
appended with a DASH: `_SESSION_DIR_RE` treats the tag as one underscore-free
field, and that regex is the only thing keeping the orphan sweep off what may be a
shared scratch path. A test pins both halves — the name changes, and the sweep
still recognises it.

Measured end-to-end on the app's own HLS segments (a real 5.1 AC3 file, same item,
same 160 s offset, same ten segments): OFF -35.2 LUFS, ON -17.2 LUFS. On a 60 s
bench: I -27.6 → -16.6 LUFS with LRA 13.3 → 9.8 LU. A/V sync is untouched — under
this pipeline's own `-copyts` the audio start PTS is identical with and without the
filter, so the 3 s lookahead desyncs nothing.

Direct-played files are served untouched and stay so; a 5.1 mix is always `remux`,
so the reported case is fully covered.
---
 backend/app/config.py                    |  5 ++
 backend/app/plex/stream.py               | 41 ++++++++++++-
 backend/app/sysconfig.py                 |  2 +
 backend/tests/test_plex_stream.py        | 77 ++++++++++++++++++++++++
 frontend/src/i18n/locales/en/config.json |  4 ++
 frontend/src/i18n/locales/hu/config.json |  4 ++
 6 files changed, 130 insertions(+), 3 deletions(-)

diff --git a/backend/app/config.py b/backend/app/config.py
index 62acd26e..ad8d13ea 100644
--- a/backend/app/config.py
+++ b/backend/app/config.py
@@ -271,6 +271,11 @@ class Settings(BaseSettings):
     # trades quality for size (lower = better + bigger). `max_height` caps the SOFTWARE transcode's output
     # height (0 = keep source) so a CPU re-encode of a tall source stays affordable — the GPU path always
     # encodes at source resolution.
+    # Loudness normalisation of the downmixed stereo audio on the HLS path (EBU R128 `loudnorm`).
+    # OFF by default: it makes a film ~11 dB louder and narrows its dynamic range, which is a taste
+    # call, not a fix. Only affects files that go through remux/transcode — a direct-played file is
+    # served untouched, but those are browser-native stereo anyway, not the 5.1 mixes this is for.
+    plex_audio_loudnorm: bool = False
     plex_transcode_preset: str = "veryfast"
     plex_transcode_crf: int = 20
     plex_transcode_max_height: int = 1080
diff --git a/backend/app/plex/stream.py b/backend/app/plex/stream.py
index e3053176..3a18f9d3 100644
--- a/backend/app/plex/stream.py
+++ b/backend/app/plex/stream.py
@@ -271,6 +271,30 @@ def _hwaccel_in_opts(hw: bool, tonemap: bool = False) -> list[str]:
     return ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi", "-vaapi_device", _VAAPI_DEVICE]
 
 
+# Audio is ALWAYS re-encoded on the HLS path: the source is typically AC3/DTS 5.1, which no browser
+# plays, so it is downmixed to stereo AAC. `-ac 2` uses ffmpeg's standard downmix matrix; nothing is
+# normalised, which is why a film mastered for a cinema arrives with whispered dialogue and deafening
+# action (bug hunt 2026-09, item 14).
+_AUDIO_ENC = ["-c:a", "aac", "-ac", "2", "-b:a", "192k"]
+# Optional loudness normalisation (admin knob `plex_audio_loudnorm`, default OFF). EBU R128 single-pass
+# `loudnorm` — two-pass is impossible here, since a seek-restart session must start emitting segments
+# immediately and cannot analyse the file first.
+#
+# The downmix is FORCED FIRST (`aformat=channel_layouts=stereo`) rather than left to `-ac 2`: measuring
+# 5.1 and then folding it down would normalise something other than what the viewer hears. `loudnorm`
+# runs its own resampler at 192 kHz internally, so the chain resamples back to 48 kHz for the AAC
+# encoder. Measured on a real 5.1 AC3 film (Westworld S1E6, 60 s from 15:00): I -27.6 → -16.6 LUFS,
+# LRA 13.3 → 9.8 LU — the quiet/loud gap narrows, and everything gets ~11 dB louder, so expect to turn
+# the volume down after switching this on. The filter's 3 s lookahead does NOT desync A/V: measured
+# under this pipeline's own `-copyts`, the audio start PTS is identical with and without it.
+_LOUDNORM_AF = "aformat=channel_layouts=stereo,loudnorm=I=-16:TP=-1.5:LRA=11,aresample=48000"
+
+
+def _aenc_opts(loudnorm: bool) -> list[str]:
+    """Audio encoder args for one output, with the normalisation filter when the admin enabled it."""
+    return [*_AUDIO_ENC, *(["-af", _LOUDNORM_AF] if loudnorm else [])]
+
+
 def _venc_opts(
     transcode: bool,
     hw: bool,
@@ -446,6 +470,7 @@ def _ffmpeg_cmd(
     preset: str = "veryfast",
     crf: int = 20,
     max_height: int = 0,
+    loudnorm: bool = False,
 ) -> list[str]:
     # For a transcode session the video is re-encoded (VAAPI or libx264) instead of stream-copied; the
     # hwaccel decode options go before -i, the encoder args replace `-c:v copy` below. Everything else is
@@ -473,7 +498,8 @@ def _ffmpeg_cmd(
         args += ["-map", "0:v:0"]
         for i in range(len(audio_langs)):
             args += ["-map", f"{ai}:a:{i}?"]
-        args += ["-sn", *venc, "-c:a", "aac", "-ac", "2", "-b:a", "192k"]
+        # One `-af` covers EVERY audio output of this file, so each rendition is normalised.
+        args += ["-sn", *venc, *_aenc_opts(loudnorm)]
         var = ["v:0,agroup:aud"]
         for i, lang in enumerate(audio_langs):
             entry = f"a:{i},agroup:aud,name:a{i}"
@@ -494,7 +520,7 @@ def _ffmpeg_cmd(
     else:
         ao = audio_ord if audio_ord is not None else 0
         args += ["-map", "0:v:0", "-map", f"{ai}:a:{ao}?", "-sn"]
-        args += [*venc, "-c:a", "aac", "-ac", "2", "-b:a", "192k"]
+        args += [*venc, *_aenc_opts(loudnorm)]
         args += _HLS_TAIL + [
             "-hls_segment_filename",
             str(out_dir / "seg_%d.ts"),
@@ -579,11 +605,19 @@ def start_session(
     src = paths.local_media_path(db, item.file_path)
     if src is None:
         return None
+    # Read once, here: the knob has to be identical for the directory name and the ffmpeg argv, and a
+    # session respawn (the HW->SW fallback) must not pick up a mid-playback config change.
+    loudnorm = sysconfig.get_bool(db, "plex_audio_loudnorm")
     key = item.rating_key
     start_s = max(0.0, float(start_s))
     audio_langs = _probe_audio_langs(src) if multi else []
     is_multi = len(audio_langs) > 1  # only worth a master playlist when there really are ≥2 tracks
-    tag = "multi" if is_multi else str(audio_ord)
+    # Loudness normalisation changes the AUDIO THE SEGMENTS CONTAIN, so it belongs in the directory
+    # name beside the other parameters that do (offset, audio track, A/V offset): a session left over
+    # from before the admin flipped the knob must not be mistaken for one that honours it. Appended to
+    # the tag with a DASH — `_SESSION_DIR_RE` treats the tag as one underscore-free field, and that
+    # regex is the only thing keeping the orphan sweep off a shared scratch path (see its comment).
+    tag = ("multi" if is_multi else str(audio_ord)) + ("-ln" if loudnorm else "")
     directory = _HLS_ROOT / f"{key}_{int(start_s)}_{tag}_{aoff:+.2f}"
 
     def _seg(i: int) -> Path:
@@ -632,6 +666,7 @@ def start_session(
                     preset=preset,
                     crf=crf,
                     max_height=max_height,
+                    loudnorm=loudnorm,
                 ),
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
diff --git a/backend/app/sysconfig.py b/backend/app/sysconfig.py
index 1fa7802f..5ade8ac2 100644
--- a/backend/app/sysconfig.py
+++ b/backend/app/sysconfig.py
@@ -167,6 +167,8 @@ SPECS: tuple[ConfigSpec, ...] = (
     ConfigSpec(
         "plex_transcode_max_height", "int", "plex", "plex_transcode_max_height", min=0, max=4320
     ),
+    # Audio loudness normalisation on the HLS path (remux + transcode alike, not direct play).
+    ConfigSpec("plex_audio_loudnorm", "bool", "plex", "plex_audio_loudnorm"),
     # NOTE: plex_watch_sync_interval_min is a config.py default read by the watch-sync scheduler job
     # (scheduler.py); it is intentionally NOT a runtime admin knob, so it stays out of SPECS.
     # --- TMDB enrichment (E5 S2; optional) — the API key is the only secret ---
diff --git a/backend/tests/test_plex_stream.py b/backend/tests/test_plex_stream.py
index 39be017f..5c354d9b 100644
--- a/backend/tests/test_plex_stream.py
+++ b/backend/tests/test_plex_stream.py
@@ -483,6 +483,7 @@ class TestColdStartWarmup:
         src.write_bytes(b"x")
         monkeypatch.setattr(stream.paths, "local_media_path", lambda db, fp: src)
         monkeypatch.setattr(stream.sysconfig, "get_int", lambda db, k: 2)
+        monkeypatch.setattr(stream.sysconfig, "get_bool", lambda db, k: False)
         monkeypatch.setattr(stream.subprocess, "Popen", lambda *a, **k: _FakeProc())
         return tmp_path
 
@@ -554,6 +555,12 @@ class TestTranscodeStartSession:
             "get_str",
             lambda db, k: {"plex_transcode_preset": "slow"}.get(k, "auto"),
         )
+        # Loudness normalisation (item 14) is off unless a test turns it on via `stream._loudnorm_on`.
+        monkeypatch.setattr(
+            stream.sysconfig,
+            "get_bool",
+            lambda db, k: {"plex_audio_loudnorm": getattr(stream, "_loudnorm_on", False)}[k],
+        )
         monkeypatch.setattr(stream, "wait_for", lambda path, timeout=20.0, proc=None: True)
         _CapturingProc.calls = []
         monkeypatch.setattr(stream.subprocess, "Popen", _CapturingProc)
@@ -868,3 +875,73 @@ class TestWaitForProcFastFail:
         seg = tmp_path / "seg_0.ts"
         seg.write_bytes(b"")
         assert stream.wait_for(seg, timeout=30.0, proc=self._DeadProc()) is False
+
+
+class TestAudioLoudnorm:
+    """`plex_audio_loudnorm` (bug hunt 2026-09, item 14): the HLS path always downmixes 5.1 to stereo
+    AAC and never normalised it, so a cinema mix arrives with whispered dialogue and deafening action.
+    The knob is OFF by default — it makes a film ~11 dB louder and narrows its dynamic range, which is
+    a taste call. Measured on a real 5.1 AC3 film: I -27.6 -> -16.6 LUFS, LRA 13.3 -> 9.8 LU.
+
+    Reuses TestTranscodeStartSession's capturing fixture: what matters is the argv ffmpeg is actually
+    spawned with, not `_ffmpeg_cmd` called with literals."""
+
+    capturing_env = TestTranscodeStartSession.capturing_env
+
+    @staticmethod
+    def _spawn(monkeypatch, *, on: bool, multi: bool = False):
+        monkeypatch.setattr(stream, "_loudnorm_on", on, raising=False)
+        monkeypatch.setattr(
+            stream, "_select_encode", lambda db, item, transcode, src: (False, False)
+        )
+        if multi:
+            monkeypatch.setattr(stream, "_probe_audio_langs", lambda src: ["hun", "eng"])
+        s = stream.start_session(db=None, item=_FakeItem(), start_s=0.0, multi=multi)
+        assert s is not None
+        (cmd, *_), _ = _CapturingProc.calls[0]
+        return s, cmd
+
+    def test_the_knob_off_leaves_the_audio_exactly_as_it_was(self, capturing_env, monkeypatch):
+        _, cmd = self._spawn(monkeypatch, on=False)
+        assert "-af" not in cmd
+        assert cmd[cmd.index("-c:a") + 1] == "aac" and cmd[cmd.index("-ac") + 1] == "2"
+
+    def test_the_knob_on_normalises_AFTER_the_downmix(self, capturing_env, monkeypatch):
+        # Order is the whole point: measuring 5.1 and folding it down afterwards would normalise
+        # something other than what the viewer hears.
+        _, cmd = self._spawn(monkeypatch, on=True)
+        af = cmd[cmd.index("-af") + 1]
+        stages = af.split(",")
+        assert stages[0] == "aformat=channel_layouts=stereo"
+        assert stages[1].startswith("loudnorm=")
+        # loudnorm runs its own 192 kHz resampler internally; the AAC encoder needs 48 kHz back.
+        assert stages[-1] == "aresample=48000"
+
+    def test_every_audio_rendition_of_a_multi_audio_file_is_normalised(
+        self, capturing_env, monkeypatch
+    ):
+        # A multi-audio session emits one AAC output per language. `-af` without a stream index
+        # covers all of them — a per-stream filter would have normalised only the first.
+        _, cmd = self._spawn(monkeypatch, on=True, multi=True)
+        assert cmd.count("-map") == 3  # video + two audio tracks
+        assert cmd.count("-af") == 1
+        assert "loudnorm=" in cmd[cmd.index("-af") + 1]
+
+    def test_the_session_directory_records_the_setting(self, capturing_env, monkeypatch):
+        # The knob changes the AUDIO THE SEGMENTS CONTAIN, so it belongs in the directory name with
+        # the other parameters that do. Otherwise a session left from before the flip is reused.
+        off, _ = self._spawn(monkeypatch, on=False)
+        _CapturingProc.calls = []
+        on, _ = self._spawn(monkeypatch, on=True)
+        assert off.dir.name != on.dir.name
+        assert on.dir.name.endswith("-ln_+0.00")
+
+    @pytest.mark.parametrize("on", [False, True])
+    def test_the_orphan_sweep_still_recognises_its_own_directory(
+        self, capturing_env, monkeypatch, on
+    ):
+        # The tag is appended with a DASH, not an underscore, precisely so `_SESSION_DIR_RE` (the only
+        # thing keeping the sweep off a shared scratch path) still matches. A session directory the
+        # sweep no longer recognises is one that never gets cleaned up.
+        s, _ = self._spawn(monkeypatch, on=on)
+        assert _SESSION_DIR_RE.match(s.dir.name)
diff --git a/frontend/src/i18n/locales/en/config.json b/frontend/src/i18n/locales/en/config.json
index 0bed3713..60d56bcf 100644
--- a/frontend/src/i18n/locales/en/config.json
+++ b/frontend/src/i18n/locales/en/config.json
@@ -183,6 +183,10 @@
     "plex_transcode_max_height": {
       "label": "Software max height",
       "hint": "Cap the software transcode's output height in pixels (e.g. 1080; 0 = keep source) so a tall source stays affordable to re-encode. The GPU path keeps source resolution."
+    },
+    "plex_audio_loudnorm": {
+      "label": "Normalize audio loudness",
+      "hint": "EBU R128 loudness normalization of the stereo downmix, for films whose dialogue is a whisper and whose action is deafening. Applies to remux/transcode playback only (a direct-played file is served untouched). Measured on a 5.1 film: −27.6 → −16.6 LUFS with the loud/quiet range narrowed — everything gets about 11 dB louder, so turn your volume down after switching it on. Takes effect on the next playback."
     }
   },
   "save": "Save",
diff --git a/frontend/src/i18n/locales/hu/config.json b/frontend/src/i18n/locales/hu/config.json
index a87a0def..a1a172ef 100644
--- a/frontend/src/i18n/locales/hu/config.json
+++ b/frontend/src/i18n/locales/hu/config.json
@@ -183,6 +183,10 @@
     "plex_transcode_max_height": {
       "label": "Szoftveres max. magasság",
       "hint": "A szoftveres transcode kimeneti magasságának korlátja képpontban (pl. 1080; 0 = forrás megtartása), hogy egy magas forrás újrakódolása megfizethető maradjon. A GPU-út a forrásfelbontást tartja."
+    },
+    "plex_audio_loudnorm": {
+      "label": "Hangerő normalizálása",
+      "hint": "A sztereó lekeverés EBU R128 szerinti hangerő-normalizálása — azokhoz a filmekhez, ahol a párbeszéd suttogás, az akció meg fülsiketítő. Csak remux/transcode lejátszásnál él (a direktben játszott fájl érintetlen marad). Egy 5.1-es filmen mérve: −27,6 → −16,6 LUFS, szűkebb halk/hangos különbséggel — minden kb. 11 dB-lel hangosabb lesz, szóval bekapcsolás után vedd lejjebb a hangerőt. A következő lejátszástól érvényes."
     }
   },
   "save": "Mentés",

From 782362b8085a9d9c8440dce9555e65017df033bd Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Thu, 10 Sep 2026 20:56:16 +0200
Subject: [PATCH 05/52] fix(channels): the video grid follows a running
 backfill instead of freezing until F5
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"Get full history" on a channel page left the list on the cards the channel already had. The
count above it climbed into the thousands, the grid did not move, and only a browser F5 brought
the rest in.

The mechanism: the backfill runs in a BackgroundTask, so the PATCH that starts it returns before
a single row is written — and the mutation invalidates `qk.feed()` on that RESPONSE, which just
refetches the OLD catalogue. Nothing afterwards refetches it: the feed's infinite query has no
interval, and the app-wide defaults are `staleTime: 30s` + `refetchOnWindowFocus: false`. The job
emits no event either (the realtime layer only carries messages today), so the channel detail's
4s live poll is the only thing in the app that sees the job progress — and it refreshed only
`qk.channel`.

So the poll now drives the grid too: on a tick where the stored count moved (or the backfill
finished), it invalidates `qk.feed()` and the `qk.feedSummary()` behind the count pill. The window
is the poll's own (`deep_requested && !backfill_done` on the previous reading), so a detail
refetch caused by some other mutation — each of which invalidates the feed itself — cannot come
through here twice.

Measured on localdev against the real account, same instrument, `document.visibilityState`
forced visible (the poll deliberately pauses on a hidden tab, and a headless pane reads hidden —
without that the first measurement was about the harness, not the fix):

  before — CASCADA 19 -> 176 stored: the header updated live to "162 normal", the grid and its
           count pill sat on "5 items" for 50s.
  after  — fern 54 -> 139 stored: "54 items" -> "139 items" by ~12s, no reload.

6 vitest, mutation-checked against six mutations (no invalidation at all; grid only, count pill
forgotten; predicate ignored; no channel-identity guard; completion with an unchanged count
dropped; poll-window guard dropped) — each one red on exactly the test that names it.
---
 frontend/src/components/ChannelPage.tsx       |   6 +-
 .../channelDetailPoll.backfill.dom.test.tsx   | 105 ++++++++++++++++++
 frontend/src/lib/channelDetailPoll.ts         |  46 ++++++++
 3 files changed, 156 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/lib/channelDetailPoll.backfill.dom.test.tsx

diff --git a/frontend/src/components/ChannelPage.tsx b/frontend/src/components/ChannelPage.tsx
index e5b91992..9098cdd8 100644
--- a/frontend/src/components/ChannelPage.tsx
+++ b/frontend/src/components/ChannelPage.tsx
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useLiveQuery } from "../lib/useLiveQuery";
-import { channelDetailPollMs } from "../lib/channelDetailPoll";
+import { channelDetailPollMs, useBackfillFeedRefresh } from "../lib/channelDetailPoll";
 import { qk } from "../lib/queryKeys";
 import { useNavigationActions } from "./NavigationProvider";
 import { PriorityStepper } from "./ui/PriorityStepper";
@@ -93,6 +93,10 @@ export default function ChannelPage({
   });
   const ch = detail.data;
   useEffect(() => setBannerAttempt(0), [ch?.banner_url]); // fresh channel/banner → try again
+  // The poll above is also the ONLY signal that the running backfill has written videos, so it
+  // drives the video grid's refresh too (the "Get full history" mutation below can't: it fires on
+  // the PATCH response, before the background job has stored anything).
+  useBackfillFeedRefresh(ch, qc);
 
   // Background auto-ingest ("explore") of an un-subscribed channel's uploads.
   const [nextToken, setNextToken] = useState<string | null | undefined>(undefined);
diff --git a/frontend/src/lib/channelDetailPoll.backfill.dom.test.tsx b/frontend/src/lib/channelDetailPoll.backfill.dom.test.tsx
new file mode 100644
index 00000000..f92ff55c
--- /dev/null
+++ b/frontend/src/lib/channelDetailPoll.backfill.dom.test.tsx
@@ -0,0 +1,105 @@
+// @vitest-environment jsdom
+//
+// "Get full history" on a channel page must not leave the video grid frozen on the cards the
+// channel already had. The backfill runs in a BackgroundTask, so the PATCH that starts it returns
+// before a single row is written — invalidating the feed on that RESPONSE (what the mutation does)
+// refetches the OLD catalogue. Reported from daily use: the stored count climbed into the
+// thousands while the list stayed on the ~19 cards from subscribe time, until a browser F5.
+//
+// The channel detail's 4s live poll is the only thing that sees the job progress, so it is what
+// has to drive the grid. These assert the real cache effect (the feed query ends up invalidated),
+// not that some helper was called.
+import { describe, it, expect } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { QueryClient } from "@tanstack/react-query";
+import { useBackfillFeedRefresh } from "./channelDetailPoll";
+import { qk } from "./queryKeys";
+import type { ChannelDetail, FeedFilters } from "./api";
+
+const CH = "UCsXVk37bltHxD1rDPwtNM8Q";
+// The channel page's Feed is channel-scoped; only the shape matters for the cache key.
+const filters = { q: "", channel: CH } as unknown as FeedFilters;
+
+/** A detail reading mid-backfill: full history requested, back-catalogue not in yet. */
+const detail = (over: Partial<ChannelDetail> = {}): ChannelDetail =>
+  ({
+    id: CH,
+    deep_requested: true,
+    backfill_done: false,
+    stored_videos: 19,
+    ...over,
+  }) as ChannelDetail;
+
+/** The two queries behind the grid and the count pill beside it. */
+const seed = (qc: QueryClient) => {
+  qc.setQueryData(qk.feed(filters), {
+    pages: [{ items: [], next_cursor: null }],
+    pageParams: [null],
+  });
+  qc.setQueryData(qk.feedSummary(filters), { count: 19 });
+};
+
+const stale = (qc: QueryClient) => ({
+  grid: qc.getQueryState(qk.feed(filters))?.isInvalidated === true,
+  count: qc.getQueryState(qk.feedSummary(filters))?.isInvalidated === true,
+});
+
+/** Mount on `first`, then hand the hook the next poll reading. */
+const poll = (qc: QueryClient, first: ChannelDetail | undefined, next: ChannelDetail) => {
+  const { rerender } = renderHook((d: ChannelDetail | undefined) => useBackfillFeedRefresh(d, qc), {
+    initialProps: first,
+  });
+  rerender(next);
+};
+
+describe("useBackfillFeedRefresh", () => {
+  it("refreshes the grid and its count when the running backfill stores more videos", () => {
+    const qc = new QueryClient();
+    seed(qc);
+    poll(qc, detail(), detail({ stored_videos: 79 }));
+    expect(stale(qc)).toEqual({ grid: true, count: true });
+  });
+
+  it("refreshes when the backfill finishes, even if its last page added nothing new", () => {
+    // The tail can be all duplicates: the count never moves, but the grid's `hasNextPage` is still
+    // the one it cached from the pre-backfill catalogue.
+    const qc = new QueryClient();
+    seed(qc);
+    poll(qc, detail(), detail({ backfill_done: true }));
+    expect(stale(qc)).toEqual({ grid: true, count: true });
+  });
+
+  it("leaves the grid alone on a poll tick that changed nothing", () => {
+    const qc = new QueryClient();
+    seed(qc);
+    poll(qc, detail(), detail());
+    expect(stale(qc)).toEqual({ grid: false, count: false });
+  });
+
+  it("stays out of the way when no backfill is running", () => {
+    // A detail refetch outside the poll window comes from a mutation, and every one of those
+    // invalidates the feed itself — firing here too would just double it.
+    const qc = new QueryClient();
+    seed(qc);
+    poll(
+      qc,
+      detail({ deep_requested: false }),
+      detail({ deep_requested: false, stored_videos: 79 }),
+    );
+    expect(stale(qc)).toEqual({ grid: false, count: false });
+  });
+
+  it("does not mistake a switch to another channel for backfill progress", () => {
+    const qc = new QueryClient();
+    seed(qc);
+    poll(qc, detail(), detail({ id: "UCba9j5PIA1zvHf7L5WVJKAg", stored_videos: 412 }));
+    expect(stale(qc)).toEqual({ grid: false, count: false });
+  });
+
+  it("survives the first render, when there is no previous reading yet", () => {
+    const qc = new QueryClient();
+    seed(qc);
+    poll(qc, undefined, detail());
+    expect(stale(qc)).toEqual({ grid: false, count: false });
+  });
+});
diff --git a/frontend/src/lib/channelDetailPoll.ts b/frontend/src/lib/channelDetailPoll.ts
index 0f796e51..f3057de1 100644
--- a/frontend/src/lib/channelDetailPoll.ts
+++ b/frontend/src/lib/channelDetailPoll.ts
@@ -1,3 +1,6 @@
+import { useEffect, useRef } from "react";
+import type { QueryClient } from "@tanstack/react-query";
+import { qk } from "./queryKeys";
 import { type ChannelDetail } from "./api";
 
 /** How often the channel page re-polls its detail (via useLiveQuery): every 4s while THIS user's
@@ -6,3 +9,46 @@ import { type ChannelDetail } from "./api";
  *  the user never requested it. Extracted so the poll-or-stop decision is unit-testable. */
 export const channelDetailPollMs = (d: ChannelDetail | undefined): number | false =>
   d?.deep_requested && !d.backfill_done ? 4000 : false;
+
+/** Did the poll above just watch the running backfill change this channel's catalogue?
+ *
+ *  Only the poll can tell: the backfill runs in a BackgroundTask, so the PATCH that STARTS it
+ *  returns before it has written anything, and it emits no event of its own. The window is the
+ *  same one the poll runs in (`deep_requested && !backfill_done` on the PREVIOUS reading), so a
+ *  detail refetch triggered by some other mutation — which invalidates the feed itself — can't
+ *  come through here twice. Completion counts even with an unchanged count: the last page can be
+ *  all-duplicates and still leave the grid's `hasNextPage` reading from a one-page catalogue. */
+const backfillChangedCatalog = (
+  prev: ChannelDetail | undefined,
+  next: ChannelDetail | undefined,
+): boolean =>
+  !!prev &&
+  !!next &&
+  prev.id === next.id &&
+  prev.deep_requested &&
+  !prev.backfill_done &&
+  (next.stored_videos !== prev.stored_videos || next.backfill_done);
+
+/** Keep the channel page's video grid in step with the backfill its detail poll is watching.
+ *
+ *  Without this the grid is frozen until an F5: the feed's infinite query has no interval, and the
+ *  app-wide defaults are `staleTime: 30s` + `refetchOnWindowFocus: false`, so nothing refetches it
+ *  on its own. "Get full history" invalidates the feed on the PATCH RESPONSE — before the
+ *  background job has written a row — which is why the list stayed on the ~19 cards the channel had
+ *  at subscribe time while the count above it climbed into the thousands.
+ *
+ *  Cost is bounded: the predicate fires only on a tick where the count actually moved, the poll
+ *  itself pauses while the tab is unfocused, and a channel grid is normally a single 60-item page
+ *  whose newest-first head the (older) backfilled videos don't disturb — so the refetch usually
+ *  comes back structurally identical and re-renders nothing. */
+export function useBackfillFeedRefresh(detail: ChannelDetail | undefined, qc: QueryClient) {
+  const seen = useRef<ChannelDetail | undefined>(undefined);
+  useEffect(() => {
+    const prev = seen.current;
+    seen.current = detail;
+    if (!backfillChangedCatalog(prev, detail)) return;
+    qc.invalidateQueries({ queryKey: qk.feed() });
+    // …and the count pill beside it, which reads the same catalogue through its own query.
+    qc.invalidateQueries({ queryKey: qk.feedSummary() });
+  }, [detail, qc]);
+}

From 889d2acf520899b35eef081a6076da8b6c64f19c Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Thu, 10 Sep 2026 22:05:39 +0200
Subject: [PATCH 06/52] feat(plex): the collection page sorts, and a linked
 collection has a name
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two halves of the same report ("Collectionben nem működik a rendezés?"). The pasted browse URL
sorts correctly — that part was working. What did not:

The Collection INFO page had no sort control at all and a hardcoded release-year-ascending order.
It now shows the browse grid's Sort control, with the browse grid's vocabulary, because a second
sort vocabulary on a neighbouring surface is exactly the kind of drift this repo keeps paying for:
`PLEX_SORT_KEYS` is now one tuple in `plex/query.py`, and a test pins BOTH implementations to it —
browse's key→column map (extracted from the handler to be reachable) and the collection page's
key→member map. A key added to the vocabulary without teaching one of them fails the gate instead
of putting a dead option in the menu.

Ordering a collection cannot be a single ORDER BY: its two legs are different tables, so the merged
member list is sorted in Python. Members with no value for the key sink to the END in both
directions (a movie with no rating is not "the worst rated" — the browse grid's `nullslast()`), and
ties always resolve title-ascending, so flipping the direction reverses the ranking rather than the
alphabet inside it. `lastwatched` needed the show leg's `resumed_at`, so the page now takes ONE
rollup pass that yields both the badge status and the recency instead of the status alone — without
it that menu entry would have ordered every show as never-watched. The default stays release-year
ascending: a franchise reads in release order, and that is what the page did before.

The other half: a shared Plex link carries the collection filter as bare rating_keys, so a link
opened cold had no name for them — the sidebar token rendered `17045` and the chip could only say
"Collection". `GET /api/plex/collections` takes a `keys=` CSV now, and a display-only hook resolves
just the missing ids. It deliberately does NOT write them into `collectionTitles`: that map is
hashed into the Plex query keys, so storing a resolved label there would split the cache from the
identical state and refetch the grid for a piece of text.

Verified in the browser on localdev against the real Plex library: the movie collection's menu
offers Length and the show collection's does not (the same scope rule as browse); rating-ascending
reorders 8.1/7.4/7.2/6.6/6.5 correctly; `lastwatched` on a show collection brings the in-progress
shows up; the choice survives a reload (it is a server pref, on its own key so opening a collection
never re-sorts the library behind it); and the reported URL now reads "Pirates of the Caribbean
Collection" in both the sidebar and the chip.

12 pytest + 8 vitest, mutation-checked against 14 mutations (direction ignored, nulls first, no
stable tiebreak, unknown key untouched, wrong default, show recency dropped, empty `keys=` falling
through to everything, a key missing from either sort map, every id refetched, ids unsorted,
fetched titles unmerged, the chip ignoring them, the hook's result never reaching the builder) —
each red on exactly the test that names it.
---
 backend/app/plex/query.py                     |  16 +
 backend/app/routes/plex/browse.py             |  25 +-
 backend/app/routes/plex/collections.py        | 144 ++++++++-
 backend/tests/test_plex_collection_sort.py    | 291 ++++++++++++++++++
 .../src/components/PlexCollectionView.tsx     |  88 ++++--
 frontend/src/components/PlexSidebar.tsx       |   9 +-
 .../usePlexActiveFilters.dom.test.tsx         |  32 +-
 .../src/components/usePlexActiveFilters.ts    |  11 +-
 frontend/src/lib/api/plex.ts                  |  23 +-
 .../lib/usePlexCollectionTitles.dom.test.tsx  |  97 ++++++
 frontend/src/lib/usePlexCollectionTitles.ts   |  31 ++
 11 files changed, 709 insertions(+), 58 deletions(-)
 create mode 100644 backend/tests/test_plex_collection_sort.py
 create mode 100644 frontend/src/lib/usePlexCollectionTitles.dom.test.tsx
 create mode 100644 frontend/src/lib/usePlexCollectionTitles.ts

diff --git a/backend/app/plex/query.py b/backend/app/plex/query.py
index c3fd6f7e..20abd28b 100644
--- a/backend/app/plex/query.py
+++ b/backend/app/plex/query.py
@@ -14,6 +14,22 @@ from app.models import PlexItem, PlexLibrary
 
 TS_CONFIG = "public.unaccent_simple"
 
+# The ONE Plex sort vocabulary, shared by every surface that offers the Sort control (the browse grid
+# and the collection info page) and mirrored by the frontend's `plexSort.ts`. It lives here rather than
+# inside a router because the two surfaces order DIFFERENT things — browse orders a union subquery in
+# SQL, a collection orders its already-loaded member list in Python — and a key that one of them cannot
+# honour would put an option in the UI that silently does nothing. Tests pin both implementations to
+# this tuple, so adding a key here fails the gate until every surface can order by it.
+PLEX_SORT_KEYS: tuple[str, ...] = (
+    "added",
+    "lastwatched",
+    "release",
+    "year",
+    "rating",
+    "duration",
+    "title",
+)
+
 # --- Language-aware column pickers (E5 S6) ----------------------------------
 #
 # The HU-overlay twin (E5 S5) stores Hungarian metadata in `*_hu` columns on the SAME EN row. When
diff --git a/backend/app/routes/plex/browse.py b/backend/app/routes/plex/browse.py
index 5cdda59a..42d04506 100644
--- a/backend/app/routes/plex/browse.py
+++ b/backend/app/routes/plex/browse.py
@@ -54,6 +54,22 @@ from app.utils import to_tsquery_str
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
 
+def sort_column(u, sort: str):
+    """The browse grid's sort key -> orderable column on the union subquery. Module-level (not inline
+    in the handler) so a test can pin its vocabulary to `PLEX_SORT_KEYS` — a key the Sort control
+    offers but this cannot order would quietly fall back to `added_at` and look like a broken control.
+    An unknown key (a stale bookmark, a hand-edited URL) deliberately keeps that fallback."""
+    return {
+        "added": u.c.added_at,
+        "title": func.lower(u.c.title),
+        "year": u.c.year,
+        "rating": u.c.rating,
+        "duration": u.c.duration_s,
+        "release": u.c.rel,
+        "lastwatched": u.c.last_watched,
+    }.get(sort, u.c.added_at)
+
+
 @router.get("/libraries")
 def list_libraries(user: User = Depends(current_user), db: Session = Depends(get_db)) -> dict:
     """The mirrored libraries the user can browse (drives the Plex scope selector). HU overlay
@@ -221,14 +237,7 @@ def unified_library(
         if tsq is not None:
             order = [u.c.rank.desc()]
         else:
-            col = {
-                "title": func.lower(u.c.title),
-                "year": u.c.year,
-                "rating": u.c.rating,
-                "duration": u.c.duration_s,
-                "release": u.c.rel,
-                "lastwatched": u.c.last_watched,
-            }.get(sort, u.c.added_at)
+            col = sort_column(u, sort)
             order = [(col.asc() if sort_dir == "asc" else col.desc()).nullslast()]
         order.append(u.c.rk.desc())
         rows = db.execute(select(u).order_by(*order).offset(offset).limit(limit)).all()
diff --git a/backend/app/routes/plex/collections.py b/backend/app/routes/plex/collections.py
index 862f5f9a..ffcfa397 100644
--- a/backend/app/routes/plex/collections.py
+++ b/backend/app/routes/plex/collections.py
@@ -1,5 +1,9 @@
 """Plex collections: browse mirrored collections + the admin manual-collection editor."""
 
+from collections.abc import Callable
+from datetime import date, datetime
+from typing import Any, NamedTuple
+
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import func, select
@@ -12,6 +16,7 @@ from app.models import (
     PlexItem,
     PlexLibrary,
     PlexShow,
+    PlexState,
     User,
 )
 from app.plex import rollup
@@ -83,13 +88,20 @@ def _collection_card(c: PlexCollection) -> dict:
 def collections(
     library: str | None = None,
     q: str | None = None,
+    keys: str | None = None,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
     """Mirrored collections as cards (most-populated first), optionally name-filtered by `q`. With a
     `library` plex_key → that one library's collections (used by the collection editor). WITHOUT one →
     the UNION across all enabled libraries (the unified-scope sidebar picker, which has no single
-    library selected)."""
+    library selected).
+
+    `keys` (CSV of rating_keys) narrows to just those. It exists because a Plex link carries the
+    collection FILTER as bare rating_keys — nothing in the URL says what "17045" is called — so the
+    sidebar token and the applied-filter chip had nothing to render but the raw id. Resolving them
+    through this endpoint costs one small row each; pulling the whole list to find two titles is
+    ~200 KB."""
     if library is not None:
         lib = (
             db.execute(select(PlexLibrary).where(PlexLibrary.plex_key == str(library)))
@@ -113,6 +125,13 @@ def collections(
     term = (q or "").strip()
     if term:
         query = query.where(PlexCollection.title.ilike(f"%{like_escape(term)}%"))
+    if keys is not None:
+        wanted = [k for k in (keys or "").split(",") if k]
+        # An explicit but empty `keys=` asks for nothing — answer nothing, rather than falling through
+        # to "every collection" (which is what an unguarded empty IN () would have to become).
+        if not wanted:
+            return {"collections": []}
+        query = query.where(PlexCollection.rating_key.in_(wanted))
     rows = (
         db.execute(
             query.order_by(
@@ -149,14 +168,69 @@ def collections(
     }
 
 
+class Member(NamedTuple):
+    """One collection member flattened to everything the Sort control can order by. The page's two
+    legs are different tables (movies and shows), so there is no single query to ORDER BY — the
+    ordering is a pure list sort over these, which is also what makes it unit-testable."""
+
+    kind: str  # "movie" | "show"
+    obj: Any  # PlexItem | PlexShow, carried through to the card serializer
+    title: str  # lower-cased; never NULL (the column is not nullable)
+    year: int | None
+    rating: float | None
+    added: datetime | None
+    release: date | None
+    duration: int | None  # movies only — a show has no single runtime
+    last_watched: datetime | None
+
+
+# Sort key -> what to read off a Member. Pinned to `PLEX_SORT_KEYS` by a test: the collection page
+# shows the SAME Sort control as the browse grid, so a key this map is missing would be an option
+# that silently does nothing here.
+MEMBER_SORT_KEYS: dict[str, Callable[[Member], Any]] = {
+    "added": lambda m: m.added,
+    "lastwatched": lambda m: m.last_watched,
+    "release": lambda m: m.release,
+    "year": lambda m: m.year,
+    "rating": lambda m: m.rating,
+    "duration": lambda m: m.duration,
+    "title": lambda m: m.title,
+}
+
+# What the page ordered by before it had a control, and still its default: a film series wants to be
+# read in release order, not by whenever Plex happened to ingest it.
+DEFAULT_MEMBER_SORT = "year"
+
+
+def sort_members(members: list[Member], sort: str, sort_dir: str) -> list[Member]:
+    """Order a collection's members by one of `PLEX_SORT_KEYS`.
+
+    Two properties worth stating because they are easy to get wrong with a plain `reverse=True`:
+    members with no value for the key sink to the END in BOTH directions (matching the browse grid's
+    `nullslast()` — a movie with no rating is not "the worst rated"), and ties always resolve
+    title-ascending, so flipping the direction reverses the ranking rather than the alphabet inside
+    it. An unknown key falls back to the page's default instead of returning an arbitrary order."""
+    key = MEMBER_SORT_KEYS.get(sort, MEMBER_SORT_KEYS[DEFAULT_MEMBER_SORT])
+    ordered = sorted(members, key=lambda m: m.title)  # stable secondary, applied first
+    have = [m for m in ordered if key(m) is not None]
+    missing = [m for m in ordered if key(m) is None]
+    have.sort(key=key, reverse=sort_dir != "asc")
+    return have + missing
+
+
 @router.get("/collections/{rating_key}")
 def collection_detail(
     rating_key: str,
+    sort: str = DEFAULT_MEMBER_SORT,
+    sort_dir: str = "asc",
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """One collection's hero data + its members (movies + shows), ordered by release year then title —
-    the Collection info page. Read-only here; edits go through the admin mutation endpoints below."""
+    """One collection's hero data + its members (movies + shows) in the requested order — the
+    Collection info page. The sort vocabulary is the browse grid's (`PLEX_SORT_KEYS`) so the same Sort
+    control means the same thing on both surfaces; the default is release year ascending, which is
+    what this page did before it had a control. Read-only here; edits go through the admin mutation
+    endpoints below."""
     col = by_rating_key(db, PlexCollection, rating_key)
     if col is None:
         raise HTTPException(status_code=404, detail="Unknown collection")
@@ -179,19 +253,63 @@ def collection_detail(
         .all()
     )
     mstate = rollup.item_state_map(db, user.id, [m.id for m in movies])
-    sstate = rollup.state_map(db, user.id, [s.id for s in shows])
-    # Merge the two type-homogeneous lists into ONE member list ordered by (year, title).
-    tagged = [(m.year, (m.title or "").lower(), "movie", m) for m in movies] + [
-        (s.year, (s.title or "").lower(), "show", s) for s in shows
+    # ONE rollup pass over the show members, for both the aggregate badge status and `resumed_at` —
+    # the browse grid's "last watched" for a show (the newest resume/watched across its episodes). The
+    # cheaper `rollup.state_map` gives only the status, which would leave `lastwatched` unorderable on
+    # a show collection while the control still offered it.
+    show_rows = (
+        db.execute(
+            rollup.agg_subquery(db, user.id, include_resumed=True).where(
+                PlexItem.show_id.in_([s.id for s in shows])
+            )
+        ).all()
+        if shows
+        else []
+    )
+    sstate = {r.show_id: rollup.show_status(r.total, r.watched, r.inprog) for r in show_rows}
+    sresumed = {r.show_id: r.resumed_at for r in show_rows}
+
+    def _movie_last_watched(st: PlexState | None) -> datetime | None:
+        # Same definition as the browse grid's: when it was last resumed, else when it was marked
+        # watched (coalesce(progress_updated_at, watched_at)).
+        return (st.progress_updated_at or st.watched_at) if st else None
+
+    # Merge the two type-homogeneous lists into ONE member list, then order it.
+    members = [
+        Member(
+            kind="movie",
+            obj=m,
+            title=(m.title or "").lower(),
+            year=m.year,
+            rating=m.rating,
+            added=m.added_at,
+            release=m.originally_available_at,
+            duration=m.duration_s,
+            last_watched=_movie_last_watched(mstate.get(m.id)),
+        )
+        for m in movies
+    ] + [
+        Member(
+            kind="show",
+            obj=sh,
+            title=(sh.title or "").lower(),
+            year=sh.year,
+            rating=sh.rating,
+            added=sh.added_at,
+            release=sh.originally_available_at,
+            duration=None,
+            last_watched=sresumed.get(sh.id),
+        )
+        for sh in shows
     ]
-    tagged.sort(key=lambda t: (t[0] is None, t[0] or 0, t[1]))
+    members = sort_members(members, sort, sort_dir)
     items = [
-        movie_card(o, mstate.get(o.id))
-        if kind == "movie"
-        else show_card(o, sstate.get(o.id, "new"))
-        for _, _, kind, o in tagged
+        movie_card(m.obj, mstate.get(m.obj.id))
+        if m.kind == "movie"
+        else show_card(m.obj, sstate.get(m.obj.id, "new"))
+        for m in members
     ]
-    years = [y for y, _, _, _ in tagged if y is not None]
+    years = [m.year for m in members if m.year is not None]
     certs = [m.content_rating for m in movies] + [s.content_rating for s in shows]
     return {
         **_collection_card(col),
diff --git a/backend/tests/test_plex_collection_sort.py b/backend/tests/test_plex_collection_sort.py
new file mode 100644
index 00000000..431e69f0
--- /dev/null
+++ b/backend/tests/test_plex_collection_sort.py
@@ -0,0 +1,291 @@
+"""The Collection info page's member ordering (`GET /api/plex/collections/{rk}?sort=&sort_dir=`) and
+the `keys=` lookup that gives the sidebar token / filter chip a title instead of a raw rating_key.
+
+Reported from daily use: "Collectionben nem működik a rendezés". The browse grid sorts fine — the
+collection page had no control at all and a hardcoded year-ascending order. Adding the control means
+the SAME vocabulary must actually work here, hence the pin against `PLEX_SORT_KEYS`.
+
+Pure-logic tests run everywhere; the endpoint tests use the `db` fixture (DB lane).
+"""
+
+from datetime import date, datetime, timedelta, timezone
+
+from fastapi.testclient import TestClient
+from sqlalchemy import literal_column
+
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
+from app.main import app
+from app.models import PlexCollection, PlexItem, PlexLibrary, PlexShow, PlexState, User
+from app.plex.query import PLEX_SORT_KEYS
+from app.routes.plex.browse import sort_column
+from app.routes.plex.collections import (
+    DEFAULT_MEMBER_SORT,
+    MEMBER_SORT_KEYS,
+    Member,
+    sort_members,
+)
+
+NOW = datetime(2024, 6, 1, tzinfo=timezone.utc)
+
+
+def _m(title: str, **over) -> Member:
+    base = dict(
+        kind="movie",
+        obj=None,
+        title=title,
+        year=None,
+        rating=None,
+        added=None,
+        release=None,
+        duration=None,
+        last_watched=None,
+    )
+    base.update(over)
+    return Member(**base)  # type: ignore[arg-type]
+
+
+def _titles(members: list[Member]) -> list[str]:
+    return [m.title for m in members]
+
+
+# --- the vocabulary is ONE vocabulary ---------------------------------------------------------
+
+
+def test_every_sort_key_is_orderable_on_a_collection():
+    """The collection page shows the same Sort control as the browse grid, so a key it cannot order
+    would be an option that silently does nothing."""
+    assert set(MEMBER_SORT_KEYS) == set(PLEX_SORT_KEYS)
+
+
+def test_every_sort_key_is_orderable_on_the_browse_grid():
+    """The other half of the same pin: browse falls back to `added_at` for an unknown key, so a key
+    missing from its map would order by date while the control claimed otherwise."""
+
+    class _Cols:
+        title = literal_column("title")
+        year = literal_column("year")
+        rating = literal_column("rating")
+        duration_s = literal_column("duration_s")
+        rel = literal_column("rel")
+        last_watched = literal_column("last_watched")
+        added_at = literal_column("added_at")
+
+    class _U:
+        c = _Cols()
+
+    u = _U()
+    fallback = u.c.added_at
+    unhandled = [k for k in PLEX_SORT_KEYS if k != "added" and sort_column(u, k) is fallback]
+    assert unhandled == []
+    # …and the fallback itself is still what an unknown key gets.
+    assert sort_column(u, "no-such-key") is fallback
+
+
+# --- ordering behaviour -----------------------------------------------------------------------
+
+
+def test_orders_by_the_requested_key_in_both_directions():
+    members = [_m("b", year=2006), _m("c", year=2017), _m("a", year=2003)]
+    assert _titles(sort_members(members, "year", "asc")) == ["a", "b", "c"]
+    assert _titles(sort_members(members, "year", "desc")) == ["c", "b", "a"]
+
+
+def test_members_without_a_value_sink_to_the_end_in_both_directions():
+    """A movie with no rating is not "the worst rated" — nullslast, like the browse grid."""
+    members = [_m("rated-low", rating=6.5), _m("unrated"), _m("rated-high", rating=8.1)]
+    assert _titles(sort_members(members, "rating", "desc")) == [
+        "rated-high",
+        "rated-low",
+        "unrated",
+    ]
+    assert _titles(sort_members(members, "rating", "asc")) == ["rated-low", "rated-high", "unrated"]
+
+
+def test_ties_stay_title_ascending_when_the_direction_flips():
+    """Flipping the direction must reverse the RANKING, not the alphabet inside a tie."""
+    members = [_m("zulu", year=2003), _m("alpha", year=2003), _m("mike", year=2017)]
+    assert _titles(sort_members(members, "year", "asc")) == ["alpha", "zulu", "mike"]
+    assert _titles(sort_members(members, "year", "desc")) == ["mike", "alpha", "zulu"]
+
+
+def test_an_unknown_key_falls_back_to_the_pages_default():
+    members = [_m("b", year=2006), _m("a", year=2017)]
+    assert _titles(sort_members(members, "no-such-key", "asc")) == _titles(
+        sort_members(members, DEFAULT_MEMBER_SORT, "asc")
+    )
+
+
+def test_a_show_has_no_duration_and_therefore_sinks_on_that_key():
+    members = [
+        _m("short movie", duration=3600),
+        _m("a show", kind="show", duration=None),
+        _m("long movie", duration=9000),
+    ]
+    assert _titles(sort_members(members, "duration", "desc")) == [
+        "long movie",
+        "short movie",
+        "a show",
+    ]
+
+
+# --- the endpoint (DB lane) -------------------------------------------------------------------
+
+
+def _seed(db):
+    lib_m = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    lib_s = PlexLibrary(plex_key="2", title="Shows", kind="show", enabled=True)
+    db.add_all([lib_m, lib_s])
+    db.flush()
+
+    col = PlexCollection(rating_key="col1", library_id=lib_m.id, title="Franchise", child_count=3)
+    other = PlexCollection(rating_key="col2", library_id=lib_m.id, title="Elsewhere", child_count=1)
+    db.add_all([col, other])
+    db.flush()
+
+    # Titles deliberately alphabetical-opposite to the years, so a year sort can't accidentally pass
+    # by falling through to the title tiebreak.
+    old = PlexItem(
+        rating_key="mo_old",
+        library_id=lib_m.id,
+        kind="movie",
+        title="Zulu",
+        year=2003,
+        rating=8.1,
+        duration_s=8000,
+        added_at=NOW - timedelta(days=1),
+        originally_available_at=date(2003, 7, 9),
+        collection_keys=["col1"],
+    )
+    mid = PlexItem(
+        rating_key="mo_mid",
+        library_id=lib_m.id,
+        kind="movie",
+        title="Mike",
+        year=2006,
+        rating=7.4,
+        duration_s=9000,
+        added_at=NOW - timedelta(days=3),
+        originally_available_at=date(2006, 7, 7),
+        collection_keys=["col1"],
+    )
+    new = PlexItem(
+        rating_key="mo_new",
+        library_id=lib_m.id,
+        kind="movie",
+        title="Alpha",
+        year=2017,
+        rating=6.5,
+        duration_s=7000,
+        added_at=NOW,
+        originally_available_at=date(2017, 5, 26),
+        collection_keys=["col1"],
+    )
+    # A show member with a resumed episode: `lastwatched` must work on this leg too, not just movies.
+    show = PlexShow(
+        rating_key="sh1",
+        library_id=lib_s.id,
+        title="Series",
+        year=2010,
+        child_count=1,
+        collection_keys=["col1"],
+    )
+    db.add_all([old, mid, new, show])
+    db.flush()
+    ep = PlexItem(
+        rating_key="sh1_e1",
+        library_id=lib_s.id,
+        kind="episode",
+        title="E1",
+        show_id=show.id,
+        season_number=1,
+        episode_number=1,
+    )
+    db.add(ep)
+    db.flush()
+
+    user = User(email="colsort@example.com")
+    db.add(user)
+    db.flush()
+    db.add_all(
+        [
+            # The show's episode is the most recently touched thing in the collection…
+            PlexState(
+                user_id=user.id,
+                item_id=ep.id,
+                status="new",
+                position_seconds=60,
+                progress_updated_at=NOW,
+            ),
+            # …and one movie was watched earlier.
+            PlexState(
+                user_id=user.id,
+                item_id=old.id,
+                status="watched",
+                watched_at=NOW - timedelta(days=2),
+            ),
+        ]
+    )
+    db.commit()
+    return user
+
+
+def _get(db, user, monkeypatch, path):
+    monkeypatch.setattr(state, "_configured_cache", True)
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: user
+    try:
+        return TestClient(app).get(path)
+    finally:
+        app.dependency_overrides.clear()
+
+
+def _order(r) -> list[str]:
+    return [i["title"] for i in r.json()["items"]]
+
+
+def test_collection_detail_defaults_to_release_year_ascending(db, monkeypatch):
+    """The order the page had before it grew a control — a franchise reads in release order."""
+    user = _seed(db)
+    r = _get(db, user, monkeypatch, "/api/plex/collections/col1")
+    assert r.status_code == 200
+    assert _order(r) == ["Zulu", "Mike", "Series", "Alpha"]
+
+
+def test_collection_detail_honours_sort_and_direction(db, monkeypatch):
+    user = _seed(db)
+    r = _get(db, user, monkeypatch, "/api/plex/collections/col1?sort=year&sort_dir=desc")
+    assert _order(r) == ["Alpha", "Series", "Mike", "Zulu"]
+    r = _get(db, user, monkeypatch, "/api/plex/collections/col1?sort=title&sort_dir=asc")
+    assert _order(r) == ["Alpha", "Mike", "Series", "Zulu"]
+    r = _get(db, user, monkeypatch, "/api/plex/collections/col1?sort=rating&sort_dir=desc")
+    # The show has no rating, so it sinks — it is not "rated 0".
+    assert _order(r) == ["Zulu", "Mike", "Alpha", "Series"]
+
+
+def test_lastwatched_ranks_a_shows_episodes_alongside_the_movies(db, monkeypatch):
+    """The show leg needs the rollup's `resumed_at`; with only a status map this key would order
+    every show as never-watched."""
+    user = _seed(db)
+    r = _get(db, user, monkeypatch, "/api/plex/collections/col1?sort=lastwatched&sort_dir=desc")
+    # Series (episode resumed NOW) > Zulu (watched 2 days ago) > the two never-touched, title-asc.
+    assert _order(r) == ["Series", "Zulu", "Alpha", "Mike"]
+
+
+def test_collections_list_resolves_titles_by_key(db, monkeypatch):
+    """What a shared Plex link needs: the URL carries bare rating_keys, so the sidebar token and the
+    filter chip have nothing to show but `17045` until these are resolved."""
+    user = _seed(db)
+    r = _get(db, user, monkeypatch, "/api/plex/collections?keys=col1")
+    assert r.status_code == 200
+    assert [c["title"] for c in r.json()["collections"]] == ["Franchise"]
+
+
+def test_an_empty_keys_param_asks_for_nothing(db, monkeypatch):
+    """`keys=` with nothing in it must not fall through to "every collection" — that would be a
+    200 KB answer to a question about zero ids."""
+    user = _seed(db)
+    r = _get(db, user, monkeypatch, "/api/plex/collections?keys=")
+    assert r.status_code == 200
+    assert r.json()["collections"] == []
diff --git a/frontend/src/components/PlexCollectionView.tsx b/frontend/src/components/PlexCollectionView.tsx
index 5feef76d..7aabdaba 100644
--- a/frontend/src/components/PlexCollectionView.tsx
+++ b/frontend/src/components/PlexCollectionView.tsx
@@ -8,6 +8,10 @@ import { formatRuntime } from "../lib/format";
 import { notifyActionError, notifyCollectionEditError } from "../lib/actionErrors";
 import { notify } from "../lib/notifications";
 import { showEpisodeKeys } from "../lib/plexQueue";
+import { healPlexSort, plexSortOptions } from "../lib/plexSort";
+import { usePref } from "../lib/usePref";
+import SortControl from "./ui/SortControl";
+import { type SortState } from "../lib/columnSort";
 import { useConfirm } from "./ConfirmProvider";
 import { BackBtn, ActionBtn, DetailHero } from "../lib/plexDetailUi";
 import { PlexPosterCard } from "./plexCards";
@@ -22,6 +26,11 @@ import { LoadingState, StateMessage } from "./ui/QueryState";
 // admin-enabled collection — rename / delete / add / remove, all write-through to Plex (the mutation
 // endpoints round-trip to Plex, so each edit awaits and re-fetches; no optimism). Read-only ones (smart
 // / imdb / tmdb / … auto-lists) are marked with a lock.
+// The order this page had before it grew a Sort control, and still its default: a franchise reads in
+// release order. MUST match the endpoint's `DEFAULT_MEMBER_SORT` — the two only diverge if a request
+// goes out without the params, which is why the control always sends them.
+const COLLECTION_SORT_DEFAULT: NonNullable<SortState> = { key: "year", dir: "asc" };
+
 function shuffled(a: string[]): string[] {
   const r = [...a];
   for (let i = r.length - 1; i > 0; i--) {
@@ -52,9 +61,17 @@ export default function PlexCollectionView({
   // One comfort-pin menu for the member grid (see ui/ContextMenu).
   const pinMenu = useContextMenu<PlexCard>();
   const isAdmin = qc.getQueryData<{ role?: string }>(qk.me())?.role === "admin";
+  // The member order is a PREFERENCE (server-synced, adopted on login), not an ephemeral filter — the
+  // same treatment the feed's view and the player's auto-advance get. It is deliberately its OWN key
+  // rather than the browse grid's sort: opening a collection must not silently re-sort the library
+  // behind it.
+  const [sortPref, setSortPref] = usePref<NonNullable<SortState>>(
+    "plexCollectionSort",
+    COLLECTION_SORT_DEFAULT,
+  );
   const q = useQuery({
-    queryKey: qk.plexCollections("detail", collectionId),
-    queryFn: () => api.plexCollection(collectionId),
+    queryKey: qk.plexCollections("detail", collectionId, sortPref.key, sortPref.dir),
+    queryFn: () => api.plexCollection(collectionId, sortPref),
   });
   const d = q.data;
 
@@ -73,6 +90,11 @@ export default function PlexCollectionView({
   };
 
   const items = d?.items ?? [];
+  // A collection lives in ONE library, so its members are all movies or all shows. That decides both
+  // what the add-panel searches and which sort keys are on offer (only a movie has a runtime).
+  const scope = items.some((c) => c.type === "show") ? "show" : "movie";
+  const sortState = healPlexSort(sortPref, scope);
+  const sortOptions = plexSortOptions(scope, (k) => t(`plex.sort.${k}`));
   // Movies/episodes are playable leaves that queue as themselves; a show can't queue directly, so
   // Play-all expands it into its episodes (buildQueue). Either kind means there's something to play —
   // this is what a show-collection needs: before, `playable` held only leaves, so a show-collection's
@@ -334,7 +356,7 @@ export default function PlexCollectionView({
           {adding && canEdit && (
             <AddItemPanel
               collectionId={collectionId}
-              scope={items.some((c) => c.type === "show") ? "show" : "movie"}
+              scope={scope}
               existing={new Set(items.map((c) => c.id))}
               onAdded={invalidate}
               onClose={() => setAdding(false)}
@@ -344,30 +366,46 @@ export default function PlexCollectionView({
           {items.length === 0 ? (
             <p className="text-muted text-sm">{t("plex.collection.empty")}</p>
           ) : (
-            <div className="grid grid-cols-3 gap-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6">
-              {items.map((c) => (
-                <div key={c.id} className="relative">
-                  <PlexPosterCard
-                    card={c}
-                    onOpen={() => onOpenCard(c)}
-                    onInfo={() => onInfoCard(c)}
-                    onToggleWatched={toggleWatched}
-                    menuProps={pinMenu.triggerProps}
+            <>
+              {/* Sort sits directly above the grid, pinned right — the same placement (and the same
+                  control, options and labels) as the browse grid, so the two read as one idea. */}
+              <div className="mb-2 flex items-center">
+                <div className="ml-auto flex shrink-0 items-center gap-1.5">
+                  <SortControl
+                    options={sortOptions}
+                    sort={sortState}
+                    onChange={(next) => setSortPref(next ?? COLLECTION_SORT_DEFAULT)}
+                    label={t("plex.filter.sort")}
+                    ascLabel={t("plex.filter.dir.asc")}
+                    descLabel={t("plex.filter.dir.desc")}
                   />
-                  {canEdit && (
-                    <button
-                      onClick={() => doRemove(c)}
-                      disabled={busy}
-                      title={t("plex.collection.removeItem")}
-                      aria-label={t("plex.collection.removeItem")}
-                      className="glass-card glass-hover absolute right-1.5 top-1.5 z-base grid h-6 w-6 place-items-center rounded-full text-fg disabled:opacity-50"
-                    >
-                      <X className="h-3.5 w-3.5" />
-                    </button>
-                  )}
                 </div>
-              ))}
-            </div>
+              </div>
+              <div className="grid grid-cols-3 gap-3 sm:grid-cols-4 md:grid-cols-5 lg:grid-cols-6">
+                {items.map((c) => (
+                  <div key={c.id} className="relative">
+                    <PlexPosterCard
+                      card={c}
+                      onOpen={() => onOpenCard(c)}
+                      onInfo={() => onInfoCard(c)}
+                      onToggleWatched={toggleWatched}
+                      menuProps={pinMenu.triggerProps}
+                    />
+                    {canEdit && (
+                      <button
+                        onClick={() => doRemove(c)}
+                        disabled={busy}
+                        title={t("plex.collection.removeItem")}
+                        aria-label={t("plex.collection.removeItem")}
+                        className="glass-card glass-hover absolute right-1.5 top-1.5 z-base grid h-6 w-6 place-items-center rounded-full text-fg disabled:opacity-50"
+                      >
+                        <X className="h-3.5 w-3.5" />
+                      </button>
+                    )}
+                  </div>
+                ))}
+              </div>
+            </>
           )}
         </>
       )}
diff --git a/frontend/src/components/PlexSidebar.tsx b/frontend/src/components/PlexSidebar.tsx
index fcdb92d2..cda82882 100644
--- a/frontend/src/components/PlexSidebar.tsx
+++ b/frontend/src/components/PlexSidebar.tsx
@@ -1,5 +1,6 @@
 import { useState } from "react";
 import { qk } from "../lib/queryKeys";
+import { usePlexCollectionTitles } from "../lib/usePlexCollectionTitles";
 import { useTranslation } from "react-i18next";
 import { plexLang } from "../i18n";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
@@ -447,6 +448,10 @@ function CollectionPicker({
     queryFn: () => api.plexCollections(undefined, searchDeb || undefined),
     enabled: open, // only fetch while the picker is open
   });
+  // …but a selection restored from a LINK has ids and no titles, and the list above is only fetched
+  // once the picker is opened — so the token rendered the raw rating_key until then. Resolve just the
+  // selected ids (see usePlexCollectionTitles).
+  const resolved = usePlexCollectionTitles(values, titles);
   const options: ComboboxOption[] = (q.data?.collections ?? []).map((c) => ({
     value: c.id,
     label: c.title,
@@ -454,7 +459,7 @@ function CollectionPicker({
   }));
   // Combine the fetched labels with the ones already stored so the trip through onChange keeps every
   // selected collection's title (the fetched list is narrowed by the current search).
-  const labelMap: Record<string, string> = { ...titles };
+  const labelMap: Record<string, string> = { ...resolved };
   for (const o of options) if (o.label) labelMap[o.value] = o.label;
 
   return (
@@ -463,7 +468,7 @@ function CollectionPicker({
       clientFilter={false} // the server already narrows to `search`
       options={options}
       selected={values}
-      selectedLabels={titles}
+      selectedLabels={resolved}
       query={search}
       onQueryChange={setSearch}
       onOpenChange={setOpen}
diff --git a/frontend/src/components/usePlexActiveFilters.dom.test.tsx b/frontend/src/components/usePlexActiveFilters.dom.test.tsx
index 9e27da56..85da3b95 100644
--- a/frontend/src/components/usePlexActiveFilters.dom.test.tsx
+++ b/frontend/src/components/usePlexActiveFilters.dom.test.tsx
@@ -6,6 +6,8 @@
 // the provider is mocked so the hook can be driven with a non-default sort present.
 import { describe, it, expect, vi } from "vitest";
 import { renderHook } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createElement, type ReactNode } from "react";
 import { EMPTY_PLEX_FILTERS } from "../lib/api";
 
 vi.mock("react-i18next", async (importOriginal) => {
@@ -21,7 +23,9 @@ const plexState = {
   filters: {
     ...EMPTY_PLEX_FILTERS,
     genres: ["Action"],
-    collections: ["A"],
+    // "A" was picked in the sidebar (its title came along); "B" arrived from a shared LINK, which
+    // carries ids only — the case that used to render a raw rating_key.
+    collections: ["A", "B"],
     collectionTitles: { A: "Marvel" },
   },
 };
@@ -33,10 +37,17 @@ vi.mock("./PlexProvider", () => ({
 }));
 
 import { usePlexActiveFilters } from "./usePlexActiveFilters";
+import { qk } from "../lib/queryKeys";
+
+// The hook resolves collection titles it does not already have through react-query, so it needs a
+// client. Every id here already HAS a title, so the query stays disabled and nothing is requested.
+const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+const wrapper = ({ children }: { children: ReactNode }) =>
+  createElement(QueryClientProvider, { client: qc }, children);
 
 describe("usePlexActiveFilters", () => {
   it("emits filter + watch-state chips but never a sort chip", () => {
-    const { result } = renderHook(() => usePlexActiveFilters());
+    const { result } = renderHook(() => usePlexActiveFilters(), { wrapper });
     const keys = result.current.map((c) => c.key);
     // The in-panel narrowings still surface...
     expect(keys).toContain("genre:Action");
@@ -46,9 +57,22 @@ describe("usePlexActiveFilters", () => {
     expect(result.current.every((c) => !c.key.startsWith("sort"))).toBe(true);
   });
 
+  it("labels a link-supplied collection with its resolved title, not the bare id", () => {
+    // Seed the resolution the hook would fetch, so this asserts the WIRING (hook -> builder -> label)
+    // rather than the network. Nothing is mocked.
+    qc.setQueryData(qk.plexCollections("titles", "B"), {
+      collections: [{ id: "B", title: "Pirates of the Caribbean Collection" }],
+    });
+    const { result } = renderHook(() => usePlexActiveFilters(), { wrapper });
+    const byKey = Object.fromEntries(result.current.map((c) => [c.key, c.label]));
+    expect(byKey["collection:B"]).toBe("Pirates of the Caribbean Collection");
+    // …and the one the filter state already knew about is untouched.
+    expect(byKey["collection:A"]).toBe("Marvel");
+  });
+
   it("removing the last collection chip prunes its title and collapses collectionTitles to undefined", () => {
     setFilters.mockClear();
-    const { result } = renderHook(() => usePlexActiveFilters());
+    const { result } = renderHook(() => usePlexActiveFilters(), { wrapper });
     const chip = result.current.find((c) => c.key === "collection:A");
     expect(chip).toBeDefined();
     chip!.remove();
@@ -59,7 +83,7 @@ describe("usePlexActiveFilters", () => {
       collections: string[];
       collectionTitles?: unknown;
     };
-    expect(arg.collections).toEqual([]);
+    expect(arg.collections).toEqual(["B"]);
     expect(arg.collectionTitles).toBeUndefined();
   });
 });
diff --git a/frontend/src/components/usePlexActiveFilters.ts b/frontend/src/components/usePlexActiveFilters.ts
index 7127fb52..514b1eb5 100644
--- a/frontend/src/components/usePlexActiveFilters.ts
+++ b/frontend/src/components/usePlexActiveFilters.ts
@@ -3,6 +3,7 @@ import { type ActiveFilter } from "../lib/useActiveFilters";
 import { EMPTY_PLEX_FILTERS, type PlexFilters } from "../lib/api";
 import { PLEX_SORT_FALLBACK } from "../lib/plexSort";
 import { usePlex, usePlexActions } from "./PlexProvider";
+import { usePlexCollectionTitles } from "../lib/usePlexCollectionTitles";
 
 // Plex's analogue of useActiveFilters: turns the shared Plex state (expanded filters + watch-state)
 // into the source-agnostic ActiveFilter[] the shared ActiveFilterChips renders above the grid.
@@ -19,7 +20,10 @@ export function usePlexActiveFilters(): ActiveFilter[] {
   const { setShow, setFilters } = usePlexActions();
   const { t } = useTranslation();
   const patch = (p: Partial<PlexFilters>) => setFilters({ ...filters, ...p });
-  return buildPlexActiveFilters(filters, show, patch, setShow, t);
+  // A link opened cold knows the collection ids but not their names — resolve the missing ones for
+  // display (see usePlexCollectionTitles for why they are NOT written back into the filter state).
+  const collectionTitles = usePlexCollectionTitles(filters.collections, filters.collectionTitles);
+  return buildPlexActiveFilters(filters, show, patch, setShow, t, collectionTitles);
 }
 
 // The pure builder behind the hook: turns a Plex filter set + watch-state into the source-agnostic
@@ -31,6 +35,9 @@ export function buildPlexActiveFilters(
   patch: (p: Partial<PlexFilters>) => void,
   setShow: (s: string) => void,
   t: TFn,
+  /** Collection titles for the chip labels, resolved beyond what the filter state carries. Omitted by
+   *  the saved-views manager, which describes a stored view and has only the captured titles. */
+  collectionTitles?: Record<string, string>,
 ): ActiveFilter[] {
   const out: ActiveFilter[] = [];
 
@@ -127,7 +134,7 @@ export function buildPlexActiveFilters(
   for (const c of filters.collections) {
     out.push({
       key: `collection:${c}`,
-      label: filters.collectionTitles?.[c] ?? t("plex.filter.collection"),
+      label: collectionTitles?.[c] ?? filters.collectionTitles?.[c] ?? t("plex.filter.collection"),
       // Prune the title too — collectionTitles is hashed into the plex query keys, so a stale entry
       // splits the cache from the logically-identical no-collection state (mirrors CollectionPicker).
       // Collapse an empty map back to undefined so the last-removed state key-matches the pristine
diff --git a/frontend/src/lib/api/plex.ts b/frontend/src/lib/api/plex.ts
index 647d5333..89aae403 100644
--- a/frontend/src/lib/api/plex.ts
+++ b/frontend/src/lib/api/plex.ts
@@ -479,16 +479,31 @@ export const plexApi = {
   },
   // With a library plex_key → that library's collections (editor). Without one → the union across all
   // enabled libraries (the unified-scope sidebar picker).
-  plexCollections: (library?: string, q?: string): Promise<{ collections: PlexCollection[] }> => {
+  plexCollections: (
+    library?: string,
+    q?: string,
+    keys?: string[],
+  ): Promise<{ collections: PlexCollection[] }> => {
     const u = new URLSearchParams();
     if (library) u.set("library", library);
     if (q) u.set("q", q);
+    // `keys` resolves specific rating_keys to their titles — a shared Plex link carries the collection
+    // filter as bare ids, so the sidebar token and the filter chip have nothing else to render.
+    if (keys) u.set("keys", keys.join(","));
     const qs = u.toString();
     return req(`/api/plex/collections${qs ? `?${qs}` : ""}`);
   },
-  // One collection's hero + ordered members (the Collection info page).
-  plexCollection: (rk: string): Promise<PlexCollectionDetail> =>
-    req(`/api/plex/collections/${encodeURIComponent(rk)}`),
+  // One collection's hero + its members in the requested order (the Collection info page). The sort
+  // vocabulary is the browse grid's, so the same Sort control means the same thing on both.
+  plexCollection: (rk: string, sort?: SortState): Promise<PlexCollectionDetail> => {
+    const u = new URLSearchParams();
+    if (sort) {
+      u.set("sort", sort.key);
+      u.set("sort_dir", sort.dir);
+    }
+    const qs = u.toString();
+    return req(`/api/plex/collections/${encodeURIComponent(rk)}${qs ? `?${qs}` : ""}`);
+  },
   // --- Collection editing (admin only; writes back to Plex) ---
   plexCreateCollection: (
     library: string,
diff --git a/frontend/src/lib/usePlexCollectionTitles.dom.test.tsx b/frontend/src/lib/usePlexCollectionTitles.dom.test.tsx
new file mode 100644
index 00000000..1064a41a
--- /dev/null
+++ b/frontend/src/lib/usePlexCollectionTitles.dom.test.tsx
@@ -0,0 +1,97 @@
+// @vitest-environment jsdom
+//
+// A shared Plex link carries the collection filter as bare rating_keys — `?pf=collections%3D17045`
+// says nothing about what 17045 is called. Opened cold, the sidebar token rendered that raw id and
+// the applied-filter chip could only say "Collection". This hook resolves the missing ones.
+//
+// Two things it must NOT do: ask the server for a title the filter state already carries (the common
+// case — the user picked the collection in the sidebar), and pull the whole collection list to find
+// one name (431 collections / ~200 KB on the owner's library).
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { createElement, type ReactNode } from "react";
+
+const plexCollections = vi.fn();
+vi.mock("./api", () => ({ api: { plexCollections: (...a: unknown[]) => plexCollections(...a) } }));
+
+import { usePlexCollectionTitles } from "./usePlexCollectionTitles";
+
+const wrap = () => {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return ({ children }: { children: ReactNode }) =>
+    createElement(QueryClientProvider, { client: qc }, children);
+};
+
+const CATALOG: Record<string, string> = {
+  "17045": "Pirates of the Caribbean Collection",
+  "68231": "IMDb Top 250",
+};
+
+beforeEach(() => {
+  plexCollections.mockReset();
+  // Answer like the endpoint does: only the requested keys come back.
+  plexCollections.mockImplementation((_lib: unknown, _q: unknown, keys: string[]) =>
+    Promise.resolve({
+      collections: (keys ?? []).map((id) => ({ id, title: CATALOG[id] })),
+    }),
+  );
+});
+
+describe("usePlexCollectionTitles", () => {
+  it("resolves the ids the filter state has no title for", async () => {
+    const { result } = renderHook(() => usePlexCollectionTitles(["17045"], undefined), {
+      wrapper: wrap(),
+    });
+    await waitFor(() =>
+      expect(result.current["17045"]).toBe("Pirates of the Caribbean Collection"),
+    );
+    // Only the missing ids are asked for — nothing else.
+    expect(plexCollections).toHaveBeenCalledWith(undefined, undefined, ["17045"]);
+  });
+
+  it("asks for nothing when every id already has a title", async () => {
+    const known = { "17045": "Pirates of the Caribbean Collection" };
+    const { result } = renderHook(() => usePlexCollectionTitles(["17045"], known), {
+      wrapper: wrap(),
+    });
+    expect(result.current["17045"]).toBe("Pirates of the Caribbean Collection");
+    // Give a would-be fetch a chance to happen before asserting it did not.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(plexCollections).not.toHaveBeenCalled();
+  });
+
+  it("asks only for the missing half of a mixed selection", async () => {
+    const { result } = renderHook(
+      () => usePlexCollectionTitles(["17045", "68231"], { "17045": "Already Known" }),
+      { wrapper: wrap() },
+    );
+    await waitFor(() => expect(result.current["68231"]).toBe("IMDb Top 250"));
+    // The known id is not in the request — and its stored title survives the merge.
+    expect(plexCollections).toHaveBeenCalledWith(undefined, undefined, ["68231"]);
+    expect(result.current["17045"]).toBe("Already Known");
+  });
+
+  it("treats the same ids in a different order as one query", async () => {
+    const w = wrap();
+    const a = renderHook(() => usePlexCollectionTitles(["68231", "17045"], undefined), {
+      wrapper: w,
+    });
+    await waitFor(() => expect(a.result.current["17045"]).toBeDefined());
+    const calls = plexCollections.mock.calls.length;
+    const b = renderHook(() => usePlexCollectionTitles(["17045", "68231"], undefined), {
+      wrapper: w,
+    });
+    await waitFor(() => expect(b.result.current["17045"]).toBeDefined());
+    expect(plexCollections.mock.calls.length).toBe(calls);
+  });
+
+  it("returns nothing extra while the lookup is still in flight", () => {
+    plexCollections.mockReturnValue(new Promise(() => {}));
+    const { result } = renderHook(() => usePlexCollectionTitles(["17045"], undefined), {
+      wrapper: wrap(),
+    });
+    // The caller falls back to its own label; it must not be handed a half-built map.
+    expect(result.current["17045"]).toBeUndefined();
+  });
+});
diff --git a/frontend/src/lib/usePlexCollectionTitles.ts b/frontend/src/lib/usePlexCollectionTitles.ts
new file mode 100644
index 00000000..ec2c380c
--- /dev/null
+++ b/frontend/src/lib/usePlexCollectionTitles.ts
@@ -0,0 +1,31 @@
+import { useQuery } from "@tanstack/react-query";
+import { api } from "./api";
+import { qk } from "./queryKeys";
+
+// A Plex link carries the collection filter as bare rating_keys (`?pf=collections%3D17045`) — nothing
+// in the URL says what "17045" is called. The title is normally picked up as a side effect of choosing
+// the collection in the sidebar (`collectionTitles`), so a link opened cold had no name for it and the
+// picker token rendered the raw id while the filter chip could only say "Collection".
+//
+// This resolves the missing ones from the server and merges them over what the filter state already
+// knows. It stays OUT of `collectionTitles`: that map is hashed into the Plex query keys, so writing a
+// resolved title back in would split the cache from the logically identical state and refetch the grid
+// for a label. Titles are display-only, so they belong in a display-only read.
+export function usePlexCollectionTitles(
+  ids: string[],
+  known: Record<string, string> | undefined,
+): Record<string, string> {
+  // Sorted so the same set of ids in a different order is the same query.
+  const missing = ids.filter((id) => !known?.[id]).sort();
+  const q = useQuery({
+    queryKey: qk.plexCollections("titles", missing.join(",")),
+    queryFn: () => api.plexCollections(undefined, undefined, missing),
+    enabled: missing.length > 0,
+    // A collection's name is about as static as data gets, and this can be asked for on every render
+    // of the sidebar and the chip row.
+    staleTime: 60 * 60_000,
+  });
+  const out: Record<string, string> = { ...known };
+  for (const c of q.data?.collections ?? []) out[c.id] = c.title;
+  return out;
+}

From f76a2afbf14297395d9dd47682f4cd091b83968c Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Thu, 10 Sep 2026 22:34:12 +0200
Subject: [PATCH 07/52] =?UTF-8?q?feat(ui):=20the=20four=20small=20gaps=20?=
 =?UTF-8?q?=E2=80=94=20player=20delete,=20repeat-move,=20a=20real=20channe?=
 =?UTF-8?q?l=20link,=20YT=20search=20sorting?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Items 2, 4, 5 and 7 of the bug hunt, one round. They are independent, but they are all the same
kind of thing: an action that exists somewhere else in the app and is missing where you actually
want it.

**5 — the channel name in the YT player is a link again.** It was a `<button>`, so middle-click and
Ctrl/Cmd-click did nothing on a thing that looks exactly like a link (the YouTube icon beside it IS
an anchor and opens a tab). It is now a real `<a>` whose href is the same `?chan=<id>` URL
`openChannel` pushes, with a plain left click still taking the in-app path — that path does more
than navigate, since the player must close and reclaim its own Back-to-close history entry first.
The "is this click ours or the browser's" test is now ONE predicate (`isPlainLeftClick`), which
VideoCard's card link also uses, so a second such link cannot forget the middle-click arm.

**2 — "Remove" from inside the player.** The parent owns the removal (the SAME `removeItem` the row
menu and the inline ✕ use: one confirm, one optimistic update, one undo-stack rebase), and the
player owns what happens next, because it is the only side that knows which item is playing — its
launch queue is frozen at mount. It drops the item, plays what followed, and closes when the list
runs out. That forced a real fix in Playlists: the player's mount was derived from `shown` every
render, so anything that dropped the launch row yanked the player off the screen mid-playback. That
was a latent edge (change the view and it happens) and the normal case for this feature. The parent
now snapshots what it launched with, and only onClose takes the player down.

**4 — "Move to <the last list you moved to>".** The submenu is two levels deep and moving a run of
videos into the same list is the shape this gets used in. The remembered id is a per-account pref;
the row is derived from `moveTargets`, which already excludes the list you are looking at, so it
cannot offer a move to where the video already is. Remembered only on a SUCCESSFUL move — a
shortcut to a move that failed is a shortcut to failing again. Absent, not disabled, when there is
nothing to repeat: there is nothing to explain.

**7 — the live-YouTube results can be sorted.** Client-side, over the page already loaded. Not a
new `order=` param, and this is the decision worth recording: the owner's case is "even one page of
results", i.e. reorder what is on screen; a re-query would REPLACE the results, which is not what
"sort these" means; and the zero-quota scrape source has no order parameter at all, so a
server-side control would silently do nothing (or quietly cost 100 quota units) depending on which
source served the page. Only keys a search hit carries are offered — `subscribers`/`priority`
describe a subscription, which a search hit is not, and `shuffle` on a ranked list is noise. Its
own pref, so sorting a search page never re-sorts the library behind it.

Verified in the browser on localdev against the real account: the channel name renders as
`<a href="…&chan=…">` and a ctrl-click / middle-click is left to the browser while a plain click
still opens the channel in-app; removing from the player stepped 1/3 → 1/2 onto the next video and
closed on the last one; the row menu grew "Move to “…”" only after a move and only on a list that
is not the target; and the results sort reordered by views 41.7M → 29.8M → 24.2M → 15.8M. (The
pane's own ctrl-click arrives without the modifier — a harness limit, so the modifier cases were
driven as real MouseEvents.) Scratch playlists and the touched prefs were cleaned up afterwards.

22 vitest, mutation-checked against 14 mutations (no href at all · href without the rest of the
query · every click hijacked in-app · the middle-click arm dropped from the predicate · plain click
no longer in-app · always jumping to the top of the list · the removed item left in the queue · no
clamp when the last item goes · an empty queue not reported as "nothing left" · sort-then-reverse
flipping ties · unknown values first · titles compared numerically · shuffle offered on search
results · direction ignored) — each red on exactly the test that names it. Item 4 has no test of
its own: its rule is enforced by construction, not by a check.
---
 .../components/ChannelNameLink.dom.test.tsx   |  73 +++++++++++
 frontend/src/components/ChannelNameLink.tsx   |  37 ++++++
 frontend/src/components/Feed.tsx              |  35 +++++-
 frontend/src/components/PlayerModal.tsx       |  62 +++++++++-
 frontend/src/components/Playlists.tsx         |  93 ++++++++++----
 frontend/src/components/VideoCard.tsx         |   3 +-
 frontend/src/i18n/locales/en/playlists.json   |   1 +
 frontend/src/i18n/locales/hu/playlists.json   |   1 +
 frontend/src/lib/feedSort.ts                  |  42 +++++++
 frontend/src/lib/feedSort.yt.test.ts          | 113 ++++++++++++++++++
 frontend/src/lib/nav.ts                       |  17 +++
 frontend/src/lib/playerQueue.test.ts          |  53 ++++++++
 frontend/src/lib/playerQueue.ts               |  30 +++++
 13 files changed, 531 insertions(+), 29 deletions(-)
 create mode 100644 frontend/src/components/ChannelNameLink.dom.test.tsx
 create mode 100644 frontend/src/components/ChannelNameLink.tsx
 create mode 100644 frontend/src/lib/feedSort.yt.test.ts
 create mode 100644 frontend/src/lib/playerQueue.test.ts
 create mode 100644 frontend/src/lib/playerQueue.ts

diff --git a/frontend/src/components/ChannelNameLink.dom.test.tsx b/frontend/src/components/ChannelNameLink.dom.test.tsx
new file mode 100644
index 00000000..6f931b0d
--- /dev/null
+++ b/frontend/src/components/ChannelNameLink.dom.test.tsx
@@ -0,0 +1,73 @@
+// @vitest-environment jsdom
+//
+// Reported from daily use: middle-clicking the channel name in the YT player did nothing. It looked
+// like a link — the YouTube icon beside it IS one — but it was a `<button>`, so the browser had no
+// href to open a tab with. These pin the two halves the fix has to keep true at once: there is a real
+// href pointing where the in-app navigation would go, AND a plain left click still takes the in-app
+// path (which does more than navigate — the player has to close and reclaim its history entry first).
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import ChannelNameLink from "./ChannelNameLink";
+
+const CH = "UCsXVk37bltHxD1rDPwtNM8Q";
+
+beforeEach(() => {
+  // No global auto-cleanup in this project's vitest setup, and several cases render more than once.
+  cleanup();
+  window.history.replaceState({}, "", "/?page=feed&show=unwatched");
+});
+
+const renderLink = () => {
+  const onOpenInApp = vi.fn();
+  render(<ChannelNameLink channelId={CH} title="LEMMiNO" onOpenInApp={onOpenInApp} />);
+  return { link: screen.getByText("LEMMiNO") as HTMLAnchorElement, onOpenInApp };
+};
+
+/** Dispatch a click and report whether the component prevented it (i.e. handled it in-app).
+ *  The document-level guard runs AFTER React's handler and swallows the default, so an
+ *  un-prevented click on a real href does not make jsdom log "Not implemented: navigation". */
+const clickWasHandled = (el: HTMLElement, init: MouseEventInit = {}): boolean => {
+  let prevented = false;
+  const guard = (e: Event) => {
+    prevented = e.defaultPrevented;
+    e.preventDefault();
+  };
+  document.addEventListener("click", guard);
+  el.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, ...init }));
+  document.removeEventListener("click", guard);
+  return prevented;
+};
+
+describe("ChannelNameLink", () => {
+  it("is an anchor whose href opens this channel on the current page", () => {
+    const { link } = renderLink();
+    expect(link.tagName).toBe("A");
+    // The same URL openChannel pushes: the current page's query plus ?chan=<id>.
+    expect(link.getAttribute("href")).toBe(`/?page=feed&show=unwatched&chan=${CH}`);
+  });
+
+  it("takes the in-app path on a plain left click, and suppresses the browser navigation", () => {
+    const { link, onOpenInApp } = renderLink();
+    expect(clickWasHandled(link, { button: 0 })).toBe(true);
+    expect(onOpenInApp).toHaveBeenCalledTimes(1);
+  });
+
+  it.each([
+    ["middle-click", { button: 1 }], // the reported gesture
+    ["ctrl-click", { ctrlKey: true }],
+    ["cmd-click", { metaKey: true }],
+    ["shift-click", { shiftKey: true }],
+  ])("leaves %s to the browser", (_name, mod) => {
+    const { link, onOpenInApp } = renderLink();
+    // Neither hijacked in-app nor prevented — the href is left to do its job.
+    expect(clickWasHandled(link, mod)).toBe(false);
+    expect(onOpenInApp).not.toHaveBeenCalled();
+  });
+
+  it("does not lose the rest of the address bar", () => {
+    window.history.replaceState({}, "", "/?page=channels&q=abc");
+    const { link } = renderLink();
+    expect(link.getAttribute("href")).toContain("page=channels");
+    expect(link.getAttribute("href")).toContain("q=abc");
+  });
+});
diff --git a/frontend/src/components/ChannelNameLink.tsx b/frontend/src/components/ChannelNameLink.tsx
new file mode 100644
index 00000000..910e68ec
--- /dev/null
+++ b/frontend/src/components/ChannelNameLink.tsx
@@ -0,0 +1,37 @@
+import { isPlainLeftClick } from "../lib/nav";
+import { urlWithParams } from "../lib/urlState";
+
+// A channel name that is a REAL link. The player showed it as a `<button>`, so the browser's own
+// gestures did nothing on it: middle-click and Ctrl/Cmd-click opened no tab, on a thing that looks
+// exactly like a link (the YouTube icon right next to it IS an anchor and does open one).
+//
+// The href is the same URL `openChannel` pushes — `?chan=<id>` on the current page — so a new tab
+// lands where the in-app navigation would have. A plain left click is still handled in-app, because
+// the SPA path does more than navigate (the player has to close first and reclaim its own
+// Back-to-close history entry; see closeThenNavigate).
+export default function ChannelNameLink({
+  channelId,
+  title,
+  onOpenInApp,
+  className,
+}: {
+  channelId: string;
+  title: string | null | undefined;
+  /** The in-app navigation, run only for a plain left click. */
+  onOpenInApp: () => void;
+  className?: string;
+}) {
+  return (
+    <a
+      href={urlWithParams({ chan: channelId })}
+      onClick={(e) => {
+        if (!isPlainLeftClick(e)) return; // let the browser open its tab/window
+        e.preventDefault();
+        onOpenInApp();
+      }}
+      className={className}
+    >
+      {title}
+    </a>
+  );
+}
diff --git a/frontend/src/components/Feed.tsx b/frontend/src/components/Feed.tsx
index 9d55c5bf..3a6c5f08 100644
--- a/frontend/src/components/Feed.tsx
+++ b/frontend/src/components/Feed.tsx
@@ -31,9 +31,12 @@ import {
   parseSort,
   SORT_DEFAULT_DIR,
   SORT_KEYS,
+  sortYtResults,
+  YT_SORT_KEYS,
   type SortKey,
 } from "../lib/feedSort";
-import { type SortOption } from "../lib/columnSort";
+import { type SortOption, type SortState } from "../lib/columnSort";
+import { usePref } from "../lib/usePref";
 import { FEED_VIEWS, type FeedView } from "../lib/feedView";
 import { clearedFilters, useActiveFilters } from "../lib/useActiveFilters";
 import ActiveFilterChips from "./ActiveFilterChips";
@@ -153,6 +156,13 @@ export default function Feed({
   // How many live-search results to gather (the count selector replaces a manual "load more";
   // the free scrape source pages through continuations until this many are collected).
   const [ytCount, setYtCount] = useState(20);
+  // How to order the loaded results. Its OWN pref, not `filters.sort`: sorting a live-search page
+  // must not silently re-sort the library you go back to. Default `relevance` — the provider's
+  // ranking, which is what the view always showed before it had a control.
+  const [ytSort, setYtSort] = usePref<NonNullable<SortState>>("ytSearchSort", {
+    key: "relevance",
+    dir: "desc",
+  });
 
   // Debounce only the search term feeding the queries: the input still updates instantly (it
   // owns filters.q), but the feed/count keys settle after a pause, so typing doesn't refetch —
@@ -378,7 +388,11 @@ export default function Feed({
   if (ytActive) {
     const ytLoaded: Video[] = (ytQuery.data?.pages ?? []).flatMap((p) => p.items);
     loadedRef.current = ytLoaded;
-    const ytItems: Video[] = withOverrides(ytLoaded);
+    const ytItems: Video[] = sortYtResults(
+      withOverrides(ytLoaded),
+      ytSort.key as SortKey,
+      ytSort.dir,
+    );
     const ytPlayerQueue: Video[] = ytItems.filter((v) => v.status !== "hidden");
     const ytError =
       ytQuery.error instanceof HttpError
@@ -430,6 +444,23 @@ export default function Feed({
                 ))}
               </select>
             </label>
+            {/* Sorts the results already on screen (see sortYtResults) — it never re-queries, so it
+                costs nothing and works the same on both search sources. */}
+            <SortControl
+              options={YT_SORT_KEYS.map((k) => ({
+                key: k,
+                label: t("feed.sortKey." + k),
+                directionless: DIRECTIONLESS.includes(k),
+                defaultDir: DIRECTIONLESS.includes(k)
+                  ? undefined
+                  : SORT_DEFAULT_DIR[k as Exclude<SortKey, "shuffle" | "relevance">],
+              }))}
+              sort={ytSort}
+              onChange={(next) => setYtSort(next ?? { key: "relevance", dir: "desc" })}
+              label={t("feed.sortLabel")}
+              ascLabel={t("feed.dirAsc")}
+              descLabel={t("feed.dirDesc")}
+            />
           </div>
           {ytItems.length > 0 && (
             <div className="flex items-center gap-2 flex-wrap mt-2 text-xs text-muted">
diff --git a/frontend/src/components/PlayerModal.tsx b/frontend/src/components/PlayerModal.tsx
index fbce8674..c79d679c 100644
--- a/frontend/src/components/PlayerModal.tsx
+++ b/frontend/src/components/PlayerModal.tsx
@@ -24,6 +24,7 @@ import {
   Minimize,
   Minimize2,
   Settings,
+  Trash2,
   Volume2,
   VolumeX,
   X,
@@ -46,6 +47,8 @@ import { renderDescription } from "../lib/descriptionLinks";
 import { fullscreenElement } from "../lib/fullscreen";
 import { dispatch, isActivationTarget, useKeyScope } from "../lib/keymap";
 import { closeThenNavigate, useBackToClose } from "../lib/history";
+import ChannelNameLink from "./ChannelNameLink";
+import { afterRemoval } from "../lib/playerQueue";
 import {
   useNativeControlsYield,
   useYtBigView,
@@ -82,6 +85,7 @@ export default function PlayerModal({
   startIndex,
   onClose,
   onState,
+  onRemoveFromList,
 }: {
   video: Video;
   // Where to start the opened video: a number of seconds (0 = Restart), or null/undefined
@@ -94,6 +98,11 @@ export default function PlayerModal({
   startIndex?: number;
   onClose: () => void;
   onState: (id: string, status: VideoStatus) => void;
+  /** Remove the playing video from the list it was opened from (the Playlists module passes its own
+   *  `removeItem`; the feed passes nothing — there is no list to remove it from). Returns whether it
+   *  actually happened, because the CONSEQUENCE is the player's: its launch queue is frozen, so it
+   *  drops the item itself and steps to the next one, closing when the list runs out. */
+  onRemoveFromList?: (video: Video) => Promise<boolean>;
   // Open the active video's channel page in-app (closes the player first). The small external
   // icon next to the name keeps the open-on-YouTube behaviour.
 }) {
@@ -110,7 +119,11 @@ export default function PlayerModal({
   // wrap back to the first item once earlier items dropped out). Snapshot once at mount via
   // useState's lazy initializer and ignore later prop changes. Items that turn out gone/
   // non-embeddable still surface the existing playback-error overlay when reached.
-  const [queue] = useState(() => queueProp);
+  //
+  // The setter exists for exactly ONE writer: removing the playing video from its playlist (below).
+  // That is not the feed changing under us — it is this player's own action — and leaving the item
+  // in the frozen queue would let prev/next step back onto a video that no longer exists.
+  const [queue, setQueue] = useState(() => queueProp);
   // Precise upload date shown inline after the relative time (e.g. "9 yr ago · 12 Jan 2017").
   const fullDate = (d: string | null | undefined) => formatDate(d, i18n.language);
   // Track the playing item by id (not a frozen index) so it survives the queue changing
@@ -245,6 +258,32 @@ export default function PlayerModal({
     const { queue: q, index: i } = navRef.current;
     if (q && i < q.length - 1) setPlayingId(q[i + 1]!.id);
   };
+  // "Remove from this playlist", offered right where you are watching the thing you want gone. The
+  // parent owns the removal (confirm + API + caches); the player owns what happens NEXT, because it
+  // is the only side that knows which item is playing — its queue is frozen at mount, so the parent
+  // cannot tell. Step to the item that followed (clamped when the last one goes), and close when the
+  // list runs out. Guarded against a double press while the confirm/request is in flight.
+  const [removing, setRemoving] = useState(false);
+  const removeFromList = async () => {
+    if (!onRemoveFromList || removing) return;
+    const victim = active;
+    setRemoving(true);
+    let done = false;
+    try {
+      done = await onRemoveFromList(victim);
+    } finally {
+      setRemoving(false);
+    }
+    if (!done) return; // cancelled at the confirm, or the request failed — leave playback alone
+    const next = afterRemoval(queue, index, victim.id);
+    if (!next) {
+      onClose(); // that was the last one
+      return;
+    }
+    setQueue(next.queue);
+    setPlayingId(next.playingId);
+  };
+
   // Relative seek within the current video (plain Arrow keys), matching YouTube's ±5s.
   const nudgeSeek = (delta: number) => {
     const p = playerRef.current;
@@ -761,8 +800,10 @@ export default function PlayerModal({
                 )
               ) : (
                 <div className="flex items-center gap-1.5 shrink-0 min-w-0">
-                  <button
-                    onClick={() => {
+                  <ChannelNameLink
+                    channelId={active.channel_id}
+                    title={active.channel_title}
+                    onOpenInApp={() => {
                       const cid = active.channel_id;
                       const cname = active.channel_title ?? undefined;
                       // Close first, open the channel only once this player's own Back-to-close
@@ -772,9 +813,7 @@ export default function PlayerModal({
                       closeThenNavigate(onClose, () => openChannel(cid, cname));
                     }}
                     className="font-medium hover:text-accent truncate text-left"
-                  >
-                    {active.channel_title}
-                  </button>
+                  />
                   <a
                     href={active.channel_url}
                     target="_blank"
@@ -863,6 +902,17 @@ export default function PlayerModal({
                   className="shrink-0 inline-flex items-center justify-center w-9 h-9 rounded-lg text-muted hover:text-fg hover:bg-surface border border-border transition"
                 />
               )}
+              {!navigated && onRemoveFromList && (
+                <button
+                  onClick={() => void removeFromList()}
+                  disabled={removing}
+                  title={t("playlists.removeItem")}
+                  aria-label={t("playlists.removeItem")}
+                  className="shrink-0 inline-flex items-center justify-center w-9 h-9 rounded-lg text-muted hover:text-danger hover:bg-surface border border-border transition disabled:opacity-50"
+                >
+                  <Trash2 className="w-4 h-4" />
+                </button>
+              )}
               {!navigated && (
                 <button
                   onClick={() => setWatched(!watched)}
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 093f34d7..6bb1d140 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -28,6 +28,7 @@ import {
   Check,
   ExternalLink,
   FolderInput,
+  History,
   GripVertical,
   ListPlus,
   Pencil,
@@ -59,6 +60,7 @@ import { useConfirm } from "./ConfirmProvider";
 import { usePlaylistActions } from "./usePlaylistActions";
 import { usePlaylists } from "./PlaylistsProvider";
 import { useMe } from "../lib/useMe";
+import { usePref } from "../lib/usePref";
 import {
   ColumnHead,
   alignClass,
@@ -214,10 +216,24 @@ export default function Playlists() {
   // re-confirms our own reorder doesn't wipe the undo history — we reset history only when
   // the actual set of items changes (different playlist, or an add/remove).
   const lastSetRef = useRef<string>("");
-  // The open player is tracked by video ID, not by a position: `shown` is derived, so a refetch or
-  // a change of view would otherwise slide a different video under the index — or unmount the player
-  // mid-playback. PlayerModal already tracks its own queue by id; this is the parent half of that.
-  const [playingId, setPlayingId] = useState<string | null>(null);
+  // What the player was LAUNCHED with, snapshotted when it opens: the video, the queue and the index
+  // inside it. `shown` is derived (sort / filter / view), and the player freezes its queue and owns
+  // its own cursor from mount — so deriving the mount from `shown` every render meant anything that
+  // dropped the launch row yanked the player off the screen mid-playback. That was a latent edge
+  // (a view change) until "remove this from the playlist" moved INSIDE the player, where it is the
+  // normal case. Only onClose takes the player down now.
+  const [playing, setPlaying] = useState<{
+    video: Video;
+    queue: Video[];
+    index: number;
+  } | null>(null);
+  // Where the last move went. `LS.playlist` is the SELECTED (source) list and `updated_at` moves on
+  // any edit, so neither answers "where do I keep sending things"; this does, and it is a per-account
+  // preference like every other remembered choice. Null until the first move of this account's life.
+  const [lastMoveTargetId, setLastMoveTargetId] = usePref<number | null>(
+    "lastMovePlaylistId",
+    null,
+  );
   // ONE context menu for the whole table, not one popover per <tr> (see ui/ContextMenu): the row it
   // belongs to is `rowMenu.target`, and the panel anchors to the pointer.
   const rowMenu = useContextMenu<Video>();
@@ -273,10 +289,23 @@ export default function Playlists() {
   const [pushing, setPushing] = useState(false);
   const [reverting, setReverting] = useState(false);
 
-  const onPlay = useCallback((v: Video) => setPlayingId(v.id), []);
-  const onRemove = useCallback((v: Video) => {
-    removeRef.current(v);
+  // Stable (the memoized row callbacks depend on it), so it reads `shown` through the ref rather
+  // than closing over it.
+  const openPlayer = useCallback((id: string) => {
+    const queue = shownRef.current;
+    const index = queue.findIndex((v) => v.id === id);
+    if (index < 0) return;
+    setPlaying({ video: queue[index]!, queue, index });
   }, []);
+  const onPlay = useCallback((v: Video) => openPlayer(v.id), [openPlayer]);
+  const onRemove = useCallback((v: Video) => {
+    void removeRef.current(v);
+  }, []);
+  // The player's "remove from this playlist" goes through the SAME removeItem the row menu and the
+  // inline ✕ use — one confirm, one optimistic update, one undo-stack rebase, no second copy to
+  // drift. It answers whether the removal actually happened, because the player has to decide
+  // afterwards whether to step to the next item or close.
+  const removeFromPlayer = useCallback((v: Video) => removeRef.current(v), []);
 
   const storedIndex = useMemo(() => {
     const m = new Map(items.map((v, i) => [v.id, i]));
@@ -478,15 +507,17 @@ export default function Playlists() {
     order.set(arrayMove(items, oldIndex, newIndex)); // onApply persists
   }
 
-  async function removeItem(video: Video) {
-    if (selectedId == null) return;
+  /** @returns whether the item was actually removed — the player needs to know, because it must
+   *  step to the next item (or close) only when the removal really happened. */
+  async function removeItem(video: Video): Promise<boolean> {
+    if (selectedId == null) return false;
     const ok = await confirm({
       title: t("playlists.removeItem"),
       message: t("playlists.confirmRemove", { title: video.title }),
       confirmLabel: t("playlists.removeItem"),
       danger: true,
     });
-    if (!ok) return;
+    if (!ok) return false;
     // A removal isn't itself undoable, but it no longer THROWS AWAY the reorder history: rebasing
     // drops the item from every snapshot, so the stack stays valid for what's left.
     const next = items.filter((v) => v.id !== video.id);
@@ -495,10 +526,12 @@ export default function Playlists() {
     try {
       await api.removeFromPlaylist(selectedId, video.id);
       refreshAll();
+      return true;
     } catch {
       // The optimistic removal above didn't stick — resync from the server to restore the row.
       // api.req already surfaced the error to the user via the global error dialog.
       refreshAll();
+      return false;
     }
   }
   // Kept in a ref so the memoized column callbacks don't rebuild on every state change.
@@ -516,6 +549,9 @@ export default function Playlists() {
       // ONE request. The two-call version (add there, remove here) leaves the video in BOTH lists
       // whenever the second call fails — see the endpoint's docstring.
       await api.moveToPlaylist(selectedId, video.id, target.id);
+      // Remembered only on SUCCESS: a shortcut that points at a move which failed would be a
+      // shortcut to failing again.
+      setLastMoveTargetId(target.id);
       notify({
         level: "success",
         message: t("playlists.movedToast", { title: video.title, name: plName(target) }),
@@ -575,7 +611,7 @@ export default function Playlists() {
 
   // Stable identity: PlayerModal's keydown/scroll-lock effect depends on it, so a fresh closure
   // every render re-subscribed those listeners and re-ran focusModal() under the open player.
-  const closePlayer = useCallback(() => setPlayingId(null), []);
+  const closePlayer = useCallback(() => setPlaying(null), []);
 
   // Name the current view in the user's terms: "Title ↑", "grouped by channel", or both.
   const sortLabel =
@@ -601,11 +637,15 @@ export default function Playlists() {
     : filterActive
       ? t("playlists.dragBlockedFilter")
       : t("playlists.dragBlockedSort");
-  const playingIndex = playingId ? shown.findIndex((v) => v.id === playingId) : -1;
 
   // The row menu, built from the row the user right-clicked. Same item shape (and therefore same
   // rows, same paint, same keyboard model) as any ⋯ ActionMenu in the app.
   const moveTargets = playlists.filter((p) => p.id !== selectedId);
+  // A one-click repeat of the last move — the submenu is two levels deep, and moving a run of videos
+  // into the same list is the shape this actually gets used in. Absent (not disabled) when there is
+  // nothing to repeat: before the first move, or when the remembered list IS the one you are looking
+  // at, which is not a move at all. Nothing to explain, so nothing to leave behind greyed out.
+  const recentMoveTarget = moveTargets.find((p) => p.id === lastMoveTargetId);
   const storedOrderEditable = canEdit && !viewActive;
   const ctxRow = rowMenu.target;
   const ctxItems: ActionMenuItem[] = !ctxRow
@@ -615,17 +655,29 @@ export default function Playlists() {
           id: "play",
           label: t("card.play"),
           icon: <Play className="w-4 h-4" />,
-          onSelect: () => setPlayingId(ctxRow.id),
+          onSelect: () => openPlayer(ctxRow.id),
         },
         ...comfortPin.item(pinVideo(ctxRow.id), ctxRow.title ?? ""),
         ...(canEdit
           ? ([
+              ...(recentMoveTarget
+                ? [
+                    {
+                      id: "move-recent",
+                      label: t("playlists.moveToRecent", { name: plName(recentMoveTarget) }),
+                      icon: <History className="w-4 h-4" />,
+                      separatorBefore: true,
+                      onSelect: () => void moveItemTo(ctxRow, recentMoveTarget),
+                    },
+                  ]
+                : []),
               moveTargets.length
                 ? {
                     id: "move",
                     label: t("playlists.moveTo"),
                     icon: <FolderInput className="w-4 h-4" />,
-                    separatorBefore: true,
+                    // Only ONE separator opens the move block, wherever it starts.
+                    separatorBefore: !recentMoveTarget,
                     items: moveTargets.map((pl) => ({
                       id: `move-${pl.id}`,
                       label: plName(pl),
@@ -647,7 +699,7 @@ export default function Playlists() {
                     id: "move",
                     label: t("playlists.moveTo"),
                     icon: <FolderInput className="w-4 h-4" />,
-                    separatorBefore: true,
+                    separatorBefore: !recentMoveTarget,
                     disabled: true,
                     title: t("playlists.moveNoTargets"),
                     onSelect: () => {},
@@ -780,7 +832,7 @@ export default function Playlists() {
                     </span>
                   )}
                   <button
-                    onClick={() => shown.length && setPlayingId(shown[0]!.id)}
+                    onClick={() => shown.length && openPlayer(shown[0]!.id)}
                     disabled={!shown.length}
                     className="inline-flex items-center gap-1.5 text-xs font-semibold px-3 py-1.5 rounded-lg btn-primary disabled:opacity-40 transition"
                   >
@@ -957,15 +1009,16 @@ export default function Playlists() {
       {/* One surface for the whole table, outside the rows — it anchors to the pointer, not the row. */}
       <ContextMenu menu={rowMenu} ariaLabel={t("playlists.rowMenu")} items={ctxItems} />
 
-      {playingIndex >= 0 && (
+      {playing && (
         <Suspense fallback={null}>
           <PlayerModal
-            video={shown[playingIndex]!}
-            queue={shown}
-            startIndex={playingIndex}
+            video={playing.video}
+            queue={playing.queue}
+            startIndex={playing.index}
             startAt={null}
             onClose={closePlayer}
             onState={playerState}
+            onRemoveFromList={canEdit ? removeFromPlayer : undefined}
           />
         </Suspense>
       )}
diff --git a/frontend/src/components/VideoCard.tsx b/frontend/src/components/VideoCard.tsx
index b2fad419..7f631d34 100644
--- a/frontend/src/components/VideoCard.tsx
+++ b/frontend/src/components/VideoCard.tsx
@@ -22,6 +22,7 @@ import clsx from "clsx";
 import type { Video, VideoStatus } from "../lib/api";
 import { FEED_VIEW_SPEC, type FeedView } from "../lib/feedView";
 import { formatDate, formatDuration, formatViews, relativeTime } from "../lib/format";
+import { isPlainLeftClick } from "../lib/nav";
 
 function Actions({
   video,
@@ -124,7 +125,7 @@ function openInApp(
   video: Video,
   onOpen?: (v: Video, startAt?: number | null) => void,
 ): void {
-  if (!onOpen || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) return;
+  if (!onOpen || !isPlainLeftClick(e)) return;
   e.preventDefault();
   onOpen(video);
 }
diff --git a/frontend/src/i18n/locales/en/playlists.json b/frontend/src/i18n/locales/en/playlists.json
index 497b311c..8514f1f9 100644
--- a/frontend/src/i18n/locales/en/playlists.json
+++ b/frontend/src/i18n/locales/en/playlists.json
@@ -72,6 +72,7 @@
   "colDuration": "Length",
   "rowMenu": "Video actions",
   "moveTo": "Move to another list",
+  "moveToRecent": "Move to “{{name}}”",
   "moveNoTargets": "There is no other playlist to move it to yet.",
   "movedToast": "“{{title}}” moved to “{{name}}” ✓",
   "moveFailed": "Couldn't move the video.",
diff --git a/frontend/src/i18n/locales/hu/playlists.json b/frontend/src/i18n/locales/hu/playlists.json
index 699c2938..7998a421 100644
--- a/frontend/src/i18n/locales/hu/playlists.json
+++ b/frontend/src/i18n/locales/hu/playlists.json
@@ -72,6 +72,7 @@
   "colDuration": "Hossz",
   "rowMenu": "Videó műveletek",
   "moveTo": "Áthelyezés másik listába",
+  "moveToRecent": "Áthelyezés ide: „{{name}}”",
   "moveNoTargets": "Még nincs másik lejátszási lista, ahová áthelyezhetnéd.",
   "movedToast": "„{{title}}” áthelyezve ide: „{{name}}” ✓",
   "moveFailed": "Nem sikerült áthelyezni a videót.",
diff --git a/frontend/src/lib/feedSort.ts b/frontend/src/lib/feedSort.ts
index 265eb389..65ba12ed 100644
--- a/frontend/src/lib/feedSort.ts
+++ b/frontend/src/lib/feedSort.ts
@@ -1,6 +1,7 @@
 // The feed's sort vocabulary. `FeedFilters.sort` is a single wire string ("newest", "views_asc",
 // …); the UI thinks in a key + direction. Kept here rather than inside Feed so the active-filter
 // chips can label a sort without re-deriving the mapping.
+import type { Video } from "./api";
 
 export type SortKey =
   | "date"
@@ -56,3 +57,44 @@ export function buildSort(key: SortKey, dir: "asc" | "desc"): string {
   if (key === "shuffle" || key === "relevance") return key;
   return SORT_MAP[key][dir];
 }
+
+// --- Live YouTube search results ----------------------------------------------------------------
+//
+// The results view had NO sort control at all — the order was the provider's and that was that. It is
+// sorted HERE, on the page already loaded, rather than by re-asking YouTube with an `order=` param,
+// for three reasons: the owner's case is "even one page of results", i.e. reorder what is on screen;
+// a re-query would REPLACE the results, which is not what "sort these" means; and the zero-quota
+// scrape source has no order parameter at all, so a server-side control would silently do nothing (or
+// quietly cost 100 quota units) depending on which source happened to serve the page.
+//
+// Only the keys a search result actually carries are offered. `subscribers` and `priority` are
+// properties of a SUBSCRIPTION, which a live search result is not, and `shuffle` on a ranked result
+// list is noise — an option that cannot mean anything here is worse than no option.
+export const YT_SORT_KEYS: SortKey[] = ["relevance", "date", "popular", "duration", "title"];
+
+const YT_SORT_VALUE: Partial<Record<SortKey, (v: Video) => number | string | null | undefined>> = {
+  date: (v) => (v.published_at ? Date.parse(v.published_at) : null),
+  popular: (v) => v.view_count,
+  duration: (v) => v.duration_seconds,
+  title: (v) => v.title,
+};
+
+/** Order a loaded page of live-search results. `relevance` is the provider's own ranking, i.e. the
+ *  order they arrived in — so it is the identity, not a sort.
+ *
+ *  Results missing the value sink to the END in both directions (a video whose duration YouTube did
+ *  not report is not "the shortest"), and ties keep the provider's ranking, in both directions —
+ *  hence a signed comparator rather than sorting and reversing, which would flip the ties too. */
+export function sortYtResults(items: Video[], key: SortKey, dir: "asc" | "desc"): Video[] {
+  const value = YT_SORT_VALUE[key];
+  if (!value) return items; // relevance, and anything a stale pref names that we no longer offer
+  const sign = dir === "asc" ? 1 : -1;
+  const have = items.filter((v) => value(v) != null);
+  const missing = items.filter((v) => value(v) == null);
+  have.sort((a, b) => {
+    const x = value(a)!;
+    const y = value(b)!;
+    return sign * (typeof x === "string" ? x.localeCompare(String(y)) : x - Number(y));
+  });
+  return [...have, ...missing];
+}
diff --git a/frontend/src/lib/feedSort.yt.test.ts b/frontend/src/lib/feedSort.yt.test.ts
new file mode 100644
index 00000000..5f4a921d
--- /dev/null
+++ b/frontend/src/lib/feedSort.yt.test.ts
@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { sortYtResults, YT_SORT_KEYS, SORT_KEYS } from "./feedSort";
+import type { Video } from "./api";
+
+// The live-YouTube results view shipped with no sort control at all: the provider's order was the
+// only order, "már 1 lapnyi találatnál is lenne értelme". These pin what the added control means —
+// it reorders the page already on screen, and it only offers keys a search result actually carries.
+const v = (over: Partial<Video>): Video => ({ id: over.title ?? "?", ...over }) as Video;
+const titles = (list: Video[]) => list.map((x) => x.title);
+
+const RESULTS: Video[] = [
+  v({
+    title: "b-old-short",
+    published_at: "2019-01-01T00:00:00Z",
+    view_count: 10,
+    duration_seconds: 60,
+  }),
+  v({
+    title: "a-new-long",
+    published_at: "2026-01-01T00:00:00Z",
+    view_count: 5,
+    duration_seconds: 6000,
+  }),
+  v({
+    title: "c-mid-mid",
+    published_at: "2022-01-01T00:00:00Z",
+    view_count: 99,
+    duration_seconds: 600,
+  }),
+];
+
+describe("YT_SORT_KEYS", () => {
+  it("offers only keys a live search result can be ordered by", () => {
+    // `subscribers`/`priority` describe a SUBSCRIPTION, which a search hit is not, and `shuffle` on a
+    // ranked result list is noise. An option that cannot mean anything here is worse than no option.
+    expect(YT_SORT_KEYS).not.toContain("subscribers");
+    expect(YT_SORT_KEYS).not.toContain("priority");
+    expect(YT_SORT_KEYS).not.toContain("shuffle");
+    // …and every key it does offer is part of the feed's one vocabulary, not a private spelling.
+    for (const k of YT_SORT_KEYS) {
+      if (k === "relevance") continue; // the provider's ranking; not in the wire-sort map
+      expect(SORT_KEYS).toContain(k);
+    }
+  });
+});
+
+describe("sortYtResults", () => {
+  it("leaves the provider's ranking alone on `relevance`", () => {
+    expect(titles(sortYtResults(RESULTS, "relevance", "desc"))).toEqual([
+      "b-old-short",
+      "a-new-long",
+      "c-mid-mid",
+    ]);
+  });
+
+  it("orders by upload date in both directions", () => {
+    expect(titles(sortYtResults(RESULTS, "date", "desc"))).toEqual([
+      "a-new-long",
+      "c-mid-mid",
+      "b-old-short",
+    ]);
+    expect(titles(sortYtResults(RESULTS, "date", "asc"))).toEqual([
+      "b-old-short",
+      "c-mid-mid",
+      "a-new-long",
+    ]);
+  });
+
+  it("orders by views and by length", () => {
+    expect(titles(sortYtResults(RESULTS, "popular", "desc"))[0]).toBe("c-mid-mid");
+    expect(titles(sortYtResults(RESULTS, "duration", "desc"))[0]).toBe("a-new-long");
+    expect(titles(sortYtResults(RESULTS, "duration", "asc"))[0]).toBe("b-old-short");
+  });
+
+  it("orders by title alphabetically, not by code point", () => {
+    const accented = [v({ title: "Zebra" }), v({ title: "Ábel" }), v({ title: "alma" })];
+    expect(titles(sortYtResults(accented, "title", "asc"))).toEqual(["Ábel", "alma", "Zebra"]);
+  });
+
+  it("sinks results with no value to the END in both directions", () => {
+    // YouTube does not always report a duration; "unknown" is not "the shortest".
+    const mixed = [
+      v({ title: "unknown", duration_seconds: null }),
+      v({ title: "long", duration_seconds: 900 }),
+      v({ title: "short", duration_seconds: 60 }),
+    ];
+    expect(titles(sortYtResults(mixed, "duration", "desc"))).toEqual(["long", "short", "unknown"]);
+    expect(titles(sortYtResults(mixed, "duration", "asc"))).toEqual(["short", "long", "unknown"]);
+  });
+
+  it("keeps the provider's ranking inside a tie, in both directions", () => {
+    // Flipping the direction must reverse the RANKING, not shuffle equally-ranked hits around.
+    const tied = [
+      v({ title: "first", view_count: 100 }),
+      v({ title: "second", view_count: 100 }),
+      v({ title: "third", view_count: 5 }),
+    ];
+    expect(titles(sortYtResults(tied, "popular", "desc"))).toEqual(["first", "second", "third"]);
+    expect(titles(sortYtResults(tied, "popular", "asc"))).toEqual(["third", "first", "second"]);
+  });
+
+  it("does not reorder anything for a key it cannot honour", () => {
+    // A pref stored before this view offered a control can name `shuffle` or `priority`.
+    expect(titles(sortYtResults(RESULTS, "priority", "desc"))).toEqual(titles(RESULTS));
+    expect(titles(sortYtResults(RESULTS, "shuffle", "desc"))).toEqual(titles(RESULTS));
+  });
+
+  it("does not mutate the array it was given", () => {
+    const input = [...RESULTS];
+    sortYtResults(input, "date", "asc");
+    expect(titles(input)).toEqual(titles(RESULTS));
+  });
+});
diff --git a/frontend/src/lib/nav.ts b/frontend/src/lib/nav.ts
index e0bb4407..61f07057 100644
--- a/frontend/src/lib/nav.ts
+++ b/frontend/src/lib/nav.ts
@@ -12,3 +12,20 @@ export function setNavigator(fn: (p: Page) => void): void {
 export function navigateTo(p: Page): void {
   _navigate?.(p);
 }
+
+/** Should this click be handled IN-APP, or left to the browser?
+ *
+ * An anchor that ALSO navigates in-app has to keep the browser's own gestures working — Ctrl/Cmd-click
+ * and Shift-click open a tab/window, and middle-click arrives as `auxclick` and never reaches React's
+ * `onClick` at all (the `button !== 0` arm is belt-and-braces for synthetic events). Otherwise the
+ * thing looks like a link and behaves like a button, which is what the channel name in the player did.
+ * One predicate, so a second such link cannot forget an arm. */
+export function isPlainLeftClick(e: {
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+  button: number;
+}): boolean {
+  return !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey && e.button === 0;
+}
diff --git a/frontend/src/lib/playerQueue.test.ts b/frontend/src/lib/playerQueue.test.ts
new file mode 100644
index 00000000..3add3a90
--- /dev/null
+++ b/frontend/src/lib/playerQueue.test.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { afterRemoval } from "./playerQueue";
+import type { Video } from "./api";
+
+// "Delete" from inside the player (the owner asked for it: today the only way to drop a video from a
+// playlist is the Playlists module). The removal itself is the parent's — this is the half the player
+// owns, because only the player knows which item is playing: its launch queue is frozen at mount, so
+// nothing outside can take the item out for it.
+const v = (id: string): Video => ({ id }) as Video;
+const ids = (q: Video[]) => q.map((x) => x.id);
+
+describe("afterRemoval", () => {
+  it("plays the item that followed the one you removed", () => {
+    const q = [v("a"), v("b"), v("c")];
+    const next = afterRemoval(q, 1, "b");
+    expect(next).not.toBeNull();
+    expect(next!.playingId).toBe("c");
+    expect(ids(next!.queue)).toEqual(["a", "c"]);
+  });
+
+  it("steps back to the new last item when the last one goes", () => {
+    // There is no "next" after the end — falling off it would leave the player on nothing.
+    const q = [v("a"), v("b"), v("c")];
+    const next = afterRemoval(q, 2, "c");
+    expect(next!.playingId).toBe("b");
+    expect(ids(next!.queue)).toEqual(["a", "b"]);
+  });
+
+  it("drops the removed item from the queue, so prev/next cannot step back onto it", () => {
+    const q = [v("a"), v("b"), v("c")];
+    expect(ids(afterRemoval(q, 0, "a")!.queue)).not.toContain("a");
+  });
+
+  it("says nothing is left when the list runs out (the player closes)", () => {
+    expect(afterRemoval([v("only")], 0, "only")).toBeNull();
+    expect(afterRemoval([], 0, "gone")).toBeNull();
+    expect(afterRemoval(undefined, 0, "gone")).toBeNull();
+  });
+
+  it("survives an index that no longer points inside the shortened queue", () => {
+    // The index comes from the frozen queue; nothing guarantees it is still in range afterwards.
+    const q = [v("a"), v("b")];
+    const next = afterRemoval(q, 5, "b");
+    expect(next!.playingId).toBe("a");
+  });
+
+  it("is a no-op-shaped answer when the id is not in the queue at all", () => {
+    const q = [v("a"), v("b")];
+    const next = afterRemoval(q, 0, "not-here");
+    expect(ids(next!.queue)).toEqual(["a", "b"]);
+    expect(next!.playingId).toBe("a");
+  });
+});
diff --git a/frontend/src/lib/playerQueue.ts b/frontend/src/lib/playerQueue.ts
new file mode 100644
index 00000000..2eac82ce
--- /dev/null
+++ b/frontend/src/lib/playerQueue.ts
@@ -0,0 +1,30 @@
+import type { Video } from "./api";
+
+// What the player does with its queue after the item it is PLAYING is removed from the list it was
+// opened from. The player's launch queue is frozen at mount (see PlayerModal), so nothing external
+// can take the item out for it: leaving it in would let prev/next step back onto a video that no
+// longer exists, and unmounting the player instead would drop you out of the list you are triaging.
+//
+// Pure, because the decision is the whole of the behaviour: which item plays next, and when there is
+// nothing left to play.
+export interface AfterRemoval {
+  /** The queue with the removed item gone. */
+  queue: Video[];
+  /** The item to play next. */
+  playingId: string;
+}
+
+/** `null` means nothing is left — the caller closes the player.
+ *
+ * The next item is the one that FOLLOWED the removed one (that is what "delete and keep going"
+ * means when you are working down a list), clamped to the end when the last item goes. */
+export function afterRemoval(
+  queue: Video[] | undefined,
+  index: number,
+  victimId: string,
+): AfterRemoval | null {
+  const rest = (queue ?? []).filter((v) => v.id !== victimId);
+  if (rest.length === 0) return null;
+  const next = rest[Math.min(Math.max(index, 0), rest.length - 1)]!;
+  return { queue: rest, playingId: next.id };
+}

From cf7ec5e9ec61e58b09aed17209d70ae8aa30e184 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 00:52:59 +0200
Subject: [PATCH 08/52] =?UTF-8?q?fix(plex):=20the=20subtitle=20extractor's?=
 =?UTF-8?q?=20seams=20=E2=80=94=20doubled=20cues,=20a=20truncated=20track?=
 =?UTF-8?q?=20cached=20as=20whole,=20a=20poll=20that=20respawned=20ffmpeg?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review of the bug-hunt round (R1). The background extractor from ed4ab4e1 held, but its seams
did not:

- Window + full pass doubled every cue in the first hour. merge_vtt de-duplicated on the raw timing
  text, and the two passes spell a timestamp differently (shift_vtt writes HH:MM:SS.mmm, ffmpeg's
  webvtt muxer drops the hour below 1 h; shift_vtt(-0.0) never normalised the full pass). Timing is
  now parsed and re-emitted canonically, keyed with the cue text so two cues sharing a time survive.
- A full pass that exited non-zero was published as complete: "ready" forever, subtitles ending
  where ffmpeg died, and no eviction to ever retry. It now covers only up to its last cue, is never
  complete, and records the failure memo.
- The window's dedup identity held the live playhead, so every 1 s poll queued another read of the
  file. It is keyed on the track now, and a queued job re-checks coverage before reading anything.
- A sidecar track waited behind an unrelated embedded full pass (the full job is per item). Its
  window job now fetches it whole — one small request.
- The <track> fetch ran the scheduler at position 0: an unrequested window over the head of the file,
  and a refusal of a window that was on disk. It is a pure read of the cache now.
- publish() is serialised (a lost update became permanent once complete was set); the pool is shut
  down and running ffmpeg children killed at app shutdown (they held interpreter exit for minutes);
  ?at=inf is a 422, not a 500; and both subtitle routes use current_user instead of the cookie-only
  poster gate, which let a suspended or epoch-revoked session keep scheduling reads (pre-existing).

_extract_and_publish finally has tests of its own — every earlier test stubbed it out. 19 mutations,
each red on the assertion that names it.
---
 backend/app/main.py                         |   4 +
 backend/app/plex/subtitles.py               | 193 ++++++++++---
 backend/app/routes/plex/playback.py         |  37 ++-
 backend/tests/test_plex_subtitle_auth.py    |  44 +++
 backend/tests/test_plex_subtitle_prepare.py | 298 ++++++++++++++++++--
 frontend/src/lib/api/plex.ts                |   3 +-
 6 files changed, 508 insertions(+), 71 deletions(-)
 create mode 100644 backend/tests/test_plex_subtitle_auth.py

diff --git a/backend/app/main.py b/backend/app/main.py
index 1386116c..7c2e6038 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -27,6 +27,7 @@ from app import state
 from app.config import settings
 from app.db import SessionLocal
 from app.plex import stream as plex_stream
+from app.plex import subtitles as plex_subtitles
 from app.routes import (
     admin,
     audit as audit_routes,
@@ -90,6 +91,9 @@ async def lifespan(app: FastAPI):
         with suppress(asyncio.CancelledError):
             await sweep
         shutdown_scheduler()
+        # Kills a running subtitle extraction: its worker would otherwise hold interpreter exit for
+        # the rest of the read (see plex_subtitles.shutdown).
+        plex_subtitles.shutdown()
 
 
 async def _sweep_hls_orphans() -> None:
diff --git a/backend/app/plex/subtitles.py b/backend/app/plex/subtitles.py
index ea685cfd..8c749c1c 100644
--- a/backend/app/plex/subtitles.py
+++ b/backend/app/plex/subtitles.py
@@ -245,35 +245,77 @@ def covers(ranges: list[list[float]], at: float) -> bool:
 def merge_vtt(*sources: str) -> str:
     """Union of the cue blocks of several absolute-time VTTs, ordered by start time.
 
-    Two extraction passes over the same file emit identical cues for the region they share, so
-    de-duplication keys off the TIMING line — the one part of a cue that identifies it uniquely and
-    that neither pass can renumber (ffmpeg's webvtt muxer writes no cue identifiers)."""
+    Two extraction passes over the same file emit identical cues for the region they share, so they
+    are de-duplicated — but NOT on the raw timing text. The two passes do not spell a timestamp the
+    same way: a window comes back through `shift_vtt`, which always writes `HH:MM:SS.mmm`, while a
+    full pass is ffmpeg's own output, and its webvtt muxer drops the hour below one hour
+    (`10:00.123`). Keyed on the text, every cue of a window in the first hour survived twice and the
+    viewer saw each line stacked on itself. So each timing line is parsed and re-emitted in one
+    canonical form, and the key is that canonical timing PLUS the cue text: two different cues that
+    happen to share a time (two speakers, a sign over dialogue) are both kept."""
     seen: set[str] = set()
     cues: list[tuple[float, str]] = []
     for src in sources:
         for block in re.split(r"\n[ \t]*\n", src or ""):
-            b = block.strip()
-            if not b or "-->" not in b:
+            canon = _canonical_cue(block.strip())
+            if canon is None:
                 continue  # header / NOTE / STYLE — the merged file gets its own single header
-            timing = next(ln for ln in b.split("\n") if "-->" in ln)
-            if timing in seen:
+            start, key, text = canon
+            if key in seen:
                 continue
-            seen.add(timing)
-            try:
-                start = _vtt_ts_to_s(timing.partition("-->")[0].strip())
-            except (ValueError, IndexError):
-                continue
-            cues.append((start, b))
+            seen.add(key)
+            cues.append((start, text))
     cues.sort(key=lambda c: c[0])
     return "WEBVTT\n\n" + "\n\n".join(b for _, b in cues) + "\n"
 
 
+def _canonical_cue(block: str) -> tuple[float, str, str] | None:
+    """(start seconds, identity, the block with its timing line canonicalised) — or None for a block
+    that is not a cue. The identity leaves out anything before the timing line (an SRT-style cue
+    number), which is a label, not content."""
+    lines = block.split("\n")
+    for i, ln in enumerate(lines):
+        if "-->" not in ln:
+            continue
+        left, _, right = ln.partition("-->")
+        rparts = right.strip().split(None, 1)
+        settings = (" " + rparts[1]) if len(rparts) > 1 else ""
+        try:
+            st = _vtt_ts_to_s(left.strip())
+            en = _vtt_ts_to_s(rparts[0])
+        except (ValueError, IndexError):
+            return None
+        lines[i] = f"{_vtt_s_to_ts(st)} --> {_vtt_s_to_ts(en)}{settings}"
+        return st, "\n".join(lines[i:]), "\n".join(lines)
+    return None
+
+
+def _last_cue_end(vtt: str) -> float:
+    """Where the last cue of a VTT ends — how far a pass that died early provably got."""
+    end = 0.0
+    for ln in vtt.split("\n"):
+        if "-->" not in ln:
+            continue
+        try:
+            end = max(end, _vtt_ts_to_s(ln.partition("-->")[2].strip().split(None, 1)[0]))
+        except (ValueError, IndexError):
+            continue
+    return end
+
+
 def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) -> None:
-    """Merge a freshly extracted region into the cached track and widen its covered ranges."""
-    old = cache_read(key)
-    old_ranges, was_complete = read_meta(key)
-    cache_write(key, merge_vtt(old or "", vtt))
-    _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
+    """Merge a freshly extracted region into the cached track and widen its covered ranges.
+
+    A read-merge-write, so it runs under `_PUBLISH_LOCK`: two jobs publish into the same keys (a
+    window and the full pass, and every embedded track of the file rides each of them), and without
+    the lock the later writer drops whatever the earlier one merged — permanently, once `complete` is
+    set. It is also the only writer of the cache files, which is what keeps their fixed `.tmp`
+    staging names safe."""
+    with _PUBLISH_LOCK:
+        old = cache_read(key)
+        old_ranges, was_complete = read_meta(key)
+        cache_write(key, merge_vtt(old or "", vtt))
+        _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
 
 
 # --- background extraction ----------------------------------------------------------------------
@@ -298,6 +340,9 @@ _POOL = ThreadPoolExecutor(max_workers=3, thread_name_prefix="plex-subs")
 _LOCK = threading.Lock()
 _INFLIGHT: set[tuple] = set()
 _FAILURES: dict[str, tuple[str, float]] = {}
+_PUBLISH_LOCK = threading.Lock()
+# The ffmpeg children currently running, so a shutdown can kill them (see `shutdown`).
+_PROCS: set[subprocess.Popen] = set()
 
 
 class SubtitleUnavailable(Exception):
@@ -328,6 +373,20 @@ def reset_state() -> None:
         _FAILURES.clear()
 
 
+def shutdown() -> None:
+    """Stop extracting, for the app's shutdown. The pool's workers are non-daemon threads and Python
+    joins them at interpreter exit — so a worker still inside a full pass (minutes on a big file, up
+    to EXTRACT_TIMEOUT_S) held the process open after uvicorn had stopped, until the container runtime
+    SIGKILLed it. Queued jobs are dropped and running ffmpeg children are killed, which returns their
+    workers at once. Nothing that matters is lost: a publish is an atomic rename, and an interrupted
+    track is simply extracted again on the next poll."""
+    _POOL.shutdown(wait=False, cancel_futures=True)
+    with _LOCK:
+        procs = list(_PROCS)
+    for p in procs:
+        p.kill()
+
+
 def _fail(key: str, code: str) -> None:
     with _LOCK:
         _FAILURES[key] = (code, time.monotonic())
@@ -362,25 +421,57 @@ def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
     return {"state": "partial" if covered else "preparing", "code": None, "gen": generation(key)}
 
 
+def cached_track(rating_key: str, sub_ord: int) -> tuple[str | None, str | None]:
+    """What the <track> fetch can serve RIGHT NOW, scheduling nothing: the cached VTT (whatever it
+    covers), else the recent failure that explains why there is none.
+
+    Scheduling belongs to `ensure` — the status poll, which knows where the viewer is. The fetch does
+    not: when it scheduled too, it judged readiness at position 0, so a viewer who resumed an hour in
+    got an unrequested window over the head of the file (plus a remount when it landed), and with a
+    failure memo alive it was refused a window that WAS on disk while the poll called it showable."""
+    key = cache_key(rating_key, sub_ord)
+    hit = cache_read(key)
+    return (hit, None) if hit is not None else (None, _recent_failure(key))
+
+
 def _schedule(rating_key: str, sub_ord: int, at: float, want_window: bool) -> None:
     """Kick off the jobs this track still needs: the window that makes it watchable now, and the one
     full pass that makes it complete. Each is deduplicated by identity, so a 1 s status poll (or a
-    second viewer) joins the running job instead of starting another ffmpeg."""
+    second viewer) joins the running job instead of starting another ffmpeg.
+
+    A window's identity is its TRACK, never its position. The poll sends the live playhead, so a
+    position-keyed window minted a new identity every second and queued one more read of the file per
+    poll until the first window landed. One window per track is in flight at a time; a seek past it
+    is picked up by the next poll after it publishes. The full pass is per ITEM, because one read
+    fans out to every embedded text track of the file."""
     jobs: list[tuple[tuple, float | None]] = []
     if want_window:
-        w_start = max(0.0, at - WINDOW_PRE_S)
-        jobs.append((("win", rating_key, round(w_start)), w_start))
+        jobs.append((("win", rating_key, sub_ord), max(0.0, at - WINDOW_PRE_S)))
     jobs.append((("full", rating_key), None))
     for ident, window_start in jobs:
         with _LOCK:
             if ident in _INFLIGHT:
                 continue
             _INFLIGHT.add(ident)
-        _POOL.submit(_run, ident, rating_key, sub_ord, window_start)
+        _POOL.submit(_run, ident, rating_key, sub_ord, window_start, at)
 
 
-def _run(ident: tuple, rating_key: str, sub_ord: int, window_start: float | None) -> None:
+def _already_done(key: str, window_start: float | None, at: float) -> bool:
+    """A queued job looks again before it reads anything. While it waited, another job may have
+    covered it: every embedded track rides each pass over its file, so a window for one language also
+    publishes the others."""
+    if not _vtt_path(key).exists():
+        return False
+    ranges, complete = read_meta(key)
+    return complete or (window_start is not None and covers(ranges, at))
+
+
+def _run(
+    ident: tuple, rating_key: str, sub_ord: int, window_start: float | None, at: float
+) -> None:
     try:
+        if _already_done(cache_key(rating_key, sub_ord), window_start, at):
+            return
         _extract_and_publish(rating_key, sub_ord, window_start)
     except SubtitleUnavailable as e:
         _fail(cache_key(rating_key, sub_ord), e.code)
@@ -422,9 +513,11 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
         want = subs[sub_ord]
         if _is_bitmap(want):
             raise SubtitleUnavailable("bitmap")
-        if want.get("key"):  # external sidecar → one fetch, always the complete track
-            if window_start is not None:
-                return  # nothing to window — the full job serves it in a single fetch
+        if want.get("key"):
+            # An external sidecar is one small fetch from Plex, never a read of the media file, so a
+            # window job fetches the whole thing too. It must not be left to the full job: that
+            # identity is per ITEM (the embedded fan-out shares it), so a sidecar picked while an
+            # embedded track's full pass was running sat behind that pass for minutes.
             vtt = _sidecar_vtt(db, want)
             publish(cache_key(rating_key, sub_ord), vtt, (0.0, _FULL_END_S), True)
             return
@@ -443,13 +536,22 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
     start = window_start or 0.0
     length = (WINDOW_LEN_S + WINDOW_PRE_S) if window_start is not None else None
     end = _FULL_END_S if length is None else start + length
-    for emb_ord, vtt in _ffmpeg_extract(str(src), sorted(targets), window_start, length).items():
+    texts, clean = _ffmpeg_extract(str(src), sorted(targets), window_start, length)
+    for emb_ord, vtt in texts.items():
+        key = cache_key(rating_key, targets[emb_ord])
+        # A pass that exited non-zero holds only what ffmpeg reached before it died. Claim no more
+        # than its last cue, never call it complete, and remember the failure: published as complete,
+        # the track read "ready" for good while its subtitles stopped wherever ffmpeg did (the cache
+        # has no eviction, so nothing would ever have extracted it again).
+        covered_end = end if clean else start + _last_cue_end(vtt)
         publish(
-            cache_key(rating_key, targets[emb_ord]),
+            key,
             shift_vtt(vtt, -start),  # zero-based window clock → absolute cue times
-            (start, end),
-            length is None,
+            (start, covered_end),
+            clean and length is None,
         )
+        if not clean:
+            _fail(key, "extract_failed")
 
 
 def _sidecar_vtt(db: Session, stream: dict) -> str:
@@ -470,14 +572,16 @@ def _sidecar_vtt(db: Session, stream: dict) -> str:
 
 def _ffmpeg_extract(
     src: str, emb_ords: list[int], start: float | None, length: float | None
-) -> dict[int, str]:
+) -> tuple[dict[int, str], bool]:
     """Extract several embedded subtitle streams to WebVTT in ONE ffmpeg run (= one read of the file).
+    Returns the texts and whether ffmpeg exited cleanly — a non-zero exit can still leave partial
+    output, which is worth publishing but must never be taken for the whole track.
 
     `start`/`length` bound the read to a window. Without `-copyts` the cues come out on a zero-based
     clock (the caller shifts them back) — which is exactly why `-copyts` is absent: with it ffmpeg
     ignores `-t` and reads the whole container anyway (measured)."""
     if not emb_ords:
-        return {}
+        return {}, True
     with tempfile.TemporaryDirectory(prefix="plexsub-") as tmpdir:
         cmd = ["ffmpeg", "-nostdin", "-loglevel", "error"]
         if start:
@@ -489,7 +593,22 @@ def _ffmpeg_extract(
             if length is not None:
                 cmd += ["-t", f"{length:.3f}"]
             cmd += ["-f", "webvtt", "-y", str(out)]
-        r = subprocess.run(cmd, capture_output=True, timeout=EXTRACT_TIMEOUT_S)
+        # Popen rather than run(): the child is registered so `shutdown` can kill it.
+        proc = subprocess.Popen(
+            cmd, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE
+        )
+        with _LOCK:
+            _PROCS.add(proc)
+        try:
+            try:
+                _, err = proc.communicate(timeout=EXTRACT_TIMEOUT_S)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.communicate()
+                raise
+        finally:
+            with _LOCK:
+                _PROCS.discard(proc)
         got = {
             o: p.read_text(encoding="utf-8", errors="replace")
             for o, p in outs.items()
@@ -497,7 +616,7 @@ def _ffmpeg_extract(
         }
     if not got:
         raise SubtitleUnavailable("extract_failed")
-    if r.returncode != 0:
-        # Partial output with a non-zero exit still beats nothing (a later pass widens it) — say so.
-        log.warning("ffmpeg subtitle pass exited %s: %s", r.returncode, (r.stderr or b"")[:200])
-    return got
+    clean = proc.returncode == 0
+    if not clean:
+        log.warning("ffmpeg subtitle pass exited %s: %s", proc.returncode, (err or b"")[:200])
+    return got, clean
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index c6e6d1dd..35fab8f3 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -10,6 +10,7 @@ from fastapi import (
     BackgroundTasks,
     Depends,
     HTTPException,
+    Query,
     Request,
     Response,
 )
@@ -87,40 +88,52 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
     return imgcache.response(data, ct)
 
 
+# Both subtitle routes authenticate with the full `current_user`, not the cookie-only
+# `_require_session` the image proxies use. That lighter gate exists for bursts of low-sensitivity
+# poster fetches and skips the is_active / is_suspended / session-epoch checks — acceptable for a
+# poster, not for a route that starts reads of the media library: a suspended or "log out
+# everywhere"-revoked cookie kept scheduling them. They are not bursty (one poll a second, one fetch
+# per track), so the DB user-load costs nothing that matters.
+
+
 @router.get("/subtitle/{rating_key}/{sub_ord}/status")
-def subtitle_status(rating_key: str, sub_ord: int, request: Request, at: float = 0.0) -> dict:
+def subtitle_status(
+    rating_key: str,
+    sub_ord: int,
+    user: User = Depends(current_user),
+    # Bounded: a non-finite position used to reach the scheduler's arithmetic and 500.
+    at: float = Query(0.0, ge=0.0, allow_inf_nan=False),
+) -> dict:
     """Is this subtitle track showable yet — and if not, get it moving. Extraction runs in the
     background (see plex/subtitles.py for the measurements that forced it there), so the player polls
     this while it waits instead of hanging on a <track> that will not load for a minute or more.
 
     `at` is the viewer's absolute position: the extractor windows around it, so what gets read first
     is the part actually about to be watched."""
-    _require_session(request)
     return subtitles.ensure(rating_key, sub_ord, at)
 
 
 @router.get("/subtitle/{rating_key}/{sub_ord}")
 def subtitle(
-    rating_key: str, sub_ord: int, request: Request, offset: float = 0.0, at: float = 0.0
+    rating_key: str, sub_ord: int, user: User = Depends(current_user), offset: float = 0.0
 ) -> Response:
     """Serve the ord-th subtitle track as WebVTT for the browser's <track> — so choosing a subtitle
     overlays it directly (no HLS re-mux / session restart). Handles EXTERNAL sidecar subs (fetched
     from Plex via the stream `key` — the old `-map 0:s` broke on these since they're not in the file)
     AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached.
 
-    NEVER extracts inline. A cold track answers 202 and the extraction proceeds in the background; the
-    player mounts the <track> only once /status says there is something to show, so in practice this
-    is only ever hit warm (or on a cache eviction race, which the 202 sends back to polling)."""
-    _require_session(request)
+    A pure READ: it serves whatever is cached and schedules nothing — the status poll owns that,
+    because only it knows where the viewer is (see `subtitles.cached_track`). The player mounts the
+    <track> only once /status says there is something to show, so in practice this is only ever hit
+    warm; on a cache eviction race the 202 sends the player back to polling."""
     # The cached VTT holds ABSOLUTE cue times (per rk+ord); the per-session cue-shift is applied on
     # the way out, so a resume/seek to any offset reuses the same track (no cache-per-offset explosion).
-    st = subtitles.ensure(rating_key, sub_ord, at)
-    if st["state"] == "failed":
+    hit, code = subtitles.cached_track(rating_key, sub_ord)
+    if hit is None and code:
         raise HTTPException(
-            status_code=subtitles.UNAVAILABLE_STATUS.get(st["code"], 422),
-            detail={"code": "subtitle", "reason": st["code"]},
+            status_code=subtitles.UNAVAILABLE_STATUS.get(code, 422),
+            detail={"code": "subtitle", "reason": code},
         )
-    hit = subtitles.cache_read(subtitles.cache_key(rating_key, sub_ord))
     if hit is None:
         return Response(
             status_code=202, media_type="application/json", content='{"state":"preparing"}'
diff --git a/backend/tests/test_plex_subtitle_auth.py b/backend/tests/test_plex_subtitle_auth.py
new file mode 100644
index 00000000..0ddb5ee8
--- /dev/null
+++ b/backend/tests/test_plex_subtitle_auth.py
@@ -0,0 +1,44 @@
+"""The subtitle routes must refuse a session the rest of the app refuses.
+
+They used to sit behind `_require_session`, the cookie-only gate the poster proxies use — a signed
+cookie was enough, with none of `current_user`'s checks (is_active, is_suspended, the session epoch
+that "log out everywhere" bumps). Fine for a poster; not for a route that starts reads of the media
+library. Found by the 2026-09 bug-hunt deep-review; the gate itself pre-dates that round.
+"""
+
+from fastapi.testclient import TestClient
+
+import app.auth as auth
+import app.state as app_state
+from app.db import get_db
+from app.main import app
+from app.plex import subtitles
+from app.routes.plex import playback
+
+
+class _NoPool:
+    def __init__(self) -> None:
+        self.jobs: list = []
+
+    def submit(self, fn, *args) -> None:
+        self.jobs.append((fn, args))
+
+
+def test_a_suspended_account_cannot_drive_the_subtitle_extractor(
+    db, make_user, override_dep, monkeypatch, tmp_path
+):
+    user = make_user(is_suspended=True)
+    override_dep(get_db, lambda: db)
+    monkeypatch.setattr(app_state, "_configured_cache", True)
+    # A validly SIGNED cookie for that account — which is all the old gate looked at.
+    for mod in (auth, playback):
+        monkeypatch.setattr(mod, "resolved_user_id", lambda request: (user.id, True))
+    monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path)
+    pool = _NoPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    subtitles.reset_state()
+
+    client = TestClient(app)
+    assert client.get("/api/plex/subtitle/98614/0/status?at=600").status_code == 401
+    assert client.get("/api/plex/subtitle/98614/0").status_code == 401
+    assert pool.jobs == [], "a refused session still scheduled an extraction"
diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
index 128a84eb..633c2587 100644
--- a/backend/tests/test_plex_subtitle_prepare.py
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -12,21 +12,27 @@ thread sat with it), and picking the second language cost the whole read again.
 
 These tests pin the three things that fixes it: the request never waits for ffmpeg, the extraction
 publishes a window around the playhead before the whole track, and one ffmpeg run covers every
-embedded text track. Pure — no Postgres, no ffmpeg.
+embedded text track — plus what the deep-review of that fix found (cues doubled at the window/full
+seam, a truncated pass cached as complete, a poll that respawned ffmpeg every second, a sidecar stuck
+behind an unrelated pass). Pure — no Postgres, no ffmpeg (the auth half is in
+test_plex_subtitle_auth.py, which needs the DB).
 """
 
 import subprocess
+import sys
 import threading
 import time
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 from fastapi.testclient import TestClient
 
 import app.state as app_state
+from app.auth import current_user
 from app.main import app
 from app.plex import subtitles
-from app.routes.plex import playback
 
 
 @pytest.fixture(autouse=True)
@@ -39,10 +45,10 @@ def _isolated_cache(tmp_path, monkeypatch):
 
 
 @pytest.fixture
-def client(monkeypatch) -> TestClient:
-    # The subtitle endpoints authenticate off the signed session cookie directly (not a FastAPI
-    # dependency), so there is no dependency_overrides hook to use.
-    monkeypatch.setattr(playback, "resolved_user_id", lambda request: (1, None))
+def client(monkeypatch, override_dep) -> TestClient:
+    # Neither route reads the user; the real `current_user` (and what it rejects) is pinned in
+    # test_plex_subtitle_auth.py against the DB.
+    override_dep(current_user, lambda: SimpleNamespace(id=1))
     monkeypatch.setattr(app_state, "_configured_cache", True)  # pass the instance-setup gate, no DB
     return TestClient(app)
 
@@ -92,15 +98,15 @@ def test_a_cold_track_answers_at_once_instead_of_waiting_for_ffmpeg(client, monk
     monkeypatch.setattr(subtitles, "_extract_and_publish", _slow)
     try:
         t0 = time.monotonic()
-        resp = client.get("/api/plex/subtitle/98614/0")
+        st = client.get("/api/plex/subtitle/98614/0/status")
         elapsed = time.monotonic() - t0
-        assert resp.status_code == 202, resp.text
+        assert st.status_code == 200 and st.json()["state"] == "preparing", st.text
         assert elapsed < 2.0, f"the request waited {elapsed:.1f}s on the extraction"
         assert started.wait(timeout=5), "the extraction never started in the background"
-        # …and the status endpoint answers just as fast while that extraction is still running.
+        # …and the <track> fetch answers just as fast while that extraction is still running.
         t0 = time.monotonic()
-        st = client.get("/api/plex/subtitle/98614/0/status")
-        assert st.status_code == 200 and st.json()["state"] == "preparing"
+        resp = client.get("/api/plex/subtitle/98614/0")
+        assert resp.status_code == 202, resp.text
         assert time.monotonic() - t0 < 2.0
     finally:
         release.set()
@@ -114,7 +120,7 @@ def test_a_burst_of_polls_starts_one_window_and_one_full_pass(monkeypatch):
     for _ in range(5):
         subtitles.ensure("98614", 0, at=600.0)
     assert len(pool.jobs) == 2  # one window (at 600 s) + the one full pass
-    # submit(_run, ident, rating_key, sub_ord, window_start) — the last arg is what distinguishes them
+    # submit(_run, ident, rating_key, sub_ord, window_start, at) — window_start tells them apart
     assert [a[3] for _, a in pool.jobs] == [570.0, None]  # the window first, then the full pass
 
 
@@ -191,18 +197,33 @@ def test_an_unshowable_track_says_why_and_maps_to_a_status(client, monkeypatch):
 # --- the ffmpeg pass itself ---------------------------------------------------------------------
 
 
-def _capture_ffmpeg(monkeypatch) -> list[list[str]]:
+class _FakeFfmpeg:
+    """Stands in for the ffmpeg child: writes the outputs its argv asked for, exits with `returncode`."""
+
+    def __init__(self, cmd: list[str], returncode: int) -> None:
+        self.cmd, self.returncode = cmd, returncode
+
+    def communicate(self, timeout=None):
+        for i, arg in enumerate(self.cmd):
+            if arg == "-y":
+                Path(self.cmd[i + 1]).write_text(
+                    _vtt(_cue("00:01.000", "00:02.000", "hi")), "utf-8"
+                )
+        return b"", b""
+
+    def kill(self) -> None:
+        pass
+
+
+def _capture_ffmpeg(monkeypatch, returncode: int = 0) -> list[list[str]]:
     """Record the argv of each ffmpeg run and satisfy it by writing the outputs it asked for."""
     runs: list[list[str]] = []
 
-    def _fake_run(cmd, **kwargs):
+    def _fake_popen(cmd, **kwargs):
         runs.append(cmd)
-        for i, arg in enumerate(cmd):
-            if arg == "-y":
-                Path(cmd[i + 1]).write_text(_vtt(_cue("00:01.000", "00:02.000", "hi")), "utf-8")
-        return subprocess.CompletedProcess(cmd, 0, b"", b"")
+        return _FakeFfmpeg(cmd, returncode)
 
-    monkeypatch.setattr(subtitles.subprocess, "run", _fake_run)
+    monkeypatch.setattr(subtitles.subprocess, "Popen", _fake_popen)
     return runs
 
 
@@ -210,12 +231,20 @@ def test_one_ffmpeg_run_extracts_every_embedded_text_track(monkeypatch):
     """The read is the cost and it is SHARED. Extracting one track at a time is what made picking
     Hungarian cost a full pass and then switching to English cost another one."""
     runs = _capture_ffmpeg(monkeypatch)
-    out = subtitles._ffmpeg_extract("/plex-media/f.mkv", [0, 1], None, None)
+    out, clean = subtitles._ffmpeg_extract("/plex-media/f.mkv", [0, 1], None, None)
     assert len(runs) == 1, "each extra ffmpeg run is another full read of the file"
-    assert set(out) == {0, 1}
+    assert set(out) == {0, 1} and clean
     assert runs[0].count("-map") == 2
 
 
+def test_a_non_zero_exit_is_reported_even_when_it_left_output(monkeypatch):
+    """ffmpeg can die partway and still leave a VTT behind. That text is worth keeping — but the
+    caller has to be TOLD, or it publishes a truncated track as the whole thing."""
+    _capture_ffmpeg(monkeypatch, returncode=1)
+    out, clean = subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], None, None)
+    assert out and not clean
+
+
 def test_a_windowed_pass_bounds_the_read_and_never_uses_copyts(monkeypatch):
     """`-copyts` is the trap: with it ffmpeg IGNORES -t and reads the whole container anyway
     (measured — a [0, 600 s] window still took the full 145 s). So the window is extracted on a
@@ -261,3 +290,230 @@ def test_a_cached_vtt_from_an_older_build_counts_as_complete(tmp_path):
     Reading one as "covers nothing" would re-extract every already-cached track after the upgrade."""
     (tmp_path / "sub_98614_0.vtt").write_text(_vtt(_cue("00:01.000", "00:02.000", "x")), "utf-8")
     assert subtitles.read_meta("sub_98614_0") == ([[0.0, 1_000_000_000.0]], True)
+
+
+# --- the deep-review round: the seams between the window and the full pass ----------------------
+
+
+def test_a_window_and_the_full_pass_do_not_double_a_cue():
+    """THE doubled-subtitle bug. The two passes spell the same timestamp differently — a window comes
+    back through shift_vtt (always HH:MM:SS.mmm), a full pass is ffmpeg's own output, whose webvtt
+    muxer drops the hour below one hour — so de-duplicating on the text kept both, and every cue of a
+    window in the first hour was on screen twice."""
+    window = subtitles.shift_vtt(_vtt(_cue("00:30.123", "00:32.000", "hello")), -570.0)
+    full = _vtt(_cue("10:00.123", "10:02.000", "hello"))  # ffmpeg's spelling of the same cue
+    merged = subtitles.merge_vtt(window, full)
+    assert merged.count("-->") == 1, merged
+    assert "00:10:00.123 --> 00:10:02.000" in merged  # one canonical spelling in the served file
+
+
+def test_two_different_cues_at_the_same_time_are_both_kept():
+    """De-duplication is by timing AND text: a sign and a line of dialogue can share a timestamp."""
+    both = _vtt(_cue("00:10.000", "00:12.000", "sign"), _cue("00:10.000", "00:12.000", "dialogue"))
+    merged = subtitles.merge_vtt(both, both)
+    assert merged.count("-->") == 2 and "sign" in merged and "dialogue" in merged
+
+
+class _NullSession:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, *exc):
+        return False
+
+
+# A file's subtitle streams as Plex lists them: a downloaded sidecar first (no `index` — it is not in
+# the file), then the embedded ones, one of them a bitmap track that can never become text.
+_STREAMS = [
+    {"key": "/library/streams/1", "codec": "srt"},  # sub_ord 0 — sidecar
+    {"index": 3, "codec": "subrip"},  # sub_ord 1 — embedded ordinal 0 (Hungarian)
+    {"index": 4, "codec": "pgs"},  # sub_ord 2 — embedded ordinal 1, bitmap
+    {"index": 5, "codec": "subrip"},  # sub_ord 3 — embedded ordinal 2 (English)
+]
+
+
+def _stub_item(monkeypatch, *, clean: bool = True, cues=("00:05.000", "00:07.000")):
+    """Everything around `_extract_and_publish` stubbed, so the function itself is what runs."""
+    monkeypatch.setattr(subtitles, "SessionLocal", _NullSession)
+    monkeypatch.setattr(
+        subtitles, "_text_streams", lambda db, rk: (SimpleNamespace(file_path="/f.mkv"), _STREAMS)
+    )
+    monkeypatch.setattr(
+        subtitles.plex_paths, "local_media_path", lambda db, fp: "/plex-media/f.mkv"
+    )
+    monkeypatch.setattr(
+        subtitles, "_sidecar_vtt", lambda db, s: _vtt(_cue("00:01.000", "00:03.000", "side"))
+    )
+    calls: list[tuple] = []
+
+    def _extract(src, emb_ords, start, length):
+        calls.append((list(emb_ords), start, length))
+        return {o: _vtt(_cue(*cues, f"track {o}")) for o in emb_ords}, clean
+
+    monkeypatch.setattr(subtitles, "_ffmpeg_extract", _extract)
+    return calls
+
+
+def test_one_window_publishes_every_embedded_text_track_at_absolute_time(monkeypatch):
+    """What `_extract_and_publish` itself is for — every other test stubs it out. One read over the
+    file's EMBEDDED text streams (the sidecar is not in the file and must not shift the `-map`
+    ordinals; the bitmap track is skipped), each published under its own sub_ord, and a window's
+    zero-based cues shifted back to where they sit in the film."""
+    calls = _stub_item(monkeypatch)
+    subtitles._extract_and_publish("98614", 3, 3570.0)
+    assert calls == [([0, 2], 3570.0, 330.0)], "one ffmpeg run over embedded ordinals 0 and 2"
+    english = subtitles.cache_read(subtitles.cache_key("98614", 3)) or ""
+    assert "00:59:35.000 --> 00:59:37.000" in english, english  # 3570 + 5 s
+    assert "track 2" in english
+    assert "track 0" in (subtitles.cache_read(subtitles.cache_key("98614", 1)) or "")
+    for never in (0, 2):  # the sidecar and the bitmap track come from nowhere in this pass
+        assert subtitles.cache_read(subtitles.cache_key("98614", never)) is None
+
+
+def test_a_full_pass_that_died_is_not_cached_as_the_whole_track(monkeypatch):
+    """A truncated full pass used to be published as complete: `ensure` answered "ready" forever, the
+    player stopped polling, and — the cache has no eviction — the subtitles simply ended wherever
+    ffmpeg had died, in every later session too. Now it covers what it provably reached, and the
+    rest of the film honestly reads as failed."""
+    _stub_item(monkeypatch, clean=False, cues=("39:58.000", "40:00.000"))
+    monkeypatch.setattr(subtitles, "_POOL", _ManualPool())
+    subtitles._extract_and_publish("98614", 3, None)
+    key = subtitles.cache_key("98614", 3)
+    assert subtitles.read_meta(key) == ([[0.0, 2400.0]], False)
+    assert subtitles.ensure("98614", 3, at=100.0)["state"] == "partial"
+    after = subtitles.ensure("98614", 3, at=3000.0)
+    assert (after["state"], after["code"]) == ("failed", "extract_failed")
+
+
+def test_polls_that_follow_the_playhead_join_one_window(monkeypatch):
+    """The poll sends the LIVE position, so it moves a second per poll. A window keyed on that
+    position was a new job every second — another read of the file per poll until the first landed."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    for at in (600.0, 601.0, 602.0, 603.0, 604.0):
+        subtitles.ensure("98614", 1, at=at)
+    assert len(pool.jobs) == 2, "one window + the one full pass"
+
+
+def test_a_queued_window_that_was_covered_meanwhile_reads_nothing(monkeypatch):
+    """Every embedded track rides each pass over its file, so by the time a queued window for one
+    language runs, another language's window may already have published it."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    calls = _stub_item(monkeypatch)
+    subtitles.ensure("98614", 3, at=600.0)
+    subtitles.publish(
+        subtitles.cache_key("98614", 3),
+        _vtt(_cue("10:00.000", "10:02.000", "x")),
+        (570.0, 900.0),
+        False,
+    )
+    pool.run_next()  # the window job
+    assert calls == []
+
+
+def test_a_sidecar_does_not_wait_behind_an_embedded_full_pass(monkeypatch):
+    """The full pass is one job per ITEM (the embedded fan-out shares it). A sidecar picked while an
+    embedded track's pass was running used to find that identity taken and wait out the whole read —
+    minutes — for a track that is one small fetch."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    _stub_item(monkeypatch)
+    subtitles._INFLIGHT.add(("full", "98614"))  # an embedded track's full pass is running
+    subtitles.ensure("98614", 0, at=600.0)
+    pool.run_all()
+    assert subtitles.ensure("98614", 0, at=600.0)["state"] == "ready"
+
+
+def test_publishes_into_one_track_do_not_lose_each_other(monkeypatch):
+    """`publish` is a read-merge-write. Two jobs publishing into the same track at once — the window
+    and the full pass both fan out to every embedded track — used to let the later writer drop the
+    earlier one's cues. Forced interleaving: the first publisher pauses right after its read."""
+    key = subtitles.cache_key("98614", 0)
+    real_read = subtitles.cache_read
+    paused, resume = threading.Event(), threading.Event()
+    reads = {"n": 0}
+
+    def _read(k):
+        reads["n"] += 1
+        out = real_read(k)
+        if reads["n"] == 1:
+            paused.set()
+            resume.wait(timeout=5)
+        return out
+
+    monkeypatch.setattr(subtitles, "cache_read", _read)
+    first = threading.Thread(
+        target=subtitles.publish,
+        args=(key, _vtt(_cue("00:10.000", "00:12.000", "alpha")), (0.0, 330.0), False),
+    )
+    first.start()
+    assert paused.wait(timeout=5)
+    second = threading.Thread(
+        target=subtitles.publish,
+        args=(key, _vtt(_cue("10:00.000", "10:02.000", "bravo")), (570.0, 900.0), False),
+    )
+    second.start()
+    time.sleep(0.3)  # without the lock, the second publisher finishes in here
+    resume.set()
+    first.join(timeout=5)
+    second.join(timeout=5)
+    merged = real_read(key) or ""
+    assert "alpha" in merged and "bravo" in merged, merged
+    assert subtitles.read_meta(key)[0] == [[0.0, 330.0], [570.0, 900.0]]
+
+
+def test_shutdown_kills_a_running_extraction(monkeypatch):
+    """The pool's workers are non-daemon threads that Python joins at exit, so one still inside a
+    full pass held a restarting process open for the rest of the read. Stand-in child: a real
+    process that would sleep for a minute."""
+    real_popen = subprocess.Popen
+    monkeypatch.setattr(
+        subtitles.subprocess,
+        "Popen",
+        lambda cmd, **kw: real_popen([sys.executable, "-c", "import time; time.sleep(60)"], **kw),
+    )
+    monkeypatch.setattr(subtitles, "_POOL", ThreadPoolExecutor(max_workers=1))
+    finished = threading.Event()
+
+    def _extract():
+        try:
+            subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], None, None)
+        except subtitles.SubtitleUnavailable:
+            pass  # killed before it wrote anything — exactly what a shutdown does
+        finally:
+            finished.set()
+
+    threading.Thread(target=_extract, daemon=True).start()
+    deadline = time.monotonic() + 10
+    while not subtitles._PROCS and time.monotonic() < deadline:
+        time.sleep(0.02)
+    assert subtitles._PROCS, "the extraction never registered its child"
+    subtitles.shutdown()
+    assert finished.wait(timeout=10), "the extraction was still running after shutdown"
+
+
+def test_the_track_fetch_serves_what_is_cached_and_schedules_nothing(client, monkeypatch):
+    """The <track> URL carries no position, and it used to run the scheduler anyway — judging
+    readiness at position 0. A viewer resumed an hour in got an unrequested extraction over the head
+    of the file, and with a failure memo alive the fetch refused a window that WAS on disk while the
+    status poll (which knows the position) called the track showable: silently blank subtitles."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    assert client.get("/api/plex/subtitle/98614/0").status_code == 202
+    assert pool.jobs == [], "the fetch scheduled an extraction"
+    key = subtitles.cache_key("98614", 0)
+    subtitles.publish(key, _vtt(_cue("59:54.187", "59:58.650", "window")), (3570.0, 3900.0), False)
+    subtitles._fail(key, "extract_failed")  # the full pass behind that window failed
+    resp = client.get("/api/plex/subtitle/98614/0")
+    assert resp.status_code == 200 and "window" in resp.text
+    assert pool.jobs == []
+
+
+@pytest.mark.parametrize("at", ["inf", "-1", "nan"])
+def test_an_impossible_position_is_rejected(client, monkeypatch, at):
+    """`?at=inf` reached the scheduler's arithmetic and came back as a 500 with a traceback."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    assert client.get(f"/api/plex/subtitle/98614/0/status?at={at}").status_code == 422
+    assert pool.jobs == []
diff --git a/frontend/src/lib/api/plex.ts b/frontend/src/lib/api/plex.ts
index 89aae403..5cbebde4 100644
--- a/frontend/src/lib/api/plex.ts
+++ b/frontend/src/lib/api/plex.ts
@@ -650,7 +650,8 @@ export const plexApi = {
   // cue times onto the HLS session's zero-based clock so subtitles line up with speech after a seek.
   // `gen` is the cached track's generation: extraction publishes a window around the playhead first
   // and widens it in the background, so the URL has to change when it grows or the browser would keep
-  // serving the first, short VTT from its own cache.
+  // serving the first, short VTT from its own cache. It deliberately carries NO position: the fetch
+  // is a pure read of what is cached — scheduling is the status poll's job, since only it knows `at`.
   plexSubtitleUrl: (id: string, ord: number, offset = 0, gen = 0): string => {
     const p = new URLSearchParams();
     if (offset) p.set("offset", String(offset));

From d2ba65e383697d7ba629864772909d46fd118458 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 01:08:27 +0200
Subject: [PATCH 09/52] fix(plex): the subtitle poll backs off on errors, a
 failed <track> is replaced, and a resume asks for the right window
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review R2, plus one defect found while verifying it on localdev.

- The status poll re-armed every second after a FAILED request: `data` stays empty on an error,
  so it read as "still preparing" for as long as the player was open — and the request was not
  quiet, so a persistent 500 re-opened the global error dialog every second. It now backs off to
  10 s (a blip still heals on its own) and is quiet; the player already shows the failure inline.
- A <track> whose own VTT fetch failed never fetched again: with the server's answer unchanged its
  key was unchanged, so React kept the dead element — silently blank subtitles. The key (now built
  in the hook, where it is tested) carries a failed-load count; after two remounts the track is
  reported as unavailable instead.
- Found in UAT: until the first timeupdate `abs` is 0, so after a resume every poll said at=0 and
  the first window was cut around the head of the film (a resume at 20:00 polled at=0 for as long
  as it stayed paused). The poll reports the session's start until playback ticks. And the window's
  dedup identity is the track plus a window-length bucket of its start — keyed on the track alone
  (R1), the right window queued behind that wrong one.

The poll's start/stop rules finally have tests (every earlier one resolved a single fixed answer).
Verified on localdev against Westworld S1E6 resumed at 20:00: the polls carried at=1197, one
subtitle line on screen at 21:02, the poll stopped at `ready`; the real file's window (56 cues) +
full pass (608) merged to 608 — the old merge would have served 664. 11 mutations, all red.
---
 backend/app/plex/subtitles.py                 |  15 ++-
 backend/tests/test_plex_subtitle_prepare.py   |  11 ++
 frontend/src/components/PlexPlayer.tsx        |   9 +-
 frontend/src/lib/api/plex.ts                  |   3 +
 .../lib/plexPlayerHooks.subtitle.dom.test.tsx | 113 +++++++++++++++++-
 frontend/src/lib/plexPlayerHooks.ts           |  49 +++++++-
 6 files changed, 179 insertions(+), 21 deletions(-)

diff --git a/backend/app/plex/subtitles.py b/backend/app/plex/subtitles.py
index 8c749c1c..f9048565 100644
--- a/backend/app/plex/subtitles.py
+++ b/backend/app/plex/subtitles.py
@@ -439,14 +439,17 @@ def _schedule(rating_key: str, sub_ord: int, at: float, want_window: bool) -> No
     full pass that makes it complete. Each is deduplicated by identity, so a 1 s status poll (or a
     second viewer) joins the running job instead of starting another ffmpeg.
 
-    A window's identity is its TRACK, never its position. The poll sends the live playhead, so a
-    position-keyed window minted a new identity every second and queued one more read of the file per
-    poll until the first window landed. One window per track is in flight at a time; a seek past it
-    is picked up by the next poll after it publishes. The full pass is per ITEM, because one read
-    fans out to every embedded text track of the file."""
+    A window's identity is its track plus WHICH STRETCH of the film it is for — never the exact
+    position. The poll sends the live playhead, so a position-keyed window minted a new identity every
+    second and queued one more read of the file per poll until the first window landed; bucketing the
+    start by the window's own length makes a playhead creeping along join the job already running. It
+    must not be the track alone either: then a window cut around the wrong spot (the first poll after
+    a resume can still report 0) made the right one wait for it. The full pass is per ITEM, because
+    one read fans out to every embedded text track of the file."""
     jobs: list[tuple[tuple, float | None]] = []
     if want_window:
-        jobs.append((("win", rating_key, sub_ord), max(0.0, at - WINDOW_PRE_S)))
+        w_start = max(0.0, at - WINDOW_PRE_S)
+        jobs.append((("win", rating_key, sub_ord, int(w_start // WINDOW_LEN_S)), w_start))
     jobs.append((("full", rating_key), None))
     for ident, window_start in jobs:
         with _LOCK:
diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
index 633c2587..13c572b1 100644
--- a/backend/tests/test_plex_subtitle_prepare.py
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -395,6 +395,17 @@ def test_polls_that_follow_the_playhead_join_one_window(monkeypatch):
     assert len(pool.jobs) == 2, "one window + the one full pass"
 
 
+def test_a_window_for_a_different_stretch_does_not_wait_behind_the_first(monkeypatch):
+    """Measured on localdev: after a resume the first poll can still report 0 (the position is only
+    known once playback ticks), so the first window is cut around the wrong spot. The poll that
+    follows, at the real position, must get its own window at once — not queue behind that one."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    subtitles.ensure("98614", 1, at=0.0)
+    subtitles.ensure("98614", 1, at=1198.0)
+    assert sorted(a[3] for _, a in pool.jobs if a[3] is not None) == [0.0, 1168.0]
+
+
 def test_a_queued_window_that_was_covered_meanwhile_reads_nothing(monkeypatch):
     """Every embedded track rides each pass over its file, so by the time a queued window for one
     language runs, another language's window may already have published it."""
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index 43c7a747..e7f3242d 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -380,6 +380,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     subShowable,
     subFail,
     subGen,
+    subTrackKey,
     onSubTrackError,
   } = usePlexTracks({
     id,
@@ -873,10 +874,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
             above flips modes; the browser fetches a track's VTT the first time it's shown. */}
         {selectedSub && subShowable && (
           <track
-            // One track = the selected sub only (no multi-track overlap). Key by the shifted-offset so
-            // a seek-restart or a (debounced) sub-offset change remounts → fresh VTT fetch, and by the
-            // extraction generation so a widened track replaces the first short window.
-            key={`${id}-${selectedSub.ord}-${subTrackOffset.toFixed(2)}-${subGen}`}
+            // One track = the selected sub only (no multi-track overlap). The key (see usePlexTracks)
+            // is what remounts it for a fresh VTT fetch: a seek-restart, an offset change, a widened
+            // track, or a failed load.
+            key={subTrackKey}
             kind="subtitles"
             src={api.plexSubtitleUrl(id, selectedSub.ord, subTrackOffset, subGen)}
             srcLang={selectedSub.language ?? undefined}
diff --git a/frontend/src/lib/api/plex.ts b/frontend/src/lib/api/plex.ts
index 5cbebde4..440a109b 100644
--- a/frontend/src/lib/api/plex.ts
+++ b/frontend/src/lib/api/plex.ts
@@ -672,8 +672,11 @@ export const plexApi = {
     code: string | null;
     gen: number;
   }> =>
+    // `quiet`: the player reports a failed poll inline, so no global error dialog on top of it.
     req(
       `/api/plex/subtitle/${encodeURIComponent(id)}/${ord}/status?at=${Math.max(0, Math.floor(at))}`,
+      undefined,
+      { quiet: true },
     ),
   // `final` marks a settled checkpoint (pause / page-hide / leaving the player) as opposed to the
   // periodic 10s tick — the backend mirrors the resume position to a linked Plex account only on a
diff --git a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
index 6dc61625..3bb046da 100644
--- a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
+++ b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
@@ -9,12 +9,13 @@
 // until the cache happened to be warm. The extraction now runs in the background, publishing a
 // window around the playhead first, and this hook's poll is what decides when there is something to
 // mount and what to say while there isn't.
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { cleanup, renderHook, waitFor } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { createRef, type ReactNode, type MutableRefObject } from "react";
 import { usePlexTracks } from "./plexPlayerHooks";
 import { api, type PlexItemDetail } from "./api";
+import { dismissError, getError } from "./errorDialog";
 import type Hls from "hls.js";
 
 const RK = "98614";
@@ -31,7 +32,7 @@ const detail = (): PlexItemDetail =>
     markers: [],
   }) as unknown as PlexItemDetail;
 
-function mount(qc: QueryClient) {
+function mount(qc: QueryClient, { sessionK = 0, abs = 3600 } = {}) {
   const wrapper = ({ children }: { children: ReactNode }) => (
     <QueryClientProvider client={qc}>{children}</QueryClientProvider>
   );
@@ -40,7 +41,7 @@ function mount(qc: QueryClient) {
       usePlexTracks({
         id: RK,
         detail: detail(),
-        sessionK: 0,
+        sessionK,
         subOffset: 0,
         subPos: 88,
         loadSession: async () => {},
@@ -50,7 +51,7 @@ function mount(qc: QueryClient) {
         multiAudioRef: { current: false },
         audioRef: { current: 0 } as MutableRefObject<number | null>,
         aoffRef: { current: 0 },
-        absRef: { current: 3600 },
+        absRef: { current: abs },
       }),
     { wrapper },
   );
@@ -91,6 +92,18 @@ describe("usePlexTracks — the <track> waits for the extraction", () => {
     await waitFor(() => expect(status).toHaveBeenCalledWith(RK, 1, 3600));
   });
 
+  it("sends the session's start before playback has ticked, not the head of the film", async () => {
+    // A resumed session starts minutes in, but `abs` stays 0 until the first timeupdate — and every
+    // poll used to say at=0, so the first window was cut around the head of the film (measured on
+    // localdev: a resume at 20:00 polled at=0 for as long as it stayed paused).
+    const status = vi
+      .spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValue({ state: "preparing", code: null, gen: 0 });
+    const { result } = mount(client(), { sessionK: 1198, abs: 0 });
+    result.current.setSubOrd(1);
+    await waitFor(() => expect(status).toHaveBeenCalledWith(RK, 1, 1198));
+  });
+
   it("becomes showable on a PARTIAL track — a window around the playhead is what is needed now", async () => {
     vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
       state: "partial",
@@ -138,3 +151,93 @@ describe("usePlexTracks — the <track> waits for the extraction", () => {
     expect(result.current.subShowable).toBe(false);
   });
 });
+
+// The poll's refetch rules ARE the feature: nothing else turns "preparing" into subtitles on screen,
+// and nothing else stops a settled track from being asked about for the length of the film. Every
+// test above resolves one fixed answer, so none of them ever reached the refetch callback.
+describe("usePlexTracks — when the status poll asks again, and when it stops", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+  });
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("keeps asking until a window lands, then shows it without the viewer doing anything", async () => {
+    const status = vi
+      .spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValueOnce({ state: "preparing", code: null, gen: 0 })
+      .mockResolvedValue({ state: "partial", code: null, gen: 7 });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(status).toHaveBeenCalledTimes(1));
+    expect(result.current.subShowable).toBe(false);
+    await vi.advanceTimersByTimeAsync(1100);
+    await waitFor(() => expect(result.current.subShowable).toBe(true));
+  });
+
+  it.each([
+    ["the whole track is there", { state: "ready" as const, code: null, gen: 3 }],
+    ["it can never be shown", { state: "failed" as const, code: "bitmap", gen: 0 }],
+  ])("stops asking once the answer is settled — %s", async (_, answer) => {
+    const status = vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue(answer);
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(status).toHaveBeenCalledTimes(1));
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(status).toHaveBeenCalledTimes(1);
+  });
+
+  it("backs off after a failed request, and still asks again so a blip heals on its own", async () => {
+    // A failed request leaves `data` empty; it used to read as "still preparing" and re-ask every
+    // second for as long as the player stayed open.
+    const status = vi.spyOn(api, "plexSubtitleStatus").mockRejectedValue(new Error("offline"));
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subFail).toBe("failed"));
+    expect(status).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(5000);
+    expect(status).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(6000);
+    expect(status).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not raise the global error dialog when it fails — the player says so inline", async () => {
+    dismissError();
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: "boom" }), {
+        status: 500,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    await expect(api.plexSubtitleStatus(RK, 0, 0)).rejects.toThrow();
+    expect(getError()).toBeNull();
+  });
+});
+
+describe("usePlexTracks — a <track> whose own VTT fetch failed", () => {
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  it("is replaced by a fresh element a couple of times, then reported instead of left blank", async () => {
+    // A failed <track> never fetches again, and while the server's answer is unchanged its key was
+    // unchanged too — so React kept the dead element and the subtitles stayed silently blank.
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({ state: "partial", code: null, gen: 5 });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subShowable).toBe(true));
+    for (let i = 0; i < 2; i++) {
+      const before = result.current.subTrackKey;
+      act(() => result.current.onSubTrackError());
+      await waitFor(() => expect(result.current.subTrackKey).not.toBe(before));
+      expect(result.current.subShowable).toBe(true);
+    }
+    act(() => result.current.onSubTrackError());
+    await waitFor(() => expect(result.current.subShowable).toBe(false));
+    expect(result.current.subFail).toBe("failed");
+  });
+});
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index e6700d43..4ccadaa6 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -349,6 +349,11 @@ export function useAutoSkip(opts: {
  *  fold happens here rather than multiplying near-identical translations. */
 export type SubFailReason = "bitmap" | "missing" | "failed";
 
+// The subtitle status poll's cadence after a FAILED request (see usePlexTracks), and how many times a
+// <track> whose own VTT fetch failed is remounted before the track is reported as unavailable.
+const SUB_POLL_ERROR_MS = 10_000;
+const SUB_TRACK_RETRIES = 2;
+
 function subFailReason(code: string | null | undefined): SubFailReason {
   if (code === "bitmap") return "bitmap";
   if (code === "no_item" || code === "no_track" || code === "no_file" || code === "not_fetchable")
@@ -394,6 +399,11 @@ export function usePlexTracks(opts: {
   /** The cached VTT's generation — it grows as the background extraction widens the track, so it
    *  belongs in the <track> key/URL or the browser keeps serving the first, short window. */
   subGen: number;
+  /** The <track>'s React key. Everything that must produce a FRESH element — and so a fresh VTT
+   *  fetch — is in it: the item and track, the shifted offset (a seek-restart or a debounced offset
+   *  change), the extraction generation (a widened track replaces the first short window), and the
+   *  failed-load count (a <track> whose fetch failed is replaced rather than left dead). */
+  subTrackKey: string;
   onSubTrackError: () => void;
 } {
   const { id, detail, sessionK, subOffset, subPos, loadSession, patchPrefs } = opts;
@@ -486,14 +496,28 @@ export function usePlexTracks(opts: {
   // around the playhead first, and this poll is what tells us when there is something to mount.
   const subStatusQ = useQuery({
     queryKey: qk.plexSubtitle(id, subOrd ?? -1),
-    queryFn: () => api.plexSubtitleStatus(id, subOrd as number, absRef.current ?? 0),
+    // The position is only known once playback has ticked: until the first timeupdate `abs` is 0
+    // even though a resumed session starts minutes in — and every poll said `at=0`, so the first
+    // window was cut around the head of the film instead of where the viewer is (measured on
+    // localdev: a resume at 20:00 polled `at=0` for as long as it stayed paused). The session's own
+    // start is the best answer until then.
+    queryFn: () =>
+      api.plexSubtitleStatus(id, subOrd as number, absRef.current > 0 ? absRef.current : sessionK),
     enabled: subOrd != null,
     // Keep polling until the track is COMPLETE, not just showable: each poll carries the current
     // position, so seeking past the extracted window is what asks for the next one. A settled
     // answer — the whole track, or a reason it can never be shown — stops the poll; without that
     // stop, a bitmap track would poll for the length of the film AND keep re-arming the extraction
     // every time the server's short failure memo expired.
+    //
+    // A FAILED request is neither: it says nothing about the track. It must not keep the 1 s cadence
+    // (it used to — `data` stays empty on an error, so every failure read as "still preparing" and
+    // re-armed a second later, for as long as the player was open), but it must not end the poll
+    // either, or one dropped request would leave "unavailable" on screen for a track that is fine.
+    // So it backs off to SUB_POLL_ERROR_MS; the player shows the failure inline meanwhile, which is
+    // also why the request is `quiet` (no global error dialog re-opening under the film).
     refetchInterval: (q) => {
+      if (q.state.status === "error") return SUB_POLL_ERROR_MS;
       const st = q.state.data?.state;
       if (st === "ready" || st === "failed") return false;
       return st === "partial" ? 2000 : 1000;
@@ -502,20 +526,32 @@ export function usePlexTracks(opts: {
     retry: false,
   });
   const subStatus = subOrd == null ? null : (subStatusQ.data ?? null);
+  // A <track> whose own VTT fetch failed never fetches again, and re-asking the status cannot fix
+  // that on its own: while the answer (and its `gen`) is unchanged the key is unchanged, so React
+  // keeps the dead element and the subtitles stay silently blank. So a failed load bumps a counter
+  // that is part of the key — a fresh element, a fresh fetch — and after SUB_TRACK_RETRIES the track
+  // is reported as unavailable instead of left blank. The count belongs to one track generation: a
+  // different track, item or `gen` starts from zero.
+  const loadKey = `${id}:${subOrd}:${subStatus?.gen ?? 0}`;
+  const [loadFails, setLoadFails] = useState({ key: "", n: 0 });
+  const subRetry = loadFails.key === loadKey ? loadFails.n : 0;
+  const subGaveUp = subRetry > SUB_TRACK_RETRIES;
   // Mount the <track> for a `partial` track too: a window around the playhead is exactly what the
   // viewer needs right now, and the poll widens it underneath them.
-  const subShowable = subStatus?.state === "ready" || subStatus?.state === "partial";
+  const subShowable =
+    (subStatus?.state === "ready" || subStatus?.state === "partial") && !subGaveUp;
   const subFail: SubFailReason | null =
-    subStatusQ.isError && subOrd != null
+    (subStatusQ.isError || subGaveUp) && subOrd != null
       ? "failed"
       : subStatus?.state === "failed"
         ? subFailReason(subStatus.code)
         : null;
-  // A <track> that errors anyway (the cached VTT was evicted between the poll and the fetch) goes
-  // back to polling rather than staying silently blank.
   const onSubTrackError = useCallback(() => {
+    setLoadFails((f) => ({ key: loadKey, n: (f.key === loadKey ? f.n : 0) + 1 }));
+    // …and ask again: if the cached VTT was evicted between the poll and the fetch, the answer drops
+    // back to `preparing` and the poll takes over until it has been re-extracted.
     if (subOrd != null) qc.invalidateQueries({ queryKey: qk.plexSubtitle(id, subOrd) });
-  }, [qc, id, subOrd]);
+  }, [qc, id, subOrd, loadKey]);
 
   // Text subtitles offered in the picker; image subs (PGS/VobSub) can't be shown as text.
   const textSubs = (detail?.subtitle_streams ?? []).filter((s) => s.text);
@@ -586,6 +622,7 @@ export function usePlexTracks(opts: {
     subShowable,
     subFail,
     subGen: subStatus?.gen ?? 0,
+    subTrackKey: `${id}-${subOrd}-${subTrackOffset.toFixed(2)}-${subStatus?.gen ?? 0}-${subRetry}`,
     onSubTrackError,
   };
 }

From d20317e0f1aeca1e6e7d5e2500551e0b7a2eb1e5 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 01:12:51 +0200
Subject: [PATCH 10/52] fix(plex): the collection page's watched toggle and
 Sort control survive the sort joining the query key
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review R3. When 889d2acf put the sort into the collection detail's query key, two things on
the page did not follow it:

- The watched toggle's optimistic write kept the key's old spelling. setQueryData matches exactly,
  so it landed on an entry nothing reads, and its resync only invalidates the library root — the
  click succeeded server-side and changed nothing on screen (badge, icon, aria-label) until a
  reload; a second click toggled it back. One `detailKey` now serves the read and the write.
- Every sort change was a key with no data yet, so the whole page — hero, grid, and the Sort control
  with its open panel — was swapped for a spinner, and focus fell to <body>: key and direction could
  not be set in one visit. The previous page now stays on screen while the new order loads, for the
  SAME collection only (stepping to another must not show this one's hero meanwhile).

Verified on localdev (Rocky Collection): the toggle flips the poster; IMDb rating then Descending set
in one open panel, the hero never blanked, order reversed. 3 mutations, each red on its test.
---
 .../PlexCollectionView.dom.test.tsx           | 59 +++++++++++++++++++
 .../src/components/PlexCollectionView.tsx     | 14 ++++-
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/frontend/src/components/PlexCollectionView.dom.test.tsx b/frontend/src/components/PlexCollectionView.dom.test.tsx
index 5255e399..bffa6610 100644
--- a/frontend/src/components/PlexCollectionView.dom.test.tsx
+++ b/frontend/src/components/PlexCollectionView.dom.test.tsx
@@ -20,6 +20,8 @@ beforeAll(() => {
     }
   }
   globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  // …and the Sort control's popover watches its anchor with an IntersectionObserver.
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
 });
 
 vi.mock("react-i18next", async (importOriginal) => {
@@ -126,3 +128,60 @@ describe("PlexCollectionView — Play-all", () => {
     expect(onPlay).not.toHaveBeenCalled();
   });
 });
+
+// Bug-hunt deep-review: the Sort control put the sort into the detail query's key, and two things
+// on this page did not follow it.
+describe("PlexCollectionView — after the sort joined the query key", () => {
+  it("flips a poster's watched state on the page it was clicked on", async () => {
+    // The optimistic write kept the key's OLD spelling — an entry nothing reads — and the resync
+    // only touches the library root, so the click did nothing visible until a reload.
+    vi.spyOn(api, "plexSetState").mockResolvedValue(undefined as never);
+    mount([card("movie1", "movie")]);
+    fireEvent.click(await screen.findByRole("button", { name: "plex.markWatched" }));
+    expect(await screen.findByRole("button", { name: "plex.markUnwatched" })).toBeTruthy();
+  });
+
+  it("keeps the page, and the open Sort panel, on screen while the new order loads", async () => {
+    // Every sort change was a key with no data yet: the whole page — the control and its open panel
+    // included — was swapped for a spinner, so key and direction could not be set in one visit.
+    vi.spyOn(api, "savePrefs").mockResolvedValue(undefined as never);
+    vi.spyOn(api, "plexCollection")
+      .mockResolvedValueOnce(detail([card("movie1", "movie"), card("movie2", "movie")]))
+      .mockReturnValueOnce(new Promise(() => {})); // the re-sorted page is still on its way
+    mount([card("movie1", "movie"), card("movie2", "movie")]);
+    fireEvent.click(await screen.findByRole("button", { name: /^plex\.filter\.sort:/ }));
+    // Popover rows are portalled and only exist while it is open, so `hidden: true`.
+    const other = (await screen.findAllByRole("menuitemradio", { hidden: true })).find(
+      (o) => o.getAttribute("aria-checked") !== "true",
+    );
+    fireEvent.click(other!);
+    await waitFor(() => expect(api.plexCollection).toHaveBeenCalledTimes(2));
+    expect(screen.queryByText("plex.loading")).toBeNull();
+    expect(screen.getAllByRole("menuitemradio", { hidden: true }).length).toBeGreaterThan(1);
+    expect(screen.getByText("plex.collection.playAll")).toBeTruthy();
+  });
+
+  it("does not show the previous collection while stepping to another one", async () => {
+    // Keeping the page on screen is for a re-sort of THIS collection only.
+    vi.spyOn(api, "plexCollection")
+      .mockResolvedValueOnce(detail([card("movie1", "movie")]))
+      .mockReturnValueOnce(new Promise(() => {}));
+    const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    const view = (id: string) => (
+      <QueryClientProvider client={qc}>
+        <PlexCollectionView
+          collectionId={id}
+          onBack={() => {}}
+          onPlay={() => {}}
+          onOpenCard={() => {}}
+          onInfoCard={() => {}}
+        />
+      </QueryClientProvider>
+    );
+    const { rerender } = render(view("col1"));
+    await screen.findByText("plex.collection.playAll");
+    rerender(view("col2"));
+    expect(await screen.findByText("plex.loading")).toBeTruthy();
+    expect(screen.queryByText("plex.collection.playAll")).toBeNull();
+  });
+});
diff --git a/frontend/src/components/PlexCollectionView.tsx b/frontend/src/components/PlexCollectionView.tsx
index 7aabdaba..bb901c06 100644
--- a/frontend/src/components/PlexCollectionView.tsx
+++ b/frontend/src/components/PlexCollectionView.tsx
@@ -69,9 +69,19 @@ export default function PlexCollectionView({
     "plexCollectionSort",
     COLLECTION_SORT_DEFAULT,
   );
+  // ONE key for the read and every write into it: when the sort joined the key, the watched toggle's
+  // optimistic write kept the old spelling and landed on an entry nothing reads (setQueryData matches
+  // exactly), so the click did nothing visible until a reload.
+  const detailKey = qk.plexCollections("detail", collectionId, sortPref.key, sortPref.dir);
   const q = useQuery({
-    queryKey: qk.plexCollections("detail", collectionId, sortPref.key, sortPref.dir),
+    queryKey: detailKey,
     queryFn: () => api.plexCollection(collectionId, sortPref),
+    // A re-sort keeps the current page on screen while the new order loads. Without it every sort
+    // change was a key with no data yet, and the whole page — the Sort control and its open panel
+    // with it — was swapped for a spinner, so key and direction could not be set in one visit. Only
+    // within the SAME collection: stepping to another one must not show this one's hero meanwhile.
+    placeholderData: (prev, prevQuery) =>
+      prevQuery?.queryKey[2] === collectionId ? prev : undefined,
   });
   const d = q.data;
 
@@ -146,7 +156,7 @@ export default function PlexCollectionView({
   const toggleWatched = (card: PlexCard) =>
     toggleWatchState(card, t, {
       optimistic: (next) => {
-        qc.setQueryData<PlexCollectionDetail>(qk.plexCollections("detail", collectionId), (old) =>
+        qc.setQueryData<PlexCollectionDetail>(detailKey, (old) =>
           old
             ? {
                 ...old,

From 4869d6c1083725910f7956b5f49396cbc31e3f25 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 01:19:14 +0200
Subject: [PATCH 11/52] fix(player): the resume position reaches the playlist
 page and live search, not just the feed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review R4. 1630a3df wrote the YT player's stored position into the react-query cache so a
reopen could not rewind it — but only the feed actually read it back:

- Playlists renders from its own undoable copy of the list, re-seeded only when the SET of ids
  changes, so the patched position never reached it: close a video at 830 s, reopen it from the
  playlist, and it resumed at the old spot and the next checkpoint wrote that over the 830. A detail
  with the same membership now rebases its fresh rows into every snapshot, keeping order and undo
  history. (The ids-only guard is older than this round; the write that depended on it was new.)
- Live YouTube search results carry the same per-user position and open the same player, but their
  cache was never patched. It is now — patched only, never invalidated, since refetching an
  API-sourced search page spends 100 quota units.

Tests for what had none: a Playlists harness (PlayerModal stubbed to record its launch props) and a
PlayerModal harness with a fake IFrame API that records where each item is started — the latter pins
that stepping back to an item watched earlier in the same session resumes at THIS session's position.
3 mutations, each red on its assertion.
---
 .../src/components/PlayerModal.dom.test.tsx   | 115 ++++++++++++++++
 .../src/components/Playlists.dom.test.tsx     | 124 ++++++++++++++++++
 frontend/src/components/Playlists.tsx         |   8 ++
 .../playerModalHooks.progress.dom.test.tsx    |  13 ++
 frontend/src/lib/progressCache.ts             |   6 +-
 5 files changed, 265 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/components/PlayerModal.dom.test.tsx
 create mode 100644 frontend/src/components/Playlists.dom.test.tsx

diff --git a/frontend/src/components/PlayerModal.dom.test.tsx b/frontend/src/components/PlayerModal.dom.test.tsx
new file mode 100644
index 00000000..f7aec589
--- /dev/null
+++ b/frontend/src/components/PlayerModal.dom.test.tsx
@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+//
+// The YouTube player modal, rendered for real. Its pure helpers (afterRemoval, the progress cache)
+// had tests; what the modal DOES with them had none — a deep-review of the 2026-09 bug hunt found
+// that deleting the lines that apply them left every lane green.
+//
+// `window.YT` is a fake installed before the module's API loader first runs (that loader memoises
+// its promise in a module-level singleton, so this file must not share a module instance with a
+// test that leaves `window.YT` unset). Each item the modal plays constructs a new YT.Player, and the
+// fake records what it was asked for — that is how these tests see where playback starts.
+import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
+import { render, screen, fireEvent, waitFor, cleanup } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, o?: Record<string, unknown>) => (o?.title ? `${key}:${o.title}` : key),
+      i18n: { language: "en" },
+    }),
+  };
+});
+vi.mock("./NavigationProvider", () => ({ useNavigationActions: () => ({ openChannel: vi.fn() }) }));
+// Their own queries and popovers are not what is under test here.
+vi.mock("./AddToPlaylist", () => ({ default: () => null }));
+vi.mock("./DownloadButton", () => ({ default: () => null }));
+
+import PlayerModal from "./PlayerModal";
+import { api, type Video } from "../lib/api";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+
+// --- the fake IFrame API ------------------------------------------------------------------------
+const clock = { current: 0, duration: 3000 };
+const started: { videoId: string; start: number | undefined }[] = [];
+const base = {
+  getCurrentTime: () => clock.current,
+  getDuration: () => clock.duration,
+  getVideoData: () => null,
+};
+// Anything else the modal calls on the player (volume, rate, destroy…) is a no-op. Not `then`:
+// a thenable would be swallowed by the first `await` that touched it.
+const fakePlayer = new Proxy(base, {
+  get: (t, k) => (k in t ? t[k as keyof typeof t] : k === "then" ? undefined : () => undefined),
+});
+window.YT = {
+  Player: function (_el: unknown, opts: { videoId: string; playerVars: { start?: number } }) {
+    started.push({ videoId: opts.videoId, start: opts.playerVars.start });
+    return fakePlayer;
+  } as never,
+};
+
+const vid = (id: string, position_seconds: number): Video =>
+  ({
+    id,
+    title: `Video ${id}`,
+    channel_id: "UCx",
+    channel_title: "Channel",
+    status: "new",
+    position_seconds,
+    duration_seconds: 3000,
+    watch_url: `https://www.youtube.com/watch?v=${id}`,
+  }) as unknown as Video;
+
+function renderModal(ui: ReactNode) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(<QueryClientProvider client={qc}>{ui}</QueryClientProvider>);
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  started.length = 0;
+});
+
+const lastStart = () => started[started.length - 1];
+
+describe("PlayerModal — where each item starts", () => {
+  it("resumes an item played earlier in the SAME session where this session left it", async () => {
+    // The launch queue is frozen at mount, so its rows keep the position they were snapshotted
+    // with (748). Stepping next→prev back to an item already watched to 830 used to start it at
+    // 748 — and the next checkpoint then wrote 748 over the 830 the server held.
+    vi.spyOn(api, "videoDetail").mockReturnValue(new Promise(() => {}));
+    vi.spyOn(api, "saveProgress").mockImplementation(async (id: string) => ({
+      video_id: id,
+      position_seconds: id === "A" ? 830 : 0,
+    }));
+    const A = vid("A", 748);
+    const B = vid("B", 0);
+    clock.current = 830;
+    renderModal(
+      <PlayerModal video={A} queue={[A, B]} startIndex={0} onClose={() => {}} onState={() => {}} />,
+    );
+    await waitFor(() => expect(lastStart()).toEqual({ videoId: "A", start: 748 }));
+    fireEvent.click(screen.getAllByRole("button", { name: "player.next" })[0]!);
+    await waitFor(() => expect(lastStart()?.videoId).toBe("B"));
+    fireEvent.click(screen.getAllByRole("button", { name: "player.previous" })[0]!);
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+    expect(lastStart()?.start).toBe(830);
+  });
+});
diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
new file mode 100644
index 00000000..cf5ab858
--- /dev/null
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -0,0 +1,124 @@
+// @vitest-environment jsdom
+//
+// The Playlists page as the player sees it: which row it is launched with, and what it is told to
+// do when the viewer removes that row from inside it. PlayerModal itself is replaced by a stand-in
+// that records its props — its own behaviour is pinned in PlayerModal.dom.test.tsx.
+import { describe, it, expect, vi, afterEach, beforeAll, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor, cleanup, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const h = vi.hoisted(() => ({
+  selectedId: 1 as number | null,
+  player: null as null | {
+    video: { id: string; position_seconds: number };
+    onClose: () => void;
+    onRemoveFromList?: (v: unknown) => Promise<boolean>;
+  },
+}));
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, o?: Record<string, unknown>) => (o?.title ? `${key}:${o.title}` : key),
+      i18n: { language: "en" },
+    }),
+  };
+});
+vi.mock("./PlaylistsProvider", () => ({ usePlaylists: () => ({ selectedId: h.selectedId }) }));
+vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
+vi.mock("./usePlaylistActions", () => ({ usePlaylistActions: () => ({ remove: vi.fn() }) }));
+vi.mock("./PlayerModal", () => ({
+  default: (props: NonNullable<typeof h.player>) => {
+    h.player = props;
+    return null;
+  },
+}));
+
+import Playlists from "./Playlists";
+import { api, type Video } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+import { patchCachedProgress } from "../lib/progressCache";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+
+const vid = (id: string, position_seconds: number): Video =>
+  ({
+    id,
+    title: `Video ${id}`,
+    channel_id: "UCx",
+    channel_title: "Channel",
+    status: "new",
+    position_seconds,
+    duration_seconds: 3000,
+    published_at: "2026-01-01T00:00:00Z",
+    watch_url: `https://www.youtube.com/watch?v=${id}`,
+  }) as unknown as Video;
+
+const list = (id: number, items: Video[]) => ({
+  id,
+  name: `List ${id}`,
+  kind: "user",
+  yt_playlist_id: null,
+  item_count: items.length,
+  items,
+});
+
+let qc: QueryClient;
+
+function mount(lists: Record<number, Video[]>) {
+  vi.spyOn(api, "playlists").mockResolvedValue(
+    Object.entries(lists).map(([id, items]) => list(Number(id), items)) as never,
+  );
+  vi.spyOn(api, "playlist").mockImplementation(
+    async (id: number) => list(id, lists[id] ?? []) as never,
+  );
+  qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  qc.setQueryData(qk.me(), { id: 1, can_write: true, prefs: {} });
+  return render(
+    <QueryClientProvider client={qc}>
+      <Playlists />
+    </QueryClientProvider>,
+  );
+}
+
+const play = async (title: string) =>
+  fireEvent.click(await screen.findByRole("button", { name: `card.play — ${title}` }));
+
+beforeEach(() => {
+  h.selectedId = 1;
+  h.player = null;
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe("Playlists — the row the player is launched with", () => {
+  it("carries the position the player just stored, not the one the list first loaded with", async () => {
+    // The page renders from its own undoable copy of the list, re-seeded only when the SET of ids
+    // changes — so the position the player wrote into the cache never reached it: reopen a video
+    // closed at 830 s and it resumed at the old spot, and the next checkpoint wrote that over 830.
+    mount({ 1: [vid("V", 748)] });
+    await play("Video V");
+    await waitFor(() => expect(h.player?.video.position_seconds).toBe(748));
+    act(() => h.player!.onClose());
+    h.player = null;
+    // What the player's cleanup does with the position the server confirmed.
+    act(() => patchCachedProgress(qc, new Map([["V", 830]])));
+    await play("Video V");
+    await waitFor(() => expect(h.player?.video.position_seconds).toBe(830));
+  });
+});
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 6bb1d140..197e14ce 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -266,6 +266,14 @@ export default function Playlists() {
     if (key !== lastSetRef.current) {
       lastSetRef.current = key;
       order.reset(detail.items);
+    } else {
+      // Same membership, fresher ROWS — a watch position the player just stored, a status. The
+      // guard above looks at the id set only, so without this the list kept showing, and handing the
+      // player, each row as it was when the list first loaded: watch a video to 830 s, close it,
+      // reopen it, and it resumed at the old spot and the next checkpoint wrote that over the 830.
+      // `rebase` takes the fresh rows into every snapshot and keeps the order and its undo history.
+      const fresh = new Map(detail.items.map((v) => [v.id, v]));
+      order.rebase((list) => list.map((v) => fresh.get(v.id) ?? v));
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [detail]);
diff --git a/frontend/src/lib/playerModalHooks.progress.dom.test.tsx b/frontend/src/lib/playerModalHooks.progress.dom.test.tsx
index 69745c07..c27fee77 100644
--- a/frontend/src/lib/playerModalHooks.progress.dom.test.tsx
+++ b/frontend/src/lib/playerModalHooks.progress.dom.test.tsx
@@ -152,6 +152,19 @@ describe("patchCachedProgress", () => {
     expect(after.items[1]?.position_seconds).toBe(12);
   });
 
+  it("patches a live YouTube search too — its rows open the same player", () => {
+    // Left out, reopening a search result resumed from the position the search was fetched with
+    // (0 for a fresh find) and the next checkpoint wrote that over the stored one.
+    const qc = new QueryClient();
+    const key = qk.ytSearch("melyik szállás", 20);
+    qc.setQueryData(key, { pages: [{ items: [video()], next_cursor: null }], pageParams: [null] });
+
+    patchCachedProgress(qc, new Map([[VID, 830]]));
+
+    const after = qc.getQueryData(key) as { pages: { items: Video[] }[] };
+    expect(after.pages[0]?.items[0]?.position_seconds).toBe(830);
+  });
+
   it("is a no-op when nothing was stored", () => {
     const qc = new QueryClient();
     seedFeed(qc, video());
diff --git a/frontend/src/lib/progressCache.ts b/frontend/src/lib/progressCache.ts
index 087c2523..fda24d37 100644
--- a/frontend/src/lib/progressCache.ts
+++ b/frontend/src/lib/progressCache.ts
@@ -61,7 +61,11 @@ export function patchCachedProgress(qc: QueryClient, positions: Map<string, numb
     return old;
   };
 
-  // Prefix keys: every filter combination of the feed, and every playlist detail.
+  // Prefix keys: every filter combination of the feed, every playlist detail, and every live YouTube
+  // search — its rows come from the same projection, carry the same per-user position, and open the
+  // same player, so leaving it out left the rewind in place on that surface. (Patched, never
+  // invalidated: a refetch of an API-sourced search page spends 100 quota units.)
   qc.setQueriesData<Cached>({ queryKey: qk.feed() }, patch);
   qc.setQueriesData<Cached>({ queryKey: qk.playlist() }, patch);
+  qc.setQueriesData<Cached>({ queryKey: qk.ytSearch() }, patch);
 }

From 060deb89d21f8ff8cda30b0ef8366a41ca179eda Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 01:28:27 +0200
Subject: [PATCH 12/52] fix(playlists): "remove" inside the player targets the
 list it came from, reports failure, and keeps the cursor and focus honest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review R5 — five defects in the Remove button f76a2afb put inside the YT player:

- It removed from whichever playlist was selected by the time it was pressed, not the one the player
  was launched from; the selection can change under an open player (the command palette opens over
  it). The launch list is now part of the player snapshot, and the optimistic row removal only
  touches the list actually on screen.
- A 403/404 failed in total silence: the catch claimed the global dialog had reported it, but `req`
  deliberately leaves those to the caller. It now notifies, as moveItemTo already did (the silent
  catch predates this round; the full-screen consumer did not). New key playlists.removeFailed, HU+EN.
- It computed the next item from the cursor as it was when the button was pressed, but prev/next and
  auto-advance keep working under the confirm dialog: the viewer was thrown back onto a video they had
  moved past. It reads the live cursor, and if they moved on it just drops the item from the queue.
- The button was disabled for the confirm's lifetime, so the dialog's focus restore hit a disabled
  element and a keyboard user who cancelled was left on <body>, outside the aria-modal player. A ref
  guards the double press instead.
- Its accessible name was a bare "Remove"; it now names its object, like the row control.

The call-site wiring (step on, drop from the queue, close on the last item, leave everything alone
when the removal did not happen) finally has tests. Verified on localdev in the real YT player: a row
reopened at the 136 s it had just stored; Cancel returned focus to the Remove button; a confirmed
removal stepped 1/3 -> 1/2. 10 mutations, each red on its assertion. Scratch list and positions reset.
---
 .../src/components/PlayerModal.dom.test.tsx   | 140 +++++++++++++++++-
 frontend/src/components/PlayerModal.tsx       |  34 +++--
 .../src/components/Playlists.dom.test.tsx     |  49 +++++-
 frontend/src/components/Playlists.tsx         |  62 +++++---
 frontend/src/i18n/locales/en/playlists.json   |   1 +
 frontend/src/i18n/locales/hu/playlists.json   |   1 +
 6 files changed, 253 insertions(+), 34 deletions(-)

diff --git a/frontend/src/components/PlayerModal.dom.test.tsx b/frontend/src/components/PlayerModal.dom.test.tsx
index f7aec589..201d86eb 100644
--- a/frontend/src/components/PlayerModal.dom.test.tsx
+++ b/frontend/src/components/PlayerModal.dom.test.tsx
@@ -8,8 +8,8 @@
 // its promise in a module-level singleton, so this file must not share a module instance with a
 // test that leaves `window.YT` unset). Each item the modal plays constructs a new YT.Player, and the
 // fake records what it was asked for — that is how these tests see where playback starts.
-import { describe, it, expect, vi, afterEach, beforeAll } from "vitest";
-import { render, screen, fireEvent, waitFor, cleanup } from "@testing-library/react";
+import { describe, it, expect, vi, afterEach, beforeAll, beforeEach } from "vitest";
+import { render, screen, fireEvent, waitFor, cleanup, act } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import type { ReactNode } from "react";
 
@@ -29,6 +29,7 @@ vi.mock("./AddToPlaylist", () => ({ default: () => null }));
 vi.mock("./DownloadButton", () => ({ default: () => null }));
 
 import PlayerModal from "./PlayerModal";
+import { ConfirmProvider, useConfirm } from "./ConfirmProvider";
 import { api, type Video } from "../lib/api";
 
 beforeAll(() => {
@@ -113,3 +114,138 @@ describe("PlayerModal — where each item starts", () => {
     expect(lastStart()?.start).toBe(830);
   });
 });
+
+// --- "remove from this playlist", from inside the player ----------------------------------------
+const trash = (title: string) =>
+  screen.getByRole("button", { name: `playlists.removeItemOf:Video ${title}` });
+const next = () => fireEvent.click(screen.getAllByRole("button", { name: "player.next" })[0]!);
+const prev = () => fireEvent.click(screen.getAllByRole("button", { name: "player.previous" })[0]!);
+const settle = () => act(async () => {});
+
+describe("PlayerModal — removing the playing video from its playlist", () => {
+  const [A, B, C, D] = ["A", "B", "C", "D"].map((id) => vid(id, 0));
+  beforeEach(() => {
+    vi.spyOn(api, "videoDetail").mockReturnValue(new Promise(() => {}));
+    vi.spyOn(api, "saveProgress").mockImplementation(async (id: string) => ({
+      video_id: id,
+      position_seconds: 0,
+    }));
+    clock.current = 0;
+  });
+
+  it("steps to the item that followed, and the removed one is gone from the queue", async () => {
+    renderModal(
+      <PlayerModal
+        video={B!}
+        queue={[A!, B!, C!]}
+        startIndex={1}
+        onClose={() => {}}
+        onState={() => {}}
+        onRemoveFromList={async () => true}
+      />,
+    );
+    await waitFor(() => expect(lastStart()?.videoId).toBe("B"));
+    fireEvent.click(trash("B"));
+    await waitFor(() => expect(lastStart()?.videoId).toBe("C"));
+    prev(); // …straight back to A: B is no longer there to step onto
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+  });
+
+  it("closes the player when the last item goes", async () => {
+    const onClose = vi.fn();
+    renderModal(
+      <PlayerModal
+        video={A!}
+        queue={[A!]}
+        startIndex={0}
+        onClose={onClose}
+        onState={() => {}}
+        onRemoveFromList={async () => true}
+      />,
+    );
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+    fireEvent.click(trash("A"));
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+  });
+
+  it("leaves playback and the queue alone when the removal did not happen", async () => {
+    const onClose = vi.fn();
+    renderModal(
+      <PlayerModal
+        video={A!}
+        queue={[A!, B!]}
+        startIndex={0}
+        onClose={onClose}
+        onState={() => {}}
+        onRemoveFromList={async () => false}
+      />,
+    );
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+    fireEvent.click(trash("A"));
+    await settle();
+    expect(onClose).not.toHaveBeenCalled();
+    expect(started.map((s) => s.videoId)).toEqual(["A"]);
+    next();
+    await waitFor(() => expect(lastStart()?.videoId).toBe("B"));
+    prev(); // A is still in the queue
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+  });
+
+  it("keeps playback where the viewer went while the confirm was open", async () => {
+    // prev/next keep working under the confirm dialog; deciding from the cursor as it was when the
+    // button was pressed threw the viewer back onto a video they had already moved past.
+    let answer!: (ok: boolean) => void;
+    renderModal(
+      <PlayerModal
+        video={A!}
+        queue={[A!, B!, C!, D!]}
+        startIndex={0}
+        onClose={() => {}}
+        onState={() => {}}
+        onRemoveFromList={() => new Promise<boolean>((r) => (answer = r))}
+      />,
+    );
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+    fireEvent.click(trash("A"));
+    next();
+    await waitFor(() => expect(lastStart()?.videoId).toBe("B"));
+    next();
+    await waitFor(() => expect(lastStart()?.videoId).toBe("C"));
+    await act(async () => answer(true));
+    expect(lastStart()?.videoId).toBe("C");
+    prev();
+    await waitFor(() => expect(lastStart()?.videoId).toBe("B"));
+    expect(started.filter((s) => s.videoId === "A")).toHaveLength(1); // never played again
+  });
+
+  it("gives focus back to the Remove button when the confirm is cancelled", async () => {
+    // The button used to be disabled for the confirm's whole lifetime, so the dialog's focus
+    // restore landed on a disabled element — a no-op — and a keyboard user was left on <body>,
+    // outside the aria-modal player.
+    function WithConfirm() {
+      const confirm = useConfirm();
+      return (
+        <PlayerModal
+          video={A!}
+          queue={[A!, B!]}
+          startIndex={0}
+          onClose={() => {}}
+          onState={() => {}}
+          onRemoveFromList={(v) =>
+            confirm({ title: "t", message: v.title, confirmLabel: "remove", danger: true })
+          }
+        />
+      );
+    }
+    renderModal(
+      <ConfirmProvider>
+        <WithConfirm />
+      </ConfirmProvider>,
+    );
+    await waitFor(() => expect(lastStart()?.videoId).toBe("A"));
+    trash("A").focus();
+    fireEvent.click(trash("A"));
+    fireEvent.click(await screen.findByRole("button", { name: "common.cancel" }));
+    await waitFor(() => expect(document.activeElement).toBe(trash("A")));
+  });
+});
diff --git a/frontend/src/components/PlayerModal.tsx b/frontend/src/components/PlayerModal.tsx
index c79d679c..216ee9d4 100644
--- a/frontend/src/components/PlayerModal.tsx
+++ b/frontend/src/components/PlayerModal.tsx
@@ -120,7 +120,7 @@ export default function PlayerModal({
   // useState's lazy initializer and ignore later prop changes. Items that turn out gone/
   // non-embeddable still surface the existing playback-error overlay when reached.
   //
-  // The setter exists for exactly ONE writer: removing the playing video from its playlist (below).
+  // The setter exists for exactly ONE writer: removing a video from its playlist (below).
   // That is not the feed changing under us — it is this player's own action — and leaving the item
   // in the frozen queue would let prev/next step back onto a video that no longer exists.
   const [queue, setQueue] = useState(() => queueProp);
@@ -262,20 +262,33 @@ export default function PlayerModal({
   // parent owns the removal (confirm + API + caches); the player owns what happens NEXT, because it
   // is the only side that knows which item is playing — its queue is frozen at mount, so the parent
   // cannot tell. Step to the item that followed (clamped when the last one goes), and close when the
-  // list runs out. Guarded against a double press while the confirm/request is in flight.
-  const [removing, setRemoving] = useState(false);
+  // list runs out.
+  //
+  // Guarded against a double press by a REF, not by disabling the button: a trigger disabled for
+  // the confirm's lifetime was still disabled when the dialog closed and restored focus to it — a
+  // no-op — so a keyboard user who cancelled was left on <body>, outside this aria-modal player.
+  const removingRef = useRef(false);
   const removeFromList = async () => {
-    if (!onRemoveFromList || removing) return;
+    if (!onRemoveFromList || removingRef.current) return;
     const victim = active;
-    setRemoving(true);
+    removingRef.current = true;
     let done = false;
     try {
       done = await onRemoveFromList(victim);
     } finally {
-      setRemoving(false);
+      removingRef.current = false;
     }
     if (!done) return; // cancelled at the confirm, or the request failed — leave playback alone
-    const next = afterRemoval(queue, index, victim.id);
+    // Decide from where the player is NOW, not where it was when the button was pressed: prev/next
+    // and auto-advance keep working under the confirm dialog, and a cursor from before the await
+    // threw the viewer back onto a video they had already moved past.
+    const { queue: q, index: i } = navRef.current;
+    if ((q?.[i] ?? video).id !== victim.id) {
+      // They moved on — take the removed item out of the queue and leave playback where it is.
+      setQueue((cur) => cur?.filter((v) => v.id !== victim.id));
+      return;
+    }
+    const next = afterRemoval(q, i, victim.id);
     if (!next) {
       onClose(); // that was the last one
       return;
@@ -905,10 +918,11 @@ export default function PlayerModal({
               {!navigated && onRemoveFromList && (
                 <button
                   onClick={() => void removeFromList()}
-                  disabled={removing}
                   title={t("playlists.removeItem")}
-                  aria-label={t("playlists.removeItem")}
-                  className="shrink-0 inline-flex items-center justify-center w-9 h-9 rounded-lg text-muted hover:text-danger hover:bg-surface border border-border transition disabled:opacity-50"
+                  // Named with its object, like the row control: a bare "Remove" among Fullscreen /
+                  // Download / Mark watched reads as "delete this video".
+                  aria-label={t("playlists.removeItemOf", { title: active.title })}
+                  className="shrink-0 inline-flex items-center justify-center w-9 h-9 rounded-lg text-muted hover:text-danger hover:bg-surface border border-border transition"
                 >
                   <Trash2 className="w-4 h-4" />
                 </button>
diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
index cf5ab858..db537359 100644
--- a/frontend/src/components/Playlists.dom.test.tsx
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -8,6 +8,7 @@ import { render, screen, fireEvent, waitFor, cleanup, act } from "@testing-libra
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
 const h = vi.hoisted(() => ({
+  notify: vi.fn(),
   selectedId: 1 as number | null,
   player: null as null | {
     video: { id: string; position_seconds: number };
@@ -26,6 +27,10 @@ vi.mock("react-i18next", async (importOriginal) => {
     }),
   };
 });
+vi.mock("../lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/notifications")>()),
+  notify: (...a: unknown[]) => h.notify(...a),
+}));
 vi.mock("./PlaylistsProvider", () => ({ usePlaylists: () => ({ selectedId: h.selectedId }) }));
 vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
 vi.mock("./usePlaylistActions", () => ({ usePlaylistActions: () => ({ remove: vi.fn() }) }));
@@ -37,7 +42,7 @@ vi.mock("./PlayerModal", () => ({
 }));
 
 import Playlists from "./Playlists";
-import { api, type Video } from "../lib/api";
+import { api, HttpError, type Video } from "../lib/api";
 import { qk } from "../lib/queryKeys";
 import { patchCachedProgress } from "../lib/progressCache";
 
@@ -87,11 +92,13 @@ function mount(lists: Record<number, Video[]>) {
   );
   qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
   qc.setQueryData(qk.me(), { id: 1, can_write: true, prefs: {} });
-  return render(
+  const tree = () => (
     <QueryClientProvider client={qc}>
       <Playlists />
-    </QueryClientProvider>,
+    </QueryClientProvider>
   );
+  const view = render(tree());
+  return { rerender: () => view.rerender(tree()) };
 }
 
 const play = async (title: string) =>
@@ -100,6 +107,7 @@ const play = async (title: string) =>
 beforeEach(() => {
   h.selectedId = 1;
   h.player = null;
+  h.notify.mockClear();
 });
 afterEach(() => {
   cleanup();
@@ -122,3 +130,38 @@ describe("Playlists — the row the player is launched with", () => {
     await waitFor(() => expect(h.player?.video.position_seconds).toBe(830));
   });
 });
+
+describe("Playlists — removing a video from inside the player", () => {
+  it("removes it from the list the player was launched from, even after the selection moved", async () => {
+    // The selection can change under an open player (the command palette opens over it); the
+    // removal read the LIVE selection, so it took the video out of a list the viewer never touched.
+    const remove = vi.spyOn(api, "removeFromPlaylist").mockResolvedValue(undefined as never);
+    const { rerender } = mount({ 1: [vid("V", 0)], 2: [vid("V", 0), vid("W", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.player).not.toBeNull());
+    h.selectedId = 2;
+    rerender();
+    await screen.findByRole("button", { name: "card.play — Video W" }); // list 2 is on screen now
+    await act(async () => {
+      await h.player!.onRemoveFromList!(vid("V", 0));
+    });
+    expect(remove).toHaveBeenCalledWith(1, "V");
+    // …and the list on screen keeps its own copy of V: nothing was taken out of it.
+    expect(screen.getByRole("button", { name: "card.play — Video V" })).toBeTruthy();
+  });
+
+  it("says so when the removal fails because the list is gone", async () => {
+    // `req` leaves 403/404 to the caller; the catch assumed a global dialog had already reported
+    // it, so a confirmed removal failed in total silence behind the full-screen player.
+    vi.spyOn(api, "removeFromPlaylist").mockRejectedValue(new HttpError(404, "Unknown playlist"));
+    mount({ 1: [vid("V", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.player).not.toBeNull());
+    let done: boolean | undefined;
+    await act(async () => {
+      done = await h.player!.onRemoveFromList!(vid("V", 0));
+    });
+    expect(done).toBe(false);
+    expect(h.notify).toHaveBeenCalledWith(expect.objectContaining({ level: "error" }));
+  });
+});
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 197e14ce..61a0ce58 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -216,16 +216,23 @@ export default function Playlists() {
   // re-confirms our own reorder doesn't wipe the undo history — we reset history only when
   // the actual set of items changes (different playlist, or an add/remove).
   const lastSetRef = useRef<string>("");
+  // The selection as of NOW, for code that runs after an await or on behalf of the open player.
+  const selectedRef = useRef(selectedId);
+  selectedRef.current = selectedId;
   // What the player was LAUNCHED with, snapshotted when it opens: the video, the queue and the index
   // inside it. `shown` is derived (sort / filter / view), and the player freezes its queue and owns
   // its own cursor from mount — so deriving the mount from `shown` every render meant anything that
   // dropped the launch row yanked the player off the screen mid-playback. That was a latent edge
   // (a view change) until "remove this from the playlist" moved INSIDE the player, where it is the
-  // normal case. Only onClose takes the player down now.
+  // normal case. Only onClose takes the player down now. `listId` is part of that snapshot for the
+  // same reason: the selection can change under an open player (the command palette opens over it),
+  // and "remove this from the playlist" means the list it was LAUNCHED from, not whichever is
+  // selected by the time the button is pressed.
   const [playing, setPlaying] = useState<{
     video: Video;
     queue: Video[];
     index: number;
+    listId: number | null;
   } | null>(null);
   // Where the last move went. `LS.playlist` is the SELECTED (source) list and `updated_at` moves on
   // any edit, so neither answers "where do I keep sending things"; this does, and it is a per-account
@@ -303,7 +310,7 @@ export default function Playlists() {
     const queue = shownRef.current;
     const index = queue.findIndex((v) => v.id === id);
     if (index < 0) return;
-    setPlaying({ video: queue[index]!, queue, index });
+    setPlaying({ video: queue[index]!, queue, index, listId: selectedRef.current });
   }, []);
   const onPlay = useCallback((v: Video) => openPlayer(v.id), [openPlayer]);
   const onRemove = useCallback((v: Video) => {
@@ -312,8 +319,13 @@ export default function Playlists() {
   // The player's "remove from this playlist" goes through the SAME removeItem the row menu and the
   // inline ✕ use — one confirm, one optimistic update, one undo-stack rebase, no second copy to
   // drift. It answers whether the removal actually happened, because the player has to decide
-  // afterwards whether to step to the next item or close.
-  const removeFromPlayer = useCallback((v: Video) => removeRef.current(v), []);
+  // afterwards whether to step to the next item or close. It removes from the list the player was
+  // launched from (see `playing.listId`), not from whatever is selected by now.
+  const launchListId = playing?.listId ?? null;
+  const removeFromPlayer = useCallback(
+    (v: Video) => removeRef.current(v, launchListId),
+    [launchListId],
+  );
 
   const storedIndex = useMemo(() => {
     const m = new Map(items.map((v, i) => [v.id, i]));
@@ -399,9 +411,9 @@ export default function Playlists() {
 
   const plName = (p: { kind: string; name: string }) => playlistName(p, t);
 
-  function refreshAll() {
+  function refreshAll(listId: number | null = selectedId) {
     qc.invalidateQueries({ queryKey: qk.playlists() });
-    qc.invalidateQueries({ queryKey: qk.playlist(selectedId) });
+    qc.invalidateQueries({ queryKey: qk.playlist(listId) });
   }
 
   async function revertToYoutube() {
@@ -517,8 +529,11 @@ export default function Playlists() {
 
   /** @returns whether the item was actually removed — the player needs to know, because it must
    *  step to the next item (or close) only when the removal really happened. */
-  async function removeItem(video: Video): Promise<boolean> {
-    if (selectedId == null) return false;
+  async function removeItem(
+    video: Video,
+    listId: number | null = selectedRef.current,
+  ): Promise<boolean> {
+    if (listId == null) return false;
     const ok = await confirm({
       title: t("playlists.removeItem"),
       message: t("playlists.confirmRemove", { title: video.title }),
@@ -526,19 +541,28 @@ export default function Playlists() {
       danger: true,
     });
     if (!ok) return false;
-    // A removal isn't itself undoable, but it no longer THROWS AWAY the reorder history: rebasing
-    // drops the item from every snapshot, so the stack stays valid for what's left.
-    const next = items.filter((v) => v.id !== video.id);
-    order.rebase((list) => list.filter((v) => v.id !== video.id));
-    lastSetRef.current = `${selectedId}:${idsKey(next)}`;
+    // Only the list ON SCREEN has rows to take the item out of optimistically — the open player can
+    // be removing from the list it was launched from while another one is selected. Read after the
+    // confirm: the selection may have changed while it was open.
+    if (listId === selectedRef.current) {
+      // A removal isn't itself undoable, but it no longer THROWS AWAY the reorder history: rebasing
+      // drops the item from every snapshot, so the stack stays valid for what's left.
+      const next = order.value.filter((v) => v.id !== video.id);
+      order.rebase((list) => list.filter((v) => v.id !== video.id));
+      lastSetRef.current = `${listId}:${idsKey(next)}`;
+    }
     try {
-      await api.removeFromPlaylist(selectedId, video.id);
-      refreshAll();
+      await api.removeFromPlaylist(listId, video.id);
+      refreshAll(listId);
       return true;
-    } catch {
-      // The optimistic removal above didn't stick — resync from the server to restore the row.
-      // api.req already surfaced the error to the user via the global error dialog.
-      refreshAll();
+    } catch (e) {
+      // `req` raises the global dialog for 4xx-validation and 5xx, but leaves 403/404 to the caller
+      // (the list was deleted or de-owned meanwhile) — so say it here, as moveItemTo does, or a
+      // confirmed removal fails in silence (inside the full-screen player there is not even a row
+      // snapping back to show it).
+      if (e instanceof HttpError && (e.status === 404 || e.status === 403))
+        notify({ level: "error", message: e.detail || t("playlists.removeFailed") });
+      refreshAll(listId); // …and resync, which restores any row the optimistic removal took out
       return false;
     }
   }
diff --git a/frontend/src/i18n/locales/en/playlists.json b/frontend/src/i18n/locales/en/playlists.json
index 8514f1f9..65f9fd5c 100644
--- a/frontend/src/i18n/locales/en/playlists.json
+++ b/frontend/src/i18n/locales/en/playlists.json
@@ -76,6 +76,7 @@
   "moveNoTargets": "There is no other playlist to move it to yet.",
   "movedToast": "“{{title}}” moved to “{{name}}” ✓",
   "moveFailed": "Couldn't move the video.",
+  "removeFailed": "Couldn't remove the video.",
   "moveErrors": {
     "not_in_playlist": "That video isn't in this playlist any more — it changed somewhere else.",
     "same_playlist": "That video is already in this playlist."
diff --git a/frontend/src/i18n/locales/hu/playlists.json b/frontend/src/i18n/locales/hu/playlists.json
index 7998a421..a9bfe1f9 100644
--- a/frontend/src/i18n/locales/hu/playlists.json
+++ b/frontend/src/i18n/locales/hu/playlists.json
@@ -76,6 +76,7 @@
   "moveNoTargets": "Még nincs másik lejátszási lista, ahová áthelyezhetnéd.",
   "movedToast": "„{{title}}” áthelyezve ide: „{{name}}” ✓",
   "moveFailed": "Nem sikerült áthelyezni a videót.",
+  "removeFailed": "Nem sikerült eltávolítani a videót.",
   "moveErrors": {
     "not_in_playlist": "Ez a videó már nincs ebben a listában — időközben máshol megváltozott.",
     "same_playlist": "Ez a videó már ebben a listában van."

From efd95fca01ef00934bae11006151345aa2c421fc Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 01:38:31 +0200
Subject: [PATCH 13/52] fix(ui): the card's channel name is a real link too;
 call sites the bug hunt left untested now have tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review R6 — the small items:

- The video card's channel name was still a <button> (pre-existing): ctrl/middle-click did nothing
  there while the title above it and the player's channel name honoured them. It renders through
  ChannelNameLink now, which grew a forwarded ref (the clamp measurement), pass-through attributes,
  a `tooltip`, and an opt-in `stopPropagation` so no click reaches the card's row.
- ChannelNameLink rendered an empty, still-tabbable <a> for a channel with no title yet (a stub first
  seen through a live search; pre-existing at this site). It falls back to the translated "Channel".
- The feed's SortKey→SortOption mapping existed twice in Feed.tsx; one `feedSortOptions` in
  feedSort.ts serves both modes (DIRECTIONLESS is module-private again).
- The backfill refresh's comment claimed a one-page cost. It refetches every loaded page of the
  grid, and that is the right price: backfilled videos are older, so they land below the head.

Tests for call sites that could be deleted with every lane green: the channel page running the
backfill refresh (knip had been blinded by the hook test's import), Feed handing the grid the live
results in the chosen key AND direction, the card using the link. Plus the alt-click arm of the shared
click predicate, and a plex filter-chip test that claimed it made no request while firing a real one.
Verified on localdev: the feed's channel names are anchors (same 14 px muted look), a plain click
opens the channel in-app. 7 mutations, each red on its assertion.
---
 .../components/ChannelNameLink.dom.test.tsx   |  36 ++++++
 frontend/src/components/ChannelNameLink.tsx   |  39 ++++--
 .../ChannelPage.backfill.dom.test.tsx         |  89 +++++++++++++
 frontend/src/components/Feed.tsx              |  26 +---
 .../src/components/Feed.ytsort.dom.test.tsx   | 118 ++++++++++++++++++
 .../components/VideoCard.channel.dom.test.tsx |  77 ++++++++++++
 frontend/src/components/VideoCard.tsx         |  30 +++--
 .../usePlexActiveFilters.dom.test.tsx         |  15 ++-
 frontend/src/lib/channelDetailPoll.ts         |  11 +-
 frontend/src/lib/feedSort.ts                  |  17 ++-
 frontend/src/lib/feedSort.yt.test.ts          |  22 +++-
 11 files changed, 425 insertions(+), 55 deletions(-)
 create mode 100644 frontend/src/components/ChannelPage.backfill.dom.test.tsx
 create mode 100644 frontend/src/components/Feed.ytsort.dom.test.tsx
 create mode 100644 frontend/src/components/VideoCard.channel.dom.test.tsx

diff --git a/frontend/src/components/ChannelNameLink.dom.test.tsx b/frontend/src/components/ChannelNameLink.dom.test.tsx
index 6f931b0d..481d7a48 100644
--- a/frontend/src/components/ChannelNameLink.dom.test.tsx
+++ b/frontend/src/components/ChannelNameLink.dom.test.tsx
@@ -7,6 +7,12 @@
 // path (which does more than navigate — the player has to close and reclaim its history entry first).
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render, screen, cleanup } from "@testing-library/react";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
 import ChannelNameLink from "./ChannelNameLink";
 
 const CH = "UCsXVk37bltHxD1rDPwtNM8Q";
@@ -57,6 +63,9 @@ describe("ChannelNameLink", () => {
     ["ctrl-click", { ctrlKey: true }],
     ["cmd-click", { metaKey: true }],
     ["shift-click", { shiftKey: true }],
+    // Alt/Option-click on a link is "download the target" — the one arm no test dispatched, so
+    // dropping it from the shared predicate hijacked it on every card thumbnail too.
+    ["alt-click", { altKey: true }],
   ])("leaves %s to the browser", (_name, mod) => {
     const { link, onOpenInApp } = renderLink();
     // Neither hijacked in-app nor prevented — the href is left to do its job.
@@ -70,4 +79,31 @@ describe("ChannelNameLink", () => {
     expect(link.getAttribute("href")).toContain("page=channels");
     expect(link.getAttribute("href")).toContain("q=abc");
   });
+
+  it("gives a channel with no title yet an accessible name", () => {
+    // A channel first seen through a live search can be a stub with no title. The anchor used to
+    // render empty — still in the tab order, announced by nothing but its href.
+    render(<ChannelNameLink channelId={CH} title={null} onOpenInApp={() => {}} />);
+    expect(screen.getByRole("link", { name: "player.channel" })).toBeTruthy();
+  });
+
+  it("keeps every click from a clickable ancestor when asked to — the browser's gestures too", () => {
+    // The video card's row reacts to clicks; its channel name must not trigger it, whichever way it
+    // is clicked.
+    const row = vi.fn();
+    render(
+      <div onClick={row}>
+        <ChannelNameLink channelId={CH} title="LEMMiNO" onOpenInApp={() => {}} stopPropagation />
+      </div>,
+    );
+    const link = screen.getByText("LEMMiNO");
+    // The bubbling guard in clickWasHandled never sees these (that is the point), so stop the
+    // browser's navigation in the capture phase instead.
+    const noNav = (e: Event) => e.preventDefault();
+    document.addEventListener("click", noNav, true);
+    for (const init of [{ button: 0 }, { ctrlKey: true }, { button: 1 }])
+      link.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true, ...init }));
+    document.removeEventListener("click", noNav, true);
+    expect(row).not.toHaveBeenCalled();
+  });
 });
diff --git a/frontend/src/components/ChannelNameLink.tsx b/frontend/src/components/ChannelNameLink.tsx
index 910e68ec..f567573c 100644
--- a/frontend/src/components/ChannelNameLink.tsx
+++ b/frontend/src/components/ChannelNameLink.tsx
@@ -1,37 +1,52 @@
+import { forwardRef, type AnchorHTMLAttributes } from "react";
+import { useTranslation } from "react-i18next";
 import { isPlainLeftClick } from "../lib/nav";
 import { urlWithParams } from "../lib/urlState";
 
 // A channel name that is a REAL link. The player showed it as a `<button>`, so the browser's own
 // gestures did nothing on it: middle-click and Ctrl/Cmd-click opened no tab, on a thing that looks
-// exactly like a link (the YouTube icon right next to it IS an anchor and does open one).
+// exactly like a link (the YouTube icon right next to it IS an anchor and does open one). The video
+// card's channel name had the same `<button>`, so it renders through here too.
 //
 // The href is the same URL `openChannel` pushes — `?chan=<id>` on the current page — so a new tab
 // lands where the in-app navigation would have. A plain left click is still handled in-app, because
 // the SPA path does more than navigate (the player has to close first and reclaim its own
 // Back-to-close history entry; see closeThenNavigate).
-export default function ChannelNameLink({
-  channelId,
-  title,
-  onOpenInApp,
-  className,
-}: {
+type Props = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "onClick" | "title"> & {
   channelId: string;
   title: string | null | undefined;
   /** The in-app navigation, run only for a plain left click. */
   onOpenInApp: () => void;
-  className?: string;
-}) {
+  /** The native tooltip (`title` is taken by the channel's name). */
+  tooltip?: string;
+  /** Keep EVERY click on the link — the browser's own gestures too — from reaching a clickable
+   *  ancestor (the video card's row). */
+  stopPropagation?: boolean;
+};
+
+const ChannelNameLink = forwardRef<HTMLAnchorElement, Props>(function ChannelNameLink(
+  { channelId, title, onOpenInApp, tooltip, stopPropagation, ...rest },
+  ref,
+) {
+  const { t } = useTranslation();
   return (
     <a
+      {...rest}
+      ref={ref}
       href={urlWithParams({ chan: channelId })}
+      title={tooltip}
       onClick={(e) => {
+        if (stopPropagation) e.stopPropagation();
         if (!isPlainLeftClick(e)) return; // let the browser open its tab/window
         e.preventDefault();
         onOpenInApp();
       }}
-      className={className}
     >
-      {title}
+      {/* A channel first seen through a live search can have no title yet. An empty anchor would
+          still be in the tab order, announced by nothing but its href. */}
+      {title || t("player.channel")}
     </a>
   );
-}
+});
+
+export default ChannelNameLink;
diff --git a/frontend/src/components/ChannelPage.backfill.dom.test.tsx b/frontend/src/components/ChannelPage.backfill.dom.test.tsx
new file mode 100644
index 00000000..bce7e3db
--- /dev/null
+++ b/frontend/src/components/ChannelPage.backfill.dom.test.tsx
@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+//
+// The channel page's video grid follows a running full-history backfill (bug hunt 2026-09, item 6).
+// The rule itself — when a poll reading should refresh the grid — is pinned on the hook in
+// lib/channelDetailPoll.backfill.dom.test.tsx. This pins that the PAGE runs it: deleting the hook's
+// one call site left every lane green, knip included (the hook test's import kept the export "used").
+//
+// The page's own poll is what feeds the hook; a newer reading is handed to it here through the same
+// query key the poll writes, rather than waiting out the 4 s interval. The Feed itself is stubbed —
+// what matters is whether its queries are told they are stale.
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, waitFor, cleanup, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+}));
+vi.mock("./NavigationProvider", () => ({
+  useNavigationActions: () => ({ closeChannel: vi.fn(), openChannel: vi.fn() }),
+}));
+vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
+vi.mock("./FeedFiltersProvider", () => ({
+  useFeedFilters: () => ({ includeNormal: true, includeShorts: false, includeLive: false }),
+}));
+vi.mock("./Feed", () => ({ default: () => null }));
+vi.mock("./ChannelAbout", () => ({ default: () => null }));
+
+import ChannelPage from "./ChannelPage";
+import { api, type ChannelDetail, type FeedFilters, type Me } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const CH = "UCsXVk37bltHxD1rDPwtNM8Q";
+const reading = (stored_videos: number): ChannelDetail =>
+  ({
+    id: CH,
+    title: "LEMMiNO",
+    subscribed: true,
+    deep_requested: true,
+    backfill_done: false,
+    stored_videos,
+  }) as unknown as ChannelDetail;
+const feedKey = qk.feed({ q: "", channel: CH } as unknown as FeedFilters);
+
+describe("ChannelPage — the grid follows a running backfill", () => {
+  it("marks the channel's video grid stale when the poll sees more stored videos", async () => {
+    vi.spyOn(api, "channelDetail").mockResolvedValue(reading(19));
+    vi.spyOn(api, "tags").mockResolvedValue([] as never);
+    const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    qc.setQueryData(feedKey, { pages: [{ items: [], next_cursor: null }], pageParams: [null] });
+    render(
+      <QueryClientProvider client={qc}>
+        <ChannelPage
+          channelId={CH}
+          initialName="LEMMiNO"
+          me={{ id: 1, can_write: true } as unknown as Me}
+          view="cards"
+          setView={() => {}}
+          onShowInFeed={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+    await waitFor(() => expect(api.channelDetail).toHaveBeenCalled());
+    await waitFor(() => expect(qc.getQueryData(qk.channel(CH))).toBeTruthy());
+    expect(qc.getQueryState(feedKey)?.isInvalidated).toBe(false);
+
+    // The next poll tick: the background job has stored 60 more.
+    act(() => qc.setQueryData(qk.channel(CH), reading(79)));
+
+    await waitFor(() => expect(qc.getQueryState(feedKey)?.isInvalidated).toBe(true));
+  });
+});
diff --git a/frontend/src/components/Feed.tsx b/frontend/src/components/Feed.tsx
index 3a6c5f08..182fb3ca 100644
--- a/frontend/src/components/Feed.tsx
+++ b/frontend/src/components/Feed.tsx
@@ -27,9 +27,8 @@ import { notify, resolveVideo } from "../lib/notifications";
 import { useDebounced } from "../lib/useDebounced";
 import {
   buildSort,
-  DIRECTIONLESS,
+  feedSortOptions,
   parseSort,
-  SORT_DEFAULT_DIR,
   SORT_KEYS,
   sortYtResults,
   YT_SORT_KEYS,
@@ -447,14 +446,7 @@ export default function Feed({
             {/* Sorts the results already on screen (see sortYtResults) — it never re-queries, so it
                 costs nothing and works the same on both search sources. */}
             <SortControl
-              options={YT_SORT_KEYS.map((k) => ({
-                key: k,
-                label: t("feed.sortKey." + k),
-                directionless: DIRECTIONLESS.includes(k),
-                defaultDir: DIRECTIONLESS.includes(k)
-                  ? undefined
-                  : SORT_DEFAULT_DIR[k as Exclude<SortKey, "shuffle" | "relevance">],
-              }))}
+              options={feedSortOptions(YT_SORT_KEYS, (k) => t("feed.sortKey." + k))}
               sort={ytSort}
               onChange={(next) => setYtSort(next ?? { key: "relevance", dir: "desc" })}
               label={t("feed.sortLabel")}
@@ -589,16 +581,10 @@ export default function Feed({
   const { key: sortKey, dir: sortDir } = parseSort(filters.sort);
   // The feed's sort vocabulary as source-agnostic options for the shared SortControl. Relevance only
   // ranks meaningfully with a search term (offered then); shuffle/relevance are directionless.
-  const sortOptions: SortOption[] = (
-    filters.q.trim() ? (["relevance", ...sortKeys] as SortKey[]) : sortKeys
-  ).map((k) => ({
-    key: k,
-    label: t("feed.sortKey." + k),
-    directionless: DIRECTIONLESS.includes(k),
-    defaultDir: DIRECTIONLESS.includes(k)
-      ? undefined
-      : SORT_DEFAULT_DIR[k as Exclude<SortKey, "shuffle" | "relevance">],
-  }));
+  const sortOptions: SortOption[] = feedSortOptions(
+    filters.q.trim() ? (["relevance", ...sortKeys] as SortKey[]) : sortKeys,
+    (k) => t("feed.sortKey." + k),
+  );
 
   // Sort + view mode are tightly bound to the grid below, so they live pinned to the right of the
   // applied-filter row (directly above the cards), not up in the filter toolbar. Extracted here so the
diff --git a/frontend/src/components/Feed.ytsort.dom.test.tsx b/frontend/src/components/Feed.ytsort.dom.test.tsx
new file mode 100644
index 00000000..d3ced48a
--- /dev/null
+++ b/frontend/src/components/Feed.ytsort.dom.test.tsx
@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+//
+// The live-YouTube results' Sort control, wired end to end: the pref it writes, the key and
+// direction Feed hands to sortYtResults, and the order that reaches the grid. sortYtResults itself
+// is pinned in feedSort.yt.test.ts; a deep-review of the 2026-09 bug hunt found that the CALL SITE
+// could ignore the chosen direction (or skip the sort entirely) with every lane green.
+//
+// The virtualised grid lays out nothing in jsdom, so it is replaced by a plain list that shows the
+// order Feed gave it — which is exactly the thing under test.
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor, cleanup } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+}));
+vi.mock("./WizardProvider", () => ({ useWizard: () => ({ openWizard: vi.fn() }) }));
+vi.mock("./VirtualFeed", () => ({
+  default: ({ items }: { items: { id: string; title: string }[] }) => (
+    <ol aria-label="results">
+      {items.map((v) => (
+        <li key={v.id}>{v.title}</li>
+      ))}
+    </ol>
+  ),
+}));
+
+import Feed from "./Feed";
+import { api, DEFAULT_TAG_MODES, type FeedFilters, type Video } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const FILTERS: FeedFilters = {
+  tags: [],
+  tagModes: DEFAULT_TAG_MODES,
+  channelIds: [],
+  q: "",
+  sort: "newest",
+  scope: "my",
+  includeNormal: true,
+  includeShorts: false,
+  includeLive: false,
+  show: "unwatched",
+};
+
+const hit = (id: string, duration_seconds: number): Video =>
+  ({
+    id,
+    title: `hit ${id}`,
+    channel_id: "UCx",
+    channel_title: "Channel",
+    status: "new",
+    position_seconds: 0,
+    duration_seconds,
+    published_at: "2026-01-01T00:00:00Z",
+    watch_url: `https://www.youtube.com/watch?v=${id}`,
+  }) as unknown as Video;
+
+const order = () =>
+  Array.from(screen.getByRole("list", { name: "results" }).querySelectorAll("li")).map(
+    (li) => li.textContent,
+  );
+
+describe("Feed — sorting the live YouTube results", () => {
+  it("hands the grid the results in the key AND direction the viewer picked", async () => {
+    vi.spyOn(api, "savePrefs").mockResolvedValue(undefined as never);
+    vi.spyOn(api, "searchYoutube").mockResolvedValue({
+      items: [hit("a", 300), hit("b", 100), hit("c", 200)],
+      next_cursor: null,
+      source: "scrape",
+    } as never);
+    const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    qc.setQueryData(qk.me(), { id: 1, can_write: true, prefs: {} });
+    render(
+      <QueryClientProvider client={qc}>
+        <Feed
+          filters={FILTERS}
+          setFilters={() => {}}
+          view="cards"
+          setView={() => {}}
+          canRead
+          ytSearch="lemmino"
+          onYtSearch={() => {}}
+          onExitYtSearch={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+    // Relevance is the provider's own ranking — the order the results arrived in.
+    await waitFor(() => expect(order()).toEqual(["hit a", "hit b", "hit c"]));
+
+    fireEvent.click(screen.getByRole("button", { name: /^feed\.sortLabel:/ }));
+    const duration = (await screen.findAllByRole("menuitemradio", { hidden: true })).find((o) =>
+      o.textContent?.includes("feed.sortKey.duration"),
+    );
+    fireEvent.click(duration!);
+    fireEvent.click(await screen.findByText("feed.dirAsc"));
+    await waitFor(() => expect(order()).toEqual(["hit b", "hit c", "hit a"]));
+    fireEvent.click(screen.getByText("feed.dirDesc"));
+    await waitFor(() => expect(order()).toEqual(["hit a", "hit c", "hit b"]));
+  });
+});
diff --git a/frontend/src/components/VideoCard.channel.dom.test.tsx b/frontend/src/components/VideoCard.channel.dom.test.tsx
new file mode 100644
index 00000000..c9e4dbe1
--- /dev/null
+++ b/frontend/src/components/VideoCard.channel.dom.test.tsx
@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+//
+// The video card's channel name was a <button>: a plain click opened the channel in-app, but
+// middle-click and Ctrl/Cmd-click did nothing — while the title right above it, an anchor, honoured
+// them. Found by the 2026-09 bug-hunt deep-review, when the player's channel name had just become a
+// real link and the card's had not. (The link's own gesture rules are pinned in
+// ChannelNameLink.dom.test.tsx; this pins that the CARD uses it.)
+import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+const h = vi.hoisted(() => ({ openChannel: vi.fn() }));
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+}));
+vi.mock("./NavigationProvider", () => ({
+  useNavigationActions: () => ({ openChannel: h.openChannel }),
+}));
+
+import VideoCard from "./VideoCard";
+import type { Video } from "../lib/api";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+
+const CH = "UCsXVk37bltHxD1rDPwtNM8Q";
+const video = {
+  id: "abc123",
+  title: "Cicada 3301",
+  channel_id: CH,
+  channel_title: "LEMMiNO",
+  status: "new",
+  saved: false,
+  position_seconds: 0,
+  duration_seconds: 1200,
+  published_at: "2026-01-01T00:00:00Z",
+  watch_url: "https://www.youtube.com/watch?v=abc123",
+  thumbnail_url: "",
+} as unknown as Video;
+
+beforeEach(() => {
+  cleanup();
+  h.openChannel.mockClear();
+  window.history.replaceState({}, "", "/?page=feed");
+});
+
+describe("VideoCard — the channel name", () => {
+  it("is a real link to the channel, and a plain click still opens it in-app", () => {
+    render(
+      <QueryClientProvider client={new QueryClient()}>
+        <VideoCard
+          video={video}
+          view="cards"
+          width={320}
+          onState={() => {}}
+          onToggleSave={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+    const link = screen.getByTestId("video-card-channel");
+    expect(link.tagName).toBe("A");
+    expect(link.getAttribute("href")).toBe(`/?page=feed&chan=${CH}`);
+    link.click();
+    expect(h.openChannel).toHaveBeenCalledWith(CH, "LEMMiNO");
+  });
+});
diff --git a/frontend/src/components/VideoCard.tsx b/frontend/src/components/VideoCard.tsx
index 7f631d34..6c657c32 100644
--- a/frontend/src/components/VideoCard.tsx
+++ b/frontend/src/components/VideoCard.tsx
@@ -23,6 +23,7 @@ import type { Video, VideoStatus } from "../lib/api";
 import { FEED_VIEW_SPEC, type FeedView } from "../lib/feedView";
 import { formatDate, formatDuration, formatViews, relativeTime } from "../lib/format";
 import { isPlainLeftClick } from "../lib/nav";
+import ChannelNameLink from "./ChannelNameLink";
 
 function Actions({
   video,
@@ -439,7 +440,7 @@ function VideoCard({
   // and the channel name: both truncate in some views and fit in others, and a tooltip that just
   // repeats what's already legible is noise.
   const titleRef = useRef<HTMLAnchorElement>(null);
-  const channelRef = useRef<HTMLButtonElement>(null);
+  const channelRef = useRef<HTMLAnchorElement>(null);
   const [titleClamped, setTitleClamped] = useState(false);
   const [channelClamped, setChannelClamped] = useState(false);
   useEffect(() => {
@@ -473,19 +474,22 @@ function VideoCard({
       {video.title}
     </a>
   );
-  const channelButton = (
-    <button
+  // A real link, like the title above it: a <button> here ignored middle-click and Ctrl/Cmd-click,
+  // so the same card honoured the browser's gestures on its title and silently dropped them on its
+  // channel name.
+  const channelLink = (
+    <ChannelNameLink
       ref={channelRef}
       data-testid="video-card-channel"
-      onClick={(e) => {
-        e.stopPropagation();
-        openChannel(video.channel_id, video.channel_title ?? t("card.thisChannel"));
-      }}
-      title={channelClamped ? (video.channel_title ?? undefined) : undefined}
+      channelId={video.channel_id}
+      title={video.channel_title}
+      onOpenInApp={() =>
+        openChannel(video.channel_id, video.channel_title ?? t("card.thisChannel"))
+      }
+      stopPropagation
+      tooltip={channelClamped ? (video.channel_title ?? undefined) : undefined}
       className="text-sm text-muted truncate block w-fit max-w-full text-left hover:text-fg"
-    >
-      {video.channel_title}
-    </button>
+    />
   );
   const actions = (
     <Actions
@@ -547,7 +551,7 @@ function VideoCard({
               filter panel are doing. Until the first measure lands (width 0) show everything: the
               row is off-screen for that frame anyway, and guessing narrow would flash. */}
           <div className="min-w-0 flex-1">{title}</div>
-          {fits(ROW_FITS.channel) && <div className="shrink-0 w-32">{channelButton}</div>}
+          {fits(ROW_FITS.channel) && <div className="shrink-0 w-32">{channelLink}</div>}
           {fits(ROW_FITS.meta) && <RowMetaCells video={video} />}
           {/* Right-aligned like the duration: it's a number, so the digits share an edge. 64px
               holds the widest bare form ("101.7K" at 48) in either language — dropping the word
@@ -578,7 +582,7 @@ function VideoCard({
   const textBlock = (
     <>
       {title}
-      <div className="mt-0.5">{channelButton}</div>
+      <div className="mt-0.5">{channelLink}</div>
       <div className="text-xs text-muted mt-0.5">
         {views}
         {views && " · "}
diff --git a/frontend/src/components/usePlexActiveFilters.dom.test.tsx b/frontend/src/components/usePlexActiveFilters.dom.test.tsx
index 85da3b95..8bfd1b09 100644
--- a/frontend/src/components/usePlexActiveFilters.dom.test.tsx
+++ b/frontend/src/components/usePlexActiveFilters.dom.test.tsx
@@ -4,11 +4,11 @@
 // for the in-panel narrowings (expanded filters + watch-state) but NO LONGER emits a sort chip —
 // sort is an always-visible control above the grid now, like the Feed. i18n is key-passthrough and
 // the provider is mocked so the hook can be driven with a non-default sort present.
-import { describe, it, expect, vi } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { renderHook } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { createElement, type ReactNode } from "react";
-import { EMPTY_PLEX_FILTERS } from "../lib/api";
+import { api, EMPTY_PLEX_FILTERS } from "../lib/api";
 
 vi.mock("react-i18next", async (importOriginal) => {
   const actual = await importOriginal<typeof import("react-i18next")>();
@@ -40,8 +40,15 @@ import { usePlexActiveFilters } from "./usePlexActiveFilters";
 import { qk } from "../lib/queryKeys";
 
 // The hook resolves collection titles it does not already have through react-query, so it needs a
-// client. Every id here already HAS a title, so the query stays disabled and nothing is requested.
+// client. "B" has no title in the state, so the hook DOES ask for it — stubbed here, so no test issues
+// a real request (an unmocked one used to fire from the first test and retry after it had finished).
 const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+beforeEach(() => {
+  vi.spyOn(api, "plexCollections").mockResolvedValue({ collections: [] } as never);
+});
+afterEach(() => {
+  vi.restoreAllMocks();
+});
 const wrapper = ({ children }: { children: ReactNode }) =>
   createElement(QueryClientProvider, { client: qc }, children);
 
@@ -59,7 +66,7 @@ describe("usePlexActiveFilters", () => {
 
   it("labels a link-supplied collection with its resolved title, not the bare id", () => {
     // Seed the resolution the hook would fetch, so this asserts the WIRING (hook -> builder -> label)
-    // rather than the network. Nothing is mocked.
+    // rather than the network.
     qc.setQueryData(qk.plexCollections("titles", "B"), {
       collections: [{ id: "B", title: "Pirates of the Caribbean Collection" }],
     });
diff --git a/frontend/src/lib/channelDetailPoll.ts b/frontend/src/lib/channelDetailPoll.ts
index f3057de1..ef191a17 100644
--- a/frontend/src/lib/channelDetailPoll.ts
+++ b/frontend/src/lib/channelDetailPoll.ts
@@ -37,10 +37,13 @@ const backfillChangedCatalog = (
  *  background job has written a row — which is why the list stayed on the ~19 cards the channel had
  *  at subscribe time while the count above it climbed into the thousands.
  *
- *  Cost is bounded: the predicate fires only on a tick where the count actually moved, the poll
- *  itself pauses while the tab is unfocused, and a channel grid is normally a single 60-item page
- *  whose newest-first head the (older) backfilled videos don't disturb — so the refetch usually
- *  comes back structurally identical and re-renders nothing. */
+ *  What it costs, honestly: an invalidation refetches EVERY loaded page of the grid's infinite
+ *  query — one request per page the viewer has scrolled through, on each 4 s tick where the count
+ *  moved, for as long as the backfill runs (the poll pauses while the tab is hidden, and stops when
+ *  the back-catalogue is in). That is the right price, not an accident: backfilled videos are OLDER
+ *  than what the grid opened with, so under the newest-first order they land in the pages BELOW the
+ *  head — refreshing only the first page would leave out exactly the rows the backfill wrote. The
+ *  head itself comes back structurally identical and re-renders nothing. */
 export function useBackfillFeedRefresh(detail: ChannelDetail | undefined, qc: QueryClient) {
   const seen = useRef<ChannelDetail | undefined>(undefined);
   useEffect(() => {
diff --git a/frontend/src/lib/feedSort.ts b/frontend/src/lib/feedSort.ts
index 65ba12ed..2257c8fc 100644
--- a/frontend/src/lib/feedSort.ts
+++ b/frontend/src/lib/feedSort.ts
@@ -2,6 +2,7 @@
 // …); the UI thinks in a key + direction. Kept here rather than inside Feed so the active-filter
 // chips can label a sort without re-deriving the mapping.
 import type { Video } from "./api";
+import type { SortOption } from "./columnSort";
 
 export type SortKey =
   | "date"
@@ -24,7 +25,7 @@ export const SORT_KEYS: SortKey[] = [
 ];
 
 /** Sorts with no meaningful asc/desc flip. */
-export const DIRECTIONLESS: SortKey[] = ["shuffle", "relevance"];
+const DIRECTIONLESS: SortKey[] = ["shuffle", "relevance"];
 
 const SORT_MAP: Record<Exclude<SortKey, "shuffle" | "relevance">, { asc: string; desc: string }> = {
   date: { desc: "newest", asc: "oldest" },
@@ -58,6 +59,20 @@ export function buildSort(key: SortKey, dir: "asc" | "desc"): string {
   return SORT_MAP[key][dir];
 }
 
+/** Feed sort keys as options for the shared SortControl. ONE mapping for the library feed and the
+ *  live search results, which share the vocabulary: two copies could hand the same key a different
+ *  direction default, or lose its directionless flag, depending on which mode you were in. */
+export function feedSortOptions(keys: SortKey[], label: (k: SortKey) => string): SortOption[] {
+  return keys.map((k) => ({
+    key: k,
+    label: label(k),
+    directionless: DIRECTIONLESS.includes(k),
+    defaultDir: DIRECTIONLESS.includes(k)
+      ? undefined
+      : SORT_DEFAULT_DIR[k as Exclude<SortKey, "shuffle" | "relevance">],
+  }));
+}
+
 // --- Live YouTube search results ----------------------------------------------------------------
 //
 // The results view had NO sort control at all — the order was the provider's and that was that. It is
diff --git a/frontend/src/lib/feedSort.yt.test.ts b/frontend/src/lib/feedSort.yt.test.ts
index 5f4a921d..ca8c178e 100644
--- a/frontend/src/lib/feedSort.yt.test.ts
+++ b/frontend/src/lib/feedSort.yt.test.ts
@@ -1,5 +1,11 @@
 import { describe, it, expect } from "vitest";
-import { sortYtResults, YT_SORT_KEYS, SORT_KEYS } from "./feedSort";
+import {
+  feedSortOptions,
+  sortYtResults,
+  SORT_DEFAULT_DIR,
+  YT_SORT_KEYS,
+  SORT_KEYS,
+} from "./feedSort";
 import type { Video } from "./api";
 
 // The live-YouTube results view shipped with no sort control at all: the provider's order was the
@@ -111,3 +117,17 @@ describe("sortYtResults", () => {
     expect(titles(input)).toEqual(titles(RESULTS));
   });
 });
+
+describe("feedSortOptions", () => {
+  // The library feed and the live results used to build their options from two copies of this
+  // mapping; one helper means a key cannot get a different default direction in one of the modes.
+  it("gives directional keys their default direction and marks shuffle/relevance directionless", () => {
+    const opts = feedSortOptions(["relevance", "date", "duration", "shuffle"], (k) => `label:${k}`);
+    expect(opts.map((o) => [o.key, o.label, !!o.directionless, o.defaultDir])).toEqual([
+      ["relevance", "label:relevance", true, undefined],
+      ["date", "label:date", false, SORT_DEFAULT_DIR.date],
+      ["duration", "label:duration", false, SORT_DEFAULT_DIR.duration],
+      ["shuffle", "label:shuffle", true, undefined],
+    ]);
+  });
+});

From d2e225666b1f55cada1f9cb54b69291d249b8d08 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 01:42:17 +0200
Subject: [PATCH 14/52] test(playlists): let react-query's notify tick run
 inside act before the reopen click
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The D1 regression test patched the cache and clicked at once; react-query delivers a cache write to
its observers on a setTimeout(0), so under the gate's parallel load the click could beat the page's
re-render and read the old row (748, not 830). Test-only race — a human reopen comes seconds later.
Stable across three full-suite runs; the D1 mutation still turns it red.
---
 frontend/src/components/Playlists.dom.test.tsx | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
index db537359..e835fc1a 100644
--- a/frontend/src/components/Playlists.dom.test.tsx
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -124,8 +124,15 @@ describe("Playlists — the row the player is launched with", () => {
     await waitFor(() => expect(h.player?.video.position_seconds).toBe(748));
     act(() => h.player!.onClose());
     h.player = null;
-    // What the player's cleanup does with the position the server confirmed.
-    act(() => patchCachedProgress(qc, new Map([["V", 830]])));
+    // What the player's cleanup does with the position the server confirmed. react-query hands a
+    // cache write to its observers on a setTimeout(0); outside act, the re-render it triggers is
+    // scheduled by React on its own and raced the click below under the gate's parallel load (the
+    // reopen read 748). The write is SYNCHRONOUS, so its notify timer is registered before ours and
+    // fires first — and inside act, the render it causes is flushed before act returns.
+    await act(async () => {
+      patchCachedProgress(qc, new Map([["V", 830]]));
+      await new Promise((r) => setTimeout(r, 0));
+    });
     await play("Video V");
     await waitFor(() => expect(h.player?.video.position_seconds).toBe(830));
   });

From 473d9f02f2dbeb1b898fef9cc1d3cae321f8c551 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:18:08 +0200
Subject: [PATCH 15/52] fix(plex): subtitle windows land where the full pass
 does, and the extractor stops re-reading, respawning and outliving the
 process
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 2 of the 2026-09 bug hunt, over the round-1 fix diff.

- A window was LATE by the distance to the keyframe its input seek landed on, and then doubled for
  good once the full pass merged in: a cue already running at the window's start came out at a
  negative time, and the webvtt muxer's default shifted the whole output so it sat at 0. Measured on
  the real Westworld S01E06 at 25:00: every window cue +5.005 s, 682 cues merged instead of 608.
  `-avoid_negative_ts disabled` keeps the times exact (the parser reads ffmpeg's signed-field
  spelling of a negative time); now 608/608 on that file, and a real-ffmpeg test pins it.
- A full pass that failed was re-armed every minute while the viewer watched what it did publish —
  a whole-container read per minute. It now backs off for an hour; windows keep running meanwhile.
- A failed WINDOW set the track's failure memo, so any uncovered position read "failed" — a final
  answer that ends the player's poll, even with the full pass about to deliver, and one any account
  could plant with an absurd `at`. It now marks only the span it failed to read; "failed" is given
  once the full pass AND a window there have both failed.
- Windows join by what they COVER, not a bucketed identity: a backward seek no longer waits behind a
  window that cannot cover it, and a playhead crossing a bucket edge no longer queues a second read.
  The queue is bounded per track and overall.
- shutdown() sets a flag a worker checks before it spawns ffmpeg (one still in its Plex lookup used to
  start a read after the kill sweep); queued-job cancellation and the lifespan call are now tested.
- A window starts where ffmpeg is told to seek (rounded to the ms it gets), a rounded-up millisecond
  carries into the minute (no more `00:00:60.000`), a key's first publish claims nothing before its
  VTT lands, and `at`/`offset`/`start`/`aoff` refuse non-finite values (`at` also an absurd one).
---
 backend/app/plex/subtitles.py               | 215 ++++++++++++----
 backend/app/routes/plex/playback.py         |  23 +-
 backend/tests/test_plex_subtitle_prepare.py | 269 +++++++++++++++++++-
 3 files changed, 454 insertions(+), 53 deletions(-)

diff --git a/backend/app/plex/subtitles.py b/backend/app/plex/subtitles.py
index f9048565..bf659372 100644
--- a/backend/app/plex/subtitles.py
+++ b/backend/app/plex/subtitles.py
@@ -73,6 +73,9 @@ def srt_to_vtt(text: str) -> str:
 
 
 def _vtt_ts_to_s(ts: str) -> float:
+    # Also reads ffmpeg's spelling of a NEGATIVE time (a windowed pass, see `_ffmpeg_extract`): its
+    # webvtt muxer splits the milliseconds with C's truncating division, so every field carries the
+    # sign — -5.005 s is `00:-5.-05`, -65.3 s is `-1:-5.-300` — and summing the signed fields is exact.
     parts = ts.split(":")
     h = "0" if len(parts) == 2 else parts[0]
     m, rest = parts[-2], parts[-1]
@@ -81,16 +84,12 @@ def _vtt_ts_to_s(ts: str) -> float:
 
 
 def _vtt_s_to_ts(x: float) -> str:
-    x = max(0.0, x)
-    h = int(x // 3600)
-    x -= h * 3600
-    m = int(x // 60)
-    x -= m * 60
-    s = int(x)
-    ms = int(round((x - s) * 1000))
-    if ms >= 1000:
-        s += 1
-        ms -= 1000
+    # Rounded to whole milliseconds FIRST, then split: rounding the fraction last carried a rounded-up
+    # millisecond into the seconds and no further, so 59.9996 came out as `00:00:60.000` — a timestamp
+    # the WebVTT parser rejects, silently dropping that cue.
+    h, rest = divmod(int(round(max(0.0, x) * 1000)), 3_600_000)
+    m, rest = divmod(rest, 60_000)
+    s, ms = divmod(rest, 1000)
     return f"{h:02d}:{m:02d}:{s:02d}.{ms:03d}"
 
 
@@ -314,6 +313,12 @@ def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) ->
     with _PUBLISH_LOCK:
         old = cache_read(key)
         old_ranges, was_complete = read_meta(key)
+        if old is None:
+            # A VTT with no sidecar reads as a COMPLETE track (see read_meta — how older builds
+            # cached), and a publish is two renames. So before a key's first VTT lands, its sidecar
+            # already claims nothing: dying between the two then leaves a window that is extracted
+            # again, never one taken for the whole track for good.
+            _write_meta(key, old_ranges, False)
         cache_write(key, merge_vtt(old or "", vtt))
         _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
 
@@ -330,19 +335,46 @@ WINDOW_LEN_S = 300.0
 # Ceiling on one ffmpeg run so a wedged extraction can't hold a pool thread forever (the old
 # in-request extraction had no timeout at all).
 EXTRACT_TIMEOUT_S = 900.0
-# A failed track is remembered briefly so a 1 s status poll doesn't respawn ffmpeg every second, and
-# forgotten again soon after so fixing the file (or Plex coming back) doesn't need a restart.
+# A failed track (or window) is remembered briefly so a 1 s status poll doesn't respawn ffmpeg every
+# second, and forgotten again soon after so fixing the file (or Plex coming back) doesn't need a
+# restart.
 FAIL_TTL_S = 60.0
+# …except a FULL pass that failed. That is a read of the whole container (minutes), a failure that
+# reproduces does so every time, and the viewer is typically inside what it did publish — so the
+# short memo re-armed a whole-file read every minute for as long as they watched. Windows around the
+# playhead still run meanwhile; only the full pass waits this out.
+FULL_RETRY_S = 3600.0
+# The furthest position the status poll accepts. No film is this long, and an absurd one used to
+# reach ffmpeg's `-ss` (which rejects anything past its int64 microseconds).
+MAX_POSITION_S = 100_000.0
 # Two items' full passes plus a window for a third: enough that a seek into an un-extracted region is
 # served while a full pass runs, bounded so a burst can't thrash the array.
 _POOL = ThreadPoolExecutor(max_workers=3, thread_name_prefix="plex-subs")
+# Bounds on what may wait for that pool. Its queue is unbounded and every job is a read of the
+# library: a viewer scrubbing through a film queued a window per stop (the one where they stopped ran
+# LAST), and a script could queue thousands. Past either bound nothing is queued — the next poll asks
+# again, by which time something has finished.
+_MAX_INFLIGHT = 12
+_MAX_TRACK_WINDOWS = 2
 
 _LOCK = threading.Lock()
-_INFLIGHT: set[tuple] = set()
+# Queued or running jobs → the absolute span a window job reads (None for a full pass).
+_INFLIGHT: dict[tuple, tuple[float, float] | None] = {}
+# Track-level failures: a track that cannot be served at all (no item, a bitmap track, Plex down…).
 _FAILURES: dict[str, tuple[str, float]] = {}
+# rating_key → when its full pass last failed (see FULL_RETRY_S).
+_FULL_FAILED: dict[str, float] = {}
+# cache key → the spans windows failed to read, with when. A failed window says nothing about the rest
+# of the track — the full pass may be about to deliver it — so it is remembered as a SPAN: it must be
+# neither respawned every poll nor taken as a failure of positions it never tried. (It used to set the
+# track-level memo, which told every viewer at any uncovered position "failed" — a final answer that
+# ends the player's poll — including one planted by a request for an absurd position.)
+_WIN_FAILED: dict[str, list[tuple[float, float, float]]] = {}
 _PUBLISH_LOCK = threading.Lock()
-# The ffmpeg children currently running, so a shutdown can kill them (see `shutdown`).
+# The ffmpeg children currently running, so a shutdown can kill them (see `shutdown`), and whether it
+# has: a worker that reaches its Popen after the kill sweep must not start a read.
 _PROCS: set[subprocess.Popen] = set()
+_STOPPING = False
 
 
 class SubtitleUnavailable(Exception):
@@ -368,9 +400,13 @@ UNAVAILABLE_STATUS = {
 
 def reset_state() -> None:
     """Drop the in-flight/failure registries (tests; nothing in the app needs it)."""
+    global _STOPPING
     with _LOCK:
         _INFLIGHT.clear()
         _FAILURES.clear()
+        _FULL_FAILED.clear()
+        _WIN_FAILED.clear()
+        _STOPPING = False
 
 
 def shutdown() -> None:
@@ -378,11 +414,14 @@ def shutdown() -> None:
     joins them at interpreter exit — so a worker still inside a full pass (minutes on a big file, up
     to EXTRACT_TIMEOUT_S) held the process open after uvicorn had stopped, until the container runtime
     SIGKILLed it. Queued jobs are dropped and running ffmpeg children are killed, which returns their
-    workers at once. Nothing that matters is lost: a publish is an atomic rename, and an interrupted
-    track is simply extracted again on the next poll."""
-    _POOL.shutdown(wait=False, cancel_futures=True)
+    workers at once — and a worker still BEFORE its ffmpeg (the Plex lookup, the DB) finds the flag
+    and never starts one. Nothing that matters is lost: an interrupted publish cannot pass for a whole
+    track (see `publish`), and an interrupted track is simply extracted again on the next poll."""
+    global _STOPPING
     with _LOCK:
+        _STOPPING = True
         procs = list(_PROCS)
+    _POOL.shutdown(wait=False, cancel_futures=True)
     for p in procs:
         p.kill()
 
@@ -401,6 +440,36 @@ def _recent_failure(key: str) -> str | None:
         return None
 
 
+def _full_failed(rating_key: str) -> bool:
+    with _LOCK:
+        when = _FULL_FAILED.get(rating_key)
+        if when is not None and time.monotonic() - when < FULL_RETRY_S:
+            return True
+        _FULL_FAILED.pop(rating_key, None)
+        return False
+
+
+def _live_window_failures(key: str) -> list[tuple[float, float, float]]:
+    """(Caller holds _LOCK.) The key's failed-window spans that are still remembered."""
+    now = time.monotonic()
+    live = [f for f in _WIN_FAILED.get(key, []) if now - f[2] < FAIL_TTL_S]
+    if live:
+        _WIN_FAILED[key] = live
+    else:
+        _WIN_FAILED.pop(key, None)
+    return live
+
+
+def _window_fail(key: str, span: tuple[float, float]) -> None:
+    with _LOCK:
+        _WIN_FAILED[key] = [*_live_window_failures(key), (span[0], span[1], time.monotonic())]
+
+
+def _window_failed(key: str, at: float) -> bool:
+    with _LOCK:
+        return any(a <= at <= b for a, b, _ in _live_window_failures(key))
+
+
 def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
     """State of one subtitle track, scheduling whatever extraction is still missing. NEVER blocks.
 
@@ -416,8 +485,21 @@ def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
     code = _recent_failure(key)
     if code and not covered:
         return {"state": "failed", "code": code, "gen": generation(key)}
+    # "Failed" is a FINAL answer — the player stops asking — so for an ffmpeg failure it is given only
+    # once nothing is left that could still cover the position: the full pass failed, AND so did a
+    # window here.
+    full_failed = _full_failed(rating_key)
+    window_failed = not covered and _window_failed(key, at)
+    if full_failed and window_failed:
+        return {"state": "failed", "code": "extract_failed", "gen": generation(key)}
     if not code:
-        _schedule(rating_key, sub_ord, at, want_window=not covered)
+        _schedule(
+            rating_key,
+            sub_ord,
+            at,
+            want_window=not covered and not window_failed,
+            want_full=not full_failed,
+        )
     return {"state": "partial" if covered else "preparing", "code": None, "gen": generation(key)}
 
 
@@ -434,28 +516,42 @@ def cached_track(rating_key: str, sub_ord: int) -> tuple[str | None, str | None]
     return (hit, None) if hit is not None else (None, _recent_failure(key))
 
 
-def _schedule(rating_key: str, sub_ord: int, at: float, want_window: bool) -> None:
+def _schedule(
+    rating_key: str, sub_ord: int, at: float, want_window: bool, want_full: bool = True
+) -> None:
     """Kick off the jobs this track still needs: the window that makes it watchable now, and the one
-    full pass that makes it complete. Each is deduplicated by identity, so a 1 s status poll (or a
-    second viewer) joins the running job instead of starting another ffmpeg.
+    full pass that makes it complete. A 1 s status poll (or a second viewer) joins a job already
+    queued or running instead of starting another ffmpeg.
 
-    A window's identity is its track plus WHICH STRETCH of the film it is for — never the exact
-    position. The poll sends the live playhead, so a position-keyed window minted a new identity every
-    second and queued one more read of the file per poll until the first window landed; bucketing the
-    start by the window's own length makes a playhead creeping along join the job already running. It
-    must not be the track alone either: then a window cut around the wrong spot (the first poll after
-    a resume can still report 0) made the right one wait for it. The full pass is per ITEM, because
-    one read fans out to every embedded text track of the file."""
+    A window is joined when one of this track's in-flight windows will COVER the position asked about
+    — decided by what it reads, not by an identity derived from the position. The poll sends the live
+    playhead, so a position-keyed window was a new job every second; bucketing the position instead
+    still queued a second read when the playhead crossed a bucket edge, and joined a backward seek to
+    a window that could not cover it. Nor may it be one window per track: a window cut around the
+    wrong spot (the first poll after a resume can still report 0) made the right one wait for it. The
+    full pass is per ITEM, because one read fans out to every embedded text track of the file."""
     jobs: list[tuple[tuple, float | None]] = []
-    if want_window:
-        w_start = max(0.0, at - WINDOW_PRE_S)
-        jobs.append((("win", rating_key, sub_ord, int(w_start // WINDOW_LEN_S)), w_start))
-    jobs.append((("full", rating_key), None))
+    with _LOCK:
+        if _STOPPING or len(_INFLIGHT) >= _MAX_INFLIGHT:
+            return
+        if want_window:
+            spans = [
+                span
+                for ident, span in _INFLIGHT.items()
+                if span is not None and ident[1:3] == (rating_key, sub_ord)
+            ]
+            if not any(a <= at <= b for a, b in spans) and len(spans) < _MAX_TRACK_WINDOWS:
+                # Rounded to what ffmpeg is told (`-ss %.3f`): the cues come back on ffmpeg's zero,
+                # and shifting them by an unrounded start put them up to half a millisecond off —
+                # enough to spell a timestamp differently from the full pass and double the cue.
+                w_start = float(f"{max(0.0, at - WINDOW_PRE_S):.3f}")
+                ident = ("win", rating_key, sub_ord, w_start)
+                _INFLIGHT[ident] = (w_start, w_start + WINDOW_PRE_S + WINDOW_LEN_S)
+                jobs.append((ident, w_start))
+        if want_full and ("full", rating_key) not in _INFLIGHT:
+            _INFLIGHT[("full", rating_key)] = None
+            jobs.append((("full", rating_key), None))
     for ident, window_start in jobs:
-        with _LOCK:
-            if ident in _INFLIGHT:
-                continue
-            _INFLIGHT.add(ident)
         _POOL.submit(_run, ident, rating_key, sub_ord, window_start, at)
 
 
@@ -472,23 +568,43 @@ def _already_done(key: str, window_start: float | None, at: float) -> bool:
 def _run(
     ident: tuple, rating_key: str, sub_ord: int, window_start: float | None, at: float
 ) -> None:
+    key = cache_key(rating_key, sub_ord)
     try:
-        if _already_done(cache_key(rating_key, sub_ord), window_start, at):
+        if _STOPPING or _already_done(key, window_start, at):
             return
         _extract_and_publish(rating_key, sub_ord, window_start)
     except SubtitleUnavailable as e:
-        _fail(cache_key(rating_key, sub_ord), e.code)
+        if e.code == "extract_failed":
+            _pass_failed(rating_key, [key], window_start)
+        else:
+            _fail(key, e.code)
     except PlexError as e:
         log.warning("subtitle extraction failed for %s/%s: %s", rating_key, sub_ord, e)
-        _fail(cache_key(rating_key, sub_ord), "plex_error")
+        _fail(key, "plex_error")
     except (
         Exception
     ):  # a worker thread has nobody to raise to — record it, let the next poll see it
         log.exception("subtitle extraction crashed for %s/%s", rating_key, sub_ord)
-        _fail(cache_key(rating_key, sub_ord), "extract_failed")
+        _pass_failed(rating_key, [key], window_start)
     finally:
         with _LOCK:
-            _INFLIGHT.discard(ident)
+            _INFLIGHT.pop(ident, None)
+
+
+def _pass_failed(
+    rating_key: str,
+    keys: list[str],
+    window_start: float | None,
+    span: tuple[float, float] | None = None,
+) -> None:
+    """Record an ffmpeg pass that failed: a full pass backs off the whole item (FULL_RETRY_S); a
+    window marks only the stretch it failed to read, for the tracks it was reading."""
+    if window_start is None:
+        with _LOCK:
+            _FULL_FAILED[rating_key] = time.monotonic()
+        return
+    for key in keys:
+        _window_fail(key, span or (window_start, window_start + WINDOW_PRE_S + WINDOW_LEN_S))
 
 
 def _text_streams(db: Session, rating_key: str) -> tuple[PlexItem, list[dict]]:
@@ -554,7 +670,7 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
             clean and length is None,
         )
         if not clean:
-            _fail(key, "extract_failed")
+            _pass_failed(rating_key, [key], window_start, (covered_end, end))
 
 
 def _sidecar_vtt(db: Session, stream: dict) -> str:
@@ -595,13 +711,26 @@ def _ffmpeg_extract(
             cmd += ["-map", f"0:s:{emb_ord}"]
             if length is not None:
                 cmd += ["-t", f"{length:.3f}"]
+                # The input seek lands on the keyframe at or BEFORE `start`, so a cue already running
+                # at `start` comes out at a negative time — and by default the muxer then shifts the
+                # WHOLE output so that cue sits at 0: every cue of the window late by the distance to
+                # that keyframe (1–5 s measured on a real library file, a whole GOP on a synthetic
+                # one), and doubled for good once the full pass merged in beside it. Kept negative, the
+                # times are exact on the zero-based clock (`_vtt_ts_to_s` reads the sign).
+                cmd += ["-avoid_negative_ts", "disabled"]
             cmd += ["-f", "webvtt", "-y", str(out)]
-        # Popen rather than run(): the child is registered so `shutdown` can kill it.
+        # Popen rather than run(): the child is registered so `shutdown` can kill it — and one that
+        # would start after the shutdown's kill sweep never does, or is killed right here.
+        with _LOCK:
+            if _STOPPING:
+                raise SubtitleUnavailable("extract_failed")
         proc = subprocess.Popen(
             cmd, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE
         )
         with _LOCK:
             _PROCS.add(proc)
+            if _STOPPING:
+                proc.kill()
         try:
             try:
                 _, err = proc.communicate(timeout=EXTRACT_TIMEOUT_S)
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 35fab8f3..f0e03ef9 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -15,7 +15,7 @@ from fastapi import (
     Response,
 )
 from fastapi.responses import FileResponse
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
@@ -101,8 +101,9 @@ def subtitle_status(
     rating_key: str,
     sub_ord: int,
     user: User = Depends(current_user),
-    # Bounded: a non-finite position used to reach the scheduler's arithmetic and 500.
-    at: float = Query(0.0, ge=0.0, allow_inf_nan=False),
+    # Bounded both ways: a non-finite position used to reach the scheduler's arithmetic and 500, and
+    # an absurd one reached ffmpeg's `-ss`, which refused it.
+    at: float = Query(0.0, ge=0.0, le=subtitles.MAX_POSITION_S, allow_inf_nan=False),
 ) -> dict:
     """Is this subtitle track showable yet — and if not, get it moving. Extraction runs in the
     background (see plex/subtitles.py for the measurements that forced it there), so the player polls
@@ -115,7 +116,12 @@ def subtitle_status(
 
 @router.get("/subtitle/{rating_key}/{sub_ord}")
 def subtitle(
-    rating_key: str, sub_ord: int, user: User = Depends(current_user), offset: float = 0.0
+    rating_key: str,
+    sub_ord: int,
+    user: User = Depends(current_user),
+    # Finite, like every float this router takes: `-inf` crashed the shift (a 500), `nan` stacked
+    # every cue at 0. It can legitimately be negative (a subtitle nudged later than the session start).
+    offset: float = Query(0.0, allow_inf_nan=False),
 ) -> Response:
     """Serve the ord-th subtitle track as WebVTT for the browser's <track> — so choosing a subtitle
     overlays it directly (no HLS re-mux / session restart). Handles EXTERNAL sidecar subs (fetched
@@ -281,6 +287,10 @@ def _push_watch(
 
 
 class ItemProgressIn(BaseModel):
+    # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
+    # one into a 500.
+    model_config = ConfigDict(allow_inf_nan=False)
+
     # float, truncated in the handler — the player may post a raw currentTime (a float); a plain
     # `int` field would 422 it on the periodic progress checkpoint (the old `int(...)` truncated).
     position_seconds: float = 0
@@ -528,9 +538,10 @@ def season_state(
 @router.post("/stream/{rating_key}/session")
 def stream_session(
     rating_key: str,
-    start: float = 0.0,
+    # Finite: `start=inf` reached `int()` in the session builder and came back as a 500.
+    start: float = Query(0.0, allow_inf_nan=False),
     audio: int | None = None,
-    aoff: float = 0.0,
+    aoff: float = Query(0.0, allow_inf_nan=False),
     multi: bool = False,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
index 13c572b1..52a3385d 100644
--- a/backend/tests/test_plex_subtitle_prepare.py
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -18,6 +18,8 @@ behind an unrelated pass). Pure — no Postgres, no ffmpeg (the auth half is in
 test_plex_subtitle_auth.py, which needs the DB).
 """
 
+import asyncio
+import shutil
 import subprocess
 import sys
 import threading
@@ -30,10 +32,13 @@ import pytest
 from fastapi.testclient import TestClient
 
 import app.state as app_state
+import app.main as app_main
 from app.auth import current_user
 from app.main import app
 from app.plex import subtitles
 
+needs_ffmpeg = pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg not available")
+
 
 @pytest.fixture(autouse=True)
 def _isolated_cache(tmp_path, monkeypatch):
@@ -373,14 +378,19 @@ def test_one_window_publishes_every_embedded_text_track_at_absolute_time(monkeyp
 def test_a_full_pass_that_died_is_not_cached_as_the_whole_track(monkeypatch):
     """A truncated full pass used to be published as complete: `ensure` answered "ready" forever, the
     player stopped polling, and — the cache has no eviction — the subtitles simply ended wherever
-    ffmpeg had died, in every later session too. Now it covers what it provably reached, and the
-    rest of the film honestly reads as failed."""
+    ffmpeg had died, in every later session too. Now it covers what it provably reached; past that
+    a window is tried, and only when that fails too is the position answered as failed."""
     _stub_item(monkeypatch, clean=False, cues=("39:58.000", "40:00.000"))
-    monkeypatch.setattr(subtitles, "_POOL", _ManualPool())
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
     subtitles._extract_and_publish("98614", 3, None)
     key = subtitles.cache_key("98614", 3)
     assert subtitles.read_meta(key) == ([[0.0, 2400.0]], False)
     assert subtitles.ensure("98614", 3, at=100.0)["state"] == "partial"
+    assert subtitles.ensure("98614", 3, at=3000.0)["state"] == "preparing"
+    assert [a[3] for _, a in pool.jobs] == [2970.0], "a window past the break — not the full pass"
+    _window_raises(monkeypatch)
+    pool.run_all()
     after = subtitles.ensure("98614", 3, at=3000.0)
     assert (after["state"], after["code"]) == ("failed", "extract_failed")
 
@@ -430,7 +440,7 @@ def test_a_sidecar_does_not_wait_behind_an_embedded_full_pass(monkeypatch):
     pool = _ManualPool()
     monkeypatch.setattr(subtitles, "_POOL", pool)
     _stub_item(monkeypatch)
-    subtitles._INFLIGHT.add(("full", "98614"))  # an embedded track's full pass is running
+    subtitles._INFLIGHT[("full", "98614")] = None  # an embedded track's full pass is running
     subtitles.ensure("98614", 0, at=600.0)
     pool.run_all()
     assert subtitles.ensure("98614", 0, at=600.0)["state"] == "ready"
@@ -528,3 +538,254 @@ def test_an_impossible_position_is_rejected(client, monkeypatch, at):
     monkeypatch.setattr(subtitles, "_POOL", pool)
     assert client.get(f"/api/plex/subtitle/98614/0/status?at={at}").status_code == 422
     assert pool.jobs == []
+
+
+@pytest.mark.parametrize("q", ["offset=-inf", "offset=nan", "offset=inf"])
+def test_an_impossible_offset_is_rejected(client, q):
+    """The sibling of `at`: `-inf` crashed the shift with a 500, `nan` stacked every cue at 0."""
+    assert client.get(f"/api/plex/subtitle/98614/0?{q}").status_code == 422
+
+
+def test_an_absurd_position_is_rejected_before_it_reaches_ffmpeg(client, monkeypatch):
+    """ffmpeg refuses an `-ss` past its int64 microseconds, and that failure was recorded against the
+    TRACK — every other viewer at an uncovered position was told "failed" for a minute."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    assert client.get("/api/plex/subtitle/98614/0/status?at=1e13").status_code == 422
+    assert pool.jobs == []
+
+
+# --- the second deep-review round ---------------------------------------------------------------
+
+
+def _window_raises(monkeypatch):
+    """From here on every window read fails outright; a full pass still works."""
+    real = subtitles._ffmpeg_extract
+
+    def _extract(src, emb_ords, start, length):
+        if length is not None:
+            raise subtitles.SubtitleUnavailable("extract_failed")
+        return real(src, emb_ords, start, length)
+
+    monkeypatch.setattr(subtitles, "_ffmpeg_extract", _extract)
+
+
+def _later(monkeypatch, seconds: float) -> None:
+    """Move the module's clock forward (the failure memos are monotonic-time TTLs)."""
+    now = time.monotonic() + seconds
+    monkeypatch.setattr(subtitles.time, "monotonic", lambda: now)
+
+
+def test_a_full_pass_that_failed_is_not_read_again_while_its_output_is_watched(monkeypatch):
+    """Published as partial, a failed full pass left the viewer inside what it DID publish — so the
+    status said `partial`, the poll kept going, and each time the one-minute failure memo lapsed it
+    re-armed a read of the whole container. A failure that reproduces did so every time: a full
+    read of the file every few minutes for as long as they watched."""
+    _stub_item(monkeypatch, clean=False, cues=("39:58.000", "40:00.000"))
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    subtitles._extract_and_publish("98614", 3, None)
+    _later(monkeypatch, subtitles.FAIL_TTL_S + 1)
+    for _ in range(3):
+        assert subtitles.ensure("98614", 3, at=100.0)["state"] == "partial"
+    assert pool.jobs == [], "a failed full pass was queued again"
+
+
+def test_a_failed_window_does_not_end_the_poll_while_the_full_pass_may_cover_it(monkeypatch):
+    """ "failed" is final — the player stops asking. A window that failed used to set the TRACK's
+    failure memo, so a viewer anywhere outside the covered part got "failed" and never heard about
+    the full pass that landed a minute later."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    _stub_item(monkeypatch)
+    _window_raises(monkeypatch)
+    subtitles.ensure("98614", 3, at=3000.0)
+    pool.run_next()  # the window fails; the full pass is still queued behind it
+    assert subtitles.ensure("98614", 3, at=3000.0)["state"] == "preparing"
+    assert subtitles.ensure("98614", 3, at=500.0)["state"] == "preparing"
+    assert [a[3] for _, a in pool.jobs] == [None, 470.0], "the failed stretch was not tried again"
+
+
+def test_a_backward_seek_gets_its_own_window(monkeypatch):
+    """A window bucketed by position joined a seek back to 6:40 onto a running window at 9:10 that
+    could not cover it — the right one waited for the wrong one."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    subtitles.ensure("98614", 1, at=580.0)
+    subtitles.ensure("98614", 1, at=400.0)
+    assert sorted(a[3] for _, a in pool.jobs if a[3] is not None) == [370.0, 550.0]
+
+
+def test_a_playhead_crossing_a_bucket_edge_joins_the_window_that_covers_it(monkeypatch):
+    """…and the same bucketing queued a second read when a playhead crossed an edge while the first
+    window — which already covered it — was still running."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    for at in (628.0, 629.0, 630.0, 631.0, 632.0):
+        subtitles.ensure("98614", 1, at=at)
+    assert len(pool.jobs) == 2, "one window + the one full pass"
+
+
+def test_a_scrubbing_viewer_cannot_queue_a_window_per_stop(monkeypatch):
+    """The pool's queue is unbounded and every job is a read of the library."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    for at in (0.0, 1000.0, 2000.0, 3000.0, 4000.0):
+        subtitles.ensure("98614", 1, at=at)
+    assert len([1 for _, a in pool.jobs if a[3] is not None]) == subtitles._MAX_TRACK_WINDOWS
+
+
+def test_nothing_more_is_queued_while_the_extractor_is_saturated(monkeypatch):
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    for rk in range(20):
+        subtitles.ensure(str(rk), 0, at=0.0)
+    assert len(pool.jobs) == subtitles._MAX_INFLIGHT
+
+
+def test_a_window_starts_where_ffmpeg_is_told_to_seek(monkeypatch):
+    """ffmpeg gets `-ss` to the millisecond, and its cues come back on THAT zero. Shifted back by an
+    unrounded start they landed up to half a millisecond off the full pass's — spelled differently,
+    and so kept twice by the merge."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    subtitles.ensure("98614", 1, at=1198.4375)
+    (window_start,) = [a[3] for _, a in pool.jobs if a[3] is not None]
+    assert window_start == 1168.438
+
+
+def test_a_millisecond_rounded_up_carries_into_the_minute():
+    """`00:00:60.000` is not a WebVTT timestamp — the browser drops the cue."""
+    assert subtitles._vtt_s_to_ts(59.9996) == "00:01:00.000"
+    assert subtitles._vtt_s_to_ts(3599.9996) == "01:00:00.000"
+    shifted = subtitles.shift_vtt(_vtt(_cue("00:01:00.000", "00:01:02.000", "x")), 0.0004)
+    assert "00:01:00.000 --> 00:01:02.000" in shifted, shifted
+
+
+def test_ffmpegs_spelling_of_a_negative_time_reads_exactly():
+    """With `-avoid_negative_ts disabled` a cue already running at the window's start comes out
+    before zero, and ffmpeg's muxer puts the sign on every field."""
+    assert subtitles._vtt_ts_to_s("00:-5.-05") == pytest.approx(-5.005)
+    assert subtitles._vtt_ts_to_s("-1:-5.-300") == pytest.approx(-65.3)
+
+
+def test_dying_between_the_two_renames_cannot_pass_a_window_off_as_the_whole_track(monkeypatch):
+    """A VTT without a sidecar is how an older build cached a COMPLETE track. A publish is two
+    renames, the VTT first — so dying between them on a key's first publish left a window that
+    read as complete, "ready" for good."""
+    key = subtitles.cache_key("98614", 0)
+    real_write = subtitles.cache_write
+
+    def _die_after(k, vtt):
+        real_write(k, vtt)
+        raise KeyboardInterrupt  # the process goes away right after the VTT landed
+
+    monkeypatch.setattr(subtitles, "cache_write", _die_after)
+    with pytest.raises(KeyboardInterrupt):
+        subtitles.publish(key, _vtt(_cue("10:00.000", "10:02.000", "x")), (570.0, 900.0), False)
+    assert subtitles.read_meta(key) == ([], False)
+
+
+def test_shutdown_drops_queued_extractions(monkeypatch):
+    """Only the kill half used to be pinned. A job still QUEUED at shutdown would otherwise start
+    after the kill sweep — a fresh read of the file holding the process open."""
+    pool = ThreadPoolExecutor(max_workers=1)
+    monkeypatch.setattr(subtitles, "_POOL", pool)
+    busy, release, ran = threading.Event(), threading.Event(), threading.Event()
+    pool.submit(lambda: (busy.set(), release.wait(timeout=5)))
+    pool.submit(ran.set)
+    assert busy.wait(timeout=5)
+    subtitles.shutdown()
+    release.set()
+    pool.shutdown(wait=True)
+    assert not ran.is_set(), "a queued extraction ran after shutdown"
+
+
+def test_a_worker_that_reaches_ffmpeg_after_shutdown_never_starts_it(monkeypatch):
+    """A worker still in its Plex lookup when the kill sweep ran used to start its ffmpeg anyway."""
+    monkeypatch.setattr(subtitles, "_POOL", ThreadPoolExecutor(max_workers=1))
+    started: list = []
+    monkeypatch.setattr(subtitles.subprocess, "Popen", lambda cmd, **kw: started.append(cmd))
+    subtitles.shutdown()
+    with pytest.raises(subtitles.SubtitleUnavailable):
+        subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], None, None)
+    assert started == []
+
+
+def test_the_app_stops_the_extractor_when_it_shuts_down(monkeypatch):
+    """No test ran the lifespan, so deleting this one call switched all of the above off with every
+    lane green."""
+
+    class _Configured:
+        def __enter__(self):
+            return None
+
+        def __exit__(self, *exc):
+            return False
+
+    async def _no_sweep():
+        return None
+
+    calls: list[str] = []
+    monkeypatch.setattr(app_main, "SessionLocal", _Configured)
+    monkeypatch.setattr(app_main.state, "is_configured", lambda db: True)
+    monkeypatch.setattr(app_main, "_sweep_hls_orphans", _no_sweep)
+    monkeypatch.setattr(app_main, "start_scheduler", lambda: None)
+    monkeypatch.setattr(app_main, "shutdown_scheduler", lambda: None)
+    monkeypatch.setattr(app_main.plex_subtitles, "shutdown", lambda: calls.append("stopped"))
+
+    async def _cycle():
+        async with app_main.lifespan(app):
+            pass
+
+    asyncio.run(_cycle())
+    assert calls == ["stopped"]
+
+
+# --- a window against a REAL ffmpeg -------------------------------------------------------------
+
+
+def _make_mkv(tmp_path: Path) -> Path:
+    """A minute of video with a keyframe every 10 s and a subtitle every 2 s — so a seek to 21.3 s
+    lands on the keyframe at 20 s, with the 20.0–21.5 s cue already running at the window's start."""
+    srt = tmp_path / "s.srt"
+    srt.write_text(
+        "".join(
+            f"{i + 1}\n00:00:{2 * i:02d},000 --> 00:00:{2 * i + 1:02d},500\nline {i}\n\n"
+            for i in range(30)
+        ),
+        "utf-8",
+    )
+    out = tmp_path / "f.mkv"
+    subprocess.run(
+        [
+            "ffmpeg", "-nostdin", "-loglevel", "error",
+            "-f", "lavfi", "-i", "color=c=black:s=32x32:r=10:d=60",
+            "-i", str(srt),
+            "-map", "0:v", "-map", "1:s", "-c:v", "mpeg4", "-g", "100", "-c:s", "srt",
+            "-y", str(out),
+        ],
+        check=True,
+    )  # fmt: skip
+    return out
+
+
+@needs_ffmpeg
+def test_a_window_lines_up_with_the_full_pass_on_a_real_file(tmp_path, monkeypatch):
+    """THE late-and-doubled window. The input seek lands on the keyframe before the window's start,
+    a cue already running there comes out at a negative time, and by default ffmpeg's muxer shifted
+    the whole window so that cue sat at 0 — every cue late by the distance to the keyframe (1–5 s on
+    a real library file), and kept twice for good once the full pass merged in beside it."""
+    src = _make_mkv(tmp_path)
+    monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path / "cache")
+    full, clean = subtitles._ffmpeg_extract(str(src), [0], None, None)
+    assert clean
+    win, clean = subtitles._ffmpeg_extract(str(src), [0], 21.3, 20.0)
+    assert clean
+    key = subtitles.cache_key("1", 0)
+    subtitles.publish(key, subtitles.shift_vtt(win[0], -21.3), (21.3, 41.3), False)
+    served = subtitles.cache_read(key) or ""
+    assert "00:00:22.000 --> 00:00:23.500\nline 11" in served, served  # on time, not 1.3 s late
+    subtitles.publish(key, full[0], (0.0, subtitles._FULL_END_S), True)
+    merged = subtitles.cache_read(key) or ""
+    assert merged.count("-->") == 30, "a window cue survived beside its full-pass twin"

From 7360339039094ce673ea543b1110fa0f7632a22f Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:18:17 +0200
Subject: [PATCH 16/52] fix(api): a non-finite number in a JSON body is refused
 with a 422, not a 500
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The JSON parser under FastAPI accepts `Infinity`/`NaN`, and both progress checkpoints truncate the
position with `int()` — a hand-written checkpoint came back as a 500 with a traceback. Their bodies
now refuse non-finite floats, and the app's validation handler — FastAPI's own shape — echoes a
non-finite input by name: the default one failed to serialise its own error (JSON has no NaN), which
was a 500 by another route. Sibling of the subtitle routes' non-finite query parameters.
---
 backend/app/main.py                   | 18 +++++++++++++-
 backend/app/routes/feed.py            |  6 ++++-
 backend/tests/test_progress_bounds.py | 34 +++++++++++++++++++++++++++
 3 files changed, 56 insertions(+), 2 deletions(-)
 create mode 100644 backend/tests/test_progress_bounds.py

diff --git a/backend/app/main.py b/backend/app/main.py
index 7c2e6038..3acb4bde 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -1,10 +1,13 @@
 import asyncio
 import logging
+import math
 import sys
 from contextlib import asynccontextmanager, suppress
 from pathlib import Path
 
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.encoders import jsonable_encoder
+from fastapi.exceptions import RequestValidationError
 
 # When started via uvicorn --log-config the "siftlode" logger is already configured
 # (see log_config.json). This block is a timestamped fallback for other entrypoints
@@ -112,6 +115,19 @@ async def _sweep_hls_orphans() -> None:
 
 app = FastAPI(title=settings.app_name, lifespan=lifespan)
 
+
+@app.exception_handler(RequestValidationError)
+async def _validation_error(request: Request, exc: RequestValidationError) -> JSONResponse:
+    """FastAPI's own 422, in its own shape — except that it can be ENCODED. The JSON parser accepts
+    `NaN`/`Infinity`, a float field refuses them, and the refusal echoes the value back: the default
+    handler then failed to serialise its own error (JSON has no NaN) and the request became a 500
+    with a traceback. A non-finite value is echoed as its name instead."""
+    finite = {float: lambda x: x if math.isfinite(x) else str(x)}
+    return JSONResponse(
+        status_code=422, content={"detail": jsonable_encoder(exc.errors(), custom_encoder=finite)}
+    )
+
+
 app.add_middleware(
     SessionMiddleware,
     secret_key=settings.secret_key,
diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index 2d6f3635..e969de25 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -1,7 +1,7 @@
 from datetime import date, datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Query
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
@@ -303,6 +303,10 @@ def clear_video_state(
 
 
 class VideoProgressIn(BaseModel):
+    # Finite only: JSON parsing here accepts `Infinity`/`NaN`, and the handler's `int()` turned
+    # one into a 500.
+    model_config = ConfigDict(allow_inf_nan=False)
+
     # Accept a float and truncate (below) — the player may post a raw currentTime (a float), which
     # the old `int(payload.get(...))` silently truncated. A plain `int` field would 422 that on the
     # 10s progress hot path, losing the resume position; `float` keeps the old tolerance.
diff --git a/backend/tests/test_progress_bounds.py b/backend/tests/test_progress_bounds.py
new file mode 100644
index 00000000..aea5dee5
--- /dev/null
+++ b/backend/tests/test_progress_bounds.py
@@ -0,0 +1,34 @@
+"""A progress checkpoint takes a FINITE position.
+
+The JSON parser under FastAPI accepts `Infinity` and `NaN`, and both progress handlers truncate the
+position with `int()` — so one hand-written checkpoint came back as a 500 with a traceback. Found in
+the 2026-09 bug hunt's second review round, as the sibling of the subtitle routes' non-finite
+`at`/`offset`. Pure: the body is refused before the handler touches the database.
+"""
+
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+
+import app.state as app_state
+from app.auth import current_user
+from app.main import app
+
+
+@pytest.fixture
+def client(monkeypatch, override_dep) -> TestClient:
+    override_dep(current_user, lambda: SimpleNamespace(id=1))
+    monkeypatch.setattr(app_state, "_configured_cache", True)  # pass the instance-setup gate, no DB
+    return TestClient(app)
+
+
+@pytest.mark.parametrize("path", ["/api/videos/v1/progress", "/api/plex/item/98614/progress"])
+@pytest.mark.parametrize("raw", ["Infinity", "-Infinity", "NaN"])
+def test_a_non_finite_position_is_refused(client, path, raw):
+    r = client.post(
+        path,
+        content=f'{{"position_seconds": {raw}, "duration_seconds": 3000}}',
+        headers={"content-type": "application/json"},
+    )
+    assert r.status_code == 422, r.text

From 645d14f45d618636d945a20c1c5519e47ab8e277 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:18:42 +0200
Subject: [PATCH 17/52] fix(plex): a subtitle track's failed load is heard and
 retried with a pause, and the poll asks about the right item, position and
 failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- The <track>'s `error` never reached `onSubTrackError`: it does not bubble, and React 18 attaches no
  listener of its own to a <track> (measured in Chrome and jsdom — `onError` 0 calls, `onErrorCapture`
  1). Round 1's remount-and-give-up was dead code behind it. The hook now hands the player
  `onErrorCapture`, and the test fires a real non-bubbling `error` at a rendered <track>.
- Once reachable, the retry burned its whole budget within milliseconds of an outage (a remount
  fetches at once) and the give-up outlived turning subtitles off and on. Retries now wait (2 s,
  doubling), running out is reported at once, and picking the track again starts a fresh budget.
- Until the first timeupdate the poll sent `sessionK` — still 0 while the session request was out,
  and the PREVIOUS item's start after a move to the next episode. It now sends where the session was
  asked to start, and the track choice belongs to the item it was made for, so the next item is not
  asked about the old ordinal at the old position.
- A failing poll over a stale `partial` answer was silent: react-query keeps the last good data, the
  track stayed "showable", and the notice only rendered for an unmounted track. The hook now decides
  what the player says (`subNotice`), independently of whether a window is mounted.
---
 frontend/src/components/PlexPlayer.tsx        |  20 ++-
 .../lib/plexPlayerHooks.subtitle.dom.test.tsx | 168 ++++++++++++++----
 frontend/src/lib/plexPlayerHooks.ts           | 110 +++++++++---
 3 files changed, 234 insertions(+), 64 deletions(-)

diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index e7f3242d..e3cecf74 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -129,6 +129,9 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   // Live mirror of `abs` for stable callbacks + the progress checkpoint (seek/skip/ended write it too).
   const absRef = useRef(0);
   absRef.current = abs;
+  // Where the current session was ASKED to start — set before the request goes out, so the subtitle
+  // poll has a position before `sessionK` (the session's answer) and before the first timeupdate.
+  const loadStartRef = useRef(0);
   const [seekableEnd, setSeekableEnd] = useState(0); // absolute end of the loaded region
   const { fs, toggleFs } = useFullscreen(wrapRef);
   const [ready, setReady] = useState(false);
@@ -243,6 +246,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     async (startAt: number, resumePlay = true) => {
       const video = videoRef.current;
       if (!video) return;
+      loadStartRef.current = startAt;
       setReady(false);
       setBuffering(false);
       setLoadError(null);
@@ -378,10 +382,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     selectedSub,
     subTrackOffset,
     subShowable,
-    subFail,
+    subNotice,
     subGen,
     subTrackKey,
-    onSubTrackError,
+    subTrackListeners,
   } = usePlexTracks({
     id,
     detail,
@@ -396,6 +400,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     audioRef,
     aoffRef,
     absRef,
+    loadStartRef,
   });
 
   // Start playback when the detail arrives (resume from the saved position unless already watched).
@@ -882,7 +887,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
             src={api.plexSubtitleUrl(id, selectedSub.ord, subTrackOffset, subGen)}
             srcLang={selectedSub.language ?? undefined}
             label={selectedSub.label}
-            onError={onSubTrackError}
+            {...subTrackListeners}
             default
           />
         )}
@@ -921,15 +926,16 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
           (154 s for a 17 GB film, measured), so it happens in the background — around the playhead
           first. Until then the <track> is deliberately NOT mounted, and this says why instead of
           leaving the viewer to conclude that switching subtitles "does nothing" (bug hunt 2026-09,
-          item 8). It sits one rung above the track-switch OSD so the two never overlap. */}
+          item 8). A failure is said even over a mounted window (see `subNotice`). It sits one rung
+          above the track-switch OSD so the two never overlap. */}
       <div
         className="pointer-events-none absolute inset-x-0 bottom-36 z-menu flex justify-center px-4"
         aria-live="polite"
       >
-        {selectedSub && !subShowable && (
+        {selectedSub && subNotice && (
           <div className="flex max-w-full items-center gap-2 truncate rounded-full border border-white/15 bg-black/75 px-4 py-2 text-sm text-white shadow-2xl">
-            {subFail ? (
-              <span className="text-danger">{t(`plex.player.subUnavailable.${subFail}`)}</span>
+            {subNotice !== "preparing" ? (
+              <span className="text-danger">{t(`plex.player.subUnavailable.${subNotice}`)}</span>
             ) : (
               <>
                 <Loader2 className="h-4 w-4 shrink-0 animate-spin" aria-hidden />
diff --git a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
index 3bb046da..462fde58 100644
--- a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
+++ b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
@@ -10,7 +10,7 @@
 // window around the playhead first, and this hook's poll is what decides when there is something to
 // mount and what to say while there isn't.
 import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
-import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import { act, cleanup, render, renderHook, waitFor } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { createRef, type ReactNode, type MutableRefObject } from "react";
 import { usePlexTracks } from "./plexPlayerHooks";
@@ -32,14 +32,14 @@ const detail = (): PlexItemDetail =>
     markers: [],
   }) as unknown as PlexItemDetail;
 
-function mount(qc: QueryClient, { sessionK = 0, abs = 3600 } = {}) {
+function mount(qc: QueryClient, { sessionK = 0, abs = 3600, loadStart = 0 } = {}) {
   const wrapper = ({ children }: { children: ReactNode }) => (
     <QueryClientProvider client={qc}>{children}</QueryClientProvider>
   );
   return renderHook(
-    () =>
+    ({ id }: { id: string }) =>
       usePlexTracks({
-        id: RK,
+        id,
         detail: detail(),
         sessionK,
         subOffset: 0,
@@ -52,8 +52,9 @@ function mount(qc: QueryClient, { sessionK = 0, abs = 3600 } = {}) {
         audioRef: { current: 0 } as MutableRefObject<number | null>,
         aoffRef: { current: 0 },
         absRef: { current: abs },
+        loadStartRef: { current: loadStart },
       }),
-    { wrapper },
+    { wrapper, initialProps: { id: RK } },
   );
 }
 
@@ -80,7 +81,7 @@ describe("usePlexTracks — the <track> waits for the extraction", () => {
     // The selected track exists and is offered in the picker — it just cannot be rendered yet, and
     // the caller must be told so rather than mounting an empty <track>.
     expect(result.current.subShowable).toBe(false);
-    expect(result.current.subFail).toBeNull();
+    expect(result.current.subNotice).toBe("preparing");
   });
 
   it("sends the viewer's position, so the extraction windows around where they are", async () => {
@@ -92,18 +93,35 @@ describe("usePlexTracks — the <track> waits for the extraction", () => {
     await waitFor(() => expect(status).toHaveBeenCalledWith(RK, 1, 3600));
   });
 
-  it("sends the session's start before playback has ticked, not the head of the film", async () => {
+  it("sends where the session was asked to start before playback has ticked, not the head of the film", async () => {
     // A resumed session starts minutes in, but `abs` stays 0 until the first timeupdate — and every
     // poll used to say at=0, so the first window was cut around the head of the film (measured on
-    // localdev: a resume at 20:00 polled at=0 for as long as it stayed paused).
+    // localdev: a resume at 20:00 polled at=0 for as long as it stayed paused). `sessionK` is no
+    // substitute: it is still 0 here, because the session request has not answered yet.
     const status = vi
       .spyOn(api, "plexSubtitleStatus")
       .mockResolvedValue({ state: "preparing", code: null, gen: 0 });
-    const { result } = mount(client(), { sessionK: 1198, abs: 0 });
+    const { result } = mount(client(), { sessionK: 0, abs: 0, loadStart: 1198 });
     result.current.setSubOrd(1);
     await waitFor(() => expect(status).toHaveBeenCalledWith(RK, 1, 1198));
   });
 
+  it("does not carry the track choice to the next item — that item's detail decides it", async () => {
+    // Carried over, the old ordinal polled the NEW item (where it may be another language) at the
+    // OLD item's position, queueing an extraction of the wrong stretch of the next file.
+    const status = vi
+      .spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValue({ state: "preparing", code: null, gen: 0 });
+    const { result, rerender } = mount(client());
+    result.current.setSubOrd(1);
+    await waitFor(() => expect(status).toHaveBeenCalledWith(RK, 1, 3600));
+    rerender({ id: "NEXT" });
+    expect(result.current.subOrd).toBeNull();
+    expect(result.current.subNotice).toBeNull();
+    await act(async () => {});
+    expect(status.mock.calls.some(([id]) => id === "NEXT")).toBe(false);
+  });
+
   it("becomes showable on a PARTIAL track — a window around the playhead is what is needed now", async () => {
     vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
       state: "partial",
@@ -126,7 +144,7 @@ describe("usePlexTracks — the <track> waits for the extraction", () => {
     });
     const { result } = mount(client());
     result.current.setSubOrd(0);
-    await waitFor(() => expect(result.current.subFail).toBe("bitmap"));
+    await waitFor(() => expect(result.current.subNotice).toBe("bitmap"));
     expect(result.current.subShowable).toBe(false);
   });
 
@@ -138,7 +156,7 @@ describe("usePlexTracks — the <track> waits for the extraction", () => {
     });
     const { result } = mount(client());
     result.current.setSubOrd(0);
-    await waitFor(() => expect(result.current.subFail).toBe("missing"));
+    await waitFor(() => expect(result.current.subNotice).toBe("missing"));
   });
 
   it("asks nothing at all while subtitles are off", async () => {
@@ -196,7 +214,7 @@ describe("usePlexTracks — when the status poll asks again, and when it stops",
     const status = vi.spyOn(api, "plexSubtitleStatus").mockRejectedValue(new Error("offline"));
     const { result } = mount(client());
     result.current.setSubOrd(0);
-    await waitFor(() => expect(result.current.subFail).toBe("failed"));
+    await waitFor(() => expect(result.current.subNotice).toBe("failed"));
     expect(status).toHaveBeenCalledTimes(1);
     await vi.advanceTimersByTimeAsync(5000);
     expect(status).toHaveBeenCalledTimes(1);
@@ -215,29 +233,117 @@ describe("usePlexTracks — when the status poll asks again, and when it stops",
     await expect(api.plexSubtitleStatus(RK, 0, 0)).rejects.toThrow();
     expect(getError()).toBeNull();
   });
-});
 
-describe("usePlexTracks — a <track> whose own VTT fetch failed", () => {
-  afterEach(() => {
-    cleanup();
-    vi.restoreAllMocks();
-  });
-
-  it("is replaced by a fresh element a couple of times, then reported instead of left blank", async () => {
-    // A failed <track> never fetches again, and while the server's answer is unchanged its key was
-    // unchanged too — so React kept the dead element and the subtitles stayed silently blank.
-    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({ state: "partial", code: null, gen: 5 });
+  it("says a failing poll even while an earlier window is still on screen", async () => {
+    // react-query keeps the last good answer through a failed refetch, so a `partial` track stayed
+    // "showable" and the failure had nowhere to appear: past the window, blank subtitles and nothing
+    // on screen saying why — with the request `quiet`, not even the global dialog.
+    vi.spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValueOnce({ state: "partial", code: null, gen: 5 })
+      .mockRejectedValue(new Error("offline"));
     const { result } = mount(client());
     result.current.setSubOrd(0);
     await waitFor(() => expect(result.current.subShowable).toBe(true));
-    for (let i = 0; i < 2; i++) {
-      const before = result.current.subTrackKey;
-      act(() => result.current.onSubTrackError());
-      await waitFor(() => expect(result.current.subTrackKey).not.toBe(before));
-      expect(result.current.subShowable).toBe(true);
+    expect(result.current.subNotice).toBeNull();
+    await vi.advanceTimersByTimeAsync(2100);
+    await waitFor(() => expect(result.current.subNotice).toBe("failed"));
+    expect(result.current.subShowable).toBe(true); // the window it has is still worth showing
+  });
+});
+
+// Rendered for real, not by calling the hook's callback: the failure arrives as the <track>'s own
+// `error` event, which does not bubble — and React 18 attaches no listener of its own to a <track>,
+// so the `onError` this used to be wired through was never called in a browser at all.
+function TrackHarness() {
+  const tracks = usePlexTracks({
+    id: RK,
+    detail: detail(),
+    sessionK: 0,
+    subOffset: 0,
+    subPos: 88,
+    loadSession: async () => {},
+    patchPrefs: () => {},
+    videoRef: createRef<HTMLVideoElement>(),
+    hlsRef: createRef<Hls>(),
+    multiAudioRef: { current: false },
+    audioRef: { current: 0 } as MutableRefObject<number | null>,
+    aoffRef: { current: 0 },
+    absRef: { current: 3600 },
+    loadStartRef: { current: 0 },
+  });
+  harness.current = tracks;
+  return (
+    <video>
+      {tracks.subShowable && (
+        <track
+          key={tracks.subTrackKey}
+          data-key={tracks.subTrackKey}
+          kind="subtitles"
+          {...tracks.subTrackListeners}
+        />
+      )}
+    </video>
+  );
+}
+const harness: { current: ReturnType<typeof usePlexTracks> | null } = { current: null };
+
+function renderTrack(qc: QueryClient) {
+  const view = render(
+    <QueryClientProvider client={qc}>
+      <TrackHarness />
+    </QueryClientProvider>,
+  );
+  const track = () => view.container.querySelector("track");
+  // What the browser does when the VTT fetch fails: a plain, NON-bubbling `error` on the element.
+  const fail = () => act(() => void track()!.dispatchEvent(new Event("error")));
+  return { track, fail };
+}
+
+describe("usePlexTracks — a <track> whose own VTT fetch failed", () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({ state: "ready", code: null, gen: 5 });
+  });
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("is replaced by a fresh element, after a pause, a couple of times — then reported instead of left blank", async () => {
+    // A failed <track> never fetches again, and while the server's answer is unchanged its key was
+    // unchanged too — so React kept the dead element and the subtitles stayed silently blank. The
+    // pause matters as much: remounting at once spent the whole budget inside a one-second outage.
+    const { track, fail } = renderTrack(client());
+    act(() => harness.current!.setSubOrd(0));
+    await waitFor(() => expect(track()).not.toBeNull());
+    for (const pause of [2000, 4000]) {
+      const before = track()!.dataset.key;
+      fail();
+      await vi.advanceTimersByTimeAsync(pause - 100);
+      expect(track()!.dataset.key).toBe(before); // not yet: still waiting out the pause
+      await vi.advanceTimersByTimeAsync(200);
+      await waitFor(() => expect(track()!.dataset.key).not.toBe(before));
     }
-    act(() => result.current.onSubTrackError());
-    await waitFor(() => expect(result.current.subShowable).toBe(false));
-    expect(result.current.subFail).toBe("failed");
+    fail();
+    await waitFor(() => expect(track()).toBeNull());
+    expect(harness.current!.subNotice).toBe("failed");
+  });
+
+  it("gets a fresh budget when the viewer picks the track again", async () => {
+    // The give-up belongs to one track generation, and a `ready` track is no longer polled, so no new
+    // generation would ever come: turning subtitles off and on used to leave "couldn't be loaded".
+    const { track, fail } = renderTrack(client());
+    act(() => harness.current!.setSubOrd(0));
+    await waitFor(() => expect(track()).not.toBeNull());
+    for (let i = 0; i < 3; i++) {
+      fail();
+      await vi.advanceTimersByTimeAsync(4100);
+    }
+    await waitFor(() => expect(track()).toBeNull());
+    act(() => harness.current!.changeSubtitle(null));
+    act(() => harness.current!.changeSubtitle(0));
+    await waitFor(() => expect(track()).not.toBeNull());
+    expect(harness.current!.subNotice).toBeNull();
   });
 });
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index 4ccadaa6..051d790f 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -349,10 +349,12 @@ export function useAutoSkip(opts: {
  *  fold happens here rather than multiplying near-identical translations. */
 export type SubFailReason = "bitmap" | "missing" | "failed";
 
-// The subtitle status poll's cadence after a FAILED request (see usePlexTracks), and how many times a
-// <track> whose own VTT fetch failed is remounted before the track is reported as unavailable.
+// The subtitle status poll's cadence after a FAILED request (see usePlexTracks), how many times a
+// <track> whose own VTT fetch failed is remounted before the track is reported as unavailable, and
+// the first of the (doubling) pauses before each remount.
 const SUB_POLL_ERROR_MS = 10_000;
 const SUB_TRACK_RETRIES = 2;
+const SUB_TRACK_RETRY_MS = 2_000;
 
 function subFailReason(code: string | null | undefined): SubFailReason {
   if (code === "bitmap") return "bitmap";
@@ -375,6 +377,9 @@ export function usePlexTracks(opts: {
   audioRef: MutableRefObject<number | null>;
   aoffRef: MutableRefObject<number>;
   absRef: MutableRefObject<number>;
+  /** The position the current (or still in-flight) session was ASKED to start at — written before
+   *  the session request goes out, unlike `sessionK`, which only lands once it has answered. */
+  loadStartRef: MutableRefObject<number>;
 }): {
   audioOrd: number | null;
   setAudioOrd: (ord: number | null) => void;
@@ -394,8 +399,10 @@ export function usePlexTracks(opts: {
   /** The selected track has something to render (a window around the playhead, or the whole thing).
    *  False means "not yet" — the caller must NOT mount a <track>, it would just sit blank. */
   subShowable: boolean;
-  /** The selected track can never be shown, bucketed for the message the player puts on screen. */
-  subFail: SubFailReason | null;
+  /** What the player must SAY about the selected track, if anything: still being prepared, or why it
+   *  can't be shown (bucketed for the sentence the player has). Independent of `subShowable` — a
+   *  failing status poll is worth saying even while an earlier window is still mounted. */
+  subNotice: "preparing" | SubFailReason | null;
   /** The cached VTT's generation — it grows as the background extraction widens the track, so it
    *  belongs in the <track> key/URL or the browser keeps serving the first, short window. */
   subGen: number;
@@ -404,14 +411,25 @@ export function usePlexTracks(opts: {
    *  change), the extraction generation (a widened track replaces the first short window), and the
    *  failed-load count (a <track> whose fetch failed is replaced rather than left dead). */
   subTrackKey: string;
-  onSubTrackError: () => void;
+  /** Spread onto the <track>. Its `error` event does not bubble, and React 18 attaches no listener of
+   *  its own to a <track> — a plain `onError` there is never called (measured in Chrome and jsdom:
+   *  0 calls, while `onErrorCapture` fires). The capture phase reaches the target regardless. */
+  subTrackListeners: { onErrorCapture: () => void };
 } {
   const { id, detail, sessionK, subOffset, subPos, loadSession, patchPrefs } = opts;
-  const { videoRef, hlsRef, multiAudioRef, audioRef, aoffRef, absRef } = opts;
+  const { videoRef, hlsRef, multiAudioRef, audioRef, aoffRef, absRef, loadStartRef } = opts;
   const qc = useQueryClient();
   // Selected audio / subtitle stream ordinals (null audio = default first; null subtitle = off).
   const [audioOrd, setAudioOrd] = useState<number | null>(null);
-  const [subOrd, setSubOrd] = useState<number | null>(null);
+  // The subtitle choice belongs to the ITEM it was made for. Moving to the next episode used to
+  // carry the old ordinal over until the new item's detail re-derived it, so the status poll asked
+  // the new item about a track number that may be a different language there, at the old item's
+  // position. Stored with its id, it simply reads as "off" on any other item.
+  const [subSel, setSubSel] = useState<{ id: string; ord: number | null }>({ id, ord: null });
+  const subOrd = subSel.id === id ? subSel.ord : null;
+  const setSubOrd = useCallback((ord: number | null) => setSubSel({ id, ord }), [id]);
+  // Failed-<track>-load count for one track generation (see onSubTrackError below).
+  const [loadFails, setLoadFails] = useState({ key: "", n: 0 });
   // Debounced user subtitle offset: avoids re-fetching the VTT on every slider step while dragging.
   const [subOffApplied, setSubOffApplied] = useState(subOffset);
   useEffect(() => {
@@ -448,12 +466,15 @@ export function usePlexTracks(opts: {
   const changeSubtitle = useCallback(
     (ord: number | null) => {
       setSubOrd(ord);
+      // Picking a track (the same one included) is the viewer asking for it NOW: a track given up on
+      // after failed loads gets a fresh budget instead of repeating "couldn't be loaded" unasked.
+      setLoadFails({ key: "", n: 0 });
       patchPrefs({
         subLang:
           ord == null ? "" : (detail?.subtitle_streams.find((s) => s.ord === ord)?.language ?? ""),
       });
     },
-    [detail, patchPrefs],
+    [detail, patchPrefs, setSubOrd],
   );
   // 'A' cycles audio tracks; 'S' cycles subtitle (off → each text sub → off).
   const cycleAudio = useCallback(() => {
@@ -499,10 +520,16 @@ export function usePlexTracks(opts: {
     // The position is only known once playback has ticked: until the first timeupdate `abs` is 0
     // even though a resumed session starts minutes in — and every poll said `at=0`, so the first
     // window was cut around the head of the film instead of where the viewer is (measured on
-    // localdev: a resume at 20:00 polled `at=0` for as long as it stayed paused). The session's own
-    // start is the best answer until then.
+    // localdev: a resume at 20:00 polled `at=0` for as long as it stayed paused). Until then the
+    // answer is where the session was asked to start. Not `sessionK`: that only lands once the
+    // session request has answered, so the first poll of a fresh open read 0 from it, and after a
+    // move to the next item it still held the PREVIOUS item's start.
     queryFn: () =>
-      api.plexSubtitleStatus(id, subOrd as number, absRef.current > 0 ? absRef.current : sessionK),
+      api.plexSubtitleStatus(
+        id,
+        subOrd as number,
+        absRef.current > 0 ? absRef.current : loadStartRef.current,
+      ),
     enabled: subOrd != null,
     // Keep polling until the track is COMPLETE, not just showable: each poll carries the current
     // position, so seeking past the extracted window is what asks for the next one. A settled
@@ -531,27 +558,58 @@ export function usePlexTracks(opts: {
   // keeps the dead element and the subtitles stay silently blank. So a failed load bumps a counter
   // that is part of the key — a fresh element, a fresh fetch — and after SUB_TRACK_RETRIES the track
   // is reported as unavailable instead of left blank. The count belongs to one track generation: a
-  // different track, item or `gen` starts from zero.
+  // different track, item or `gen` starts from zero, and so does picking the track again.
   const loadKey = `${id}:${subOrd}:${subStatus?.gen ?? 0}`;
-  const [loadFails, setLoadFails] = useState({ key: "", n: 0 });
   const subRetry = loadFails.key === loadKey ? loadFails.n : 0;
   const subGaveUp = subRetry > SUB_TRACK_RETRIES;
   // Mount the <track> for a `partial` track too: a window around the playhead is exactly what the
   // viewer needs right now, and the poll widens it underneath them.
   const subShowable =
     (subStatus?.state === "ready" || subStatus?.state === "partial") && !subGaveUp;
-  const subFail: SubFailReason | null =
-    (subStatusQ.isError || subGaveUp) && subOrd != null
-      ? "failed"
-      : subStatus?.state === "failed"
-        ? subFailReason(subStatus.code)
-        : null;
+  // A failing poll is said even while an earlier window stays mounted: react-query keeps the last
+  // good `data` through a failed refetch, so a `partial` answer kept the track "showable" and the
+  // failure had nowhere to appear — blank subtitles past the window, no spinner, no message.
+  const subNotice: "preparing" | SubFailReason | null =
+    subOrd == null
+      ? null
+      : subStatusQ.isError || subGaveUp
+        ? "failed"
+        : subStatus?.state === "failed"
+          ? subFailReason(subStatus.code)
+          : subShowable
+            ? null
+            : "preparing";
+  // A remount fetches at once, so remounting straight away spent the whole budget inside a
+  // one-second outage (an API restart): three failures in a few milliseconds, then "unavailable"
+  // for a track that would have loaded a moment later. Each retry waits, doubling; running out is
+  // reported at once. A pending retry dies with the generation it was for.
+  const retryTimer = useRef<number | null>(null);
+  useEffect(
+    () => () => {
+      if (retryTimer.current != null) window.clearTimeout(retryTimer.current);
+      retryTimer.current = null;
+    },
+    [loadKey],
+  );
   const onSubTrackError = useCallback(() => {
-    setLoadFails((f) => ({ key: loadKey, n: (f.key === loadKey ? f.n : 0) + 1 }));
-    // …and ask again: if the cached VTT was evicted between the poll and the fetch, the answer drops
-    // back to `preparing` and the poll takes over until it has been re-extracted.
-    if (subOrd != null) qc.invalidateQueries({ queryKey: qk.plexSubtitle(id, subOrd) });
-  }, [qc, id, subOrd, loadKey]);
+    const bump = () =>
+      setLoadFails((f) => ({ key: loadKey, n: (f.key === loadKey ? f.n : 0) + 1 }));
+    if (subRetry >= SUB_TRACK_RETRIES) {
+      bump();
+      return;
+    }
+    if (retryTimer.current != null) window.clearTimeout(retryTimer.current);
+    retryTimer.current = window.setTimeout(
+      () => {
+        retryTimer.current = null;
+        bump();
+        // …and ask again: if the cached VTT was evicted between the poll and the fetch, the answer
+        // drops back to `preparing` and the poll takes over until it has been re-extracted.
+        if (subOrd != null) qc.invalidateQueries({ queryKey: qk.plexSubtitle(id, subOrd) });
+      },
+      SUB_TRACK_RETRY_MS * 2 ** subRetry,
+    );
+  }, [qc, id, subOrd, loadKey, subRetry]);
 
   // Text subtitles offered in the picker; image subs (PGS/VobSub) can't be shown as text.
   const textSubs = (detail?.subtitle_streams ?? []).filter((s) => s.text);
@@ -620,9 +678,9 @@ export function usePlexTracks(opts: {
     selectedSub,
     subTrackOffset,
     subShowable,
-    subFail,
+    subNotice,
     subGen: subStatus?.gen ?? 0,
     subTrackKey: `${id}-${subOrd}-${subTrackOffset.toFixed(2)}-${subStatus?.gen ?? 0}-${subRetry}`,
-    onSubTrackError,
+    subTrackListeners: { onErrorCapture: onSubTrackError },
   };
 }

From 6de2cd950d6a067ccdcab6da5987c5779ff21d2a Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:18:55 +0200
Subject: [PATCH 18/52] fix(ui): toasts raised while a full-screen player is
 open show inside it, not under its scrim
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The app's Toaster lives in the content column, which is a stacking context (its `@container` implies
layout containment), so both full-screen players — portalled to <body> at the same z-index — painted
over every toast. Round 1's "a failed Remove is reported" fix was therefore still silent inside the
player: its toast sat under an 80% black, blurred scrim (elementFromPoint returned the scrim), and a
click on it closed the player.

An overlay now mounts its own `<Toaster overlay />`, and exactly one host shows the toasts: the most
recently mounted overlay, else the app's. Same component, same look — and inside the aria-modal
dialog, where a screen reader can still reach it. A click on a toast inside an overlay stays there.
Both players get one (the Plex player's also works in native fullscreen, where nothing outside the
fullscreen element is drawn). Verified on localdev: the removal failure reads above the scrim,
bottom-left, and clicking it leaves the player open.
---
 .../src/components/PlayerModal.dom.test.tsx   | 17 ++++++
 frontend/src/components/PlayerModal.tsx       |  4 ++
 frontend/src/components/PlexPlayer.tsx        |  4 ++
 .../src/components/ui/Toaster.dom.test.tsx    | 61 +++++++++++++++++++
 frontend/src/components/ui/Toaster.tsx        | 35 ++++++++++-
 5 files changed, 118 insertions(+), 3 deletions(-)
 create mode 100644 frontend/src/components/ui/Toaster.dom.test.tsx

diff --git a/frontend/src/components/PlayerModal.dom.test.tsx b/frontend/src/components/PlayerModal.dom.test.tsx
index 201d86eb..194580a4 100644
--- a/frontend/src/components/PlayerModal.dom.test.tsx
+++ b/frontend/src/components/PlayerModal.dom.test.tsx
@@ -31,6 +31,7 @@ vi.mock("./DownloadButton", () => ({ default: () => null }));
 import PlayerModal from "./PlayerModal";
 import { ConfirmProvider, useConfirm } from "./ConfirmProvider";
 import { api, type Video } from "../lib/api";
+import { clearAll, notify } from "../lib/notifications";
 
 beforeAll(() => {
   class Stub {
@@ -249,3 +250,19 @@ describe("PlayerModal — removing the playing video from its playlist", () => {
     await waitFor(() => expect(document.activeElement).toBe(trash("A")));
   });
 });
+
+describe("PlayerModal — toasts raised while it is open", () => {
+  afterEach(() => act(() => clearAll()));
+
+  it("shows them inside the player, not under its scrim", async () => {
+    // The app's Toaster is in a stacking context below this body-level portal: a failed Remove
+    // reported by a toast was drawn under the 80% black scrim, i.e. still silent.
+    vi.spyOn(api, "videoDetail").mockReturnValue(new Promise(() => {}));
+    const A = vid("A", 0);
+    renderModal(
+      <PlayerModal video={A} queue={[A]} startIndex={0} onClose={() => {}} onState={() => {}} />,
+    );
+    act(() => void notify({ level: "error", message: "Couldn't remove the video." }));
+    expect(screen.getByTestId("player-modal").textContent).toContain("Couldn't remove the video.");
+  });
+});
diff --git a/frontend/src/components/PlayerModal.tsx b/frontend/src/components/PlayerModal.tsx
index 216ee9d4..d0ac068c 100644
--- a/frontend/src/components/PlayerModal.tsx
+++ b/frontend/src/components/PlayerModal.tsx
@@ -48,6 +48,7 @@ import { fullscreenElement } from "../lib/fullscreen";
 import { dispatch, isActivationTarget, useKeyScope } from "../lib/keymap";
 import { closeThenNavigate, useBackToClose } from "../lib/history";
 import ChannelNameLink from "./ChannelNameLink";
+import Toaster from "./ui/Toaster";
 import { afterRemoval } from "../lib/playerQueue";
 import {
   useNativeControlsYield,
@@ -960,6 +961,9 @@ export default function PlayerModal({
           </button>
         )}
       </div>
+      {/* Toasts raised while the player is open (a failed Remove, a lost connection) — the app's own
+          Toaster is underneath this scrim. See ui/Toaster. */}
+      <Toaster overlay />
     </div>,
     document.body,
   );
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index e3cecf74..4d99f0bc 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -43,6 +43,7 @@ import { PlexPlayerSettings } from "./PlexPlayerSettings";
 import { PlexStatsOverlay } from "./PlexStatsOverlay";
 import { createFragMeter } from "../lib/plexStats";
 import { UpNextCard } from "./UpNextCard";
+import Toaster from "./ui/Toaster";
 import {
   useAutoSkip,
   useControlsVisibility,
@@ -1379,6 +1380,9 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
           </div>
         </div>
       )}
+      {/* The app's Toaster is underneath this full-screen player (and outside it in native
+          fullscreen), so toasts raised while watching show here instead. See ui/Toaster. */}
+      <Toaster overlay />
     </div>,
     document.body,
   );
diff --git a/frontend/src/components/ui/Toaster.dom.test.tsx b/frontend/src/components/ui/Toaster.dom.test.tsx
new file mode 100644
index 00000000..ab67ce1b
--- /dev/null
+++ b/frontend/src/components/ui/Toaster.dom.test.tsx
@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+//
+// Which Toaster shows the toasts. The app's own sits in the content column, which is a stacking
+// context — so a full-screen player portalled to <body> at the same z painted over every toast: a
+// failed Remove raised while watching was drawn under the player's scrim, and clicking it closed
+// the player. An overlay mounts its own host, and exactly one host shows the toasts.
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
+});
+
+import Toaster from "./Toaster";
+import { clearAll, notify } from "../../lib/notifications";
+
+afterEach(() => {
+  cleanup();
+  act(() => clearAll());
+});
+
+const hosts = () => Array.from(document.querySelectorAll("[aria-live='polite']"));
+
+describe("Toaster — one host shows the toasts", () => {
+  it("moves the toasts into an open overlay, and back when it closes", () => {
+    const app = render(
+      <div data-testid="app">
+        <Toaster />
+      </div>,
+    );
+    act(() => void notify({ level: "error", message: "Couldn't remove the video." }));
+    expect(screen.getByTestId("app").textContent).toContain("Couldn't remove the video.");
+
+    const overlay = render(
+      <div data-testid="overlay">
+        <Toaster overlay />
+      </div>,
+    );
+    expect(screen.getByTestId("overlay").textContent).toContain("Couldn't remove the video.");
+    expect(screen.getByTestId("app").textContent).not.toContain("Couldn't remove the video.");
+    // Both live regions stay mounted — a polite region has to pre-exist to be announced.
+    expect(hosts()).toHaveLength(2);
+
+    overlay.unmount();
+    expect(screen.getByTestId("app").textContent).toContain("Couldn't remove the video.");
+    app.unmount();
+  });
+
+  it("does not let a click on a toast reach the overlay's backdrop", () => {
+    const backdrop = vi.fn();
+    render(
+      <div onClick={backdrop}>
+        <Toaster overlay />
+      </div>,
+    );
+    act(() => void notify({ level: "error", message: "boom" }));
+    fireEvent.click(screen.getByText("boom"));
+    expect(backdrop).not.toHaveBeenCalled();
+  });
+});
diff --git a/frontend/src/components/ui/Toaster.tsx b/frontend/src/components/ui/Toaster.tsx
index aa834082..2720feeb 100644
--- a/frontend/src/components/ui/Toaster.tsx
+++ b/frontend/src/components/ui/Toaster.tsx
@@ -1,4 +1,4 @@
-import { useSyncExternalStore } from "react";
+import { useEffect, useId, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { AlertCircle, AlertTriangle, CheckCircle2, Info, X, XCircle } from "lucide-react";
 import { dismiss, getActiveToasts, subscribe, type NotifLevel } from "../../lib/notifications";
@@ -11,9 +11,36 @@ export const LEVEL_STYLE: Record<NotifLevel, { icon: typeof Info; color: string;
   fatal: { icon: XCircle, color: "text-danger", bar: "bg-danger" },
 };
 
-export default function Toaster() {
+// Overlay hosts. The app's own Toaster sits in the content column, and that column is a stacking
+// context (its `@container` implies layout containment) — so a full-screen player, portalled to
+// <body> at the same z-overlay, painted over every toast: a failure raised while watching was
+// drawn under an 80% black, blurred scrim, and a click on it closed the player. Such an overlay
+// mounts its OWN `<Toaster overlay />` inside itself instead, and exactly one host shows the
+// toasts: the most recently mounted overlay, else the app's. Same component, same look — and inside
+// the overlay's aria-modal dialog, where a screen reader can still reach it.
+let overlayHosts: string[] = [];
+const hostListeners = new Set<() => void>();
+const subscribeHosts = (l: () => void) => {
+  hostListeners.add(l);
+  return () => void hostListeners.delete(l);
+};
+const topHost = () => overlayHosts[overlayHosts.length - 1] ?? null;
+const setHosts = (next: string[]) => {
+  overlayHosts = next;
+  hostListeners.forEach((l) => l());
+};
+
+export default function Toaster({ overlay = false }: { overlay?: boolean }) {
   const { t } = useTranslation();
-  const toasts = useSyncExternalStore(subscribe, getActiveToasts, getActiveToasts);
+  const id = useId();
+  useEffect(() => {
+    if (!overlay) return;
+    setHosts([...overlayHosts, id]);
+    return () => setHosts(overlayHosts.filter((h) => h !== id));
+  }, [overlay, id]);
+  const top = useSyncExternalStore(subscribeHosts, topHost, topHost);
+  const active = useSyncExternalStore(subscribe, getActiveToasts, getActiveToasts);
+  const toasts = top === (overlay ? id : null) ? active : [];
 
   return (
     // Stable, always-mounted polite live region — a polite region must PRE-EXIST in the DOM for a
@@ -25,6 +52,8 @@ export default function Toaster() {
     <div
       aria-live="polite"
       className="absolute bottom-4 left-4 z-overlay flex flex-col gap-2 w-80 max-w-[calc(100vw-2rem)]"
+      // Inside an overlay, a click on a toast is not a click on the overlay's backdrop.
+      onClick={overlay ? (e) => e.stopPropagation() : undefined}
     >
       {toasts.map((toast) => {
         const { icon: Icon, color, bar } = LEVEL_STYLE[toast.level];

From dcd8a9566a5d23877d4a995b884d7052b905a1f8 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:19:07 +0200
Subject: [PATCH 19/52] fix(playlists): the player's Remove follows the list it
 was launched from, the player survives a change of selection, and a gone list
 is said in the reader's language
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- D3 snapshotted the removal's TARGET, but whether the player offered Remove still followed the
  selected list: launched from Watch later (no Remove, by design), selecting another list under it
  made Remove appear — and delete from Watch later. The snapshot now carries the launch list's
  editability too.
- Selecting another list under an open player (the command palette works over it) put the page into
  "Loading…", and the player was rendered only in the loaded branch — it vanished mid-playback and
  came back at its launch video. It now sits at one place in the tree whatever the page is doing.
- A removal takes the video out of the CACHED list as well as the rows: the player's progress
  checkpoint rewrote that entry before the refetch landed, handing the membership guard a list that
  still held the video — the row came back and the undo history went.
- The watched-state callback refreshed the selected list, not the launch list (D3's sibling).
- `_own_playlist`'s 404 is structured (`{"code": "playlist", "reason": "not_found"}`) and localised:
  the bare "Unknown playlist" reached the Hungarian UI in English, which also made round 1's new
  `removeFailed` string unreachable. Both Remove and Move report through `notifyActionError` now.
- The "viewer moved on under the confirm" test stepped back only once, which lands on the same video
  whether or not the removed one left the queue; it now takes the second step that tells them apart.
---
 backend/app/routes/playlists.py               |   5 +-
 backend/tests/test_playlist_move.py           |  16 +
 .../src/components/PlayerModal.dom.test.tsx   |   5 +
 .../src/components/Playlists.dom.test.tsx     |  93 ++-
 frontend/src/components/Playlists.tsx         | 555 ++++++++++--------
 frontend/src/i18n/locales/en/playlists.json   |   3 +
 frontend/src/i18n/locales/hu/playlists.json   |   3 +
 frontend/src/lib/api/core.test.ts             |  20 +-
 frontend/src/lib/api/core.ts                  |   2 +
 9 files changed, 438 insertions(+), 264 deletions(-)

diff --git a/backend/app/routes/playlists.py b/backend/app/routes/playlists.py
index 3a1bcd12..1051ddcb 100644
--- a/backend/app/routes/playlists.py
+++ b/backend/app/routes/playlists.py
@@ -50,7 +50,10 @@ def _check_pull_cooldown(user: User) -> None:
 def _own_playlist(db: Session, user: User, playlist_id: int) -> Playlist:
     pl = db.get(Playlist, playlist_id)
     if pl is None or pl.user_id != user.id:
-        raise HTTPException(status_code=404, detail="Unknown playlist")
+        # Structured, so the UI can say it in the reader's language: this 404 is exactly the one a
+        # user meets in practice (the list was deleted in another tab), and a bare "Unknown
+        # playlist" reached the Hungarian UI in English. One reason for "gone" and "not yours" alike.
+        raise HTTPException(status_code=404, detail={"code": "playlist", "reason": "not_found"})
     return pl
 
 
diff --git a/backend/tests/test_playlist_move.py b/backend/tests/test_playlist_move.py
index 8590c2a8..027f0606 100644
--- a/backend/tests/test_playlist_move.py
+++ b/backend/tests/test_playlist_move.py
@@ -128,6 +128,22 @@ def test_move_into_someone_elses_list_404s_and_changes_nothing(db, make_user, as
     assert _ids(db, theirs.id) == []
 
 
+def test_a_list_that_is_not_yours_answers_with_a_reason_the_ui_can_translate(
+    db, make_user, as_user
+):
+    # The one 404 a user meets in practice (the list went away in another tab). It used to be a bare
+    # English "Unknown playlist", which the Hungarian UI then showed verbatim.
+    user, other = make_user(), make_user()
+    _seed_videos(db, ["v1"])
+    theirs = _playlist(db, other, "Theirs", ["v1"])
+
+    r = as_user(user).delete(f"/api/playlists/{theirs.id}/items/v1")
+    assert r.status_code == 404
+    assert r.json()["detail"] == {"code": "playlist", "reason": "not_found"}
+    db.expire_all()
+    assert _ids(db, theirs.id) == ["v1"]
+
+
 def test_move_marks_both_linked_sides_dirty(db, make_user, as_user):
     """A move edits two YouTube mirrors at once — the source lost an item, the target gained one.
     Marking only the source is the asymmetric fix this repo keeps re-learning."""
diff --git a/frontend/src/components/PlayerModal.dom.test.tsx b/frontend/src/components/PlayerModal.dom.test.tsx
index 194580a4..08c07545 100644
--- a/frontend/src/components/PlayerModal.dom.test.tsx
+++ b/frontend/src/components/PlayerModal.dom.test.tsx
@@ -216,6 +216,11 @@ describe("PlayerModal — removing the playing video from its playlist", () => {
     expect(lastStart()?.videoId).toBe("C");
     prev();
     await waitFor(() => expect(lastStart()?.videoId).toBe("B"));
+    // …and A is gone from the queue, not just skipped over: B is its head now, so stepping back
+    // again goes nowhere. (One step back lands on B either way — it took the second to tell.)
+    prev();
+    await settle();
+    expect(lastStart()?.videoId).toBe("B");
     expect(started.filter((s) => s.videoId === "A")).toHaveLength(1); // never played again
   });
 
diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
index e835fc1a..7a9cf766 100644
--- a/frontend/src/components/Playlists.dom.test.tsx
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -10,9 +10,11 @@ import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 const h = vi.hoisted(() => ({
   notify: vi.fn(),
   selectedId: 1 as number | null,
+  mounted: false,
   player: null as null | {
     video: { id: string; position_seconds: number };
     onClose: () => void;
+    onState: (id: string, status: string) => void;
     onRemoveFromList?: (v: unknown) => Promise<boolean>;
   },
 }));
@@ -34,12 +36,21 @@ vi.mock("../lib/notifications", async (importOriginal) => ({
 vi.mock("./PlaylistsProvider", () => ({ usePlaylists: () => ({ selectedId: h.selectedId }) }));
 vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
 vi.mock("./usePlaylistActions", () => ({ usePlaylistActions: () => ({ remove: vi.fn() }) }));
-vi.mock("./PlayerModal", () => ({
-  default: (props: NonNullable<typeof h.player>) => {
-    h.player = props;
-    return null;
-  },
-}));
+vi.mock("./PlayerModal", async () => {
+  const { useEffect } = await import("react");
+  return {
+    default: function PlayerStandIn(props: NonNullable<typeof h.player>) {
+      h.player = props;
+      useEffect(() => {
+        h.mounted = true;
+        return () => {
+          h.mounted = false;
+        };
+      }, []);
+      return null;
+    },
+  };
+});
 
 import Playlists from "./Playlists";
 import { api, HttpError, type Video } from "../lib/api";
@@ -72,10 +83,11 @@ const vid = (id: string, position_seconds: number): Video =>
     watch_url: `https://www.youtube.com/watch?v=${id}`,
   }) as unknown as Video;
 
+const WATCH_LATER = 9;
 const list = (id: number, items: Video[]) => ({
   id,
   name: `List ${id}`,
-  kind: "user",
+  kind: id === WATCH_LATER ? "watch_later" : "user",
   yt_playlist_id: null,
   item_count: items.length,
   items,
@@ -107,6 +119,7 @@ const play = async (title: string) =>
 beforeEach(() => {
   h.selectedId = 1;
   h.player = null;
+  h.mounted = false;
   h.notify.mockClear();
 });
 afterEach(() => {
@@ -171,4 +184,70 @@ describe("Playlists — removing a video from inside the player", () => {
     expect(done).toBe(false);
     expect(h.notify).toHaveBeenCalledWith(expect.objectContaining({ level: "error" }));
   });
+
+  it("offers Remove by the list it was launched from, not by whichever list is selected now", async () => {
+    // Watch later deliberately has no Remove. Gated on the SELECTED list, it appeared on a player
+    // launched from Watch later as soon as another list was selected under it — and deleted from
+    // Watch later, since the removal itself targets the launch list.
+    h.selectedId = WATCH_LATER;
+    const { rerender } = mount({ [WATCH_LATER]: [vid("V", 0)], 2: [vid("W", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.player).not.toBeNull());
+    expect(h.player!.onRemoveFromList).toBeUndefined();
+    h.selectedId = 2;
+    rerender();
+    await screen.findByRole("button", { name: "card.play — Video W" });
+    expect(h.player!.onRemoveFromList).toBeUndefined();
+  });
+
+  it("takes the removed video out of the cached list, so a progress checkpoint cannot bring it back", async () => {
+    // The player steps to the next item after a removal and stores the last one's position into
+    // every cached list. Landing before the refetch, that write handed the page a list still holding
+    // the video, and the page — seeing a different set of ids — reset: the row came back.
+    vi.spyOn(api, "removeFromPlaylist").mockResolvedValue(undefined as never);
+    mount({ 1: [vid("V", 0), vid("W", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.player).not.toBeNull());
+    vi.mocked(api.playlist).mockReturnValue(new Promise(() => {})); // the refetch is still out
+    await act(async () => {
+      await h.player!.onRemoveFromList!(vid("V", 0));
+    });
+    await act(async () => {
+      patchCachedProgress(qc, new Map([["V", 99]]));
+      await new Promise((r) => setTimeout(r, 0));
+    });
+    expect(screen.queryByRole("button", { name: "card.play — Video V" })).toBeNull();
+    expect(screen.getByRole("button", { name: "card.play — Video W" })).toBeTruthy();
+  });
+});
+
+describe("Playlists — the player outlives a change of selection", () => {
+  it("stays mounted while a newly selected list is still loading", async () => {
+    // The page swaps itself for "Loading…" until the new list arrives; with the player rendered only
+    // in the loaded branch, that took it down mid-playback and put it back at its launch video.
+    const { rerender } = mount({ 1: [vid("V", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.mounted).toBe(true));
+    vi.mocked(api.playlist).mockReturnValue(new Promise(() => {}));
+    h.selectedId = 2;
+    rerender();
+    await screen.findByText("playlists.loading");
+    expect(h.mounted).toBe(true);
+  });
+
+  it("refreshes the list it was launched from when the viewer marks the video in it", async () => {
+    // Invalidating the SELECTED list left the launch list's row showing the old status.
+    vi.spyOn(api, "setState").mockResolvedValue(undefined as never);
+    const { rerender } = mount({ 1: [vid("V", 0)], 2: [vid("W", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.player).not.toBeNull());
+    h.selectedId = 2;
+    rerender();
+    await screen.findByRole("button", { name: "card.play — Video W" });
+    await act(async () => {
+      h.player!.onState("V", "watched");
+      await new Promise((r) => setTimeout(r, 0));
+    });
+    expect(qc.getQueryState(qk.playlist(1))?.isInvalidated).toBe(true);
+  });
 });
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 61a0ce58..0c6641ab 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -40,8 +40,9 @@ import {
   X,
   Youtube,
 } from "lucide-react";
-import { api, HttpError, type Playlist, type Video } from "../lib/api";
+import { api, HttpError, type Playlist, type PlaylistDetail, type Video } from "../lib/api";
 import { notify } from "../lib/notifications";
+import { notifyActionError } from "../lib/actionErrors";
 import { notifyYouTubeActionError } from "../lib/youtubeErrors";
 import { playlistName } from "../lib/playlistName";
 import { useUndoable } from "../lib/useUndoable";
@@ -227,12 +228,15 @@ export default function Playlists() {
   // normal case. Only onClose takes the player down now. `listId` is part of that snapshot for the
   // same reason: the selection can change under an open player (the command palette opens over it),
   // and "remove this from the playlist" means the list it was LAUNCHED from, not whichever is
-  // selected by the time the button is pressed.
+  // selected by the time the button is pressed. So does whether that button exists at all
+  // (`editable`): gating it on the current selection offered Remove on a player launched from
+  // Watch later — which deliberately has none — as soon as another list was selected under it.
   const [playing, setPlaying] = useState<{
     video: Video;
     queue: Video[];
     index: number;
     listId: number | null;
+    editable: boolean;
   } | null>(null);
   // Where the last move went. `LS.playlist` is the SELECTED (source) list and `updated_at` moves on
   // any edit, so neither answers "where do I keep sending things"; this does, and it is a per-account
@@ -301,6 +305,8 @@ export default function Playlists() {
   // push/delete-on-YouTube paths. Folding it in here would have taken drag and remove away from
   // every account without the scope, which they have always had.
   const canEdit = editable;
+  const canEditRef = useRef(canEdit);
+  canEditRef.current = canEdit;
   const [pushing, setPushing] = useState(false);
   const [reverting, setReverting] = useState(false);
 
@@ -310,7 +316,13 @@ export default function Playlists() {
     const queue = shownRef.current;
     const index = queue.findIndex((v) => v.id === id);
     if (index < 0) return;
-    setPlaying({ video: queue[index]!, queue, index, listId: selectedRef.current });
+    setPlaying({
+      video: queue[index]!,
+      queue,
+      index,
+      listId: selectedRef.current,
+      editable: canEditRef.current,
+    });
   }, []);
   const onPlay = useCallback((v: Video) => openPlayer(v.id), [openPlayer]);
   const onRemove = useCallback((v: Video) => {
@@ -551,6 +563,14 @@ export default function Playlists() {
       order.rebase((list) => list.filter((v) => v.id !== video.id));
       lastSetRef.current = `${listId}:${idsKey(next)}`;
     }
+    // …and out of the CACHED list too, not just the rows. Anything that rewrites that cache entry
+    // before the refetch lands handed the membership guard a list that still held the video — the
+    // player's own progress checkpoint does exactly that when a removal steps it to the next item —
+    // so the guard reset the order: the removed row came back and the undo history the rebase had
+    // kept went with it. (A failure resyncs below, which puts the row back where it belongs.)
+    qc.setQueryData<PlaylistDetail>(qk.playlist(listId), (old) =>
+      old ? { ...old, items: old.items.filter((v) => v.id !== video.id) } : old,
+    );
     try {
       await api.removeFromPlaylist(listId, video.id);
       refreshAll(listId);
@@ -561,7 +581,7 @@ export default function Playlists() {
       // confirmed removal fails in silence (inside the full-screen player there is not even a row
       // snapping back to show it).
       if (e instanceof HttpError && (e.status === 404 || e.status === 403))
-        notify({ level: "error", message: e.detail || t("playlists.removeFailed") });
+        notifyActionError(e, t("playlists.removeFailed"));
       refreshAll(listId); // …and resync, which restores any row the optimistic removal took out
       return false;
     }
@@ -597,7 +617,7 @@ export default function Playlists() {
       // error dialog for 400/409/422 and 5xx and raises the connectivity notice for a bad gateway,
       // so toasting unconditionally reported a transport fault twice (E10 review round 2).
       if (e instanceof HttpError && (e.status === 404 || e.status === 403))
-        notify({ level: "error", message: e.detail || t("playlists.moveFailed") });
+        notifyActionError(e, t("playlists.moveFailed"));
     }
     // BOTH sides changed, and so did this video's membership. `qk.playlist(selectedId)` is an exact
     // key, so it cannot cover the target — invalidate the whole `["playlist"]` prefix, exactly as
@@ -636,7 +656,10 @@ export default function Playlists() {
 
   function playerState(id: string, status: string) {
     api.setState(id, status).then(() => {
-      qc.invalidateQueries({ queryKey: qk.playlist(selectedId) });
+      // Every cached list, not `qk.playlist(selectedId)`: the player may have been launched from a
+      // list that is no longer the selected one (see `playing`), and that list holds the row whose
+      // status just changed. Only lists actually on screen refetch.
+      qc.invalidateQueries({ queryKey: qk.playlist() });
       qc.invalidateQueries({ queryKey: qk.feed() });
     });
   }
@@ -767,293 +790,315 @@ export default function Playlists() {
           : []),
       ];
 
+  // The open player, at ONE place in the tree whichever state the page below it is in. Selecting
+  // another list under an open player (the command palette works over it) puts the page into
+  // "Loading…" until that list arrives; with the player rendered only in the loaded branch, that
+  // unmounted it mid-playback and remounted it at the video it was launched with.
+  const player = playing && (
+    <Suspense fallback={null}>
+      <PlayerModal
+        video={playing.video}
+        queue={playing.queue}
+        startIndex={playing.index}
+        startAt={null}
+        onClose={closePlayer}
+        onState={playerState}
+        onRemoveFromList={playing.editable ? removeFromPlayer : undefined}
+      />
+    </Suspense>
+  );
+
   if (selectedId == null) {
-    return <div className="text-muted text-sm p-4">{t("playlists.pickOne")}</div>;
+    return (
+      <>
+        <div className="text-muted text-sm p-4">{t("playlists.pickOne")}</div>
+        {player}
+      </>
+    );
   }
   // The page used to render "Loading…" forever when the detail query failed — an error read as a
   // slow network that never arrived.
   if (detailQuery.isError) {
     return (
-      <div className="text-sm p-4 flex flex-col items-start gap-3">
-        <span className="inline-flex items-center gap-2 text-muted">
-          <AlertTriangle className="w-4 h-4 text-danger" />
-          {t("playlists.loadFailed")}
-        </span>
-        <Button variant="outline" size="xs" onClick={() => detailQuery.refetch()}>
-          {t("common.retry")}
-        </Button>
-      </div>
+      <>
+        <div className="text-sm p-4 flex flex-col items-start gap-3">
+          <span className="inline-flex items-center gap-2 text-muted">
+            <AlertTriangle className="w-4 h-4 text-danger" />
+            {t("playlists.loadFailed")}
+          </span>
+          <Button variant="outline" size="xs" onClick={() => detailQuery.refetch()}>
+            {t("common.retry")}
+          </Button>
+        </div>
+        {player}
+      </>
     );
   }
   if (!detail) {
-    return <div className="text-muted text-sm p-4">{t("playlists.loading")}</div>;
+    return (
+      <>
+        <div className="text-muted text-sm p-4">{t("playlists.loading")}</div>
+        {player}
+      </>
+    );
   }
 
+  // No top padding: the sticky column header must sit flush at the scroller top so it doesn't
+  // shift up when `position: sticky` engages on the first scroll (the fixed toolbar band above
+  // gives the breathing room). Same reason as the channel table — see Channels.tsx.
   return (
-    // No top padding: the sticky column header must sit flush at the scroller top so it doesn't
-    // shift up when `position: sticky` engages on the first scroll (the fixed toolbar band above
-    // gives the breathing room). Same reason as the channel table — see Channels.tsx.
-    <div className="px-4 pb-4">
-      {/* Header (title, actions, view controls) is fixed chrome — it portals into the shell's
+    <>
+      <div className="px-4 pb-4">
+        {/* Header (title, actions, view controls) is fixed chrome — it portals into the shell's
           fixed band, so only the video list scrolls. */}
-      <PageToolbar>
-        {/* Two tight rows beside a small cover: title + actions on the first, the meta line and the
+        <PageToolbar>
+          {/* Two tight rows beside a small cover: title + actions on the first, the meta line and the
             view controls sharing the second. This band is FIXED chrome (it never scrolls), so every
             row it sheds is list height won back — the old layout stacked three rows next to the
             cover plus a fourth block under it, for roughly twice this height. */}
-        <div className="px-4 py-2 max-w-5xl mx-auto">
-          <div className="flex gap-3 items-center">
-            <div className="w-20 h-11.25 rounded-lg bg-card overflow-hidden shrink-0">
-              {items[0]?.thumbnail_url && (
-                <img src={items[0].thumbnail_url} alt="" className="w-full h-full object-cover" />
-              )}
-            </div>
-            <div className="min-w-0 flex-1">
-              <div className="flex items-center gap-2 min-w-0">
-                {renaming ? (
-                  <input
-                    autoFocus
-                    value={renameValue}
-                    onChange={(e) => setRenameValue(e.target.value)}
-                    onBlur={saveRename}
-                    onKeyDown={(e) => {
-                      if (e.key === "Enter") saveRename();
-                      if (e.key === "Escape") setRenaming(false);
-                    }}
-                    aria-label={t("playlists.rename")}
-                    className="min-w-0 flex-1 text-lg font-semibold bg-surface border border-border rounded-md px-2 py-0.5 focus:outline-hidden focus:ring-2 focus:ring-accent/40"
-                  />
-                ) : (
-                  <>
-                    <h2 className="text-lg font-semibold truncate">{plName(detail)}</h2>
-                    {editable && (
-                      <button
-                        onClick={() => {
-                          setRenameValue(detail.name);
-                          setRenaming(true);
-                        }}
-                        title={t("playlists.rename")}
-                        aria-label={t("playlists.rename")}
-                        className="shrink-0 text-muted hover:text-fg"
-                      >
-                        <Pencil className="w-3.5 h-3.5" />
-                      </button>
-                    )}
-                    {detail.yt_playlist_id && (
-                      <a
-                        href={`https://www.youtube.com/playlist?list=${detail.yt_playlist_id}`}
-                        target="_blank"
-                        rel="noreferrer noopener"
-                        title={t("playlists.openOnYoutube")}
-                        aria-label={t("playlists.openOnYoutube")}
-                        className="shrink-0 text-muted hover:text-accent"
-                      >
-                        <ExternalLink className="w-3.5 h-3.5" />
-                      </a>
-                    )}
-                  </>
+          <div className="px-4 py-2 max-w-5xl mx-auto">
+            <div className="flex gap-3 items-center">
+              <div className="w-20 h-11.25 rounded-lg bg-card overflow-hidden shrink-0">
+                {items[0]?.thumbnail_url && (
+                  <img src={items[0].thumbnail_url} alt="" className="w-full h-full object-cover" />
                 )}
-                <div className="ml-auto flex gap-1.5 items-center shrink-0">
-                  {linked && detail.dirty && (
-                    <span
-                      title={t("playlists.unsyncedHint")}
-                      className="inline-flex items-center gap-1.5 text-2xs text-accent mr-1"
-                    >
-                      <span className="w-1.5 h-1.5 rounded-full bg-accent" />
-                      {t("playlists.unsynced")}
-                    </span>
-                  )}
-                  <button
-                    onClick={() => shown.length && openPlayer(shown[0]!.id)}
-                    disabled={!shown.length}
-                    className="inline-flex items-center gap-1.5 text-xs font-semibold px-3 py-1.5 rounded-lg btn-primary disabled:opacity-40 transition"
-                  >
-                    <Play className="w-3.5 h-3.5 fill-current" /> {t("playlists.playAll")}
-                  </button>
-                  {editable && canWrite && (
-                    <button
-                      onClick={pushToYoutube}
-                      disabled={pushing}
-                      title={linked ? t("playlists.pushToYoutube") : t("playlists.exportToYoutube")}
-                      aria-label={
-                        linked ? t("playlists.pushToYoutube") : t("playlists.exportToYoutube")
-                      }
-                      className={`inline-flex items-center justify-center p-2 rounded-lg border transition disabled:opacity-40 ${
-                        detail.dirty
-                          ? "border-accent text-accent hover:bg-accent/10"
-                          : "border-border text-muted hover:text-fg hover:border-accent"
-                      }`}
-                    >
-                      {pushing ? (
-                        <RefreshCw className="w-3.5 h-3.5 animate-spin" />
-                      ) : linked ? (
-                        <Youtube className="w-3.5 h-3.5" />
-                      ) : (
-                        <Upload className="w-3.5 h-3.5" />
-                      )}
-                    </button>
-                  )}
-                  {linked && detail.dirty && (
-                    <Button
-                      variant="outline"
-                      size="icon-sm"
-                      onClick={revertToYoutube}
-                      disabled={reverting}
-                      title={t("playlists.revert")}
-                      aria-label={t("playlists.revert")}
-                    >
-                      <RotateCcw className={`w-3.5 h-3.5 ${reverting ? "animate-spin" : ""}`} />
-                    </Button>
-                  )}
-                  {editable && (
-                    <Button
-                      variant="outline-danger"
-                      size="icon-sm"
-                      onClick={deletePlaylist}
-                      title={t("playlists.delete")}
-                      aria-label={t("playlists.delete")}
-                      icon={<Trash2 className="w-3.5 h-3.5" />}
-                    />
-                  )}
-                </div>
               </div>
-
-              <div className="flex items-center gap-2 mt-1 flex-wrap">
-                <span className="text-xs text-muted">
-                  {t("playlists.itemCount", { count: items.length })}
-                  {totalSeconds > 0 && ` · ${formatRuntime(totalSeconds)}`}
-                  {filterActive && ` · ${t("playlists.filteredCount", { count: shown.length })}`}
-                </span>
-                {(items.length > 1 || viewActive) && (
-                  <>
-                    <span aria-hidden="true" className="text-xs text-muted/40">
-                      ·
-                    </span>
-                    <label className="inline-flex items-center gap-1.5 text-xs text-muted cursor-pointer select-none">
-                      <input
-                        type="checkbox"
-                        checked={groupBy}
-                        onChange={(e) => setGroupBy(e.target.checked)}
-                        className="accent-accent"
-                      />
-                      {t("playlists.groupByChannel")}
-                    </label>
-                    {viewActive && (
-                      <button
-                        onClick={clearView}
-                        className="text-xs text-muted hover:text-accent underline underline-offset-2 transition"
+              <div className="min-w-0 flex-1">
+                <div className="flex items-center gap-2 min-w-0">
+                  {renaming ? (
+                    <input
+                      autoFocus
+                      value={renameValue}
+                      onChange={(e) => setRenameValue(e.target.value)}
+                      onBlur={saveRename}
+                      onKeyDown={(e) => {
+                        if (e.key === "Enter") saveRename();
+                        if (e.key === "Escape") setRenaming(false);
+                      }}
+                      aria-label={t("playlists.rename")}
+                      className="min-w-0 flex-1 text-lg font-semibold bg-surface border border-border rounded-md px-2 py-0.5 focus:outline-hidden focus:ring-2 focus:ring-accent/40"
+                    />
+                  ) : (
+                    <>
+                      <h2 className="text-lg font-semibold truncate">{plName(detail)}</h2>
+                      {editable && (
+                        <button
+                          onClick={() => {
+                            setRenameValue(detail.name);
+                            setRenaming(true);
+                          }}
+                          title={t("playlists.rename")}
+                          aria-label={t("playlists.rename")}
+                          className="shrink-0 text-muted hover:text-fg"
+                        >
+                          <Pencil className="w-3.5 h-3.5" />
+                        </button>
+                      )}
+                      {detail.yt_playlist_id && (
+                        <a
+                          href={`https://www.youtube.com/playlist?list=${detail.yt_playlist_id}`}
+                          target="_blank"
+                          rel="noreferrer noopener"
+                          title={t("playlists.openOnYoutube")}
+                          aria-label={t("playlists.openOnYoutube")}
+                          className="shrink-0 text-muted hover:text-accent"
+                        >
+                          <ExternalLink className="w-3.5 h-3.5" />
+                        </a>
+                      )}
+                    </>
+                  )}
+                  <div className="ml-auto flex gap-1.5 items-center shrink-0">
+                    {linked && detail.dirty && (
+                      <span
+                        title={t("playlists.unsyncedHint")}
+                        className="inline-flex items-center gap-1.5 text-2xs text-accent mr-1"
                       >
-                        {t("playlists.clearView")}
+                        <span className="w-1.5 h-1.5 rounded-full bg-accent" />
+                        {t("playlists.unsynced")}
+                      </span>
+                    )}
+                    <button
+                      onClick={() => shown.length && openPlayer(shown[0]!.id)}
+                      disabled={!shown.length}
+                      className="inline-flex items-center gap-1.5 text-xs font-semibold px-3 py-1.5 rounded-lg btn-primary disabled:opacity-40 transition"
+                    >
+                      <Play className="w-3.5 h-3.5 fill-current" /> {t("playlists.playAll")}
+                    </button>
+                    {editable && canWrite && (
+                      <button
+                        onClick={pushToYoutube}
+                        disabled={pushing}
+                        title={
+                          linked ? t("playlists.pushToYoutube") : t("playlists.exportToYoutube")
+                        }
+                        aria-label={
+                          linked ? t("playlists.pushToYoutube") : t("playlists.exportToYoutube")
+                        }
+                        className={`inline-flex items-center justify-center p-2 rounded-lg border transition disabled:opacity-40 ${
+                          detail.dirty
+                            ? "border-accent text-accent hover:bg-accent/10"
+                            : "border-border text-muted hover:text-fg hover:border-accent"
+                        }`}
+                      >
+                        {pushing ? (
+                          <RefreshCw className="w-3.5 h-3.5 animate-spin" />
+                        ) : linked ? (
+                          <Youtube className="w-3.5 h-3.5" />
+                        ) : (
+                          <Upload className="w-3.5 h-3.5" />
+                        )}
                       </button>
                     )}
-                    {canSaveOrder && (
+                    {linked && detail.dirty && (
                       <Button
-                        variant="outline-accent"
-                        size="xs"
-                        onClick={saveOrder}
-                        icon={<Check className="w-3.5 h-3.5" />}
+                        variant="outline"
+                        size="icon-sm"
+                        onClick={revertToYoutube}
+                        disabled={reverting}
+                        title={t("playlists.revert")}
+                        aria-label={t("playlists.revert")}
                       >
-                        {t("playlists.saveOrder")}
+                        <RotateCcw className={`w-3.5 h-3.5 ${reverting ? "animate-spin" : ""}`} />
                       </Button>
                     )}
-                    {/* ONE sentence that names the state. Three loose texts used to pile up here
+                    {editable && (
+                      <Button
+                        variant="outline-danger"
+                        size="icon-sm"
+                        onClick={deletePlaylist}
+                        title={t("playlists.delete")}
+                        aria-label={t("playlists.delete")}
+                        icon={<Trash2 className="w-3.5 h-3.5" />}
+                      />
+                    )}
+                  </div>
+                </div>
+
+                <div className="flex items-center gap-2 mt-1 flex-wrap">
+                  <span className="text-xs text-muted">
+                    {t("playlists.itemCount", { count: items.length })}
+                    {totalSeconds > 0 && ` · ${formatRuntime(totalSeconds)}`}
+                    {filterActive && ` · ${t("playlists.filteredCount", { count: shown.length })}`}
+                  </span>
+                  {(items.length > 1 || viewActive) && (
+                    <>
+                      <span aria-hidden="true" className="text-xs text-muted/40">
+                        ·
+                      </span>
+                      <label className="inline-flex items-center gap-1.5 text-xs text-muted cursor-pointer select-none">
+                        <input
+                          type="checkbox"
+                          checked={groupBy}
+                          onChange={(e) => setGroupBy(e.target.checked)}
+                          className="accent-accent"
+                        />
+                        {t("playlists.groupByChannel")}
+                      </label>
+                      {viewActive && (
+                        <button
+                          onClick={clearView}
+                          className="text-xs text-muted hover:text-accent underline underline-offset-2 transition"
+                        >
+                          {t("playlists.clearView")}
+                        </button>
+                      )}
+                      {canSaveOrder && (
+                        <Button
+                          variant="outline-accent"
+                          size="xs"
+                          onClick={saveOrder}
+                          icon={<Check className="w-3.5 h-3.5" />}
+                        >
+                          {t("playlists.saveOrder")}
+                        </Button>
+                      )}
+                      {/* ONE sentence that names the state. Three loose texts used to pile up here
                         (reset link + save hint + "reordering is off"), and none of them answered the
                         question a user actually has — "did I just change my playlist?". Worse,
                         sorting a list whose stored order ALREADY matches the sort produced a
                         warning, no Save button and no visible change, which reads as a malfunction.
                         Now the line says which of the three situations you are in; the disabled grip
                         still explains itself on hover/focus. */}
-                    {viewActive && <span className="text-2xs text-muted/80">{viewStatus}</span>}
-                    {canEdit && (
-                      <div className="ml-auto">
-                        <UndoToolbar
-                          canUndo={order.canUndo}
-                          canRedo={order.canRedo}
-                          onUndo={order.undo}
-                          onRedo={order.redo}
-                        />
-                      </div>
-                    )}
-                  </>
-                )}
+                      {viewActive && <span className="text-2xs text-muted/80">{viewStatus}</span>}
+                      {canEdit && (
+                        <div className="ml-auto">
+                          <UndoToolbar
+                            canUndo={order.canUndo}
+                            canRedo={order.canRedo}
+                            onUndo={order.undo}
+                            onRedo={order.redo}
+                          />
+                        </div>
+                      )}
+                    </>
+                  )}
+                </div>
               </div>
             </div>
           </div>
-        </div>
-      </PageToolbar>
+        </PageToolbar>
 
-      {items.length === 0 ? (
-        <div className="text-sm text-muted grid place-items-center text-center py-12">
-          <div>
-            <ListPlus className="w-6 h-6 mx-auto mb-2 opacity-60" />
-            {t("playlists.empty")}
+        {items.length === 0 ? (
+          <div className="text-sm text-muted grid place-items-center text-center py-12">
+            <div>
+              <ListPlus className="w-6 h-6 mx-auto mb-2 opacity-60" />
+              {t("playlists.empty")}
+            </div>
           </div>
-        </div>
-      ) : (
-        <DndContext
-          sensors={sensors}
-          collisionDetection={closestCenter}
-          onDragEnd={onDragEnd}
-          // dnd-kit's defaults are hardcoded English. They were harmless while only a pointer could
-          // drag; now that the keyboard can, they ARE the instructions for the feature.
-          accessibility={{ screenReaderInstructions, announcements }}
-        >
-          {/* Not clipped, so the header's filter popovers can overflow the table box. */}
-          <div className="max-w-5xl mx-auto">
-            {/* table-fixed, not auto: every column but the title has a declared width, so the
+        ) : (
+          <DndContext
+            sensors={sensors}
+            collisionDetection={closestCenter}
+            onDragEnd={onDragEnd}
+            // dnd-kit's defaults are hardcoded English. They were harmless while only a pointer could
+            // drag; now that the keyboard can, they ARE the instructions for the feature.
+            accessibility={{ screenReaderInstructions, announcements }}
+          >
+            {/* Not clipped, so the header's filter popovers can overflow the table box. */}
+            <div className="max-w-5xl mx-auto">
+              {/* table-fixed, not auto: every column but the title has a declared width, so the
                 title absorbs the rest and its `truncate` works. Auto layout sizes columns from
                 min-content, and a nowrap title cell's min-content is the entire title. */}
-            <table className="w-full table-fixed border-collapse text-sm">
-              <ColumnHead
-                columns={columns}
-                sort={viewSort}
-                onToggleSort={toggleSort}
-                filters={filters}
-                onFilter={applyFilter}
-              />
-              <SortableContext
-                items={shown.map((v) => v.id)}
-                strategy={verticalListSortingStrategy}
-              >
-                <tbody>
-                  {shown.map((v) => (
-                    <Row
-                      key={v.id}
-                      video={v}
-                      columns={columns}
-                      dragDisabled={!canEdit || viewActive}
-                      dragHint={dragHint}
-                      menuProps={rowMenu.triggerProps(v)}
-                    />
-                  ))}
-                </tbody>
-              </SortableContext>
-            </table>
-            {shown.length === 0 && (
-              <div className="text-muted py-8 text-center text-sm">
-                {t("playlists.noneMatchFilter")}
-              </div>
-            )}
-          </div>
-        </DndContext>
-      )}
+              <table className="w-full table-fixed border-collapse text-sm">
+                <ColumnHead
+                  columns={columns}
+                  sort={viewSort}
+                  onToggleSort={toggleSort}
+                  filters={filters}
+                  onFilter={applyFilter}
+                />
+                <SortableContext
+                  items={shown.map((v) => v.id)}
+                  strategy={verticalListSortingStrategy}
+                >
+                  <tbody>
+                    {shown.map((v) => (
+                      <Row
+                        key={v.id}
+                        video={v}
+                        columns={columns}
+                        dragDisabled={!canEdit || viewActive}
+                        dragHint={dragHint}
+                        menuProps={rowMenu.triggerProps(v)}
+                      />
+                    ))}
+                  </tbody>
+                </SortableContext>
+              </table>
+              {shown.length === 0 && (
+                <div className="text-muted py-8 text-center text-sm">
+                  {t("playlists.noneMatchFilter")}
+                </div>
+              )}
+            </div>
+          </DndContext>
+        )}
 
-      {/* One surface for the whole table, outside the rows — it anchors to the pointer, not the row. */}
-      <ContextMenu menu={rowMenu} ariaLabel={t("playlists.rowMenu")} items={ctxItems} />
-
-      {playing && (
-        <Suspense fallback={null}>
-          <PlayerModal
-            video={playing.video}
-            queue={playing.queue}
-            startIndex={playing.index}
-            startAt={null}
-            onClose={closePlayer}
-            onState={playerState}
-            onRemoveFromList={canEdit ? removeFromPlayer : undefined}
-          />
-        </Suspense>
-      )}
-    </div>
+        {/* One surface for the whole table, outside the rows — it anchors to the pointer, not the row. */}
+        <ContextMenu menu={rowMenu} ariaLabel={t("playlists.rowMenu")} items={ctxItems} />
+      </div>
+      {player}
+    </>
   );
 }
diff --git a/frontend/src/i18n/locales/en/playlists.json b/frontend/src/i18n/locales/en/playlists.json
index 65f9fd5c..06792711 100644
--- a/frontend/src/i18n/locales/en/playlists.json
+++ b/frontend/src/i18n/locales/en/playlists.json
@@ -77,6 +77,9 @@
   "movedToast": "“{{title}}” moved to “{{name}}” ✓",
   "moveFailed": "Couldn't move the video.",
   "removeFailed": "Couldn't remove the video.",
+  "errors": {
+    "not_found": "This playlist doesn't exist any more."
+  },
   "moveErrors": {
     "not_in_playlist": "That video isn't in this playlist any more — it changed somewhere else.",
     "same_playlist": "That video is already in this playlist."
diff --git a/frontend/src/i18n/locales/hu/playlists.json b/frontend/src/i18n/locales/hu/playlists.json
index a9bfe1f9..50d68821 100644
--- a/frontend/src/i18n/locales/hu/playlists.json
+++ b/frontend/src/i18n/locales/hu/playlists.json
@@ -77,6 +77,9 @@
   "movedToast": "„{{title}}” áthelyezve ide: „{{name}}” ✓",
   "moveFailed": "Nem sikerült áthelyezni a videót.",
   "removeFailed": "Nem sikerült eltávolítani a videót.",
+  "errors": {
+    "not_found": "Ez a lejátszási lista már nem létezik."
+  },
   "moveErrors": {
     "not_in_playlist": "Ez a videó már nincs ebben a listában — időközben máshol megváltozott.",
     "same_playlist": "Ez a videó már ebben a listában van."
diff --git a/frontend/src/lib/api/core.test.ts b/frontend/src/lib/api/core.test.ts
index 73e3b365..fee88f07 100644
--- a/frontend/src/lib/api/core.test.ts
+++ b/frontend/src/lib/api/core.test.ts
@@ -21,7 +21,7 @@ vi.mock("../activeAccount", () => ({
   notifyActiveAccountChange: vi.fn(),
 }));
 
-import { uploadReq, setUnauthorizedHandler, HttpError } from "./core";
+import { req, uploadReq, setUnauthorizedHandler, HttpError } from "./core";
 
 // A fake XHR whose lifecycle the test drives: capture the instance, set status/responseText, then
 // invoke onload/onerror/abort by hand.
@@ -117,3 +117,21 @@ describe("uploadReq", () => {
     expect(reportError).not.toHaveBeenCalled();
   });
 });
+
+describe("req — a structured refusal reads in the user's language", () => {
+  it("names a playlist that is gone instead of passing the server's English through", async () => {
+    // The 404 every playlist route answers when the list was deleted in another tab. It used to be a
+    // bare "Unknown playlist" string, shown verbatim under the Hungarian UI.
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: { code: "playlist", reason: "not_found" } }), {
+        status: 404,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    await expect(req("/api/playlists/7/items/v1", { method: "DELETE" })).rejects.toMatchObject({
+      status: 404,
+      detail: "playlists.errors.not_found",
+    });
+    expect(reportError).not.toHaveBeenCalled(); // a 404 is the caller's to report
+  });
+});
diff --git a/frontend/src/lib/api/core.ts b/frontend/src/lib/api/core.ts
index c507f67e..2847df40 100644
--- a/frontend/src/lib/api/core.ts
+++ b/frontend/src/lib/api/core.ts
@@ -82,6 +82,8 @@ function localizeDetail(d: unknown): string {
   // unknown reason falls back to the plain failure rather than printing a key.
   if (o?.code === "playlist_move")
     return t(`playlists.moveErrors.${o.reason}`, t("playlists.moveFailed"));
+  // Any playlist route whose list is gone (deleted in another tab) — or was never the caller's.
+  if (o?.code === "playlist") return t(`playlists.errors.${o.reason}`, t("errors.generic"));
   // SEC-14: a manual sync trigger on cooldown. Not an error the user caused so much as a pace
   // limit, and the copy says so.
   if (o?.code === "sync_cooldown") return t("errors.syncCooldown");

From d349bc90847e4ec01ee5a390c11198886898eebb Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:19:17 +0200
Subject: [PATCH 20/52] fix(plex): a collection's failed watched toggle is put
 back the way it was
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

C1 moved the optimistic flip onto the key the page reads — and so made visible that nothing corrects
it: the resync only invalidated `plex-library`, so a failed toggle stayed "watched" beside its own
error toast, and the collection's other cached sort orders stayed stale after a good one. The
resync now takes this page's `detail` prefix too, as the Discover and person pages do for theirs.
The C1 test holds the request open, so it still pins the optimistic write on its own.
---
 .../PlexCollectionView.dom.test.tsx           | 22 +++++++++++++++++--
 .../src/components/PlexCollectionView.tsx     |  9 +++++++-
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/frontend/src/components/PlexCollectionView.dom.test.tsx b/frontend/src/components/PlexCollectionView.dom.test.tsx
index bffa6610..b57763ec 100644
--- a/frontend/src/components/PlexCollectionView.dom.test.tsx
+++ b/frontend/src/components/PlexCollectionView.dom.test.tsx
@@ -38,7 +38,13 @@ vi.mock("../lib/notifications", async (importOriginal) => ({
 }));
 
 import PlexCollectionView from "./PlexCollectionView";
-import { api, type PlexCard, type PlexCollectionDetail, type PlexShowDetail } from "../lib/api";
+import {
+  api,
+  HttpError,
+  type PlexCard,
+  type PlexCollectionDetail,
+  type PlexShowDetail,
+} from "../lib/api";
 
 afterEach(() => {
   cleanup();
@@ -135,12 +141,24 @@ describe("PlexCollectionView — after the sort joined the query key", () => {
   it("flips a poster's watched state on the page it was clicked on", async () => {
     // The optimistic write kept the key's OLD spelling — an entry nothing reads — and the resync
     // only touches the library root, so the click did nothing visible until a reload.
-    vi.spyOn(api, "plexSetState").mockResolvedValue(undefined as never);
+    // The request never answers, so the resync never runs: only the optimistic write can flip it.
+    vi.spyOn(api, "plexSetState").mockReturnValue(new Promise(() => {}));
     mount([card("movie1", "movie")]);
     fireEvent.click(await screen.findByRole("button", { name: "plex.markWatched" }));
     expect(await screen.findByRole("button", { name: "plex.markUnwatched" })).toBeTruthy();
   });
 
+  it("puts a toggle that failed back the way it was", async () => {
+    // With the flip landing on the entry the page reads, the resync is what corrects it — and it only
+    // touched the library root, so a failed toggle stayed "watched" beside its own error toast.
+    vi.spyOn(api, "plexSetState").mockRejectedValue(new HttpError(422, "nope"));
+    mount([card("movie1", "movie")]);
+    fireEvent.click(await screen.findByRole("button", { name: "plex.markWatched" }));
+    await waitFor(() => expect(api.plexCollection).toHaveBeenCalledTimes(2));
+    expect(await screen.findByRole("button", { name: "plex.markWatched" })).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "plex.markUnwatched" })).toBeNull();
+  });
+
   it("keeps the page, and the open Sort panel, on screen while the new order loads", async () => {
     // Every sort change was a key with no data yet: the whole page — the control and its open panel
     // included — was swapped for a spinner, so key and direction could not be set in one visit.
diff --git a/frontend/src/components/PlexCollectionView.tsx b/frontend/src/components/PlexCollectionView.tsx
index bb901c06..02743cdc 100644
--- a/frontend/src/components/PlexCollectionView.tsx
+++ b/frontend/src/components/PlexCollectionView.tsx
@@ -165,7 +165,14 @@ export default function PlexCollectionView({
             : old,
         );
       },
-      resync: () => qc.invalidateQueries({ queryKey: qk.plexLibrary() }),
+      // This page's OWN key too, not just the library's: the flip above lands on the entry the page
+      // reads, and resync is what corrects it to the truth when the toggle fails — invalidating only
+      // `plex-library` left a failed toggle flipped on screen. The prefix (no sort in it) also
+      // refreshes the other sort orders of this collection cached behind this one.
+      resync: () => {
+        qc.invalidateQueries({ queryKey: qk.plexLibrary() });
+        qc.invalidateQueries({ queryKey: qk.plexCollections("detail", collectionId) });
+      },
     });
 
   async function doRename() {

From 0b4b26867816a8568ad6c1dc55dad5c7c0952e77 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:19:17 +0200
Subject: [PATCH 21/52] test(feed): pin the sort options' default directions as
 literals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The feedSortOptions test compared each option's default direction against SORT_DEFAULT_DIR — the
implementation's own table, so a wrong entry passed — and that import was the export's only user
outside its module, which kept knip from seeing it had become dead after F3. The test now states the
directions, the table is private again.
---
 frontend/src/lib/feedSort.ts         |  2 +-
 frontend/src/lib/feedSort.yt.test.ts | 20 ++++++++++----------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/frontend/src/lib/feedSort.ts b/frontend/src/lib/feedSort.ts
index 2257c8fc..745e6556 100644
--- a/frontend/src/lib/feedSort.ts
+++ b/frontend/src/lib/feedSort.ts
@@ -36,7 +36,7 @@ const SORT_MAP: Record<Exclude<SortKey, "shuffle" | "relevance">, { asc: string;
   priority: { desc: "priority", asc: "priority_asc" },
 };
 
-export const SORT_DEFAULT_DIR: Record<Exclude<SortKey, "shuffle" | "relevance">, "asc" | "desc"> = {
+const SORT_DEFAULT_DIR: Record<Exclude<SortKey, "shuffle" | "relevance">, "asc" | "desc"> = {
   date: "desc",
   popular: "desc",
   duration: "desc",
diff --git a/frontend/src/lib/feedSort.yt.test.ts b/frontend/src/lib/feedSort.yt.test.ts
index ca8c178e..2e76d4d2 100644
--- a/frontend/src/lib/feedSort.yt.test.ts
+++ b/frontend/src/lib/feedSort.yt.test.ts
@@ -1,11 +1,5 @@
 import { describe, it, expect } from "vitest";
-import {
-  feedSortOptions,
-  sortYtResults,
-  SORT_DEFAULT_DIR,
-  YT_SORT_KEYS,
-  SORT_KEYS,
-} from "./feedSort";
+import { feedSortOptions, sortYtResults, YT_SORT_KEYS, SORT_KEYS } from "./feedSort";
 import type { Video } from "./api";
 
 // The live-YouTube results view shipped with no sort control at all: the provider's order was the
@@ -122,11 +116,17 @@ describe("feedSortOptions", () => {
   // The library feed and the live results used to build their options from two copies of this
   // mapping; one helper means a key cannot get a different default direction in one of the modes.
   it("gives directional keys their default direction and marks shuffle/relevance directionless", () => {
-    const opts = feedSortOptions(["relevance", "date", "duration", "shuffle"], (k) => `label:${k}`);
+    // Literal directions, not the implementation's own table: comparing against that table let a
+    // wrong entry in it pass. Name is the one key that starts ascending.
+    const opts = feedSortOptions(
+      ["relevance", "date", "duration", "title", "shuffle"],
+      (k) => `label:${k}`,
+    );
     expect(opts.map((o) => [o.key, o.label, !!o.directionless, o.defaultDir])).toEqual([
       ["relevance", "label:relevance", true, undefined],
-      ["date", "label:date", false, SORT_DEFAULT_DIR.date],
-      ["duration", "label:duration", false, SORT_DEFAULT_DIR.duration],
+      ["date", "label:date", false, "desc"],
+      ["duration", "label:duration", false, "desc"],
+      ["title", "label:title", false, "asc"],
       ["shuffle", "label:shuffle", true, undefined],
     ]);
   });

From f7faa19ee26b7b5ba6c785d50787fc118ae7d155 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 03:47:36 +0200
Subject: [PATCH 22/52] fix(plex): the player starts, and resumes after a
 session-restart seek, when React mounts it twice
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The player's "still alive" flag — every play() is gated on it, so a late one cannot start a detached
<video> after Back — was only ever LOWERED, in an effect's cleanup. React may run a cleanup and mount
again (StrictMode does exactly that in development), and then the flag stayed false for the life of
the player: it never started by itself, and a seek back past the loaded region, which restarts the
session, left it paused. Found on localdev (Westworld S01E06: playing → seek back → the picture
settles, paused). Production does not double-mount, which is why only dev showed it — and why
several earlier localdev measurements "stayed paused".

The effect now raises the flag in its setup. A new test renders the real player under StrictMode and
checks it plays once the media is ready; red without the fix. Verified on localdev: it starts by
itself, and keeps playing through a backward session-restart seek.
---
 .../PlexPlayer.strictmode.dom.test.tsx        | 101 ++++++++++++++++++
 frontend/src/components/PlexPlayer.tsx        |   6 ++
 2 files changed, 107 insertions(+)
 create mode 100644 frontend/src/components/PlexPlayer.strictmode.dom.test.tsx

diff --git a/frontend/src/components/PlexPlayer.strictmode.dom.test.tsx b/frontend/src/components/PlexPlayer.strictmode.dom.test.tsx
new file mode 100644
index 00000000..149037b8
--- /dev/null
+++ b/frontend/src/components/PlexPlayer.strictmode.dom.test.tsx
@@ -0,0 +1,101 @@
+// @vitest-environment jsdom
+//
+// The Plex player must start playing by itself — also when React mounts it, unmounts it and mounts
+// it again, which StrictMode does to every component in development.
+//
+// Bug hunt 2026-09, found on localdev: the player's "still alive" flag (every play() is gated on it,
+// so a late one cannot start a detached <video> after Back) was only ever LOWERED, in an effect's
+// cleanup. StrictMode's dry-run unmount lowered it for good: the player never started on its own, and
+// a seek that restarts the session — back past the loaded region — left it paused. Production does
+// not double-mount, which is why only dev showed it.
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { StrictMode } from "react";
+import { render, cleanup, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+
+import PlexPlayer from "./PlexPlayer";
+import { api, type PlexItemDetail } from "../lib/api";
+
+const played: string[] = [];
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+  // jsdom has no media pipeline: record what the player asks of the element instead.
+  Object.defineProperty(HTMLMediaElement.prototype, "play", {
+    configurable: true,
+    value(this: HTMLMediaElement) {
+      played.push(this.getAttribute("src") ?? "");
+      return Promise.resolve();
+    },
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "pause", { configurable: true, value() {} });
+  Object.defineProperty(HTMLMediaElement.prototype, "load", { configurable: true, value() {} });
+  Object.defineProperty(HTMLMediaElement.prototype, "textTracks", {
+    configurable: true,
+    get: () => Object.assign([], { addEventListener() {}, removeEventListener() {} }),
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  played.length = 0;
+});
+
+const detail = {
+  id: "99079",
+  title: "The Adversary",
+  type: "episode",
+  duration_seconds: 3434,
+  status: "new",
+  position_seconds: 0,
+  audio_streams: [{ ord: 0, label: "English", language: "en", default: true }],
+  subtitle_streams: [],
+  markers: [],
+} as unknown as PlexItemDetail;
+
+describe("PlexPlayer under StrictMode", () => {
+  it("starts playing by itself once the media is ready", async () => {
+    vi.spyOn(api, "plexItem").mockResolvedValue(detail);
+    // A direct-play session: the element gets the file URL and plays on `loadedmetadata`. (hls.js is
+    // not supported under jsdom, so this is the path the test can drive; the HLS path gates its
+    // play() on the very same flag.)
+    vi.spyOn(api, "plexSession").mockResolvedValue({
+      mode: "direct",
+      url: "/api/plex/direct/99079",
+      start_s: 0,
+    } as never);
+    const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    render(
+      <StrictMode>
+        <QueryClientProvider client={qc}>
+          <PlexPlayer itemId="99079" onClose={() => {}} />
+        </QueryClientProvider>
+      </StrictMode>,
+    );
+    const video = await waitFor(() => {
+      const v = document.querySelector("video");
+      expect(v?.getAttribute("src")).toBe("/api/plex/direct/99079");
+      return v!;
+    });
+    video.dispatchEvent(new Event("loadedmetadata"));
+    await waitFor(() => expect(played).toContain("/api/plex/direct/99079"));
+  });
+});
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index 4d99f0bc..c6d5b564 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -428,7 +428,13 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
 
   // Full media teardown on unmount (Back): stop + detach the <video> and destroy hls, so a late
   // play() can't leave audio playing on a detached element after leaving the player.
+  //
+  // The setup half matters as much as the cleanup: React may run the cleanup and then MOUNT AGAIN
+  // (StrictMode does exactly that in development). With the flag only ever lowered, it stayed false
+  // for the life of the player — every play() is gated on it, so the player never started by itself,
+  // and a seek that restarts the session left it paused (bug hunt 2026-09, found on localdev).
   useEffect(() => {
+    aliveRef.current = true;
     return () => {
       aliveRef.current = false;
       if (hlsRef.current) {

From 4f37c41021b2929ff3f5e23b9712428dfa7ce83c Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:04:30 +0200
Subject: [PATCH 23/52] fix(plex): a subtitle failure about one position no
 longer ends the track, and windows are read ahead and never wait behind a
 full pass
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09.

- `failed` is now final only for a track that can never be text (bitmap, no item/track/file). A Plex
  hiccup or a stretch ffmpeg could not read answers `unavailable`: said, polled again every 5 s, and
  the <track> stays mounted when cues exist elsewhere (gen > 0). Re-picking the selected track asks
  the server again at once.
- Within LOOKAHEAD_S of a covered stretch's end the next window is read ahead, instead of only once
  the playhead has fallen off it (subtitles dropped out at every edge while the full pass was backed
  off or slower than a window lasts).
- Windows and full passes run on separate pools with separate in-flight caps, so a window never
  queues behind (or is refused by) minute-long full passes — the pool comment promised that and
  nothing enforced it.
- A pass that times out is TERMinated and keeps what it reached (published as partial) instead of
  being killed and discarded.
- Lapsed failure memos are swept on every write (they were only pruned when the same key was read
  again, so polling fresh keys grew the process without bound).
- `publish` no longer merges into a sidecar with no VTT behind it, or claims a region whose VTT write
  failed, or overwrites an unreadable track with one window.
- A NUL in a rating_key names no row (it was a DataError, a 500, on every Plex route) and no longer
  500s the status poll.

Tests: 16 new, each mutation-checked (18 mutations, all red on the test that names them).
---
 backend/app/plex/lookups.py                   |   7 +-
 backend/app/plex/subtitles.py                 | 158 ++++++---
 backend/tests/test_plex_subtitle_auth.py      |   3 +-
 backend/tests/test_plex_subtitle_prepare.py   | 305 +++++++++++++++---
 frontend/src/lib/api/plex.ts                  |   6 +-
 .../lib/plexPlayerHooks.subtitle.dom.test.tsx |  43 +++
 frontend/src/lib/plexPlayerHooks.ts           |  29 +-
 7 files changed, 453 insertions(+), 98 deletions(-)

diff --git a/backend/app/plex/lookups.py b/backend/app/plex/lookups.py
index a66b83d3..4d2e4987 100644
--- a/backend/app/plex/lookups.py
+++ b/backend/app/plex/lookups.py
@@ -11,5 +11,10 @@ _M = TypeVar("_M")
 def by_rating_key(db: Session, model: type[_M], rating_key: str) -> _M | None:
     """The mirrored row for a Plex rating_key, or None. `model` is any of the rating_key-keyed Plex
     tables (PlexItem / PlexShow / PlexSeason / PlexCollection); the return type is that model, so call
-    sites keep their `Model | None` static type."""
+    sites keep their `Model | None` static type.
+
+    A key with a NUL in it (`%00` in a path segment) names no row — and Postgres refuses NUL in text,
+    so asking would be a DataError, i.e. a 500, from every route that looks an item up."""
+    if "\x00" in str(rating_key):
+        return None
     return db.execute(select(model).where(model.rating_key == str(rating_key))).scalars().first()
diff --git a/backend/app/plex/subtitles.py b/backend/app/plex/subtitles.py
index bf659372..7948bb7b 100644
--- a/backend/app/plex/subtitles.py
+++ b/backend/app/plex/subtitles.py
@@ -166,14 +166,17 @@ def cache_read(key: str) -> str | None:
         return None
 
 
-def cache_write(key: str, vtt: str) -> None:
+def cache_write(key: str, vtt: str) -> bool:
+    """Atomically replace the cached VTT; False when it could not be written (`publish` must then
+    not claim the region it was carrying)."""
     try:
         CACHE_DIR.mkdir(parents=True, exist_ok=True)
         tmp = CACHE_DIR / f"{key}.vtt.tmp"
         tmp.write_text(vtt, encoding="utf-8")
         tmp.replace(CACHE_DIR / f"{key}.vtt")  # atomic publish
+        return True
     except OSError:
-        pass
+        return False
 
 
 # --- cache identity -----------------------------------------------------------------------------
@@ -222,7 +225,7 @@ def generation(key: str) -> int:
     window is superseded by a wider one the browser refetches instead of keeping the short VTT."""
     try:
         return _vtt_path(key).stat().st_mtime_ns
-    except OSError:
+    except (OSError, ValueError):  # ValueError: a NUL in the key — `stat` refuses the path outright
         return 0
 
 
@@ -312,14 +315,22 @@ def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) ->
     staging names safe."""
     with _PUBLISH_LOCK:
         old = cache_read(key)
+        if old is None and _vtt_path(key).exists():
+            # There, but unreadable (`cache_read` swallows the OSError). Merging into "" would replace
+            # a whole track with this one region while its sidecar still claimed all of it.
+            log.warning("subtitle cache %s unreadable; not publishing into it", key)
+            return
         old_ranges, was_complete = read_meta(key)
         if old is None:
-            # A VTT with no sidecar reads as a COMPLETE track (see read_meta — how older builds
-            # cached), and a publish is two renames. So before a key's first VTT lands, its sidecar
-            # already claims nothing: dying between the two then leaves a window that is extracted
-            # again, never one taken for the whole track for good.
-            _write_meta(key, old_ranges, False)
-        cache_write(key, merge_vtt(old or "", vtt))
+            # A sidecar with no VTT behind it claims cues that are not there, so it is not merged
+            # into. And a VTT with no sidecar reads as a COMPLETE track (see read_meta — how older
+            # builds cached), while a publish is two renames: so before a key's first VTT lands, its
+            # sidecar is made to claim nothing. Dying between the two then leaves a window that is
+            # extracted again, never one taken for the whole track for good.
+            old_ranges, was_complete = [], False
+            _write_meta(key, [], False)
+        if not cache_write(key, merge_vtt(old or "", vtt)):
+            return  # the region never landed, so the sidecar must not claim it
         _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
 
 
@@ -332,9 +343,16 @@ def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) ->
 # any realistic full pass.
 WINDOW_PRE_S = 30.0
 WINDOW_LEN_S = 300.0
+# …but it does not always land: a full pass can be backed off (FULL_RETRY_S) or simply slower than
+# the window lasts (a file past ~40 GB, or several passes sharing the array). A window was only asked
+# for once the playhead had LEFT coverage, so every edge unmounted the track for a poll plus an
+# extraction. Within this distance of a covered stretch's end, the next window is read ahead.
+LOOKAHEAD_S = 60.0
 # Ceiling on one ffmpeg run so a wedged extraction can't hold a pool thread forever (the old
 # in-request extraction had no timeout at all).
 EXTRACT_TIMEOUT_S = 900.0
+# How long a timed-out ffmpeg gets, after a TERM, to close its outputs before it is killed.
+_TERM_GRACE_S = 10.0
 # A failed track (or window) is remembered briefly so a 1 s status poll doesn't respawn ffmpeg every
 # second, and forgotten again soon after so fixing the file (or Plex coming back) doesn't need a
 # restart.
@@ -347,14 +365,20 @@ FULL_RETRY_S = 3600.0
 # The furthest position the status poll accepts. No film is this long, and an absurd one used to
 # reach ffmpeg's `-ss` (which rejects anything past its int64 microseconds).
 MAX_POSITION_S = 100_000.0
-# Two items' full passes plus a window for a third: enough that a seek into an un-extracted region is
-# served while a full pass runs, bounded so a burst can't thrash the array.
-_POOL = ThreadPoolExecutor(max_workers=3, thread_name_prefix="plex-subs")
-# Bounds on what may wait for that pool. Its queue is unbounded and every job is a read of the
-# library: a viewer scrubbing through a film queued a window per stop (the one where they stopped ran
-# LAST), and a script could queue thousands. Past either bound nothing is queued — the next poll asks
-# again, by which time something has finished.
-_MAX_INFLIGHT = 12
+# Windows and full passes run on SEPARATE pools, so a window never waits behind a full pass. They
+# shared one FIFO pool of three whose comment promised "room for a window" that nothing enforced:
+# stepping through three episodes with subtitles on left three full passes (minutes each) holding every
+# worker, and a seek window on the third queued behind them. Two of each: bounded, so a burst can't
+# thrash the array.
+_WIN_POOL = ThreadPoolExecutor(max_workers=2, thread_name_prefix="plex-subs-win")
+_FULL_POOL = ThreadPoolExecutor(max_workers=2, thread_name_prefix="plex-subs-full")
+# Bounds on what may wait for those pools — separate too, so held full-pass slots (minutes each)
+# cannot refuse a window (seconds). The queues are unbounded and every job is a read of the library:
+# a viewer scrubbing through a film queued a window per stop (the one where they stopped ran LAST),
+# and a script could queue thousands. Past a bound nothing is queued — the next poll asks again, by
+# which time something has finished.
+_MAX_WINDOWS_INFLIGHT = 8
+_MAX_FULL_INFLIGHT = 6
 _MAX_TRACK_WINDOWS = 2
 
 _LOCK = threading.Lock()
@@ -396,6 +420,12 @@ UNAVAILABLE_STATUS = {
     "extract_failed": 422,
     "plex_error": 422,
 }
+# The codes that are a FINAL answer about the track: it can never be served as text, so the player
+# stops asking. The others (`plex_error`, `extract_failed`) are about now or about one stretch — a
+# memo that lapses, a window that failed where the rest is fine — and answered as `unavailable`: said,
+# but asked again. Given as `failed`, one Plex hiccup ended the subtitles for the rest of the session,
+# at cached positions too, and after the full pass had completed behind it.
+FINAL_CODES = frozenset({"no_item", "no_track", "no_file", "not_fetchable", "bitmap"})
 
 
 def reset_state() -> None:
@@ -421,13 +451,28 @@ def shutdown() -> None:
     with _LOCK:
         _STOPPING = True
         procs = list(_PROCS)
-    _POOL.shutdown(wait=False, cancel_futures=True)
+    for pool in (_WIN_POOL, _FULL_POOL):
+        pool.shutdown(wait=False, cancel_futures=True)
     for p in procs:
         p.kill()
 
 
+def _sweep_memos() -> None:
+    """(Caller holds _LOCK.) Drop every lapsed failure memo. They were only ever pruned when the SAME
+    key was read again, and the status route takes any rating_key/ordinal — so a script polling fresh
+    keys grew the API process without bound. Swept on every write, they hold at most a TTL's worth."""
+    now = time.monotonic()
+    for k in [k for k, (_, t) in _FAILURES.items() if now - t >= FAIL_TTL_S]:
+        del _FAILURES[k]
+    for k in [k for k, t in _FULL_FAILED.items() if now - t >= FULL_RETRY_S]:
+        del _FULL_FAILED[k]
+    for k in list(_WIN_FAILED):
+        _live_window_failures(k)
+
+
 def _fail(key: str, code: str) -> None:
     with _LOCK:
+        _sweep_memos()
         _FAILURES[key] = (code, time.monotonic())
 
 
@@ -462,6 +507,7 @@ def _live_window_failures(key: str) -> list[tuple[float, float, float]]:
 
 def _window_fail(key: str, span: tuple[float, float]) -> None:
     with _LOCK:
+        _sweep_memos()
         _WIN_FAILED[key] = [*_live_window_failures(key), (span[0], span[1], time.monotonic())]
 
 
@@ -474,33 +520,41 @@ def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
     """State of one subtitle track, scheduling whatever extraction is still missing. NEVER blocks.
 
     ``ready`` = fully extracted · ``partial`` = usable, covers ``at``, still growing · ``preparing``
-    = nothing to show for ``at`` yet · ``failed`` = ``code`` says why. ``gen`` changes whenever the
-    cached file grows, so the client can refetch a window that has been superseded."""
+    = nothing to show for ``at`` yet · ``unavailable`` = nothing for ``at`` and nothing being read
+    for it right now (``code`` says why), ask again · ``failed`` = the track can never be shown
+    (``code`` says why) — the only final answer. ``gen`` changes whenever the cached file grows, so
+    the client can refetch a window that has been superseded; 0 = nothing is cached at all."""
     key = cache_key(rating_key, sub_ord)
     ranges, complete = read_meta(key)
     have = cache_read(key) is not None
     covered = have and covers(ranges, at)
+    gen = generation(key)
     if complete and have:
-        return {"state": "ready", "code": None, "gen": generation(key)}
+        return {"state": "ready", "code": None, "gen": gen}
     code = _recent_failure(key)
     if code and not covered:
-        return {"state": "failed", "code": code, "gen": generation(key)}
-    # "Failed" is a FINAL answer — the player stops asking — so for an ffmpeg failure it is given only
-    # once nothing is left that could still cover the position: the full pass failed, AND so did a
-    # window here.
+        return {
+            "state": "failed" if code in FINAL_CODES else "unavailable",
+            "code": code,
+            "gen": gen,
+        }
+    # Nothing left that could cover the position for now: the full pass failed, AND so did a window
+    # here. Still not final — the memos lapse, and the rest of the track may be right there.
     full_failed = _full_failed(rating_key)
     window_failed = not covered and _window_failed(key, at)
     if full_failed and window_failed:
-        return {"state": "failed", "code": "extract_failed", "gen": generation(key)}
+        return {"state": "unavailable", "code": "extract_failed", "gen": gen}
     if not code:
-        _schedule(
-            rating_key,
-            sub_ord,
-            at,
-            want_window=not covered and not window_failed,
-            want_full=not full_failed,
-        )
-    return {"state": "partial" if covered else "preparing", "code": None, "gen": generation(key)}
+        probe, want_window = at, not covered and not window_failed
+        if covered:
+            # Read ahead of an edge instead of waiting to fall off it (see LOOKAHEAD_S). The probe is
+            # just PAST the edge: `covers` is inclusive, so the edge itself reads as already done.
+            edge = max(b for a, b in ranges if a <= at <= b)
+            if edge - at <= LOOKAHEAD_S and edge < _FULL_END_S:
+                probe = edge + 1.0
+                want_window = not _window_failed(key, probe)
+        _schedule(rating_key, sub_ord, probe, want_window=want_window, want_full=not full_failed)
+    return {"state": "partial" if covered else "preparing", "code": None, "gen": gen}
 
 
 def cached_track(rating_key: str, sub_ord: int) -> tuple[str | None, str | None]:
@@ -532,9 +586,11 @@ def _schedule(
     full pass is per ITEM, because one read fans out to every embedded text track of the file."""
     jobs: list[tuple[tuple, float | None]] = []
     with _LOCK:
-        if _STOPPING or len(_INFLIGHT) >= _MAX_INFLIGHT:
+        if _STOPPING:
             return
-        if want_window:
+        n_windows = sum(1 for span in _INFLIGHT.values() if span is not None)
+        n_full = len(_INFLIGHT) - n_windows
+        if want_window and n_windows < _MAX_WINDOWS_INFLIGHT:
             spans = [
                 span
                 for ident, span in _INFLIGHT.items()
@@ -548,11 +604,12 @@ def _schedule(
                 ident = ("win", rating_key, sub_ord, w_start)
                 _INFLIGHT[ident] = (w_start, w_start + WINDOW_PRE_S + WINDOW_LEN_S)
                 jobs.append((ident, w_start))
-        if want_full and ("full", rating_key) not in _INFLIGHT:
+        if want_full and n_full < _MAX_FULL_INFLIGHT and ("full", rating_key) not in _INFLIGHT:
             _INFLIGHT[("full", rating_key)] = None
             jobs.append((("full", rating_key), None))
     for ident, window_start in jobs:
-        _POOL.submit(_run, ident, rating_key, sub_ord, window_start, at)
+        pool = _FULL_POOL if window_start is None else _WIN_POOL
+        pool.submit(_run, ident, rating_key, sub_ord, window_start, at)
 
 
 def _already_done(key: str, window_start: float | None, at: float) -> bool:
@@ -601,6 +658,7 @@ def _pass_failed(
     window marks only the stretch it failed to read, for the tracks it was reading."""
     if window_start is None:
         with _LOCK:
+            _sweep_memos()
             _FULL_FAILED[rating_key] = time.monotonic()
         return
     for key in keys:
@@ -731,13 +789,23 @@ def _ffmpeg_extract(
             _PROCS.add(proc)
             if _STOPPING:
                 proc.kill()
+        timed_out = False
         try:
             try:
                 _, err = proc.communicate(timeout=EXTRACT_TIMEOUT_S)
             except subprocess.TimeoutExpired:
-                proc.kill()
-                proc.communicate()
-                raise
+                # A pass that ran out of time is a pass that died partway: what it reached is kept and
+                # published as partial (the caller's unclean path), like any other non-zero exit. It
+                # used to be killed and its outputs deleted unread — and with the full-pass backoff, the
+                # same doomed read came back every hour. TERM first: ffmpeg closes its outputs on it,
+                # whereas a KILL leaves only what was already flushed in whole blocks (measured: none).
+                timed_out = True
+                proc.terminate()
+                try:
+                    _, err = proc.communicate(timeout=_TERM_GRACE_S)
+                except subprocess.TimeoutExpired:
+                    proc.kill()
+                    _, err = proc.communicate()
         finally:
             with _LOCK:
                 _PROCS.discard(proc)
@@ -748,7 +816,11 @@ def _ffmpeg_extract(
         }
     if not got:
         raise SubtitleUnavailable("extract_failed")
-    clean = proc.returncode == 0
+    clean = proc.returncode == 0 and not timed_out
     if not clean:
-        log.warning("ffmpeg subtitle pass exited %s: %s", proc.returncode, (err or b"")[:200])
+        log.warning(
+            "ffmpeg subtitle pass %s: %s",
+            "timed out" if timed_out else f"exited {proc.returncode}",
+            (err or b"")[:200],
+        )
     return got, clean
diff --git a/backend/tests/test_plex_subtitle_auth.py b/backend/tests/test_plex_subtitle_auth.py
index 0ddb5ee8..a4f6b2fe 100644
--- a/backend/tests/test_plex_subtitle_auth.py
+++ b/backend/tests/test_plex_subtitle_auth.py
@@ -35,7 +35,8 @@ def test_a_suspended_account_cannot_drive_the_subtitle_extractor(
         monkeypatch.setattr(mod, "resolved_user_id", lambda request: (user.id, True))
     monkeypatch.setattr(subtitles, "CACHE_DIR", tmp_path)
     pool = _NoPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    monkeypatch.setattr(subtitles, "_WIN_POOL", pool)
+    monkeypatch.setattr(subtitles, "_FULL_POOL", pool)
     subtitles.reset_state()
 
     client = TestClient(app)
diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
index 52a3385d..0cd0c9b4 100644
--- a/backend/tests/test_plex_subtitle_prepare.py
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -14,8 +14,11 @@ These tests pin the three things that fixes it: the request never waits for ffmp
 publishes a window around the playhead before the whole track, and one ffmpeg run covers every
 embedded text track — plus what the deep-review of that fix found (cues doubled at the window/full
 seam, a truncated pass cached as complete, a poll that respawned ffmpeg every second, a sidecar stuck
-behind an unrelated pass). Pure — no Postgres, no ffmpeg (the auth half is in
-test_plex_subtitle_auth.py, which needs the DB).
+behind an unrelated pass). No Postgres (the auth half is in test_plex_subtitle_auth.py, which needs
+the DB). Almost every test stubs ffmpeg out, but not all: a few run a real child process, and
+`test_a_window_lines_up_with_the_full_pass_on_a_real_file` needs the real ffmpeg — it is the only
+guard of `-avoid_negative_ts disabled`. It skips without one, except in the gate's DB lane, where
+conftest refuses to run without ffmpeg rather than let it skip.
 """
 
 import asyncio
@@ -77,6 +80,24 @@ class _ManualPool:
             fn(*args)
         return len(jobs)
 
+    def shutdown(self, wait=True, cancel_futures=False) -> None:
+        pass  # jobs still run only when the test says so — which is what the shutdown tests probe
+
+
+def _manual_pool(monkeypatch) -> _ManualPool:
+    """One manual pool standing in for BOTH extraction pools, so a test sees every job in the order
+    it was submitted (window or full pass — `window_start` tells them apart)."""
+    pool = _ManualPool()
+    monkeypatch.setattr(subtitles, "_WIN_POOL", pool)
+    monkeypatch.setattr(subtitles, "_FULL_POOL", pool)
+    return pool
+
+
+def _real_pools(monkeypatch) -> None:
+    """Fresh single-worker pools (the module's own may have been shut down by an earlier test)."""
+    monkeypatch.setattr(subtitles, "_WIN_POOL", ThreadPoolExecutor(max_workers=1))
+    monkeypatch.setattr(subtitles, "_FULL_POOL", ThreadPoolExecutor(max_workers=1))
+
 
 def _cue(start: str, end: str, text: str) -> str:
     return f"{start} --> {end}\n{text}"
@@ -120,8 +141,7 @@ def test_a_cold_track_answers_at_once_instead_of_waiting_for_ffmpeg(client, monk
 def test_a_burst_of_polls_starts_one_window_and_one_full_pass(monkeypatch):
     """The player polls once a second while it waits. Each poll must JOIN the running jobs, not
     start another ffmpeg over the same 17 GB."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     for _ in range(5):
         subtitles.ensure("98614", 0, at=600.0)
     assert len(pool.jobs) == 2  # one window (at 600 s) + the one full pass
@@ -135,8 +155,7 @@ def test_a_burst_of_polls_starts_one_window_and_one_full_pass(monkeypatch):
 def test_status_walks_preparing_to_partial_to_ready(client, monkeypatch):
     """A window around the playhead makes the track showable long before it is complete, and the
     generation changes when it grows so the browser refetches instead of keeping the short VTT."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     key = subtitles.cache_key("98614", 0)
 
     def _publish(rating_key, sub_ord, window_start):
@@ -170,8 +189,7 @@ def test_status_walks_preparing_to_partial_to_ready(client, monkeypatch):
 def test_a_position_outside_the_extracted_window_is_not_called_showable(client, monkeypatch):
     """Honest states: cues exist, but none for where the viewer just seeked to. Saying "ready" there
     would put an empty track on screen with no explanation — the original complaint."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    _manual_pool(monkeypatch)
     subtitles.publish(
         subtitles.cache_key("98614", 0),
         _vtt(_cue("00:10.000", "00:12.000", "x")),
@@ -183,8 +201,7 @@ def test_a_position_outside_the_extracted_window_is_not_called_showable(client,
 
 
 def test_an_unshowable_track_says_why_and_maps_to_a_status(client, monkeypatch):
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
 
     def _bitmap(rating_key, sub_ord, window_start):
         raise subtitles.SubtitleUnavailable("bitmap")
@@ -379,10 +396,9 @@ def test_a_full_pass_that_died_is_not_cached_as_the_whole_track(monkeypatch):
     """A truncated full pass used to be published as complete: `ensure` answered "ready" forever, the
     player stopped polling, and — the cache has no eviction — the subtitles simply ended wherever
     ffmpeg had died, in every later session too. Now it covers what it provably reached; past that
-    a window is tried, and only when that fails too is the position answered as failed."""
+    a window is tried, and only when that fails too is the position answered as unavailable."""
     _stub_item(monkeypatch, clean=False, cues=("39:58.000", "40:00.000"))
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     subtitles._extract_and_publish("98614", 3, None)
     key = subtitles.cache_key("98614", 3)
     assert subtitles.read_meta(key) == ([[0.0, 2400.0]], False)
@@ -392,14 +408,13 @@ def test_a_full_pass_that_died_is_not_cached_as_the_whole_track(monkeypatch):
     _window_raises(monkeypatch)
     pool.run_all()
     after = subtitles.ensure("98614", 3, at=3000.0)
-    assert (after["state"], after["code"]) == ("failed", "extract_failed")
+    assert (after["state"], after["code"]) == ("unavailable", "extract_failed")
 
 
 def test_polls_that_follow_the_playhead_join_one_window(monkeypatch):
     """The poll sends the LIVE position, so it moves a second per poll. A window keyed on that
     position was a new job every second — another read of the file per poll until the first landed."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     for at in (600.0, 601.0, 602.0, 603.0, 604.0):
         subtitles.ensure("98614", 1, at=at)
     assert len(pool.jobs) == 2, "one window + the one full pass"
@@ -409,8 +424,7 @@ def test_a_window_for_a_different_stretch_does_not_wait_behind_the_first(monkeyp
     """Measured on localdev: after a resume the first poll can still report 0 (the position is only
     known once playback ticks), so the first window is cut around the wrong spot. The poll that
     follows, at the real position, must get its own window at once — not queue behind that one."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     subtitles.ensure("98614", 1, at=0.0)
     subtitles.ensure("98614", 1, at=1198.0)
     assert sorted(a[3] for _, a in pool.jobs if a[3] is not None) == [0.0, 1168.0]
@@ -419,8 +433,7 @@ def test_a_window_for_a_different_stretch_does_not_wait_behind_the_first(monkeyp
 def test_a_queued_window_that_was_covered_meanwhile_reads_nothing(monkeypatch):
     """Every embedded track rides each pass over its file, so by the time a queued window for one
     language runs, another language's window may already have published it."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     calls = _stub_item(monkeypatch)
     subtitles.ensure("98614", 3, at=600.0)
     subtitles.publish(
@@ -437,8 +450,7 @@ def test_a_sidecar_does_not_wait_behind_an_embedded_full_pass(monkeypatch):
     """The full pass is one job per ITEM (the embedded fan-out shares it). A sidecar picked while an
     embedded track's pass was running used to find that identity taken and wait out the whole read —
     minutes — for a track that is one small fetch."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     _stub_item(monkeypatch)
     subtitles._INFLIGHT[("full", "98614")] = None  # an embedded track's full pass is running
     subtitles.ensure("98614", 0, at=600.0)
@@ -494,7 +506,7 @@ def test_shutdown_kills_a_running_extraction(monkeypatch):
         "Popen",
         lambda cmd, **kw: real_popen([sys.executable, "-c", "import time; time.sleep(60)"], **kw),
     )
-    monkeypatch.setattr(subtitles, "_POOL", ThreadPoolExecutor(max_workers=1))
+    _real_pools(monkeypatch)
     finished = threading.Event()
 
     def _extract():
@@ -519,8 +531,7 @@ def test_the_track_fetch_serves_what_is_cached_and_schedules_nothing(client, mon
     readiness at position 0. A viewer resumed an hour in got an unrequested extraction over the head
     of the file, and with a failure memo alive the fetch refused a window that WAS on disk while the
     status poll (which knows the position) called the track showable: silently blank subtitles."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     assert client.get("/api/plex/subtitle/98614/0").status_code == 202
     assert pool.jobs == [], "the fetch scheduled an extraction"
     key = subtitles.cache_key("98614", 0)
@@ -534,8 +545,7 @@ def test_the_track_fetch_serves_what_is_cached_and_schedules_nothing(client, mon
 @pytest.mark.parametrize("at", ["inf", "-1", "nan"])
 def test_an_impossible_position_is_rejected(client, monkeypatch, at):
     """`?at=inf` reached the scheduler's arithmetic and came back as a 500 with a traceback."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     assert client.get(f"/api/plex/subtitle/98614/0/status?at={at}").status_code == 422
     assert pool.jobs == []
 
@@ -549,8 +559,7 @@ def test_an_impossible_offset_is_rejected(client, q):
 def test_an_absurd_position_is_rejected_before_it_reaches_ffmpeg(client, monkeypatch):
     """ffmpeg refuses an `-ss` past its int64 microseconds, and that failure was recorded against the
     TRACK — every other viewer at an uncovered position was told "failed" for a minute."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     assert client.get("/api/plex/subtitle/98614/0/status?at=1e13").status_code == 422
     assert pool.jobs == []
 
@@ -582,8 +591,7 @@ def test_a_full_pass_that_failed_is_not_read_again_while_its_output_is_watched(m
     re-armed a read of the whole container. A failure that reproduces did so every time: a full
     read of the file every few minutes for as long as they watched."""
     _stub_item(monkeypatch, clean=False, cues=("39:58.000", "40:00.000"))
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     subtitles._extract_and_publish("98614", 3, None)
     _later(monkeypatch, subtitles.FAIL_TTL_S + 1)
     for _ in range(3):
@@ -595,8 +603,7 @@ def test_a_failed_window_does_not_end_the_poll_while_the_full_pass_may_cover_it(
     """ "failed" is final — the player stops asking. A window that failed used to set the TRACK's
     failure memo, so a viewer anywhere outside the covered part got "failed" and never heard about
     the full pass that landed a minute later."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     _stub_item(monkeypatch)
     _window_raises(monkeypatch)
     subtitles.ensure("98614", 3, at=3000.0)
@@ -609,8 +616,7 @@ def test_a_failed_window_does_not_end_the_poll_while_the_full_pass_may_cover_it(
 def test_a_backward_seek_gets_its_own_window(monkeypatch):
     """A window bucketed by position joined a seek back to 6:40 onto a running window at 9:10 that
     could not cover it — the right one waited for the wrong one."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     subtitles.ensure("98614", 1, at=580.0)
     subtitles.ensure("98614", 1, at=400.0)
     assert sorted(a[3] for _, a in pool.jobs if a[3] is not None) == [370.0, 550.0]
@@ -619,8 +625,7 @@ def test_a_backward_seek_gets_its_own_window(monkeypatch):
 def test_a_playhead_crossing_a_bucket_edge_joins_the_window_that_covers_it(monkeypatch):
     """…and the same bucketing queued a second read when a playhead crossed an edge while the first
     window — which already covered it — was still running."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     for at in (628.0, 629.0, 630.0, 631.0, 632.0):
         subtitles.ensure("98614", 1, at=at)
     assert len(pool.jobs) == 2, "one window + the one full pass"
@@ -628,27 +633,26 @@ def test_a_playhead_crossing_a_bucket_edge_joins_the_window_that_covers_it(monke
 
 def test_a_scrubbing_viewer_cannot_queue_a_window_per_stop(monkeypatch):
     """The pool's queue is unbounded and every job is a read of the library."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     for at in (0.0, 1000.0, 2000.0, 3000.0, 4000.0):
         subtitles.ensure("98614", 1, at=at)
     assert len([1 for _, a in pool.jobs if a[3] is not None]) == subtitles._MAX_TRACK_WINDOWS
 
 
 def test_nothing_more_is_queued_while_the_extractor_is_saturated(monkeypatch):
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     for rk in range(20):
         subtitles.ensure(str(rk), 0, at=0.0)
-    assert len(pool.jobs) == subtitles._MAX_INFLIGHT
+    windows = [a for _, a in pool.jobs if a[3] is not None]
+    assert len(windows) == subtitles._MAX_WINDOWS_INFLIGHT
+    assert len(pool.jobs) - len(windows) == subtitles._MAX_FULL_INFLIGHT
 
 
 def test_a_window_starts_where_ffmpeg_is_told_to_seek(monkeypatch):
     """ffmpeg gets `-ss` to the millisecond, and its cues come back on THAT zero. Shifted back by an
     unrounded start they landed up to half a millisecond off the full pass's — spelled differently,
     and so kept twice by the merge."""
-    pool = _ManualPool()
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    pool = _manual_pool(monkeypatch)
     subtitles.ensure("98614", 1, at=1198.4375)
     (window_start,) = [a[3] for _, a in pool.jobs if a[3] is not None]
     assert window_start == 1168.438
@@ -690,7 +694,8 @@ def test_shutdown_drops_queued_extractions(monkeypatch):
     """Only the kill half used to be pinned. A job still QUEUED at shutdown would otherwise start
     after the kill sweep — a fresh read of the file holding the process open."""
     pool = ThreadPoolExecutor(max_workers=1)
-    monkeypatch.setattr(subtitles, "_POOL", pool)
+    monkeypatch.setattr(subtitles, "_WIN_POOL", pool)
+    monkeypatch.setattr(subtitles, "_FULL_POOL", pool)
     busy, release, ran = threading.Event(), threading.Event(), threading.Event()
     pool.submit(lambda: (busy.set(), release.wait(timeout=5)))
     pool.submit(ran.set)
@@ -703,7 +708,7 @@ def test_shutdown_drops_queued_extractions(monkeypatch):
 
 def test_a_worker_that_reaches_ffmpeg_after_shutdown_never_starts_it(monkeypatch):
     """A worker still in its Plex lookup when the kill sweep ran used to start its ffmpeg anyway."""
-    monkeypatch.setattr(subtitles, "_POOL", ThreadPoolExecutor(max_workers=1))
+    _real_pools(monkeypatch)
     started: list = []
     monkeypatch.setattr(subtitles.subprocess, "Popen", lambda cmd, **kw: started.append(cmd))
     subtitles.shutdown()
@@ -789,3 +794,211 @@ def test_a_window_lines_up_with_the_full_pass_on_a_real_file(tmp_path, monkeypat
     subtitles.publish(key, full[0], (0.0, subtitles._FULL_END_S), True)
     merged = subtitles.cache_read(key) or ""
     assert merged.count("-->") == 30, "a window cue survived beside its full-pass twin"
+
+
+# --- the third deep-review round ----------------------------------------------------------------
+
+
+def test_a_transient_failure_is_said_but_is_not_a_final_answer(monkeypatch):
+    """`failed` ends the player's poll and unmounts the track. A Plex hiccup memo (a minute) was given
+    as `failed`, so one blip ended the subtitles for the rest of the session — at cached positions
+    too, and after the full pass had completed behind it. It is `unavailable` now: said, asked again."""
+    pool = _manual_pool(monkeypatch)
+    key = subtitles.cache_key("98614", 0)
+    subtitles.publish(key, _vtt(_cue("01:40.000", "01:42.000", "x")), (70.0, 400.0), False)
+    subtitles._fail(key, "plex_error")
+    here = subtitles.ensure("98614", 0, at=3000.0)
+    assert (here["state"], here["code"]) == ("unavailable", "plex_error")
+    assert here["gen"] > 0, "the client needs to know there are cues elsewhere to keep showing"
+    assert subtitles.ensure("98614", 0, at=100.0)["state"] == "partial"
+    assert pool.jobs == [], "nothing is re-read while the memo is alive"
+    _later(monkeypatch, subtitles.FAIL_TTL_S + 1)
+    assert subtitles.ensure("98614", 0, at=3000.0)["state"] == "preparing"
+    assert [a[3] for _, a in pool.jobs] == [2970.0, None], "asked again once the memo lapsed"
+
+
+def test_the_next_window_is_read_ahead_of_its_edge(monkeypatch):
+    """With the full pass backed off (or slower than a window lasts) a window was only asked for once
+    the playhead had LEFT coverage — the track unmounted at every edge for a poll plus a read."""
+    pool = _manual_pool(monkeypatch)
+    subtitles._FULL_FAILED["98614"] = time.monotonic()
+    key = subtitles.cache_key("98614", 0)
+    subtitles.publish(key, _vtt(_cue("16:20.000", "16:22.000", "x")), (970.0, 1300.0), False)
+    assert subtitles.ensure("98614", 0, at=1200.0)["state"] == "partial"
+    assert pool.jobs == [], "far from the edge: nothing to read yet"
+    assert subtitles.ensure("98614", 0, at=1250.0)["state"] == "partial"
+    assert [a[3] for _, a in pool.jobs] == [1271.0], "the next window, before the edge is reached"
+
+
+def test_a_window_that_died_partway_marks_the_stretch_it_did_not_reach(monkeypatch):
+    """Without the span memo, a window that died before the playhead left it uncovered AND not
+    failed — so every poll queued the same read of the library again."""
+    _stub_item(monkeypatch, clean=False, cues=("00:10.000", "00:12.000"))
+    pool = _manual_pool(monkeypatch)
+    subtitles._extract_and_publish("98614", 3, 3570.0)
+    key = subtitles.cache_key("98614", 3)
+    assert subtitles.read_meta(key) == ([[3570.0, 3582.0]], False)
+    assert subtitles.ensure("98614", 3, at=3700.0)["state"] == "preparing"
+    assert [a[3] for _, a in pool.jobs] == [None], "the dead stretch was queued again"
+
+
+def test_a_crashed_pass_is_recorded_like_a_failed_one(monkeypatch):
+    """A timeout or a crash lands in `_run`'s catch-all. Recorded against the TRACK, a crashed window
+    told every viewer at any uncovered position "failed", and a crashed full pass re-armed a
+    whole-file read every minute instead of backing off."""
+
+    def _crash(rating_key, sub_ord, window_start):
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(subtitles, "_extract_and_publish", _crash)
+    key = subtitles.cache_key("98614", 3)
+    subtitles._run(("win", "98614", 3, 570.0), "98614", 3, 570.0, 600.0)
+    assert subtitles._window_failed(key, 600.0) and not subtitles._window_failed(key, 3000.0)
+    subtitles._run(("full", "98614"), "98614", 3, None, 600.0)
+    assert subtitles._full_failed("98614")
+    assert subtitles._recent_failure(key) is None, "a crash is not a verdict on the whole track"
+
+
+def test_the_failure_memos_lapse(monkeypatch):
+    """Both memos exist to stop a re-read, not to forbid one: permanent, a transient failure would
+    have held until the process restarted."""
+    pool = _manual_pool(monkeypatch)
+    key = subtitles.cache_key("98614", 3)
+    subtitles._pass_failed("98614", [key], None)
+    subtitles._pass_failed("98614", [key], 570.0)
+    assert subtitles.ensure("98614", 3, at=600.0)["state"] == "unavailable"
+    _later(monkeypatch, subtitles.FAIL_TTL_S + 1)
+    subtitles.ensure("98614", 3, at=600.0)
+    assert [a[3] for _, a in pool.jobs] == [570.0], "the window memo lapsed; the full one has not"
+    pool.jobs.clear()
+    subtitles._INFLIGHT.clear()
+    _later(monkeypatch, subtitles.FULL_RETRY_S + 1)
+    subtitles.ensure("98614", 3, at=600.0)
+    assert None in [a[3] for _, a in pool.jobs], "the full pass was never tried again"
+
+
+def test_lapsed_memos_are_swept_not_kept_forever(monkeypatch):
+    """They were pruned only when the SAME key was read again, and the status route takes any key:
+    polling fresh ones grew the API process without bound."""
+    for i in range(50):
+        subtitles._fail(f"sub_x{i}_0", "no_item")
+        subtitles._pass_failed(f"x{i}", [f"sub_x{i}_0"], None)
+        subtitles._pass_failed(f"x{i}", [f"sub_x{i}_0"], 0.0)
+    _later(monkeypatch, subtitles.FULL_RETRY_S + 1)
+    subtitles._fail("sub_y_0", "no_item")
+    assert list(subtitles._FAILURES) == ["sub_y_0"]
+    assert subtitles._FULL_FAILED == {} and subtitles._WIN_FAILED == {}
+
+
+def test_a_window_is_not_refused_while_full_passes_hold_their_slots(monkeypatch):
+    """One pool and one cap for both kinds of job: full passes (minutes each) held every worker and
+    every slot, and a seek window — seconds of work — waited behind them or was not queued at all."""
+    win, full = _ManualPool(), _ManualPool()
+    monkeypatch.setattr(subtitles, "_WIN_POOL", win)
+    monkeypatch.setattr(subtitles, "_FULL_POOL", full)
+    for rk in range(subtitles._MAX_FULL_INFLIGHT):
+        subtitles._INFLIGHT[("full", str(rk))] = None
+    subtitles.ensure("98614", 1, at=600.0)
+    assert [a[3] for _, a in win.jobs] == [570.0]
+    assert full.jobs == [], "past its bound no full pass is queued"
+
+
+def test_a_poll_after_shutdown_queues_nothing(monkeypatch):
+    pool = _manual_pool(monkeypatch)
+    subtitles.shutdown()
+    subtitles.ensure("98614", 1, at=600.0)
+    assert pool.jobs == []
+
+
+def test_a_job_dequeued_after_shutdown_reads_nothing(monkeypatch):
+    pool = _manual_pool(monkeypatch)
+    ran: list = []
+    monkeypatch.setattr(subtitles, "_extract_and_publish", lambda *a: ran.append(a))
+    subtitles.ensure("98614", 1, at=600.0)
+    subtitles.shutdown()
+    pool.run_all()
+    assert ran == []
+
+
+def test_a_child_started_while_the_shutdown_sweep_runs_is_killed(monkeypatch):
+    """The sweep can run between the pre-Popen check and the child's registration."""
+    killed: list = []
+
+    class _Child:
+        returncode = -9
+
+        def kill(self):
+            killed.append(True)
+
+        def communicate(self, timeout=None):
+            return b"", b""
+
+    def _popen(cmd, **kw):
+        subtitles._STOPPING = True  # the shutdown sweep ran while this child was being started
+        return _Child()
+
+    monkeypatch.setattr(subtitles.subprocess, "Popen", _popen)
+    with pytest.raises(subtitles.SubtitleUnavailable):
+        subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], None, None)
+    assert killed == [True]
+
+
+def test_a_pass_that_times_out_keeps_what_it_reached(monkeypatch):
+    """It was killed and its outputs deleted unread — so a file too big to read inside the timeout
+    never got past the head, and with the full-pass backoff the same doomed read came back hourly."""
+    real_popen = subprocess.Popen
+    cue = _vtt(_cue("00:05.000", "00:07.000", "reached"))
+
+    def _popen(cmd, **kw):
+        out = cmd[cmd.index("-y") + 1]
+        script = f"import time\nopen({out!r}, 'w').write({cue!r})\ntime.sleep(60)"
+        return real_popen([sys.executable, "-c", script], **kw)
+
+    monkeypatch.setattr(subtitles.subprocess, "Popen", _popen)
+    monkeypatch.setattr(subtitles, "EXTRACT_TIMEOUT_S", 1.0)
+    out, clean = subtitles._ffmpeg_extract("/plex-media/f.mkv", [0], None, None)
+    assert not clean, "a pass that ran out of time must not pass for a whole one"
+    assert "reached" in out[0]
+
+
+def test_an_orphan_sidecar_is_not_merged_into(monkeypatch):
+    """A sidecar with no VTT behind it claims cues that are not there. Merged into, it made one
+    window read as the whole track — `ready`, and the full pass skipped as already done."""
+    key = subtitles.cache_key("98614", 0)
+    subtitles._write_meta(key, [[0.0, subtitles._FULL_END_S]], True)
+    subtitles.publish(key, _vtt(_cue("16:20.000", "16:22.000", "x")), (970.0, 1300.0), False)
+    assert subtitles.read_meta(key) == ([[970.0, 1300.0]], False)
+    assert subtitles.ensure("98614", 0, at=5000.0)["state"] != "ready"
+
+
+def test_an_unreadable_track_is_not_overwritten_by_one_window(monkeypatch):
+    """`cache_read` answers None for a file it could not READ as well as for one that is not there.
+    Taken for absent, a whole track was replaced by the one window being published."""
+    key = subtitles.cache_key("98614", 0)
+    whole = _vtt(_cue("00:01.000", "00:02.000", "whole"))
+    subtitles.publish(key, whole, (0.0, subtitles._FULL_END_S), True)
+    monkeypatch.setattr(subtitles, "cache_read", lambda k: None)  # an I/O error on the read
+    subtitles.publish(key, _vtt(_cue("16:20.000", "16:22.000", "x")), (970.0, 1300.0), False)
+    assert "whole" in subtitles._vtt_path(key).read_text("utf-8")
+
+
+def test_a_region_that_could_not_be_written_is_not_claimed(monkeypatch):
+    monkeypatch.setattr(subtitles, "cache_write", lambda key, vtt: False)
+    key = subtitles.cache_key("98614", 0)
+    subtitles.publish(key, _vtt(_cue("16:20.000", "16:22.000", "x")), (0.0, 1e9), True)
+    assert subtitles.read_meta(key) == ([], False)
+
+
+def test_a_nul_in_the_rating_key_is_not_a_500(client, monkeypatch):
+    """`%00` reached `Path.stat`, which raises ValueError rather than OSError — a 500 on every poll,
+    after the scheduler had already queued two jobs for a key that names nothing."""
+    _manual_pool(monkeypatch)
+    assert client.get("/api/plex/subtitle/%00/0/status").status_code == 200
+
+
+def test_a_nul_rating_key_names_no_row():
+    """Postgres refuses NUL in text, so looking it up was a DataError (a 500) on every Plex route."""
+    from app.models import PlexItem
+    from app.plex.lookups import by_rating_key
+
+    assert by_rating_key(None, PlexItem, "12\x0034") is None  # type: ignore[arg-type]
diff --git a/frontend/src/lib/api/plex.ts b/frontend/src/lib/api/plex.ts
index 440a109b..9be6b783 100644
--- a/frontend/src/lib/api/plex.ts
+++ b/frontend/src/lib/api/plex.ts
@@ -662,13 +662,15 @@ export const plexApi = {
   // Whether a subtitle track can be shown yet. Extracting one out of a big MKV costs a full read of
   // the container (measured: 154 s for a 17 GB film), so the server does it in the background — around
   // `at`, the viewer's position, first — and the player polls this instead of mounting a <track> that
-  // would sit empty for minutes. `partial` = a window around `at` is ready and still growing.
+  // would sit empty for minutes. `partial` = a window around `at` is ready and still growing;
+  // `unavailable` = nothing for `at` right now (`code` says why) but ask again — cues elsewhere, when
+  // `gen` > 0, are still there; `failed` = the track can never be shown (the only final answer).
   plexSubtitleStatus: (
     id: string,
     ord: number,
     at = 0,
   ): Promise<{
-    state: "ready" | "partial" | "preparing" | "failed";
+    state: "ready" | "partial" | "preparing" | "unavailable" | "failed";
     code: string | null;
     gen: number;
   }> =>
diff --git a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
index 462fde58..a1ebf86c 100644
--- a/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
+++ b/frontend/src/lib/plexPlayerHooks.subtitle.dom.test.tsx
@@ -249,6 +249,49 @@ describe("usePlexTracks — when the status poll asks again, and when it stops",
     await waitFor(() => expect(result.current.subNotice).toBe("failed"));
     expect(result.current.subShowable).toBe(true); // the window it has is still worth showing
   });
+
+  it("says `unavailable` but keeps asking — and keeps the cues it has on screen", async () => {
+    // A Plex hiccup, or a stretch ffmpeg could not read, is the server's answer about NOW. Taken as
+    // final it stopped the poll and unmounted the track: no subtitles for the rest of the session,
+    // at cached positions too, after the full pass had completed behind it.
+    const status = vi
+      .spyOn(api, "plexSubtitleStatus")
+      .mockResolvedValueOnce({ state: "unavailable", code: "plex_error", gen: 5 })
+      .mockResolvedValue({ state: "partial", code: null, gen: 6 });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subNotice).toBe("failed"));
+    expect(result.current.subShowable).toBe(true);
+    await vi.advanceTimersByTimeAsync(5100);
+    expect(status).toHaveBeenCalledTimes(2);
+    await waitFor(() => expect(result.current.subNotice).toBeNull());
+  });
+
+  it("does not mount an `unavailable` track that has no cues anywhere", async () => {
+    vi.spyOn(api, "plexSubtitleStatus").mockResolvedValue({
+      state: "unavailable",
+      code: "plex_error",
+      gen: 0,
+    });
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subNotice).toBe("failed"));
+    expect(result.current.subShowable).toBe(false);
+  });
+
+  it("re-asks the server at once when the viewer picks the track that is already selected", async () => {
+    // Same track, same query key: without an explicit refetch "picking it again" did nothing for a
+    // poll that was backing off after a failed request.
+    const status = vi.spyOn(api, "plexSubtitleStatus").mockRejectedValue(new Error("offline"));
+    const { result } = mount(client());
+    result.current.setSubOrd(0);
+    await waitFor(() => expect(result.current.subNotice).toBe("failed"));
+    expect(status).toHaveBeenCalledTimes(1);
+    status.mockResolvedValue({ state: "partial", code: null, gen: 2 });
+    act(() => result.current.changeSubtitle(0));
+    await waitFor(() => expect(status).toHaveBeenCalledTimes(2));
+    await waitFor(() => expect(result.current.subShowable).toBe(true));
+  });
 });
 
 // Rendered for real, not by calling the hook's callback: the failure arrives as the <track>'s own
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index 051d790f..797d9373 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -353,6 +353,10 @@ export type SubFailReason = "bitmap" | "missing" | "failed";
 // <track> whose own VTT fetch failed is remounted before the track is reported as unavailable, and
 // the first of the (doubling) pauses before each remount.
 const SUB_POLL_ERROR_MS = 10_000;
+// …and after an `unavailable` answer: nothing is being read for this position right now (a memo the
+// server keeps for a minute), so no need for the 1 s cadence — but the poll carries the position, and
+// moving into a stretch that IS cached should stop saying "couldn't be loaded" within a few seconds.
+const SUB_POLL_UNAVAILABLE_MS = 5_000;
 const SUB_TRACK_RETRIES = 2;
 const SUB_TRACK_RETRY_MS = 2_000;
 
@@ -467,14 +471,19 @@ export function usePlexTracks(opts: {
     (ord: number | null) => {
       setSubOrd(ord);
       // Picking a track (the same one included) is the viewer asking for it NOW: a track given up on
-      // after failed loads gets a fresh budget instead of repeating "couldn't be loaded" unasked.
+      // after failed loads gets a fresh budget instead of repeating "couldn't be loaded" unasked —
+      // and the server is asked again at once. Re-picking the highlighted track changes no query key,
+      // so without the refetch that half of "now" did nothing: a poll backing off after a failed
+      // request, or one waiting out an `unavailable`, kept waiting.
       setLoadFails({ key: "", n: 0 });
+      if (ord != null && ord === subOrd)
+        void qc.refetchQueries({ queryKey: qk.plexSubtitle(id, ord), exact: true });
       patchPrefs({
         subLang:
           ord == null ? "" : (detail?.subtitle_streams.find((s) => s.ord === ord)?.language ?? ""),
       });
     },
-    [detail, patchPrefs, setSubOrd],
+    [detail, patchPrefs, setSubOrd, subOrd, qc, id],
   );
   // 'A' cycles audio tracks; 'S' cycles subtitle (off → each text sub → off).
   const cycleAudio = useCallback(() => {
@@ -543,10 +552,15 @@ export function usePlexTracks(opts: {
     // either, or one dropped request would leave "unavailable" on screen for a track that is fine.
     // So it backs off to SUB_POLL_ERROR_MS; the player shows the failure inline meanwhile, which is
     // also why the request is `quiet` (no global error dialog re-opening under the film).
+    //
+    // `unavailable` is not settled either — it is the server's "nothing for this position right now"
+    // (a Plex hiccup, a stretch ffmpeg could not read), which it forgets within a minute. Treated as
+    // final it ended the subtitles for the rest of the session, cached stretches included.
     refetchInterval: (q) => {
       if (q.state.status === "error") return SUB_POLL_ERROR_MS;
       const st = q.state.data?.state;
       if (st === "ready" || st === "failed") return false;
+      if (st === "unavailable") return SUB_POLL_UNAVAILABLE_MS;
       return st === "partial" ? 2000 : 1000;
     },
     staleTime: 0,
@@ -563,9 +577,14 @@ export function usePlexTracks(opts: {
   const subRetry = loadFails.key === loadKey ? loadFails.n : 0;
   const subGaveUp = subRetry > SUB_TRACK_RETRIES;
   // Mount the <track> for a `partial` track too: a window around the playhead is exactly what the
-  // viewer needs right now, and the poll widens it underneath them.
+  // viewer needs right now, and the poll widens it underneath them. And for an `unavailable` one that
+  // has cues somewhere (`gen` > 0): nothing shows at a stretch with no cues, while a seek back into a
+  // cached one shows them again — unmounting it blanked those too.
   const subShowable =
-    (subStatus?.state === "ready" || subStatus?.state === "partial") && !subGaveUp;
+    (subStatus?.state === "ready" ||
+      subStatus?.state === "partial" ||
+      (subStatus?.state === "unavailable" && subStatus.gen > 0)) &&
+    !subGaveUp;
   // A failing poll is said even while an earlier window stays mounted: react-query keeps the last
   // good `data` through a failed refetch, so a `partial` answer kept the track "showable" and the
   // failure had nowhere to appear — blank subtitles past the window, no spinner, no message.
@@ -574,7 +593,7 @@ export function usePlexTracks(opts: {
       ? null
       : subStatusQ.isError || subGaveUp
         ? "failed"
-        : subStatus?.state === "failed"
+        : subStatus?.state === "failed" || subStatus?.state === "unavailable"
           ? subFailReason(subStatus.code)
           : subShowable
             ? null

From 5c5cabbe5a3b6b12f935d51a1977d3768508f4a7 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:04:41 +0200
Subject: [PATCH 24/52] fix(plex): the player drops a session answer that lands
 late, and Next neither loses nor lends a position
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09.

- loadSession checks, after its await, that it is still the newest call and the player is still
  mounted. A late answer used to replace what was playing (Next twice quickly: the slower transcode
  landed last and played the middle item under the last one's title, recording its progress there)
  or attach a stream to the detached <video> after Back, never destroyed.
- The <video>'s clock is trusted only once the new session has answered. go()'s pause() fires a
  timeupdate AFTER the reset to 0 (measured in Chrome), so the previous item's position was sent as
  the next item's subtitle position and saved as its progress (final, pushed to Plex).
- Next settles the item being left (final checkpoint + reopen-cache patch) before switching: the
  progress cleanup ran with the position already reset and skipped, so every Next dropped the last
  stretch watched.
- A seek-restart puts its target into the position state too; the ref alone was re-synced back to
  the pre-seek spot by the restart's own render.
- The unmount teardown captures the <video> at mount: React detaches refs before an unmount's
  cleanups, so the stop/detach never ran.
- The tracks panel exposes the selected audio/subtitle track via aria-pressed.

Verified in real Chrome on localdev (Westworld S1E6 → Next): the item left was settled at 783 s, the
next asked for subtitles at its own start (0), and no progress was written for it.
---
 .../PlexPlayer.session.dom.test.tsx           | 278 ++++++++++++++++++
 frontend/src/components/PlexPlayer.tsx        |  86 ++++--
 frontend/src/lib/plexPlayerHooks.ts           |  44 +--
 3 files changed, 373 insertions(+), 35 deletions(-)
 create mode 100644 frontend/src/components/PlexPlayer.session.dom.test.tsx

diff --git a/frontend/src/components/PlexPlayer.session.dom.test.tsx b/frontend/src/components/PlexPlayer.session.dom.test.tsx
new file mode 100644
index 00000000..d2fecf9c
--- /dev/null
+++ b/frontend/src/components/PlexPlayer.session.dom.test.tsx
@@ -0,0 +1,278 @@
+// @vitest-environment jsdom
+//
+// The Plex player's session lifecycle, rendered for real (deep-review round 3 of bug hunt 2026-09).
+//
+// jsdom has no media pipeline, so the <video> is a small stand-in that behaves like Chrome where it
+// matters here: `pause()` fires its `timeupdate` in a LATER task (measured in Chrome — which is how the
+// previous item's position used to arrive after the player had already reset it for the next one).
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { render, cleanup, waitFor, screen, fireEvent, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+
+import PlexPlayer from "./PlexPlayer";
+import { api, type PlexItemDetail } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+import { notify } from "../lib/notifications";
+import { ACTIVE_ACCOUNT_KEY } from "../lib/activeAccount";
+
+type Media = HTMLMediaElement & { _t?: number };
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+  const later = (el: HTMLMediaElement, ...types: string[]) =>
+    setTimeout(() => types.forEach((ty) => el.dispatchEvent(new Event(ty))), 0);
+  Object.defineProperty(HTMLMediaElement.prototype, "currentTime", {
+    configurable: true,
+    get(this: Media) {
+      return this._t ?? 0;
+    },
+    set(this: Media, v: number) {
+      this._t = v;
+    },
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "play", {
+    configurable: true,
+    value: () => Promise.resolve(),
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "pause", {
+    configurable: true,
+    value(this: HTMLMediaElement) {
+      later(this, "timeupdate", "pause"); // as Chrome does: after the call has returned
+    },
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "load", {
+    configurable: true,
+    value(this: Media) {
+      this._t = 0;
+    },
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "seekable", {
+    configurable: true,
+    get: () => ({ length: 0, end: () => 0 }),
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "textTracks", {
+    configurable: true,
+    get: () => Object.assign([], { addEventListener() {}, removeEventListener() {} }),
+  });
+});
+
+beforeEach(() => {
+  // A signed-in account whose saved subtitle language is English (prefs are per account).
+  sessionStorage.setItem(ACTIVE_ACCOUNT_KEY, "7");
+  localStorage.setItem("siftlode.plexPlayerPrefs.7", JSON.stringify({ subLang: "en" }));
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  sessionStorage.clear();
+  localStorage.clear();
+});
+
+const item = (id: string, position = 0): PlexItemDetail =>
+  ({
+    id,
+    title: `Title ${id}`,
+    type: "episode",
+    duration_seconds: 3000,
+    status: "new",
+    position_seconds: position,
+    audio_streams: [{ ord: 0, label: "English", language: "en", default: true }],
+    subtitle_streams: [{ ord: 0, label: "English", language: "en", text: true }],
+    markers: [],
+  }) as unknown as PlexItemDetail;
+
+const direct = (id: string) =>
+  ({ mode: "direct", url: `/media/${id}`, start_s: 0 }) as Awaited<
+    ReturnType<typeof api.plexSession>
+  >;
+
+/** A session answer the test releases when it wants to. */
+function deferred() {
+  let resolve!: (v: Awaited<ReturnType<typeof api.plexSession>>) => void;
+  const promise = new Promise<Awaited<ReturnType<typeof api.plexSession>>>((r) => (resolve = r));
+  return { promise, resolve };
+}
+
+function mount(opts: {
+  details: Record<string, PlexItemDetail>;
+  sessions: Record<string, () => Promise<Awaited<ReturnType<typeof api.plexSession>>>>;
+  queue?: string[];
+  qc?: QueryClient;
+}) {
+  vi.spyOn(api, "plexItem").mockImplementation((id: string) => Promise.resolve(opts.details[id]!));
+  vi.spyOn(api, "plexSession").mockImplementation((id: string) => opts.sessions[id]!());
+  const progress = vi.spyOn(api, "plexProgress").mockResolvedValue(undefined as never);
+  const status = vi
+    .spyOn(api, "plexSubtitleStatus")
+    .mockResolvedValue({ state: "preparing", code: null, gen: 0 });
+  const qc = opts.qc ?? new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const first = opts.queue?.[0] ?? Object.keys(opts.details)[0]!;
+  const view = render(
+    <QueryClientProvider client={qc}>
+      <PlexPlayer itemId={first} onClose={() => {}} queue={opts.queue} />
+    </QueryClientProvider>,
+  );
+  return { ...view, progress, status, qc };
+}
+
+const video = () => document.querySelector("video") as Media;
+
+async function playingAt(src: string, t: number) {
+  await waitFor(() => expect(video()?.getAttribute("src")).toBe(src));
+  const v = video();
+  v._t = t;
+  act(() => void v.dispatchEvent(new Event("timeupdate")));
+}
+
+const tick = () => act(() => new Promise((r) => setTimeout(r, 20)));
+
+describe("moving to the next item", () => {
+  it("settles the item being left, and gives the next one none of its position", async () => {
+    const { progress, status, unmount } = mount({
+      details: { A: item("A"), B: item("B", 300) },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    await playingAt("/media/A", 1500);
+    fireEvent.click(screen.getByLabelText("plex.player.next"));
+    await waitFor(() => expect(status.mock.calls.some(([id]) => id === "B")).toBe(true));
+    await tick(); // the timeupdate that pause() queued has landed by now
+    // B's session has not answered, so where B is is where it was asked to start — not A's 25:00.
+    expect(status.mock.calls.filter(([id]) => id === "B").map(([, , at]) => at)).not.toContain(
+      1500,
+    );
+    expect(status.mock.calls.find(([id]) => id === "B")?.[2]).toBe(300);
+    // A got its final checkpoint at the position it was left at…
+    expect(progress.mock.calls).toContainEqual(["A", 1500, 3000, true]);
+    unmount();
+    // …and leaving B while it was still loading saved nothing of A's position as B's.
+    expect(progress.mock.calls.filter(([id]) => id === "B")).toEqual([]);
+  });
+});
+
+it("a seek that restarts the session is saved at its target while the new session loads", async () => {
+  // seekTo wrote the target into the position ref only — and the restart re-renders at once, which
+  // re-syncs that ref from the state: a page-hide during the restart saved the pre-seek spot.
+  let calls = 0;
+  mount({
+    details: { A: item("A") },
+    sessions: {
+      A: () => (calls++ === 0 ? Promise.resolve(direct("A")) : new Promise(() => {})),
+    },
+  });
+  const beacon = vi.spyOn(api, "plexProgressBeacon").mockImplementation(() => {});
+  await playingAt("/media/A", 1500);
+  fireEvent.click(screen.getByLabelText("plex.player.forward10"));
+  await waitFor(() => expect(api.plexSession).toHaveBeenCalledTimes(2)); // a restart, not a native seek
+  await tick();
+  act(() => void window.dispatchEvent(new Event("pagehide")));
+  expect(beacon).toHaveBeenLastCalledWith("A", 1510, 3000, true);
+});
+
+describe("a session answer that lands late", () => {
+  it("is dropped when the viewer has moved on to another item meanwhile", async () => {
+    const slowB = deferred();
+    mount({
+      details: { A: item("A"), B: item("B"), C: item("C") },
+      sessions: {
+        A: () => Promise.resolve(direct("A")),
+        B: () => slowB.promise,
+        C: () => Promise.resolve(direct("C")),
+      },
+      queue: ["A", "B", "C"],
+    });
+    await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+    fireEvent.click(screen.getByLabelText("plex.player.next"));
+    await screen.findByText("Title B");
+    fireEvent.click(screen.getByLabelText("plex.player.next"));
+    await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/C"));
+    await act(async () => slowB.resolve(direct("B")));
+    await tick();
+    expect(video().getAttribute("src")).toBe("/media/C");
+  });
+
+  it("is dropped when the player has been closed meanwhile", async () => {
+    const slowA = deferred();
+    const { unmount } = mount({ details: { A: item("A") }, sessions: { A: () => slowA.promise } });
+    await waitFor(() => expect(api.plexSession).toHaveBeenCalled());
+    const v = video();
+    unmount();
+    await act(async () => slowA.resolve(direct("A")));
+    await tick();
+    expect(v.getAttribute("src")).toBeNull();
+  });
+});
+
+it("closing the player detaches the <video> it was playing", async () => {
+  const { unmount } = mount({
+    details: { A: item("A") },
+    sessions: { A: () => Promise.resolve(direct("A")) },
+  });
+  await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+  const v = video();
+  unmount();
+  expect(v.getAttribute("src")).toBeNull();
+});
+
+describe("the subtitle poll and notice", () => {
+  it("asks about where a resumed session was asked to start, before playback has ticked", async () => {
+    const { status } = mount({
+      details: { A: item("A", 1198) },
+      sessions: { A: () => new Promise(() => {}) },
+    });
+    await waitFor(() => expect(status).toHaveBeenCalled());
+    expect(status.mock.calls[0]).toEqual(["A", 0, 1198]);
+  });
+
+  it("says a failing poll even while an earlier window is still on screen", async () => {
+    const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    qc.setQueryData(qk.plexSubtitle("A", 0), { state: "partial", code: null, gen: 1 });
+    const view = mount({
+      details: { A: item("A") },
+      sessions: { A: () => Promise.resolve(direct("A")) },
+      qc,
+    });
+    view.status.mockRejectedValue(new Error("offline"));
+    await waitFor(() => expect(view.status).toHaveBeenCalled());
+    await screen.findByText("plex.player.subUnavailable.failed");
+    expect(document.querySelector("track")).not.toBeNull(); // the window stays mounted meanwhile
+  });
+
+  it("marks which track is selected for assistive tech, not only by colour", async () => {
+    mount({ details: { A: item("A") }, sessions: { A: () => new Promise(() => {}) } });
+    await screen.findByText("Title A");
+    fireEvent.click(screen.getByLabelText("plex.player.tracks"));
+    const off = await screen.findByText("plex.player.subOff");
+    expect(off.closest("button")?.getAttribute("aria-pressed")).toBe("false");
+    const pressed = document.querySelectorAll('[aria-pressed="true"]');
+    expect([...pressed].map((b) => b.textContent)).toEqual(["English"]); // the saved subtitle
+  });
+});
+
+it("shows a toast raised while it is open inside itself, not under its scrim", async () => {
+  mount({ details: { A: item("A") }, sessions: { A: () => new Promise(() => {}) } });
+  await screen.findByText("Title A");
+  act(() => notify({ level: "error", message: "Couldn't mark it watched." }));
+  const toast = await screen.findByText("Couldn't mark it watched.");
+  let host: Element | null = video();
+  while (host && !host.contains(toast)) host = host.parentElement;
+  expect(host).not.toBe(document.body); // the player's own host, beside its <video>
+});
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index c6d5b564..e8b5a80b 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -109,6 +109,20 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   const aliveRef = useRef(true);
   const wrapRef = useRef<HTMLDivElement>(null);
   const sessionStartRef = useRef(0); // absolute offset the current HLS/direct session begins at
+  // Which loadSession call is the current one. Everything after its `await` checks it: a response
+  // that lands after a newer call, an item change or the player's unmount is dropped — it used to
+  // replace whatever was playing (Next twice quickly, the slower transcode answering last, played the
+  // middle item under the last one's title and recorded its progress there) or attach a stream to the
+  // detached <video> after Back, never destroyed, keeping the server session warm.
+  const sessGenRef = useRef(0);
+  // Whether the <video>'s clock belongs to the session `sessionStartRef` describes. False from the
+  // moment a session is asked for until it has answered: the media still attached meanwhile is the
+  // OLD one, so `sessionStartRef + currentTime` was the previous item's position (go()'s pause() fires
+  // a timeupdate AFTER the reset to 0) — sent as the new item's subtitle position and saved as its
+  // progress, or, during a seek-restart, the pre-seek spot overwriting the target.
+  const clockLiveRef = useRef(false);
+  // The item whose session is attached to the <video> right now (see loadSession's failure path).
+  const attachedIdRef = useRef<string | null>(null);
   // Which encoder the current transcode session ran: true=VAAPI hardware, false=libx264 software,
   // null=not a transcode. Feeds the stats overlay's mode row ("transcode · GPU" / "· CPU").
   const hwRef = useRef<boolean | null>(null);
@@ -247,6 +261,9 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     async (startAt: number, resumePlay = true) => {
       const video = videoRef.current;
       if (!video) return;
+      const gen = ++sessGenRef.current;
+      const current = () => gen === sessGenRef.current && aliveRef.current;
+      clockLiveRef.current = false;
       loadStartRef.current = startAt;
       setReady(false);
       setBuffering(false);
@@ -262,6 +279,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         const m = multiAudioRef.current;
         sess = await api.plexSession(id, startAt, m ? null : audioRef.current, aoffRef.current, m);
       } catch (e) {
+        if (!current()) return; // superseded or left: not this request's error to show
+        // A failed seek-restart leaves the old session attached and its clock still true; a failed
+        // move to another item leaves the previous item's media, which is not this item's clock.
+        clockLiveRef.current = attachedIdRef.current === id;
         // Surface WHY playback can't start instead of an eternal spinner. 404 = the physical file
         // isn't reachable (missing media bind-mount or a wrong plex_path_map); 501 = the codec
         // needs full transcoding (a later phase).
@@ -275,6 +296,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         );
         return;
       }
+      if (!current()) return;
       // Surface the active mode for the stats overlay + the honest cold-start label: a transcode session
       // re-encodes the video (hw = which encoder), and its first segment is genuinely slower than remux.
       const isTranscode = sess.mode === "hls" && !!sess.transcode;
@@ -288,6 +310,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         sess.mode === "hls" && sess.start_s > 0 ? sess.start_s - HLS_SUB_LAG : sess.start_s;
       sessionStartRef.current = trueStart;
       setSessionK(trueStart);
+      // From here the <video>'s clock is this session's: the old source is replaced just below, and a
+      // timeupdate its teardown queues already reads the new start.
+      clockLiveRef.current = true;
+      attachedIdRef.current = id;
       // Belt-and-suspenders resume: the play() fired on MANIFEST_PARSED / loadedmetadata can be
       // rejected when the media isn't ready yet (slow first segments over a proxy), which would leave
       // the video paused after a seek even though the user was watching. Retry once the element can
@@ -416,6 +442,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     const resume = detail.status !== "watched" ? detail.position_seconds || 0 : 0;
     loadSession(resume);
     return () => {
+      // A session still in flight for this item must not land after it. The LIVE counter is the point
+      // (bumping it is what outdates the pending call), so the "ref may have changed" hint is moot.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      sessGenRef.current++;
       if (hlsRef.current) {
         hlsRef.current.destroy();
         hlsRef.current = null;
@@ -433,15 +463,21 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   // (StrictMode does exactly that in development). With the flag only ever lowered, it stayed false
   // for the life of the player — every play() is gated on it, so the player never started by itself,
   // and a seek that restarts the session left it paused (bug hunt 2026-09, found on localdev).
+  //
+  // The element is captured HERE, not read in the cleanup: React detaches a ref before it runs an
+  // unmount's effect cleanups, so `videoRef.current` was already null there and the stop/detach below
+  // never ran (only StrictMode's simulated unmount, which keeps refs, ever reached it).
   useEffect(() => {
     aliveRef.current = true;
+    const v = videoRef.current;
     return () => {
       aliveRef.current = false;
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- the live counter, as above
+      sessGenRef.current++;
       if (hlsRef.current) {
         hlsRef.current.destroy();
         hlsRef.current = null;
       }
-      const v = videoRef.current;
       if (v) {
         try {
           v.pause();
@@ -459,6 +495,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     const video = videoRef.current;
     if (!video) return;
     const onTime = () => {
+      if (!clockLiveRef.current) return; // the old session's clock (see clockLiveRef)
       const a = sessionStartRef.current + video.currentTime;
       setAbs(a);
       try {
@@ -511,7 +548,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   }, [id]);
 
   // Periodic + on-unmount progress checkpoint (interval flush + pause/pagehide + reopen cache patch).
-  usePlexProgress({ id, qc, videoRef, absRef, durationRef });
+  const { settle: settleProgress } = usePlexProgress({ id, qc, videoRef, absRef, durationRef });
 
   // --- seeking (native within the loaded region, else restart the session) ---------------------
   const seekTo = useCallback(
@@ -521,7 +558,11 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       const wasPlaying = !video.paused; // preserve play/pause intent across the seek
       const dur = durationRef.current || target;
       const T = Math.max(0, Math.min(target, dur - 1));
-      absRef.current = T; // reflect the target immediately so a save/beacon right after a seek is accurate
+      // Reflect the target immediately so a save/beacon right after a seek is accurate — in the STATE
+      // too: `absRef` is re-synced from `abs` on every render, and the restart below renders at once,
+      // so the ref alone was back at the pre-seek spot before anything could read it.
+      absRef.current = T;
+      setAbs(T);
       const rel = T - sessionStartRef.current;
       if (rel >= 0 && rel <= (video.seekable.length ? video.seekable.end(0) : 0) + 0.5) {
         video.currentTime = rel; // native seek within the loaded region keeps playing on its own
@@ -551,21 +592,29 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     helpOpenRef,
   });
 
-  const go = useCallback((otherId: string | null | undefined) => {
-    if (otherId) {
-      // Stop the outgoing media BEFORE switching. If the next item fails to load (e.g. no local
-      // file), loadSession returns without replacing the <video> source, leaving the old episode
-      // still playing — it would then fire 'ended' against the NEW id and mark the wrong item
-      // watched (and scrobble it to Plex). Pausing here severs that stale-tail race.
-      try {
-        videoRef.current?.pause();
-      } catch {
-        /* ignore */
+  const go = useCallback(
+    (otherId: string | null | undefined) => {
+      if (otherId) {
+        // Stop the outgoing media BEFORE switching. If the next item fails to load (e.g. no local
+        // file), loadSession returns without replacing the <video> source, leaving the old episode
+        // still playing — it would then fire 'ended' against the NEW id and mark the wrong item
+        // watched (and scrobble it to Plex). Pausing here severs that stale-tail race.
+        try {
+          videoRef.current?.pause();
+        } catch {
+          /* ignore */
+        }
+        // Settle the item being left while the position still is its own (see usePlexProgress), and
+        // stop trusting the old media's clock: the timeupdate that pause() queues lands after the
+        // reset below and would otherwise hand the old position to the new item.
+        settleProgress();
+        clockLiveRef.current = false;
+        setAbs(0);
+        setId(otherId);
       }
-      setAbs(0);
-      setId(otherId);
-    }
-  }, []);
+    },
+    [settleProgress],
+  );
 
   // Prev/next: from the playlist queue when playing one, else the item's own episode neighbours.
   const qIdx = queue ? queue.indexOf(id) : -1;
@@ -1250,6 +1299,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
                           <button
                             key={a.ord}
                             onClick={() => changeAudio(a.ord)}
+                            aria-pressed={(audioOrd ?? 0) === a.ord}
                             className={`block w-full truncate rounded px-2 py-1 text-left hover:bg-white/10 ${
                               (audioOrd ?? 0) === a.ord ? "text-accent" : "text-white"
                             }`}
@@ -1264,6 +1314,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
                         <PanelHead>{t("plex.player.subtitles")}</PanelHead>
                         <button
                           onClick={() => changeSubtitle(null)}
+                          aria-pressed={subOrd == null}
                           className={`block w-full rounded px-2 py-1 text-left hover:bg-white/10 ${
                             subOrd == null ? "text-accent" : "text-white"
                           }`}
@@ -1274,6 +1325,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
                           <button
                             key={s.ord}
                             onClick={() => changeSubtitle(s.ord)}
+                            aria-pressed={subOrd === s.ord}
                             className={`block w-full truncate rounded px-2 py-1 text-left hover:bg-white/10 ${
                               subOrd === s.ord ? "text-accent" : "text-white"
                             }`}
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index 797d9373..d7e4decd 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -79,14 +79,20 @@ export function useControlsVisibility(opts: {
 // Periodic + on-unmount progress checkpoint. Reads live position/duration through refs (owned by the
 // component, since seeking/skip/ended all mutate absRef too) so the interval and unload beacon see the
 // current spot without rebuilding the effect.
+//
+// `settle` is what leaving the item does (the final checkpoint + the reopen-cache patch). The player
+// calls it itself BEFORE it moves to another item: by the time this effect's cleanup runs for the
+// outgoing id, the position has already been reset for the incoming one — so the cleanup found 0 and
+// skipped, and every Next dropped the last stretch watched of the episode being left.
 export function usePlexProgress(opts: {
   id: string;
   qc: QueryClient;
   videoRef: RefObject<HTMLVideoElement | null>;
   absRef: MutableRefObject<number>;
   durationRef: MutableRefObject<number>;
-}): void {
+}): { settle: () => void } {
   const { id, qc, videoRef, absRef, durationRef } = opts;
+  const settleRef = useRef<() => void>(() => {});
   useEffect(() => {
     // `final` = a settled checkpoint (pause / page-hide / leaving the player) vs. the periodic tick.
     // Only final checkpoints get mirrored to a linked Plex account (backend-side debounce), so Plex
@@ -120,23 +126,15 @@ export function usePlexProgress(opts: {
         api.plexProgressBeacon(id, Math.floor(absRef.current), durationRef.current, true);
     };
     window.addEventListener("pagehide", onHide);
-    return () => {
-      window.clearInterval(iv);
-      window.clearTimeout(seekTimer);
-      window.removeEventListener("pagehide", onHide);
-      video?.removeEventListener("pause", onPauseFlush);
-      video?.removeEventListener("seeked", onSeekFlush);
+    // Back (unmount) persists the position server-side via flush(), but reopening the same item in
+    // the SAME session read react-query's CACHED detail — whose position_seconds predated this watch —
+    // so the resume landed at the old spot (the progress GET could also race the POST). So leaving
+    // also patches the cached detail, and a reopen resumes from where we left off. (F5 was always fine:
+    // a reload starts with an empty cache and fetches the fresh position.) Safe to do only when leaving
+    // — patching while mounted would retrigger the loadSession effect and reseek mid-play. Reading the
+    // LATEST abs/duration is the whole point of the checkpoint (the resume point when leaving).
+    const settle = () => {
       flush(true);
-      // Back (unmount) persists the position server-side via flush(), but reopening the same item in
-      // the SAME session read react-query's CACHED detail — whose position_seconds predated this
-      // watch — so the resume landed at the old spot (the progress GET could also race the POST).
-      // Patch the cached detail here so a reopen resumes from where we left off. (F5 was always fine:
-      // a reload starts with an empty cache and fetches the fresh position.) Safe to do only on
-      // unmount — patching while mounted would retrigger the loadSession effect and reseek mid-play.
-      // Reading the LATEST abs/duration at cleanup is the whole point of the checkpoint (the resume
-      // point when leaving), not a stale snapshot — the "ref value may have changed" hint is a false
-      // positive here. Scoped disable so the deps array below is still checked.
-      /* eslint-disable react-hooks/exhaustive-deps */
       if (absRef.current > 0 && durationRef.current > 0) {
         const pos = Math.floor(absRef.current);
         // Match the language-keyed detail query (E5 S6) so the optimistic resume patch lands.
@@ -144,13 +142,23 @@ export function usePlexProgress(opts: {
           old ? { ...old, position_seconds: pos } : old,
         );
       }
-      /* eslint-enable react-hooks/exhaustive-deps */
+    };
+    settleRef.current = settle;
+    return () => {
+      window.clearInterval(iv);
+      window.clearTimeout(seekTimer);
+      window.removeEventListener("pagehide", onHide);
+      video?.removeEventListener("pause", onPauseFlush);
+      video?.removeEventListener("seeked", onSeekFlush);
+      settle();
+      settleRef.current = () => {};
       qc.invalidateQueries({ queryKey: qk.plexLibrary() });
       qc.invalidateQueries({ queryKey: qk.plexShow() });
     };
     // absRef/durationRef/videoRef are stable ref objects — listed to satisfy exhaustive-deps without
     // changing when the effect re-runs (id/qc only), matching the original in-component effect.
   }, [id, qc, absRef, durationRef, videoRef]);
+  return { settle: useCallback(() => settleRef.current(), []) };
 }
 
 // Volume/mute for the Plex player's HTML5 <video> (0..1 float, independent .muted flag). Persists to

From 33fe895539727559a3931877d880ed16617bc808 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:04:54 +0200
Subject: [PATCH 25/52] fix(ui): every full-screen overlay hosts its own
 toasts, above the players' controls, without re-announcing them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09 (the round-2 overlay toast host, finished).

- Inside an overlay the toast stack sits above the bottom band (bottom-24, the UpNextCard rung) and
  lets clicks between cards through: at the app's own spot it covered the Plex transport row and
  PlayerModal's docked bar and took their clicks while a toast was up (measured: play/pause, ±10,
  stop, prev/next, mute all hit the toast).
- ui/Modal and the onboarding wizard mount an overlay host too, so a toast raised under any dialog
  is readable and a click on it no longer closes the dialog; the Modal's Tab trap spans the whole
  dialog, so a toast's action and dismiss are keyboard-reachable. A test now enforces the
  convention: a component that covers the viewport at z-overlay must mount <Toaster overlay />.
- PlayerModal's host moves into the stage in true fullscreen (outside the element holding the lock it
  was painted under it).
- A host that takes over shows the toasts it inherits silently (no second role=alert, its region
  aria-live=off until they are in), and each countdown bar starts as far in as its toast already is
  instead of restarting while the real dismiss timer does not.
- The overlay-host registry uses lib/store instead of a hand-rolled listener triad.
---
 frontend/src/components/OnboardingWizard.tsx  |  4 +
 .../src/components/PlayerModal.dom.test.tsx   | 19 ++++
 frontend/src/components/PlayerModal.tsx       |  6 +-
 .../src/components/UploadDialog.dom.test.tsx  |  6 +-
 frontend/src/components/ui/Modal.dom.test.tsx | 46 +++++++++
 frontend/src/components/ui/Modal.tsx          | 14 ++-
 .../src/components/ui/Toaster.dom.test.tsx    | 43 +++++++-
 .../src/components/ui/Toaster.hosts.test.ts   | 33 +++++++
 frontend/src/components/ui/Toaster.tsx        | 98 ++++++++++++-------
 9 files changed, 228 insertions(+), 41 deletions(-)
 create mode 100644 frontend/src/components/ui/Toaster.hosts.test.ts

diff --git a/frontend/src/components/OnboardingWizard.tsx b/frontend/src/components/OnboardingWizard.tsx
index abbf3f6d..b57c57a5 100644
--- a/frontend/src/components/OnboardingWizard.tsx
+++ b/frontend/src/components/OnboardingWizard.tsx
@@ -7,6 +7,7 @@ import { api, type Me } from "../lib/api";
 import { beginGrant, endOnboarding } from "../lib/onboarding";
 import { Button } from "./ui/Button";
 import Overlay from "./ui/Overlay";
+import Toaster from "./ui/Toaster";
 
 // A first-login wizard that walks the user through granting YouTube access one scope at a
 // time, each with a plain explanation and an up-front heads-up about Google's "unverified
@@ -262,6 +263,9 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
             <Dots index={stepIndex} total={3} />
           </div>
         </div>
+        {/* Toasts raised while the wizard is up (the connection notice among them) show above its
+            scrim, not under it — see ui/Toaster. */}
+        <Toaster overlay />
       </div>
     </Overlay>
   );
diff --git a/frontend/src/components/PlayerModal.dom.test.tsx b/frontend/src/components/PlayerModal.dom.test.tsx
index 08c07545..e24c3c67 100644
--- a/frontend/src/components/PlayerModal.dom.test.tsx
+++ b/frontend/src/components/PlayerModal.dom.test.tsx
@@ -270,4 +270,23 @@ describe("PlayerModal — toasts raised while it is open", () => {
     act(() => void notify({ level: "error", message: "Couldn't remove the video." }));
     expect(screen.getByTestId("player-modal").textContent).toContain("Couldn't remove the video.");
   });
+
+  it("shows them inside the stage in true fullscreen — the element holding the lock", async () => {
+    // Anything outside the fullscreen element is painted under it. The player's host sat beside the
+    // card, so in fullscreen a lost connection was reported to nobody.
+    vi.spyOn(api, "videoDetail").mockReturnValue(new Promise(() => {}));
+    const A = vid("A", 0);
+    renderModal(
+      <PlayerModal video={A} queue={[A]} startIndex={0} onClose={() => {}} onState={() => {}} />,
+    );
+    const stage = document.querySelector(".player-stage")!;
+    Object.defineProperty(document, "fullscreenElement", { configurable: true, get: () => stage });
+    try {
+      act(() => void document.dispatchEvent(new Event("fullscreenchange")));
+      act(() => void notify({ level: "error", message: "Connection lost" }));
+      await waitFor(() => expect(stage.textContent).toContain("Connection lost"));
+    } finally {
+      delete (document as { fullscreenElement?: unknown }).fullscreenElement;
+    }
+  });
 });
diff --git a/frontend/src/components/PlayerModal.tsx b/frontend/src/components/PlayerModal.tsx
index d0ac068c..47b73975 100644
--- a/frontend/src/components/PlayerModal.tsx
+++ b/frontend/src/components/PlayerModal.tsx
@@ -586,6 +586,7 @@ export default function PlayerModal({
               the exit button also re-arms our shortcuts. Add-to-playlist works in true fullscreen (its
               popover portals INTO the fullscreen element); download stays hidden there because it opens
               a Modal, which still portals to <body> — outside the fullscreen element. */}
+            {isFullscreen && <Toaster overlay />}
             {(maximized || isFullscreen) && (
               <div
                 onClick={(e) => e.stopPropagation()}
@@ -962,8 +963,9 @@ export default function PlayerModal({
         )}
       </div>
       {/* Toasts raised while the player is open (a failed Remove, a lost connection) — the app's own
-          Toaster is underneath this scrim. See ui/Toaster. */}
-      <Toaster overlay />
+          Toaster is underneath this scrim. See ui/Toaster. In true fullscreen it moves into the
+          stage, the element holding the lock: out here it was painted under it, i.e. not at all. */}
+      {!isFullscreen && <Toaster overlay />}
     </div>,
     document.body,
   );
diff --git a/frontend/src/components/UploadDialog.dom.test.tsx b/frontend/src/components/UploadDialog.dom.test.tsx
index 4259b031..ccbecf77 100644
--- a/frontend/src/components/UploadDialog.dom.test.tsx
+++ b/frontend/src/components/UploadDialog.dom.test.tsx
@@ -20,7 +20,11 @@ vi.mock("react-i18next", async (importOriginal) => {
 });
 vi.mock("../lib/api", () => ({ api: { uploadDownload: h.uploadDownload } }));
 vi.mock("../lib/downloads", () => ({ invalidateDownloads: vi.fn() }));
-vi.mock("../lib/notifications", () => ({ notify: h.notify }));
+// The rest of the module stays real: the dialog is a ui/Modal, which hosts its own toasts.
+vi.mock("../lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/notifications")>()),
+  notify: h.notify,
+}));
 vi.mock("../lib/nav", () => ({ navigateTo: vi.fn() }));
 
 import UploadDialog from "./UploadDialog";
diff --git a/frontend/src/components/ui/Modal.dom.test.tsx b/frontend/src/components/ui/Modal.dom.test.tsx
index ef886c69..7e5571ce 100644
--- a/frontend/src/components/ui/Modal.dom.test.tsx
+++ b/frontend/src/components/ui/Modal.dom.test.tsx
@@ -20,6 +20,7 @@ vi.mock("react-i18next", async (importOriginal) => {
 vi.mock("../../lib/history", () => ({ useBackToClose: () => {} }));
 
 import Modal from "./Modal";
+import { clearAll, notify } from "../../lib/notifications";
 
 // Fire a keydown on window (where Modal installs its handler), inside act.
 const press = (key: string, shiftKey = false) =>
@@ -91,6 +92,32 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
     expect(document.activeElement).toBe(screen.getByText("beta"));
   });
 
+  it("Tab reaches a toast shown inside the dialog, and wraps from it", () => {
+    // The dialog's toast host sits beside the panel; trapped to the panel, a toast's Undo or dismiss
+    // could not be reached from the keyboard at all.
+    render(
+      <Modal title="t" onClose={() => {}}>
+        <Body />
+      </Modal>,
+    );
+    act(() => void notify({ level: "info", message: "Saved" }));
+    try {
+      const dismissToast = screen.getByTitle("notifications.dismiss");
+      // The panel's last control is no longer the trap's edge: Tab carries on (natively) to the toast.
+      screen.getByText("beta").focus();
+      press("Tab");
+      expect(document.activeElement).toBe(screen.getByText("beta")); // not wrapped back to the top
+      // The toast is the edge now: past it, Tab wraps to the first control, and Shift+Tab reaches it.
+      dismissToast.focus();
+      press("Tab");
+      expect(document.activeElement).toBe(closeBtn());
+      press("Tab", true);
+      expect(document.activeElement).toBe(dismissToast);
+    } finally {
+      act(() => clearAll());
+    }
+  });
+
   it("Tab pulls focus back inside when it has escaped to the page behind", () => {
     const outside = document.createElement("button");
     document.body.appendChild(outside);
@@ -189,3 +216,22 @@ describe("Modal focus trap (raw jsdom — every offsetParent null)", () => {
     expect(document.activeElement).toBe(panelEl());
   });
 });
+
+describe("Modal — toasts raised while it is open", () => {
+  afterEach(() => {
+    cleanup();
+    act(() => clearAll());
+  });
+
+  it("shows them inside the dialog, above its scrim", () => {
+    // The app's Toaster is in a stacking context under this body-level portal: a failed share or
+    // rename was drawn under the scrim, and clicking it landed on the backdrop and closed the dialog.
+    render(
+      <Modal title="Share" onClose={() => {}}>
+        <Body />
+      </Modal>,
+    );
+    act(() => void notify({ level: "error", message: "Couldn't share it." }));
+    expect(screen.getByRole("dialog").textContent).toContain("Couldn't share it.");
+  });
+});
diff --git a/frontend/src/components/ui/Modal.tsx b/frontend/src/components/ui/Modal.tsx
index a38857bf..fa38737c 100644
--- a/frontend/src/components/ui/Modal.tsx
+++ b/frontend/src/components/ui/Modal.tsx
@@ -6,6 +6,7 @@ import { useBackToClose } from "../../lib/history";
 import { pushLayer, removeLayer, isTopmost } from "../../lib/layerStack";
 import { useFullscreenElement } from "../../lib/fullscreen";
 import { Button } from "./Button";
+import Toaster from "./Toaster";
 
 // Tabbable elements inside the dialog, in DOM order. `:not([tabindex="-1"])` drops programmatically
 // focusable-only nodes; the visibility filter (offsetParent) drops display:none ones (e.g. a
@@ -56,6 +57,7 @@ export default function Modal({
   // drag that begins inside the dialog (e.g. selecting text in an input) and is released out on
   // the backdrop wrongly dismisses — the click event bubbles to the common ancestor (the backdrop).
   const pressedOnBackdrop = useRef(false);
+  const rootRef = useRef<HTMLDivElement>(null);
 
   // Keep a stable handler across renders so the stack id is assigned once per mount.
   const onCloseRef = useRef(onClose);
@@ -74,7 +76,10 @@ export default function Modal({
       if (e.key === "Tab") {
         const panel = panelRef.current;
         if (!panel) return;
-        const items = focusablesIn(panel);
+        // The whole dialog, not just the panel: its toast host sits beside the panel (see ui/Toaster),
+        // and a toast's Undo or dismiss must be reachable from the keyboard like everything else.
+        const scope = rootRef.current ?? panel;
+        const items = focusablesIn(scope);
         const first = items[0];
         const last = items[items.length - 1];
         if (!first || !last) {
@@ -82,7 +87,7 @@ export default function Modal({
           return;
         }
         const active = document.activeElement;
-        if (!panel.contains(active) || active === panel) {
+        if (!scope.contains(active) || active === panel) {
           // Focus escaped the dialog, OR sits on the panel container itself (tabIndex=-1, reached by
           // clicking dialog dead space) — Node.contains(self) is true, so `active === panel` must be
           // checked explicitly or Shift+Tab from the panel would leak to the background. Pull it back.
@@ -119,6 +124,7 @@ export default function Modal({
   const top = placement === "top";
   return createPortal(
     <div
+      ref={rootRef}
       className={`fixed inset-0 z-overlay flex bg-black/70 overlay-backdrop ${
         drawer
           ? "justify-end"
@@ -161,6 +167,10 @@ export default function Modal({
         </div>
         <div className="px-5 pb-5">{children}</div>
       </div>
+      {/* Toasts raised while a dialog is open show inside it: the app's own host is under this
+          scrim, where a failed share or rename was unreadable and a click on it closed the dialog
+          (see ui/Toaster). */}
+      <Toaster overlay />
     </div>,
     fsRoot ?? document.body,
   );
diff --git a/frontend/src/components/ui/Toaster.dom.test.tsx b/frontend/src/components/ui/Toaster.dom.test.tsx
index ab67ce1b..ca13a1e0 100644
--- a/frontend/src/components/ui/Toaster.dom.test.tsx
+++ b/frontend/src/components/ui/Toaster.dom.test.tsx
@@ -20,7 +20,7 @@ afterEach(() => {
   act(() => clearAll());
 });
 
-const hosts = () => Array.from(document.querySelectorAll("[aria-live='polite']"));
+const hosts = () => Array.from(document.querySelectorAll("[aria-live]"));
 
 describe("Toaster — one host shows the toasts", () => {
   it("moves the toasts into an open overlay, and back when it closes", () => {
@@ -41,6 +41,7 @@ describe("Toaster — one host shows the toasts", () => {
     expect(screen.getByTestId("app").textContent).not.toContain("Couldn't remove the video.");
     // Both live regions stay mounted — a polite region has to pre-exist to be announced.
     expect(hosts()).toHaveLength(2);
+    expect(hosts().map((h) => h.getAttribute("aria-live"))).toEqual(["off", "polite"]);
 
     overlay.unmount();
     expect(screen.getByTestId("app").textContent).toContain("Couldn't remove the video.");
@@ -59,3 +60,43 @@ describe("Toaster — one host shows the toasts", () => {
     expect(backdrop).not.toHaveBeenCalled();
   });
 });
+
+describe("Toaster — handing the toasts to another host", () => {
+  it("does not announce the toasts it inherits again, only the ones that come after", () => {
+    // The new host gets them as NEW nodes: a screen reader read every one out again, an error
+    // assertively, each time a player (or any dialog) opened or closed.
+    render(<Toaster />);
+    act(() => void notify({ level: "error", message: "old news" }));
+    render(<Toaster overlay />);
+    const old = screen.getByText("old news").closest(".toast-card")!;
+    expect(old.getAttribute("role")).toBeNull();
+    act(() => void notify({ level: "error", message: "fresh" }));
+    expect(screen.getByText("fresh").closest(".toast-card")!.getAttribute("role")).toBe("alert");
+  });
+
+  it("keeps the countdown where it was, instead of starting it again from full", () => {
+    // The bar is a CSS animation on the node; the dismiss timer was armed once, at notify time. A
+    // new node restarted the bar, and the toast vanished with it still two-thirds full.
+    const t0 = Date.now();
+    const now = vi.spyOn(Date, "now").mockReturnValue(t0);
+    render(<Toaster />);
+    act(() => void notify({ level: "info", message: "saved" }));
+    now.mockReturnValue(t0 + 4000);
+    render(<Toaster overlay />);
+    const bar = screen.getByText("saved").closest(".toast-card")!.lastElementChild as HTMLElement;
+    expect(bar.style.animation).toContain("-4000ms");
+  });
+
+  it("keeps the players' control band free inside an overlay", () => {
+    // At the app's own spot (bottom-4) the stack sat on the Plex transport row and PlayerModal's
+    // docked bar, above them at z-overlay, and took their clicks for as long as a toast was up.
+    render(<Toaster overlay />);
+    act(() => void notify({ level: "error", message: "boom" }));
+    const host = hosts()[0]!;
+    expect(host.className).toContain("bottom-24");
+    expect(host.className).toContain("pointer-events-none");
+    expect(screen.getByText("boom").closest(".toast-card")!.className).toContain(
+      "pointer-events-auto",
+    );
+  });
+});
diff --git a/frontend/src/components/ui/Toaster.hosts.test.ts b/frontend/src/components/ui/Toaster.hosts.test.ts
new file mode 100644
index 00000000..874d03b0
--- /dev/null
+++ b/frontend/src/components/ui/Toaster.hosts.test.ts
@@ -0,0 +1,33 @@
+// Every full-screen overlay hosts its own toasts (see ui/Toaster).
+//
+// The app's Toaster lives in the content column, a stacking context: anything that covers the
+// viewport at z-overlay paints over it, so a toast raised while that overlay is open is unreadable and
+// a click on it lands on the overlay's backdrop. The fix is a convention — the overlay mounts
+// `<Toaster overlay />` inside itself — and a convention stated in a comment is one the next overlay
+// forgets (deep-review round 3 found every ui/Modal and the onboarding wizard without one). So it is
+// checked here: a component that renders a viewport-covering z-overlay layer mounts an overlay host.
+import { describe, it, expect } from "vitest";
+
+const sources = import.meta.glob("../**/*.tsx", { query: "?raw", import: "default", eager: true });
+
+// Covers the viewport for a moment with nothing a toast could be about (a lazy chunk's black
+// placeholder while the player loads).
+const EXEMPT = new Set(["../PlexBrowse.tsx"]);
+
+describe("full-screen overlays host their own toasts", () => {
+  it("every one that covers the viewport at z-overlay mounts <Toaster overlay />", () => {
+    const missing = Object.entries(sources)
+      .filter(([path]) => !path.endsWith(".test.tsx") && !EXEMPT.has(path))
+      .filter(([, src]) => /fixed inset-0 z-overlay/.test(src as string))
+      .filter(([, src]) => !(src as string).includes("<Toaster overlay />"))
+      .map(([path]) => path);
+    expect(missing).toEqual([]);
+  });
+
+  it("finds the overlays it is meant to check", () => {
+    const covered = Object.entries(sources).filter(([, src]) =>
+      /fixed inset-0 z-overlay/.test(src as string),
+    );
+    expect(covered.length).toBeGreaterThanOrEqual(3); // Modal, PlayerModal, the wizard at least
+  });
+});
diff --git a/frontend/src/components/ui/Toaster.tsx b/frontend/src/components/ui/Toaster.tsx
index 2720feeb..3e471194 100644
--- a/frontend/src/components/ui/Toaster.tsx
+++ b/frontend/src/components/ui/Toaster.tsx
@@ -1,7 +1,8 @@
-import { useEffect, useId, useSyncExternalStore } from "react";
+import { useEffect, useId, useMemo, useState, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { AlertCircle, AlertTriangle, CheckCircle2, Info, X, XCircle } from "lucide-react";
 import { dismiss, getActiveToasts, subscribe, type NotifLevel } from "../../lib/notifications";
+import { createStore } from "../../lib/store";
 
 export const LEVEL_STYLE: Record<NotifLevel, { icon: typeof Info; color: string; bar: string }> = {
   info: { icon: Info, color: "text-info", bar: "bg-info" },
@@ -12,22 +13,17 @@ export const LEVEL_STYLE: Record<NotifLevel, { icon: typeof Info; color: string;
 };
 
 // Overlay hosts. The app's own Toaster sits in the content column, and that column is a stacking
-// context (its `@container` implies layout containment) — so a full-screen player, portalled to
-// <body> at the same z-overlay, painted over every toast: a failure raised while watching was
-// drawn under an 80% black, blurred scrim, and a click on it closed the player. Such an overlay
-// mounts its OWN `<Toaster overlay />` inside itself instead, and exactly one host shows the
-// toasts: the most recently mounted overlay, else the app's. Same component, same look — and inside
-// the overlay's aria-modal dialog, where a screen reader can still reach it.
-let overlayHosts: string[] = [];
-const hostListeners = new Set<() => void>();
-const subscribeHosts = (l: () => void) => {
-  hostListeners.add(l);
-  return () => void hostListeners.delete(l);
-};
-const topHost = () => overlayHosts[overlayHosts.length - 1] ?? null;
-const setHosts = (next: string[]) => {
-  overlayHosts = next;
-  hostListeners.forEach((l) => l());
+// context (its `@container` implies layout containment) — so anything portalled to <body> at the
+// same z-overlay painted over every toast: a failure raised while watching was drawn under an 80%
+// black, blurred scrim, and a click on it closed the player. So every full-screen overlay mounts its
+// OWN `<Toaster overlay />` inside itself — ui/Modal does it for every dialog, the players for
+// themselves — and exactly one host shows the toasts: the most recently mounted overlay, else the
+// app's. Same component, same look — and inside the overlay's aria-modal dialog, where a screen
+// reader can still reach it.
+const overlayHosts = createStore<readonly string[]>([]);
+const topHost = () => {
+  const hosts = overlayHosts.get();
+  return hosts[hosts.length - 1] ?? null;
 };
 
 export default function Toaster({ overlay = false }: { overlay?: boolean }) {
@@ -35,23 +31,43 @@ export default function Toaster({ overlay = false }: { overlay?: boolean }) {
   const id = useId();
   useEffect(() => {
     if (!overlay) return;
-    setHosts([...overlayHosts, id]);
-    return () => setHosts(overlayHosts.filter((h) => h !== id));
+    overlayHosts.set((hosts) => [...hosts, id]);
+    return () => overlayHosts.set((hosts) => hosts.filter((h) => h !== id));
   }, [overlay, id]);
-  const top = useSyncExternalStore(subscribeHosts, topHost, topHost);
+  const top = useSyncExternalStore(overlayHosts.subscribe, topHost, topHost);
   const active = useSyncExternalStore(subscribe, getActiveToasts, getActiveToasts);
-  const toasts = top === (overlay ? id : null) ? active : [];
+  const isTop = top === (overlay ? id : null);
+  const toasts = isTop ? active : [];
+  // A host that takes over (an overlay opening, or the app's own once it closes) receives the toasts
+  // that were already up as NEW nodes — and a screen reader announced every one of them again, an
+  // error assertively. So the ones it inherits are shown silently: no `role="alert"`, and the region
+  // stays `aria-live="off"` until they are in, turning polite (for the toasts that come after) once
+  // they have been rendered.
+  const inherited = useMemo(
+    () => new Set(isTop ? getActiveToasts().map((n) => n.id) : []),
+    [isTop],
+  );
+  const [armed, setArmed] = useState(false);
+  useEffect(() => setArmed(isTop), [isTop]);
 
   return (
-    // Stable, always-mounted polite live region — a polite region must PRE-EXIST in the DOM for a
-    // screen reader to announce content later inserted into it (a region created together with its
-    // first message is unreliably announced). `aria-live` (not role="status") on purpose:
-    // role="status" implies aria-atomic="true", which would re-read the WHOLE stack on every toast;
-    // aria-live defaults atomic=false, so only the newly-added toast is spoken. Error/fatal toasts
-    // additionally carry role="alert", which announces assertively on insertion regardless.
+    // Stable, always-mounted live region — a polite region must PRE-EXIST in the DOM for a screen
+    // reader to announce content later inserted into it (a region created together with its first
+    // message is unreliably announced). `aria-live` (not role="status") on purpose: role="status"
+    // implies aria-atomic="true", which would re-read the WHOLE stack on every toast; aria-live
+    // defaults atomic=false, so only the newly-added toast is spoken. Error/fatal toasts additionally
+    // carry role="alert", which announces assertively on insertion regardless.
+    //
+    // Inside an overlay it sits ABOVE the bottom band: that is where the players keep their control
+    // bars (the Plex transport row, PlayerModal's docked bar), and the toast stack — on top of them at
+    // z-overlay, and catching the click — took play/pause, ±10, stop, prev/next and mute for as long
+    // as a toast was up (the connection notice: until the server answered). The same rung UpNextCard
+    // uses for the same reason. Clicks between the cards go through to what is underneath.
     <div
-      aria-live="polite"
-      className="absolute bottom-4 left-4 z-overlay flex flex-col gap-2 w-80 max-w-[calc(100vw-2rem)]"
+      aria-live={isTop && armed ? "polite" : "off"}
+      className={`absolute left-4 z-overlay flex flex-col gap-2 w-80 max-w-[calc(100vw-2rem)] ${
+        overlay ? "bottom-24 pointer-events-none" : "bottom-4"
+      }`}
       // Inside an overlay, a click on a toast is not a click on the overlay's backdrop.
       onClick={overlay ? (e) => e.stopPropagation() : undefined}
     >
@@ -61,8 +77,8 @@ export default function Toaster({ overlay = false }: { overlay?: boolean }) {
         return (
           <div
             key={toast.id}
-            role={urgent ? "alert" : undefined}
-            className="toast-card glass relative overflow-hidden rounded-xl px-3 py-3 flex items-start gap-3 animate-[popIn_0.16s_ease]"
+            role={urgent && !inherited.has(toast.id) ? "alert" : undefined}
+            className="toast-card glass pointer-events-auto relative overflow-hidden rounded-xl px-3 py-3 flex items-start gap-3 animate-[popIn_0.16s_ease]"
           >
             <Icon className={`w-5 h-5 shrink-0 mt-0.5 ${color}`} />
             <div className="min-w-0 flex-1">
@@ -95,10 +111,8 @@ export default function Toaster({ overlay = false }: { overlay?: boolean }) {
               <X className="w-4 h-4" />
             </button>
             {toast.duration && (
-              <div
-                className={`absolute left-0 bottom-0 h-0.5 w-full origin-left ${bar}`}
-                style={{ animation: `toastbar ${toast.duration}ms linear forwards` }}
-              />
+              // Keyed by `ts`: a coalesced repeat re-arms the dismiss timer, so its bar restarts too.
+              <CountdownBar key={toast.ts} since={toast.ts} duration={toast.duration} bar={bar} />
             )}
           </div>
         );
@@ -106,3 +120,17 @@ export default function Toaster({ overlay = false }: { overlay?: boolean }) {
     </div>
   );
 }
+
+/** The auto-dismiss countdown, started as far in as the toast already is. A toast handed to another
+ *  host is a new node, and its bar used to start again from full while the dismiss timer — armed
+ *  once, at notify time — did not: the toast vanished with the bar still two-thirds full. The offset
+ *  is taken once, at mount; recomputed on a later render it would jump the running animation ahead. */
+function CountdownBar({ since, duration, bar }: { since: number; duration: number; bar: string }) {
+  const [elapsed] = useState(() => Math.min(duration, Math.max(0, Date.now() - since)));
+  return (
+    <div
+      className={`absolute left-0 bottom-0 h-0.5 w-full origin-left ${bar}`}
+      style={{ animation: `toastbar ${duration}ms linear -${elapsed}ms forwards` }}
+    />
+  );
+}

From 1cfe6a7f5953a21ca3717c09db73dd8a8fb30814 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:05:19 +0200
Subject: [PATCH 26/52] fix(api): a gone row and a refused playlist action are
 said in the reader's language, and a failure is reported once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09.

- get_or_404 / owned_or_404 answer a structured {code: "not_found", reason: <what>}
  (errors.notFound.* in HU+EN, generic fallback). The structured-404 fix of round 2 had gone into the
  ad-hoc `_own_playlist` (CLAUDE.md's "Not" pattern) while the shared helpers stayed string-only, so
  views, tags, pins, Plex playlists, invites and users still 404'd in English. `_own_playlist` now
  goes through owned_or_404; admin's hand-rolled user lookups use get_or_404.
- A move into a list that is gone names the TARGET (reason "move_target") — "this playlist doesn't
  exist any more" was read as the list on screen, which still exists.
- Every refusal in the playlists router is a {code: "playlist", reason} (playlists.errors.* HU+EN)
  instead of a bare English string shown verbatim in the Hungarian UI.
- `req` / `uploadReq` mark the errors they already put on screen (the error dialog, the connection
  notice, the 401 sign-out), and notifyActionError skips those. The watched toggles, the saved views
  and a playlist delete toasted a fault the dialog was already showing; Playlists' two hand-written
  status filters now go through the same check.
---
 backend/app/routes/_common.py                 | 18 +++--
 backend/app/routes/admin.py                   | 26 +++----
 backend/app/routes/channels.py                |  2 +-
 backend/app/routes/discover.py                |  2 +-
 backend/app/routes/playlists.py               | 61 ++++++++--------
 backend/app/routes/plex/playlists.py          |  2 +-
 backend/app/routes/saved_views.py             |  2 +-
 backend/app/routes/tags.py                    |  2 +-
 backend/tests/test_not_found_detail.py        | 20 ++++++
 backend/tests/test_playlist_move.py           | 40 ++++++++++-
 frontend/src/components/Playlists.tsx         | 20 +++---
 .../usePlaylistActions.dom.test.tsx           | 69 +++++++++++++++++++
 frontend/src/components/usePlaylistActions.ts | 18 ++---
 frontend/src/i18n/locales/en/errors.json      | 11 +++
 frontend/src/i18n/locales/en/playlists.json   |  9 ++-
 frontend/src/i18n/locales/hu/errors.json      | 11 +++
 frontend/src/i18n/locales/hu/playlists.json   |  9 ++-
 frontend/src/lib/actionErrors.test.ts         | 26 ++++++-
 frontend/src/lib/actionErrors.ts              |  8 ++-
 frontend/src/lib/api.ts                       |  2 +
 frontend/src/lib/api/core.test.ts             | 59 +++++++++++++++-
 frontend/src/lib/api/core.ts                  | 35 ++++++++--
 22 files changed, 358 insertions(+), 94 deletions(-)
 create mode 100644 backend/tests/test_not_found_detail.py
 create mode 100644 frontend/src/components/usePlaylistActions.dom.test.tsx

diff --git a/backend/app/routes/_common.py b/backend/app/routes/_common.py
index 32590e7b..7223ce93 100644
--- a/backend/app/routes/_common.py
+++ b/backend/app/routes/_common.py
@@ -17,12 +17,20 @@ from app.models import User
 M = TypeVar("M", bound=Base)
 
 
-def get_or_404(db: Session, model: type[M], id_: Any, *, detail: str = "Not found") -> M:
+def not_found(what: str = "generic") -> HTTPException:
+    """The 404 for a row that is gone — structured, so the bilingual UI says it in the reader's
+    language (`errors.notFound.<what>`, generic fallback). This is the 404 a user actually meets: the
+    thing was deleted in another tab or on another device. It used to be a bare English string
+    ("Unknown view", "Not found"), which the Hungarian UI toasted verbatim."""
+    return HTTPException(status_code=404, detail={"code": "not_found", "reason": what})
+
+
+def get_or_404(db: Session, model: type[M], id_: Any, *, what: str = "generic") -> M:
     """Fetch a row by primary key or raise 404. Replaces the `db.get(Model, id); if None: 404`
     idiom repeated across routes."""
     obj = db.get(model, id_)
     if obj is None:
-        raise HTTPException(status_code=404, detail=detail)
+        raise not_found(what)
     return obj
 
 
@@ -33,13 +41,13 @@ def owned_or_404(
     user: User,
     *,
     owner_attr: str = "user_id",
-    detail: str = "Not found",
+    what: str = "generic",
 ) -> M:
     """Fetch a row by primary key that `user` owns, or raise 404. A row owned by someone
     else 404s (NOT 403) on purpose — a 403 would confirm the id exists to a stranger.
     Generalizes the near-identical per-route ownership helpers (e.g. plex's
     `_own_playlist_or_404`, the saved-views owner check)."""
-    obj = get_or_404(db, model, id_, detail=detail)
+    obj = get_or_404(db, model, id_, what=what)
     if getattr(obj, owner_attr) != user.id:
-        raise HTTPException(status_code=404, detail=detail)
+        raise not_found(what)
     return obj
diff --git a/backend/app/routes/admin.py b/backend/app/routes/admin.py
index b9b3a04f..86ad5ade 100644
--- a/backend/app/routes/admin.py
+++ b/backend/app/routes/admin.py
@@ -173,7 +173,7 @@ def _activate_user_by_email(db: Session, email: str) -> None:
 
 
 def _decide(db: Session, invite_id: int, admin: User, approved: bool) -> Invite:
-    inv = get_or_404(db, Invite, invite_id, detail="No such invite")
+    inv = get_or_404(db, Invite, invite_id, what="invite")
     # Idempotency guard: only a still-pending invite can be decided. Without this a repeat/stale
     # approve or deny re-runs its side effects — re-activating a user, or (now that deny emails)
     # sending a duplicate decision mail, even flipping an already-approved invite to "denied" and
@@ -291,7 +291,7 @@ def send_invitation(
 
     Only an APPROVED row can be invited: there is nothing to invite someone to while their request is
     undecided, and inviting a denied address would contradict the decision."""
-    inv = get_or_404(db, Invite, invite_id, detail="No such invite")
+    inv = get_or_404(db, Invite, invite_id, what="invite")
     if inv.status != "approved":
         raise HTTPException(
             status_code=409,
@@ -364,7 +364,7 @@ def delete_invite(
     falls back to the env ALLOWED_EMAILS / ADMIN_EMAILS bootstrap lists once no invite exists, so for
     an address on those the deletion leaves access intact (and an ADMIN_EMAILS address is still
     promoted to admin on its next Google sign-in). The admin has to hear that, not guess it."""
-    inv = get_or_404(db, Invite, invite_id, detail="No such invite")
+    inv = get_or_404(db, Invite, invite_id, what="invite")
     if _accounts_for(db, [inv.email]):
         raise HTTPException(
             status_code=409,
@@ -434,9 +434,7 @@ def set_user_role(
     role = body.role
     if role not in ("user", "admin"):
         raise HTTPException(status_code=400, detail="role must be 'user' or 'admin'")
-    target = db.get(User, user_id)
-    if target is None:
-        raise HTTPException(status_code=404, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
         raise HTTPException(status_code=400, detail="The demo account's role can't be changed.")
     if target.id == admin.id:
@@ -491,9 +489,7 @@ def set_user_suspended(
     un-suspend the user is emailed they can return (suspend is announced reactively, on a blocked
     sign-in)."""
     suspended = body.suspended
-    target = db.get(User, user_id)
-    if target is None:
-        raise HTTPException(status_code=404, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
         raise HTTPException(status_code=400, detail="The demo account can't be suspended.")
     if target.id == admin.id:
@@ -537,9 +533,7 @@ def admin_delete_user(
     """Admin-triggered account deletion — the same full erasure a user can perform on themselves
     (cascade delete of all personal data + access-request cleanup + Google-grant revoke). Guards:
     not the demo account, not yourself (use Settings → Account), and not the last admin."""
-    target = db.get(User, user_id)
-    if target is None:
-        raise HTTPException(status_code=404, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
         raise HTTPException(status_code=400, detail="The demo account can't be deleted.")
     if target.id == admin.id:
@@ -632,7 +626,7 @@ def user_access(
     Its own endpoint rather than extra columns on /users: `is_allowed` and `can_activate` each run a
     query, and the panel opens for ONE user at a time — folding them into the list would pay that cost
     per row on every load to answer a question nobody asked yet."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     return _serialize_user(target) | {
         "is_allowed": is_allowed(db, target.email),
         "can_activate": can_activate(db, target),
@@ -657,7 +651,7 @@ def create_set_password_link(
     an instance with no mail — narrowing it to one of those would only make the admin's real case the
     one it refuses. The demo account is the single exception: it is shared, so handing anyone a way to
     change its password is handing them everyone else's session."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
         raise HTTPException(
             status_code=400, detail={"code": "setpw", "reason": "demo", "email": target.email}
@@ -693,7 +687,7 @@ def activate_user(
     This endpoint changes nothing about what an unauthenticated caller can cause — the admin could
     already do exactly this by re-entering the address in the whitelist box (`add_invite` →
     `_activate_user_by_email`). What was missing was any way to know they had to."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     if target.is_demo:
         raise HTTPException(status_code=400, detail="The demo account can't be activated.")
     if target.is_active:
@@ -732,7 +726,7 @@ def resend_user_verification(
 
     Not rate-limited: an admin is not a threat model to enumerate against, and the deliberate silence
     of the public endpoint is exactly what this exists to escape."""
-    target = get_or_404(db, User, user_id, detail="No such user")
+    target = get_or_404(db, User, user_id, what="user")
     if target.is_demo or target.email_verified:
         raise HTTPException(
             status_code=409,
diff --git a/backend/app/routes/channels.py b/backend/app/routes/channels.py
index d848d6cd..f2c28603 100644
--- a/backend/app/routes/channels.py
+++ b/backend/app/routes/channels.py
@@ -706,7 +706,7 @@ def attach_tag(
     _user_subscription(db, user, channel_id)
     # Only the user's own tags may be attached as personal links (owned_or_404 → 404 if the tag
     # is missing OR belongs to someone else, without leaking which).
-    owned_or_404(db, Tag, body.tag_id, user, detail="Unknown tag")
+    owned_or_404(db, Tag, body.tag_id, user, what="tag")
     exists = db.execute(
         select(ChannelTag).where(
             ChannelTag.channel_id == channel_id,
diff --git a/backend/app/routes/discover.py b/backend/app/routes/discover.py
index f029f0e2..e7447c09 100644
--- a/backend/app/routes/discover.py
+++ b/backend/app/routes/discover.py
@@ -168,7 +168,7 @@ def remove_pin(
     user: User = Depends(require_human),
     db: Session = Depends(get_db),
 ) -> dict:
-    pin = owned_or_404(db, ComfortPin, pin_id, user)
+    pin = owned_or_404(db, ComfortPin, pin_id, user, what="pin")
     db.delete(pin)
     db.commit()
     return {"deleted": pin_id}
diff --git a/backend/app/routes/playlists.py b/backend/app/routes/playlists.py
index 1051ddcb..a7083c95 100644
--- a/backend/app/routes/playlists.py
+++ b/backend/app/routes/playlists.py
@@ -23,6 +23,7 @@ from app.sync.playlists import (
     sync_user_playlists,
 )
 from app.ratelimit import RateLimiter
+from app.routes._common import not_found, owned_or_404
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -48,13 +49,13 @@ def _check_pull_cooldown(user: User) -> None:
 
 
 def _own_playlist(db: Session, user: User, playlist_id: int) -> Playlist:
-    pl = db.get(Playlist, playlist_id)
-    if pl is None or pl.user_id != user.id:
-        # Structured, so the UI can say it in the reader's language: this 404 is exactly the one a
-        # user meets in practice (the list was deleted in another tab), and a bare "Unknown
-        # playlist" reached the Hungarian UI in English. One reason for "gone" and "not yours" alike.
-        raise HTTPException(status_code=404, detail={"code": "playlist", "reason": "not_found"})
-    return pl
+    return owned_or_404(db, Playlist, playlist_id, user, what="playlist")
+
+
+def _refused(status: int, reason: str) -> HTTPException:
+    """A playlist action the server refuses, as a reason the UI translates
+    (`playlists.errors.<reason>`) — a bare English detail reached the Hungarian UI verbatim."""
+    return HTTPException(status_code=status, detail={"code": "playlist", "reason": reason})
 
 
 def _touch(pl: Playlist) -> None:
@@ -259,7 +260,7 @@ def create_playlist(
 ) -> dict:
     name = body.name.strip()
     if not name:
-        raise HTTPException(status_code=400, detail="name is required")
+        raise _refused(400, "name_required")
     pl = Playlist(user_id=user.id, name=name, position=_next_playlist_position(db, user.id))
     db.add(pl)
     db.commit()
@@ -292,7 +293,7 @@ def add_watch_later(
     """Bookmark shortcut: add a video to the built-in Watch later playlist."""
     video_id = body.video_id
     if db.get(Video, video_id) is None:
-        raise HTTPException(status_code=404, detail="Unknown video")
+        raise not_found("video")
     pl = _watch_later(db, user)
     _add_item(db, pl, video_id, mark_dirty=False)
     return {"saved": True, "playlist_id": pl.id}
@@ -320,10 +321,7 @@ def sync_youtube(
     """Pull the user's YouTube playlists into local mirrors now (read-only direction).
     Also runs automatically on the scheduler; this is the manual 'sync now'."""
     if not has_read_scope(user):
-        raise HTTPException(
-            status_code=403,
-            detail="Connect YouTube (read access) to sync your playlists.",
-        )
+        raise _refused(403, "youtube_read_scope")
     _check_pull_cooldown(user)
     with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
         return sync_user_playlists(db, user)
@@ -340,18 +338,16 @@ def revert_youtube(
     once the in-session undo history is gone."""
     pl = _own_playlist(db, user, playlist_id)
     if not pl.yt_playlist_id:
-        raise HTTPException(status_code=400, detail="This playlist isn't linked to YouTube.")
+        raise _refused(400, "not_on_youtube")
     if not has_read_scope(user):
-        raise HTTPException(
-            status_code=403, detail="Connect YouTube (read access) to sync your playlists."
-        )
+        raise _refused(403, "youtube_read_scope")
     _check_pull_cooldown(user)
     try:
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PULL):
             return repull_playlist(db, user, pl)
     except YouTubeError:
         db.rollback()
-        raise HTTPException(status_code=422, detail="Couldn't refresh from YouTube.")
+        raise _refused(422, "youtube_failed")
 
 
 def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
@@ -359,9 +355,7 @@ def _pushable(db: Session, user: User, playlist_id: int) -> Playlist:
     Watch later and read-only YouTube mirrors are never pushable."""
     pl = _own_playlist(db, user, playlist_id)
     if pl.kind == "watch_later":
-        raise HTTPException(
-            status_code=400, detail="The Watch later list can't be sent to YouTube."
-        )
+        raise _refused(400, "watch_later_not_pushable")
     return pl
 
 
@@ -379,7 +373,7 @@ def push_plan(
         with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_PUSH):
             plan = plan_merge(db, user, pl)
     except YouTubeError:
-        raise HTTPException(status_code=422, detail="Couldn't read the playlist on YouTube.")
+        raise _refused(422, "youtube_failed")
     plan["remaining_today"] = quota.remaining_today(db)
     plan["affordable"] = plan["units_estimate"] <= plan["remaining_today"]
     return plan
@@ -409,14 +403,11 @@ def push(
                     )
             plan = plan_merge(db, user, pl, live=live)
             if plan["units_estimate"] > quota.remaining_today(db):
-                raise HTTPException(
-                    status_code=429,
-                    detail="Not enough YouTube quota left today for this sync.",
-                )
+                raise _refused(429, "quota_exceeded")
             return merge_playlist(db, user, pl, live=live)
     except YouTubeError:
         db.rollback()
-        raise HTTPException(status_code=422, detail="YouTube playlist sync failed.")
+        raise _refused(422, "youtube_failed")
 
 
 @router.get("/{playlist_id}")
@@ -461,7 +452,7 @@ def rename_playlist(
     if "name" in body.model_fields_set:
         name = (body.name or "").strip()
         if not name:
-            raise HTTPException(status_code=400, detail="name cannot be empty")
+            raise _refused(400, "name_required")
         if name != pl.name:
             pl.name = name
             recompute_dirty(db, pl)
@@ -496,18 +487,18 @@ def delete_playlist(
 ) -> dict:
     pl = _own_playlist(db, user, playlist_id)
     if pl.kind == "watch_later":
-        raise HTTPException(status_code=400, detail="The Watch later list can't be deleted.")
+        raise _refused(400, "watch_later_undeletable")
     if on_youtube:
         if not pl.yt_playlist_id:
-            raise HTTPException(status_code=400, detail="This playlist isn't on YouTube.")
+            raise _refused(400, "not_on_youtube")
         if not has_write_scope(user):
-            raise HTTPException(status_code=403, detail="Enable YouTube editing in Settings first.")
+            raise _refused(403, "youtube_editing_off")
         try:
             with quota.attribute(user.id, quota.QuotaAction.PLAYLISTS_DELETE):
                 with YouTubeClient(db, user) as yt:
                     yt.delete_playlist(pl.yt_playlist_id)
         except YouTubeError:
-            raise HTTPException(status_code=422, detail="YouTube delete failed.")
+            raise _refused(422, "youtube_failed")
     db.delete(pl)  # items cascade
     db.commit()
     return {"deleted": playlist_id}
@@ -523,7 +514,7 @@ def add_item(
     pl = _own_playlist(db, user, playlist_id)
     video_id = body.video_id
     if db.get(Video, video_id) is None:
-        raise HTTPException(status_code=404, detail="Unknown video")
+        raise not_found("video")
     _add_item(db, pl, video_id, mark_dirty=True)
     return {"playlist_id": pl.id, "video_id": video_id}
 
@@ -560,7 +551,9 @@ def move_item(
     case. Idempotent: if the video is already in the target, the source row is simply dropped
     (moving into a list that already has it is a removal, not a duplicate)."""
     src = _own_playlist(db, user, playlist_id)
-    dst = _own_playlist(db, user, body.target_playlist_id)
+    # Its own reason: "this playlist doesn't exist any more" about a TARGET that is gone was read as
+    # the list on screen — which is still there.
+    dst = owned_or_404(db, Playlist, body.target_playlist_id, user, what="move_target")
     if src.id == dst.id:
         raise HTTPException(
             status_code=400, detail={"code": "playlist_move", "reason": "same_playlist"}
diff --git a/backend/app/routes/plex/playlists.py b/backend/app/routes/plex/playlists.py
index 81739a34..022af3ae 100644
--- a/backend/app/routes/plex/playlists.py
+++ b/backend/app/routes/plex/playlists.py
@@ -25,7 +25,7 @@ router = APIRouter(prefix="/api/plex", tags=["plex"])
 
 
 def _own_playlist_or_404(db: Session, pid: int, user: User) -> PlexPlaylist:
-    return owned_or_404(db, PlexPlaylist, pid, user, detail="Playlist not found")
+    return owned_or_404(db, PlexPlaylist, pid, user, what="playlist")
 
 
 def _playlist_card(pl: PlexPlaylist, count: int, thumb_rk: str | None) -> dict:
diff --git a/backend/app/routes/saved_views.py b/backend/app/routes/saved_views.py
index 4ac5b835..e2d6f68e 100644
--- a/backend/app/routes/saved_views.py
+++ b/backend/app/routes/saved_views.py
@@ -91,7 +91,7 @@ def create_view(
 
 
 def _own_view(db: Session, user: User, view_id: int) -> SavedView:
-    return owned_or_404(db, SavedView, view_id, user, detail="Unknown view")
+    return owned_or_404(db, SavedView, view_id, user, what="view")
 
 
 class UpdateViewIn(BaseModel):
diff --git a/backend/app/routes/tags.py b/backend/app/routes/tags.py
index 0000cb7c..d5b8c8d8 100644
--- a/backend/app/routes/tags.py
+++ b/backend/app/routes/tags.py
@@ -80,7 +80,7 @@ def create_tag(
 
 def _own_tag(db: Session, user: User, tag_id: int) -> Tag:
     # System tags (user_id NULL) are not user-editable → owned_or_404 404s them too.
-    return owned_or_404(db, Tag, tag_id, user, detail="Unknown tag")
+    return owned_or_404(db, Tag, tag_id, user, what="tag")
 
 
 class TagUpdateIn(BaseModel):
diff --git a/backend/tests/test_not_found_detail.py b/backend/tests/test_not_found_detail.py
new file mode 100644
index 00000000..c5eb78a2
--- /dev/null
+++ b/backend/tests/test_not_found_detail.py
@@ -0,0 +1,20 @@
+"""A row that is gone answers with a reason the bilingual UI can translate (deep-review round 3).
+
+The 404 a user actually meets is the one for something deleted in another tab or on another device.
+`owned_or_404` / `get_or_404` sent it as a bare English string ("Unknown view", "Not found"), and the
+Hungarian UI toasted it verbatim. The structured-404 fix had gone into one ad-hoc helper instead of
+the shared one, so every other owner check kept the English. Needs the DB.
+"""
+
+
+def test_a_gone_view_tag_or_pin_says_what_is_gone(db, make_user, as_user):
+    client = as_user(make_user())
+    for method, url, what in [
+        ("patch", "/api/saved-views/999999", "view"),
+        ("delete", "/api/saved-views/999999", "view"),
+        ("delete", "/api/tags/999999", "tag"),
+        ("delete", "/api/discover/pins/999999", "pin"),
+    ]:
+        r = getattr(client, method)(url, **({"json": {"name": "x"}} if method == "patch" else {}))
+        assert r.status_code == 404, (url, r.text)
+        assert r.json()["detail"] == {"code": "not_found", "reason": what}, url
diff --git a/backend/tests/test_playlist_move.py b/backend/tests/test_playlist_move.py
index 027f0606..9a936d32 100644
--- a/backend/tests/test_playlist_move.py
+++ b/backend/tests/test_playlist_move.py
@@ -139,11 +139,49 @@ def test_a_list_that_is_not_yours_answers_with_a_reason_the_ui_can_translate(
 
     r = as_user(user).delete(f"/api/playlists/{theirs.id}/items/v1")
     assert r.status_code == 404
-    assert r.json()["detail"] == {"code": "playlist", "reason": "not_found"}
+    assert r.json()["detail"] == {"code": "not_found", "reason": "playlist"}
     db.expire_all()
     assert _ids(db, theirs.id) == ["v1"]
 
 
+def test_a_move_into_a_list_that_is_gone_names_the_target_not_the_list_on_screen(
+    db, make_user, as_user
+):
+    # Both lists 404'd with the same reason, which the UI reads as "THIS playlist doesn't exist any
+    # more" — said about the source the reader is looking at, which is still there.
+    user = make_user()
+    _seed_videos(db, ["v1"])
+    src = _playlist(db, user, "Mine", ["v1"])
+    gone = _playlist(db, user, "Gone", [])
+    gone_id = gone.id
+    db.delete(gone)
+    db.commit()
+
+    r = _move(as_user(user), src.id, "v1", gone_id)
+    assert r.status_code == 404
+    assert r.json()["detail"] == {"code": "not_found", "reason": "move_target"}
+    db.expire_all()
+    assert _ids(db, src.id) == ["v1"]
+
+
+def test_a_refused_playlist_action_answers_with_a_reason_the_ui_can_translate(
+    db, make_user, as_user
+):
+    # The rest of the router's refusals were bare English too ("The Watch later list can't be
+    # deleted.", "YouTube delete failed.", ...), shown verbatim under the Hungarian UI.
+    user = make_user()
+    client = as_user(user)
+    wl = client.post("/api/playlists/watch-later", json={"video_id": "nope"})
+    assert wl.status_code == 404
+    assert wl.json()["detail"] == {"code": "not_found", "reason": "video"}
+    _seed_videos(db, ["v1"])
+    saved = client.post("/api/playlists/watch-later", json={"video_id": "v1"})
+    wl_id = saved.json()["playlist_id"]
+    r = client.delete(f"/api/playlists/{wl_id}")
+    assert r.status_code == 400
+    assert r.json()["detail"] == {"code": "playlist", "reason": "watch_later_undeletable"}
+
+
 def test_move_marks_both_linked_sides_dirty(db, make_user, as_user):
     """A move edits two YouTube mirrors at once — the source lost an item, the target gained one.
     Marking only the source is the asymmetric fix this repo keeps re-learning."""
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 0c6641ab..b006635a 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -40,7 +40,7 @@ import {
   X,
   Youtube,
 } from "lucide-react";
-import { api, HttpError, type Playlist, type PlaylistDetail, type Video } from "../lib/api";
+import { api, type Playlist, type PlaylistDetail, type Video } from "../lib/api";
 import { notify } from "../lib/notifications";
 import { notifyActionError } from "../lib/actionErrors";
 import { notifyYouTubeActionError } from "../lib/youtubeErrors";
@@ -576,12 +576,10 @@ export default function Playlists() {
       refreshAll(listId);
       return true;
     } catch (e) {
-      // `req` raises the global dialog for 4xx-validation and 5xx, but leaves 403/404 to the caller
-      // (the list was deleted or de-owned meanwhile) — so say it here, as moveItemTo does, or a
-      // confirmed removal fails in silence (inside the full-screen player there is not even a row
-      // snapping back to show it).
-      if (e instanceof HttpError && (e.status === 404 || e.status === 403))
-        notifyActionError(e, t("playlists.removeFailed"));
+      // Said here, as moveItemTo does, or a confirmed removal fails in silence (inside the
+      // full-screen player there is not even a row snapping back to show it) — unless `req` already
+      // said it (the error dialog, the connection notice), which `notifyActionError` checks.
+      notifyActionError(e, t("playlists.removeFailed"));
       refreshAll(listId); // …and resync, which restores any row the optimistic removal took out
       return false;
     }
@@ -613,11 +611,9 @@ export default function Playlists() {
       // every move failure a user can actually reach is a 404 (the 400 `same_playlist` case is already
       // impossible — the submenu never offers the current list). So the row used to snap back with no
       // explanation and the shipped moveErrors strings were unreachable (E10 review round 1).
-      // ONLY the statuses `req` deliberately leaves to the caller. It already opens the blocking
-      // error dialog for 400/409/422 and 5xx and raises the connectivity notice for a bad gateway,
-      // so toasting unconditionally reported a transport fault twice (E10 review round 2).
-      if (e instanceof HttpError && (e.status === 404 || e.status === 403))
-        notifyActionError(e, t("playlists.moveFailed"));
+      // A fault `req` already reported (the error dialog, the connection notice) is not toasted
+      // again — `notifyActionError` checks (E10 review round 2 found it reported twice).
+      notifyActionError(e, t("playlists.moveFailed"));
     }
     // BOTH sides changed, and so did this video's membership. `qk.playlist(selectedId)` is an exact
     // key, so it cannot cover the target — invalidate the whole `["playlist"]` prefix, exactly as
diff --git a/frontend/src/components/usePlaylistActions.dom.test.tsx b/frontend/src/components/usePlaylistActions.dom.test.tsx
new file mode 100644
index 00000000..32f43c3c
--- /dev/null
+++ b/frontend/src/components/usePlaylistActions.dom.test.tsx
@@ -0,0 +1,69 @@
+// @vitest-environment jsdom
+//
+// A failed playlist delete is reported once (deep-review round 3 of bug hunt 2026-09). `req` already
+// opens the blocking error dialog for a 422 (a YouTube-side delete failure) and a 5xx; the delete
+// then toasted the same failure as well — in English, before the router's errors were structured.
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, act, cleanup } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+
+const h = vi.hoisted(() => ({ notify: vi.fn(), reportError: vi.fn() }));
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
+});
+vi.mock("../lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/notifications")>()),
+  notify: (...a: unknown[]) => h.notify(...a),
+}));
+vi.mock("../lib/errorDialog", () => ({ reportError: (...a: unknown[]) => h.reportError(...a) }));
+vi.mock("./ConfirmProvider", () => ({ useChoice: () => async () => "both" }));
+vi.mock("./PlaylistsProvider", () => ({
+  usePlaylists: () => ({ selectedId: null }),
+  usePlaylistsActions: () => ({ setSelectedId: () => {} }),
+}));
+vi.mock("../lib/useMe", () => ({ useMe: () => ({ can_write: true }) }));
+
+import { usePlaylistActions } from "./usePlaylistActions";
+import { HttpError, api } from "../lib/api";
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  h.notify.mockReset();
+  h.reportError.mockReset();
+});
+
+function mount() {
+  const qc = new QueryClient();
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
+  );
+  return renderHook(() => usePlaylistActions(), { wrapper });
+}
+
+const linked = { id: 4, name: "Mix", kind: "user", yt_playlist_id: "PL1" } as const;
+
+describe("usePlaylistActions — deleting a list", () => {
+  it("does not toast a failure the request layer already put on screen", async () => {
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: { code: "playlist", reason: "youtube_failed" } }), {
+        status: 422,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    const { result } = mount();
+    await act(() => result.current.remove(linked));
+    expect(h.reportError).toHaveBeenCalledTimes(1);
+    expect(h.notify).not.toHaveBeenCalled();
+  });
+
+  it("does say one it was left to handle", async () => {
+    vi.spyOn(api, "deletePlaylist").mockRejectedValue(new HttpError(404, "gone"));
+    const { result } = mount();
+    await act(() => result.current.remove(linked));
+    expect(h.notify).toHaveBeenCalledWith(expect.objectContaining({ message: "gone" }));
+  });
+});
diff --git a/frontend/src/components/usePlaylistActions.ts b/frontend/src/components/usePlaylistActions.ts
index 4b4a64d4..541f376e 100644
--- a/frontend/src/components/usePlaylistActions.ts
+++ b/frontend/src/components/usePlaylistActions.ts
@@ -1,7 +1,7 @@
 import { useQueryClient } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
 import { qk } from "../lib/queryKeys";
-import { api, HttpError, type Playlist } from "../lib/api";
+import { alreadyReported, api, HttpError, type Playlist } from "../lib/api";
 import { notify } from "../lib/notifications";
 import { notifyYouTubeActionError } from "../lib/youtubeErrors";
 import { playlistName } from "../lib/playlistName";
@@ -70,13 +70,15 @@ export function usePlaylistActions() {
       await api.deletePlaylist(pl.id, onYoutube);
     } catch (err) {
       // Prefer the server's specific reason (e.g. a local vs YouTube-side failure) over a blanket
-      // "couldn't delete on YouTube" that misleads when the failure wasn't the YouTube side.
-      notify({
-        level: "warning",
-        message:
-          (err instanceof HttpError && err.detail) ||
-          (onYoutube ? t("playlists.deleteYtFailed") : t("playlists.deleteFailed")),
-      });
+      // "couldn't delete on YouTube" that misleads when the failure wasn't the YouTube side — unless
+      // `req` already put it on screen (the error dialog, the connection notice): not twice.
+      if (!alreadyReported(err))
+        notify({
+          level: "warning",
+          message:
+            (err instanceof HttpError && err.detail) ||
+            (onYoutube ? t("playlists.deleteYtFailed") : t("playlists.deleteFailed")),
+        });
     }
     qc.removeQueries({ queryKey: qk.playlist(pl.id) });
     qc.invalidateQueries({ queryKey: qk.playlists() });
diff --git a/frontend/src/i18n/locales/en/errors.json b/frontend/src/i18n/locales/en/errors.json
index d595a028..2d1b8388 100644
--- a/frontend/src/i18n/locales/en/errors.json
+++ b/frontend/src/i18n/locales/en/errors.json
@@ -4,6 +4,17 @@
   "validation": "Some of the values you entered weren't valid. Please check them and try again.",
   "server": "Server error",
   "syncCooldown": "You've synced a few times just now — give it a few minutes. The YouTube budget is shared with everyone on this instance, and background syncing keeps running either way.",
+  "notFound": {
+    "generic": "This item doesn't exist any more.",
+    "view": "This view doesn't exist any more.",
+    "tag": "This tag doesn't exist any more.",
+    "pin": "This isn't on your comfort shelf any more.",
+    "playlist": "This playlist doesn't exist any more.",
+    "move_target": "The playlist you're moving it to doesn't exist any more.",
+    "video": "This video isn't in the library any more.",
+    "invite": "This invite doesn't exist any more.",
+    "user": "This user doesn't exist any more."
+  },
   "ok": "OK",
   "offline": {
     "title": "Connection lost",
diff --git a/frontend/src/i18n/locales/en/playlists.json b/frontend/src/i18n/locales/en/playlists.json
index 06792711..2b2d6ddb 100644
--- a/frontend/src/i18n/locales/en/playlists.json
+++ b/frontend/src/i18n/locales/en/playlists.json
@@ -78,7 +78,14 @@
   "moveFailed": "Couldn't move the video.",
   "removeFailed": "Couldn't remove the video.",
   "errors": {
-    "not_found": "This playlist doesn't exist any more."
+    "name_required": "Give the playlist a name.",
+    "youtube_read_scope": "Connect YouTube (read access) to sync your playlists.",
+    "not_on_youtube": "This playlist isn't on YouTube.",
+    "youtube_failed": "YouTube didn't accept that just now. Please try again.",
+    "watch_later_not_pushable": "The Watch later list can't be sent to YouTube.",
+    "watch_later_undeletable": "The Watch later list can't be deleted.",
+    "youtube_editing_off": "Enable YouTube editing in Settings first.",
+    "quota_exceeded": "Not enough YouTube quota left today for this sync."
   },
   "moveErrors": {
     "not_in_playlist": "That video isn't in this playlist any more — it changed somewhere else.",
diff --git a/frontend/src/i18n/locales/hu/errors.json b/frontend/src/i18n/locales/hu/errors.json
index 3fcd3f93..7fb3e5c8 100644
--- a/frontend/src/i18n/locales/hu/errors.json
+++ b/frontend/src/i18n/locales/hu/errors.json
@@ -4,6 +4,17 @@
   "validation": "Néhány megadott érték érvénytelen volt. Ellenőrizd, majd próbáld újra.",
   "server": "Szerverhiba",
   "syncCooldown": "Az imént többször is szinkronizáltál — várj pár percet. A YouTube-keret közös az instance összes felhasználójával, a háttérszinkron pedig így is fut tovább.",
+  "notFound": {
+    "generic": "Ez az elem már nem létezik.",
+    "view": "Ez a nézet már nem létezik.",
+    "tag": "Ez a címke már nem létezik.",
+    "pin": "Ez már nincs a komfort polcodon.",
+    "playlist": "Ez a lejátszási lista már nem létezik.",
+    "move_target": "A lejátszási lista, ahová áthelyeznéd, már nem létezik.",
+    "video": "Ez a videó már nincs a könyvtárban.",
+    "invite": "Ez a meghívó már nem létezik.",
+    "user": "Ez a felhasználó már nem létezik."
+  },
   "ok": "OK",
   "offline": {
     "title": "Megszakadt a kapcsolat",
diff --git a/frontend/src/i18n/locales/hu/playlists.json b/frontend/src/i18n/locales/hu/playlists.json
index 50d68821..44f0b30a 100644
--- a/frontend/src/i18n/locales/hu/playlists.json
+++ b/frontend/src/i18n/locales/hu/playlists.json
@@ -78,7 +78,14 @@
   "moveFailed": "Nem sikerült áthelyezni a videót.",
   "removeFailed": "Nem sikerült eltávolítani a videót.",
   "errors": {
-    "not_found": "Ez a lejátszási lista már nem létezik."
+    "name_required": "Adj nevet a lejátszási listának.",
+    "youtube_read_scope": "A listák szinkronizálásához kapcsold össze a YouTube-ot (olvasási hozzáférés).",
+    "not_on_youtube": "Ez a lejátszási lista nincs fent a YouTube-on.",
+    "youtube_failed": "A YouTube most nem fogadta el. Próbáld újra.",
+    "watch_later_not_pushable": "A „Megnézem később” listát nem lehet a YouTube-ra küldeni.",
+    "watch_later_undeletable": "A „Megnézem később” lista nem törölhető.",
+    "youtube_editing_off": "Előbb engedélyezd a YouTube-szerkesztést a Beállításokban.",
+    "quota_exceeded": "Mára nem maradt elég YouTube-keret ehhez a szinkronhoz."
   },
   "moveErrors": {
     "not_in_playlist": "Ez a videó már nincs ebben a listában — időközben máshol megváltozott.",
diff --git a/frontend/src/lib/actionErrors.test.ts b/frontend/src/lib/actionErrors.test.ts
index 7142f0f4..721f9ab6 100644
--- a/frontend/src/lib/actionErrors.test.ts
+++ b/frontend/src/lib/actionErrors.test.ts
@@ -6,9 +6,9 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 // Spy on the toast sink so we can assert exactly what each error maps to.
 vi.mock("./notifications", () => ({ notify: vi.fn(() => 0) }));
 
-import { HttpError } from "./api";
+import { HttpError, api } from "./api";
 import { notify } from "./notifications";
-import { notifyCollectionEditError } from "./actionErrors";
+import { notifyActionError, notifyCollectionEditError } from "./actionErrors";
 
 const notifyMock = vi.mocked(notify);
 beforeEach(() => notifyMock.mockClear());
@@ -29,3 +29,25 @@ describe("notifyCollectionEditError", () => {
     expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "EDIT_FAILED" });
   });
 });
+
+describe("notifyActionError", () => {
+  it("does not toast a fault the request layer already put on screen", async () => {
+    // A 500 opens the blocking error dialog inside `req`; the watched toggles, the saved views and a
+    // playlist delete then toasted the same failure as well.
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: "boom" }), {
+        status: 500,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    const err = await api.plexSetState("1", "watched").catch((e: unknown) => e);
+    notifyMock.mockClear();
+    notifyActionError(err, "FAILED");
+    expect(notifyMock).not.toHaveBeenCalled();
+  });
+
+  it("does toast one the caller was left to handle", () => {
+    notifyActionError(new HttpError(404, "gone"), "FAILED");
+    expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "gone" });
+  });
+});
diff --git a/frontend/src/lib/actionErrors.ts b/frontend/src/lib/actionErrors.ts
index f59b099c..93fd8a6b 100644
--- a/frontend/src/lib/actionErrors.ts
+++ b/frontend/src/lib/actionErrors.ts
@@ -1,4 +1,6 @@
-import { HttpError } from "./api";
+// From the core, not the `./api` barrel: these two are pure (no request), and a test that mocks the
+// barrel wholesale to stub its requests must not take the error path's own plumbing with it.
+import { alreadyReported, HttpError } from "./api/core";
 import { notify } from "./notifications";
 
 /**
@@ -9,6 +11,10 @@ import { notify } from "./notifications";
  * for its non-403 case.
  */
 export function notifyActionError(err: unknown, fallbackMessage: string): void {
+  // Already on screen (`req` opened the error dialog, or raised the connection notice): a toast on
+  // top reported one fault twice. Playlists filtered this by status by hand; the watched toggles,
+  // the saved views and a playlist delete did not.
+  if (alreadyReported(err)) return;
   const detail = err instanceof HttpError ? err.detail : null;
   notify({ level: "error", message: detail || fallbackMessage });
 }
diff --git a/frontend/src/lib/api.ts b/frontend/src/lib/api.ts
index 151b6d07..372a9c9b 100644
--- a/frontend/src/lib/api.ts
+++ b/frontend/src/lib/api.ts
@@ -7,6 +7,7 @@
 // A new endpoint therefore has nowhere to land except a domain module — the interleave that
 // motivated R7.5 cannot re-grow here. (An automated guard for that invariant lands in S3.)
 import {
+  alreadyReported,
   getActiveAccount,
   HttpError,
   setActiveAccount,
@@ -16,6 +17,7 @@ import {
 
 // Re-export the shared HTTP machinery so consumers keep importing these from "./api" unchanged.
 export {
+  alreadyReported,
   HttpError,
   getActiveAccount,
   setActiveAccount,
diff --git a/frontend/src/lib/api/core.test.ts b/frontend/src/lib/api/core.test.ts
index fee88f07..ca5c2b79 100644
--- a/frontend/src/lib/api/core.test.ts
+++ b/frontend/src/lib/api/core.test.ts
@@ -21,7 +21,7 @@ vi.mock("../activeAccount", () => ({
   notifyActiveAccountChange: vi.fn(),
 }));
 
-import { req, uploadReq, setUnauthorizedHandler, HttpError } from "./core";
+import { req, uploadReq, setUnauthorizedHandler, HttpError, alreadyReported } from "./core";
 
 // A fake XHR whose lifecycle the test drives: capture the instance, set status/responseText, then
 // invoke onload/onerror/abort by hand.
@@ -123,15 +123,68 @@ describe("req — a structured refusal reads in the user's language", () => {
     // The 404 every playlist route answers when the list was deleted in another tab. It used to be a
     // bare "Unknown playlist" string, shown verbatim under the Hungarian UI.
     vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify({ detail: { code: "playlist", reason: "not_found" } }), {
+      new Response(JSON.stringify({ detail: { code: "not_found", reason: "playlist" } }), {
         status: 404,
         headers: { "content-type": "application/json" },
       }),
     );
     await expect(req("/api/playlists/7/items/v1", { method: "DELETE" })).rejects.toMatchObject({
       status: 404,
-      detail: "playlists.errors.not_found",
+      detail: "errors.notFound.playlist",
     });
     expect(reportError).not.toHaveBeenCalled(); // a 404 is the caller's to report
   });
 });
+
+describe("req — what it has already put in front of the user", () => {
+  // A caller that toasts a failed action on top of the dialog `req` already opened reported one fault
+  // twice. `alreadyReported` is how `notifyActionError` tells the two apart.
+  const answer = (status: number) =>
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: "x" }), {
+        status,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+
+  it.each([500, 422, 409, 400])("marks a %s it raised the error dialog for", async (status) => {
+    answer(status);
+    const err = await req("/api/x", { method: "POST" }).catch((e: unknown) => e);
+    expect(reportError).toHaveBeenCalled();
+    expect(alreadyReported(err)).toBe(true);
+  });
+
+  it.each([404, 403, 429])("leaves a %s to the caller", async (status) => {
+    answer(status);
+    const err = await req("/api/x", { method: "POST" }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(HttpError);
+    expect(alreadyReported(err)).toBe(false);
+  });
+
+  it("marks a 401 the app shell handles (it signs the tab out)", async () => {
+    answer(401);
+    const err = await req("/api/x", { method: "POST" }).catch((e: unknown) => e);
+    expect(alreadyReported(err)).toBe(true);
+  });
+
+  it("marks a request that never reached the server (the connection notice says it)", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("Failed to fetch"));
+    const err = await req("/api/x", { method: "POST" }).catch((e: unknown) => e);
+    expect(notify).toHaveBeenCalled();
+    expect(alreadyReported(err)).toBe(true);
+  });
+
+  it("marks what the upload path reported the same way", async () => {
+    const dead = uploadReq("/u", form());
+    FakeXHR.last.onerror!();
+    expect(alreadyReported(await dead.catch((e: unknown) => e))).toBe(true);
+    const refused = uploadReq("/u", form());
+    FakeXHR.last.status = 500;
+    FakeXHR.last.onload!();
+    expect(alreadyReported(await refused.catch((e: unknown) => e))).toBe(true);
+    const gone = uploadReq("/u", form());
+    FakeXHR.last.status = 404;
+    FakeXHR.last.onload!();
+    expect(alreadyReported(await gone.catch((e: unknown) => e))).toBe(false);
+  });
+});
diff --git a/frontend/src/lib/api/core.ts b/frontend/src/lib/api/core.ts
index 2847df40..7d598e92 100644
--- a/frontend/src/lib/api/core.ts
+++ b/frontend/src/lib/api/core.ts
@@ -14,6 +14,14 @@ import { activeAccountId, ACTIVE_ACCOUNT_KEY, notifyActiveAccountChange } from "
  *  field nobody ever filled (E9.5 S6 → S7). */
 export const uiLang = (): string => i18n.language.split("-")[0] || "en";
 
+// Errors `req` has already put in front of the user — the blocking error dialog, or the connection
+// notice. A caller that toasts a failed action as well reported the same fault twice (a modal AND a
+// toast); `notifyActionError` asks this instead of each caller filtering statuses by hand.
+const reported = new WeakSet<object>();
+export function alreadyReported(err: unknown): boolean {
+  return typeof err === "object" && err !== null && reported.has(err);
+}
+
 export class HttpError extends Error {
   status: number;
   detail?: string; // server-provided reason (FastAPI's `detail`), when present
@@ -82,8 +90,13 @@ function localizeDetail(d: unknown): string {
   // unknown reason falls back to the plain failure rather than printing a key.
   if (o?.code === "playlist_move")
     return t(`playlists.moveErrors.${o.reason}`, t("playlists.moveFailed"));
-  // Any playlist route whose list is gone (deleted in another tab) — or was never the caller's.
+  // A playlist action the server refused (Watch later can't be deleted, YouTube said no, …).
   if (o?.code === "playlist") return t(`playlists.errors.${o.reason}`, t("errors.generic"));
+  // Any row that is gone — deleted in another tab or device, or never the caller's (a stranger's
+  // row 404s the same way). `reason` names WHAT is gone; one this build doesn't know says it
+  // generically rather than printing a key.
+  if (o?.code === "not_found")
+    return t(`errors.notFound.${o.reason}`, t("errors.notFound.generic"));
   // SEC-14: a manual sync trigger on cooldown. Not an error the user caused so much as a pace
   // limit, and the copy says so.
   if (o?.code === "sync_cooldown") return t("errors.syncCooldown");
@@ -223,6 +236,7 @@ export async function req<T = unknown>(
         continue;
       }
       markConnectivityLost();
+      if (typeof e === "object" && e !== null) reported.add(e);
       throw e;
     }
 
@@ -257,20 +271,26 @@ export async function req<T = unknown>(
       // self-clearing toast rather than a blocking modal the user must acknowledge.
       // A genuine 500 (real fault, carries a JSON detail) still gets the modal, as do
       // 400/409/422 (validation/conflict). 401/403/404 are caller-handled control flow.
+      const err = new HttpError(r.status, detail, detailData);
       if (RETRIABLE_GATEWAY.has(r.status)) {
         markConnectivityLost();
+        reported.add(err);
       } else if (r.status === 401) {
         // Session ended server-side (e.g. the account was suspended or deleted mid-visit). Let the
-        // app shell decide what to do (drop to the login page if we were signed in). Not a modal.
+        // app shell decide what to do (drop to the login page if we were signed in). Not a modal —
+        // but handled all the same, so not the caller's to toast either.
         onUnauthorized?.();
+        reported.add(err);
       } else if (cfg.quiet) {
         /* caller handles the error inline — no global modal */
       } else if (r.status >= 500) {
         reportError(detail || `${i18n.t("errors.server")} (${r.status})`);
+        reported.add(err);
       } else if (r.status === 400 || r.status === 409 || r.status === 422) {
         reportError(detail);
+        reported.add(err);
       }
-      throw new HttpError(r.status, detail, detailData);
+      throw err;
     }
     // The single audited cast in this layer: the server contract is asserted here, once, so
     // every typed api.* method (T comes from its declared return type) is checked from here up.
@@ -326,16 +346,21 @@ export function uploadReq<T = unknown>(
       } catch {
         /* no JSON body */
       }
+      const err = new HttpError(xhr.status, detail, detailData);
       if (xhr.status === 401) onUnauthorized?.();
       else if (xhr.status >= 500)
         reportError(detail || `${i18n.t("errors.server")} (${xhr.status})`);
       else if (xhr.status === 400 || xhr.status === 409 || xhr.status === 422) reportError(detail);
-      reject(new HttpError(xhr.status, detail, detailData));
+      if (xhr.status === 401 || xhr.status >= 500 || [400, 409, 422].includes(xhr.status))
+        reported.add(err); // as in `req`: already on screen, not the caller's to toast again
+      reject(err);
     };
     // A network-level failure (server unreachable) — same soft "connection lost" status as `req`.
     xhr.onerror = () => {
       markConnectivityLost();
-      reject(new HttpError(0, i18n.t("errors.offline.body")));
+      const err = new HttpError(0, i18n.t("errors.offline.body"));
+      reported.add(err);
+      reject(err);
     };
     xhr.onabort = () => reject(new HttpError(0, "aborted"));
     xhr.send(form);

From 76b5f7c93e1a2ae90f0ba006a555ee2f3b6bd9b9 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:05:19 +0200
Subject: [PATCH 27/52] fix(playlists): a failed background refetch keeps the
 list on screen, and the player outlives every branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09.

- The detail's error branch applies only when there is nothing to show (`isError && <no data>`, the
  QueryState convention): one failed refetch — on focus, after a move or a removal — replaced a
  loaded list with "couldn't load". The error line is announced (role=alert).
- Tests for the two branches of "the player survives a change of selection" that round 2 left
  untested (a list that fails to load, no selection).
---
 .../src/components/Playlists.dom.test.tsx     | 38 +++++++++++++++++++
 frontend/src/components/Playlists.tsx         |  8 ++--
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
index 7a9cf766..28a5860f 100644
--- a/frontend/src/components/Playlists.dom.test.tsx
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -221,6 +221,23 @@ describe("Playlists — removing a video from inside the player", () => {
   });
 });
 
+describe("Playlists — a failed refetch of a list that is on screen", () => {
+  it("keeps the list, instead of replacing it with the error", async () => {
+    // A background refetch — on focus, after a move or a removal — failing during an API restart
+    // replaced a loaded list with "couldn't load" (the `isError && <no data>` convention, ignored).
+    mount({ 1: [vid("V", 0)] });
+    await screen.findByRole("button", { name: "card.play — Video V" });
+    vi.mocked(api.playlist).mockRejectedValue(new HttpError(502, "gateway"));
+    await act(async () => {
+      await qc.invalidateQueries({ queryKey: qk.playlist(1) });
+      await new Promise((r) => setTimeout(r, 20)); // react-query notifies its observers on a timer
+    });
+    expect(qc.getQueryState(qk.playlist(1))?.status).toBe("error");
+    expect(screen.queryByText("playlists.loadFailed")).toBeNull();
+    expect(screen.getByRole("button", { name: "card.play — Video V" })).toBeTruthy();
+  });
+});
+
 describe("Playlists — the player outlives a change of selection", () => {
   it("stays mounted while a newly selected list is still loading", async () => {
     // The page swaps itself for "Loading…" until the new list arrives; with the player rendered only
@@ -235,6 +252,27 @@ describe("Playlists — the player outlives a change of selection", () => {
     expect(h.mounted).toBe(true);
   });
 
+  it("stays mounted when the newly selected list fails to load — a list deleted elsewhere", async () => {
+    const { rerender } = mount({ 1: [vid("V", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.mounted).toBe(true));
+    vi.mocked(api.playlist).mockRejectedValue(new HttpError(404, "gone"));
+    h.selectedId = 2;
+    rerender();
+    await screen.findByText("playlists.loadFailed");
+    expect(h.mounted).toBe(true);
+  });
+
+  it("stays mounted when nothing is selected any more", async () => {
+    const { rerender } = mount({ 1: [vid("V", 0)] });
+    await play("Video V");
+    await waitFor(() => expect(h.mounted).toBe(true));
+    h.selectedId = null;
+    rerender();
+    await screen.findByText("playlists.pickOne");
+    expect(h.mounted).toBe(true);
+  });
+
   it("refreshes the list it was launched from when the viewer marks the video in it", async () => {
     // Invalidating the SELECTED list left the launch list's row showing the old status.
     vi.spyOn(api, "setState").mockResolvedValue(undefined as never);
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index b006635a..9f7439aa 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -813,11 +813,13 @@ export default function Playlists() {
     );
   }
   // The page used to render "Loading…" forever when the detail query failed — an error read as a
-  // slow network that never arrived.
-  if (detailQuery.isError) {
+  // slow network that never arrived. Only with nothing to show, though (the `isError && <no data>`
+  // convention, see ui/QueryState): a background refetch that failed — on focus, after a move or a
+  // removal — replaced a list that was on screen with this message.
+  if (detailQuery.isError && !detail) {
     return (
       <>
-        <div className="text-sm p-4 flex flex-col items-start gap-3">
+        <div role="alert" className="text-sm p-4 flex flex-col items-start gap-3">
           <span className="inline-flex items-center gap-2 text-muted">
             <AlertTriangle className="w-4 h-4 text-danger" />
             {t("playlists.loadFailed")}

From 785080f3da0064ca5c27ec604739b31f32ab0f03 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:05:30 +0200
Subject: [PATCH 28/52] fix(plex): a Surprise card whose watched toggle failed
 is put back
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09 — the sibling of the collection page's fix (d349bc90).
Discover's toggle flips the Surprise draw too, but its resync refetches only the rails (refetching the
draw would reshuffle it under the viewer), so a refused toggle stayed flipped there. toggleWatchState
takes an optional `revert`, called on a failure only; the queryKeys comment that claimed the watched
toggle invalidates the Surprise key now says what the code does.
---
 .../src/components/PlexDiscover.dom.test.tsx  | 27 +++++++++++++++++++
 frontend/src/components/PlexDiscover.tsx      | 16 ++++++++---
 frontend/src/lib/plexWatch.ts                 |  6 ++++-
 frontend/src/lib/queryKeys.ts                 |  5 ++--
 4 files changed, 47 insertions(+), 7 deletions(-)

diff --git a/frontend/src/components/PlexDiscover.dom.test.tsx b/frontend/src/components/PlexDiscover.dom.test.tsx
index 548f5314..df49dee5 100644
--- a/frontend/src/components/PlexDiscover.dom.test.tsx
+++ b/frontend/src/components/PlexDiscover.dom.test.tsx
@@ -235,4 +235,31 @@ describe("PlexDiscover", () => {
     );
     await screen.findByText("plex.discover.empty");
   });
+
+  it("puts a Surprise card back when its watched toggle fails", async () => {
+    // The resync refetches the rails but not the Surprise draw (that would reshuffle it), so a
+    // refused toggle stayed flipped there — the sibling of the collection page's fix.
+    plexDiscover.mockResolvedValue({
+      ...fullPayload,
+      continue_watching: [],
+      recently_watched: [],
+      recently_added: [],
+      because_you_watched: null,
+    });
+    plexSurprise.mockResolvedValue({ scope: "both", items: [card("sp1", "Random Pick")] });
+    plexSetState.mockRejectedValueOnce(new Error("refused"));
+    wrap(
+      <PlexDiscover
+        scope="both"
+        onOpenCard={noop}
+        onInfoCard={noop}
+        onGenre={noop}
+        onSeeAllRecent={noop}
+      />,
+    );
+    fireEvent.click(await screen.findByLabelText("plex.markWatched"));
+    await waitFor(() => expect(plexSetState).toHaveBeenCalledWith("sp1", "watched"));
+    await waitFor(() => expect(screen.getByLabelText("plex.markWatched")).toBeTruthy());
+    expect(screen.queryByLabelText("plex.markUnwatched")).toBeNull();
+  });
 });
diff --git a/frontend/src/components/PlexDiscover.tsx b/frontend/src/components/PlexDiscover.tsx
index c7414ef5..435b06c9 100644
--- a/frontend/src/components/PlexDiscover.tsx
+++ b/frontend/src/components/PlexDiscover.tsx
@@ -105,6 +105,14 @@ export default function PlexDiscover({
 
   // Watched toggle over BOTH this surface's cache (so a rail card flips instantly) and the surprise
   // list, then persist + resync via the shared helper — invalidating the grid too so it agrees.
+  const setSurpriseStatus = (card: PlexCard, status: PlexCard["status"]) =>
+    qc.setQueryData<{ scope: string; items: PlexCard[] }>(
+      qk.plexSurprise(scope, lang, filters),
+      (old) =>
+        old
+          ? { ...old, items: old.items.map((c) => (c.id === card.id ? { ...c, status } : c)) }
+          : old,
+    );
   const toggleWatched = (card: PlexCard) =>
     toggleWatchState(card, t, {
       optimistic: (next) => {
@@ -122,11 +130,11 @@ export default function PlexDiscover({
               }
             : old,
         );
-        qc.setQueryData<{ scope: string; items: PlexCard[] }>(
-          qk.plexSurprise(scope, lang, filters),
-          (old) => (old ? { ...old, items: flip(old.items) } : old),
-        );
+        setSurpriseStatus(card, next);
       },
+      // The resync below leaves the Surprise rail alone (a refetch would reshuffle it), so a failed
+      // toggle was left flipped there — put back in place instead.
+      revert: () => setSurpriseStatus(card, card.status),
       resync: () => {
         qc.invalidateQueries({ queryKey: qk.plexDiscover() });
         qc.invalidateQueries({ queryKey: qk.plexLibrary() });
diff --git a/frontend/src/lib/plexWatch.ts b/frontend/src/lib/plexWatch.ts
index 2ba8afd0..7749af7c 100644
--- a/frontend/src/lib/plexWatch.ts
+++ b/frontend/src/lib/plexWatch.ts
@@ -6,16 +6,20 @@ import { notifyActionError } from "./actionErrors";
 // updater, call the API, surface a failure (the click used to look dead on 403/404/429), then
 // `resync` (invalidate) — which corrects the optimistic flip to truth either way. Shared by the
 // browse grid and the person page, each of which owns a different cache shape.
+//
+// `revert` is for a cache `resync` must NOT refetch — a random draw (Discover's Surprise rail), which
+// a refetch would reshuffle under the viewer. It is called on a failure only, to put the card back.
 export async function toggleWatchState(
   card: PlexCard,
   t: TFunction,
-  handlers: { optimistic: (next: string) => void; resync: () => void },
+  handlers: { optimistic: (next: string) => void; resync: () => void; revert?: () => void },
 ) {
   const next = card.status === "watched" ? "new" : "watched";
   handlers.optimistic(next);
   try {
     await api.plexSetState(card.id, next);
   } catch (e) {
+    handlers.revert?.();
     notifyActionError(e, t("plex.watchedFailed"));
   }
   handlers.resync();
diff --git a/frontend/src/lib/queryKeys.ts b/frontend/src/lib/queryKeys.ts
index 423f9743..deee4b24 100644
--- a/frontend/src/lib/queryKeys.ts
+++ b/frontend/src/lib/queryKeys.ts
@@ -117,8 +117,9 @@ export const qk = {
   // refetches it alone.
   plexDiscover: (...rest: unknown[]) => ["plex-discover", ...rest],
   // Variadic like plexDiscover so it can key by scope + lang + the active filters (lang because a genre
-  // filter narrows against the language-specific genre column, like the grid); `plexSurprise()` (no args)
-  // stays a prefix for the reshuffle/watched-toggle invalidations.
+  // filter narrows against the language-specific genre column, like the grid). The ↻ reshuffle is the
+  // query's own refetch, and nothing invalidates this key — deliberately: a watched toggle flips the
+  // card in place (and reverts it on a failure) rather than reshuffle the rail under the viewer.
   plexSurprise: (...rest: unknown[]) => ["plex-surprise", ...rest],
   plexSuggest: (...rest: unknown[]) => ["plex-suggest", ...rest],
   // Optional trailing `lang` (E5 S6): a language switch remounts the detail with a new key so HU/EN

From 86971c574d22f8773faa5c1c8e036fc18282c36e Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 18:05:30 +0200
Subject: [PATCH 29/52] fix(api): progress checkpoints past the int4 column are
 a 422, and idle HLS sessions are reaped on a timer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 3 of bug hunt 2026-09.

- The YouTube and Plex progress bodies are bounded by POSITION_MAX_S (the int4 position columns): a
  finite position of 2^31 or more was a DataError, i.e. a 500 — the sibling of round 2's non-finite
  fix.
- plex/stream.py promised "a periodic reaper", but reap_idle ran only inside the NEXT session
  request: after the last playback an abandoned session (its ffmpeg still working, its directory a
  whole segmented copy of the film) lived until someone pressed play again. A lifespan task reaps
  every 60 s.
- Tests for what round 2 left untested: the 422's body keeps the list shape the UI localizes, and
  stream_session refuses non-finite start/aoff.
---
 backend/app/main.py                   | 25 ++++++++++++++--
 backend/app/models.py                 |  6 ++++
 backend/app/routes/feed.py            |  8 ++++--
 backend/app/routes/plex/playback.py   |  8 ++++--
 backend/tests/test_hls_reaper.py      | 41 +++++++++++++++++++++++++++
 backend/tests/test_progress_bounds.py | 29 +++++++++++++++++++
 6 files changed, 108 insertions(+), 9 deletions(-)
 create mode 100644 backend/tests/test_hls_reaper.py

diff --git a/backend/app/main.py b/backend/app/main.py
index 3acb4bde..a8add1d1 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -81,6 +81,7 @@ async def lifespan(app: FastAPI):
     # alone doesn't buy that; not waiting does. The sweep only touches directories no live session
     # owns, so racing it against early playback is safe.
     sweep = asyncio.create_task(_sweep_hls_orphans())
+    reaper = asyncio.create_task(_reap_hls_sessions())
     start_scheduler()
     try:
         yield
@@ -90,15 +91,33 @@ async def lifespan(app: FastAPI):
         # pending ("Task was destroyed but it is pending!" — noise that reads like a bug during
         # triage). Cancelling does NOT interrupt the rmtree thread itself; this only makes our own
         # bookkeeping honest.
-        sweep.cancel()
-        with suppress(asyncio.CancelledError):
-            await sweep
+        for task in (sweep, reaper):
+            task.cancel()
+            with suppress(asyncio.CancelledError):
+                await task
         shutdown_scheduler()
         # Kills a running subtitle extraction: its worker would otherwise hold interpreter exit for
         # the rest of the read (see plex_subtitles.shutdown).
         plex_subtitles.shutdown()
 
 
+# How often idle HLS sessions are reaped (see plex/stream.py `reap_idle`).
+_HLS_REAP_EVERY_S = 60.0
+
+
+async def _reap_hls_sessions() -> None:
+    """The periodic reaper plex/stream.py's docstring promises. `reap_idle` used to run only inside
+    the NEXT session request, so after the last playback of the day an abandoned session — its
+    ffmpeg still working through the film, its directory a whole segmented copy of it — lived until
+    somebody pressed play again or the process restarted."""
+    while True:
+        await asyncio.sleep(_HLS_REAP_EVERY_S)
+        try:
+            await asyncio.to_thread(plex_stream.reap_idle)
+        except Exception:
+            log.exception("HLS session reap failed")
+
+
 async def _sweep_hls_orphans() -> None:
     """Background half of the startup HLS sweep (see lifespan). Owns its own errors: a failure here
     must never take the app down, and a cancelled shutdown is not one."""
diff --git a/backend/app/models.py b/backend/app/models.py
index 02a2895a..6ea02966 100644
--- a/backend/app/models.py
+++ b/backend/app/models.py
@@ -24,6 +24,11 @@ from app.db import Base
 from app.utils import canonical_email
 
 
+# The resume-position columns (VideoState / PlexState.position_seconds) are int4. The checkpoint
+# routes bound their bodies by this, so an out-of-range position is a 422 rather than a 500.
+POSITION_MAX_S = 2**31 - 1
+
+
 class TimestampMixin:
     """Adds a server-defaulted `created_at`. Models that index created_at or order it
     differently (QuotaEvent, Notification, Message) keep their own column on purpose."""
@@ -423,6 +428,7 @@ class VideoState(Base, UpdatedAtMixin):
     # status: a partially-watched video keeps status "new" but a non-zero position, so
     # it can render a progress bar and match the "in progress" feed filter. 0 = not
     # started / finished (trivially-early and near-finished positions are not stored).
+    # int4: a checkpoint body must stay under POSITION_MAX_S, or the flush is a DataError (a 500).
     position_seconds: Mapped[int] = mapped_column(
         Integer, default=0, server_default="0", nullable=False
     )
diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index e969de25..a1a8a8c3 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -1,7 +1,7 @@
 from datetime import date, datetime, timezone
 
 from fastapi import APIRouter, Depends, HTTPException, Query
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
@@ -22,6 +22,7 @@ from app.feedquery import (
     sort_keys,
 )
 from app.models import (
+    POSITION_MAX_S,
     ChannelTag,
     Tag,
     User,
@@ -310,8 +311,9 @@ class VideoProgressIn(BaseModel):
     # Accept a float and truncate (below) — the player may post a raw currentTime (a float), which
     # the old `int(payload.get(...))` silently truncated. A plain `int` field would 422 that on the
     # 10s progress hot path, losing the resume position; `float` keeps the old tolerance.
-    position_seconds: float = 0
-    duration_seconds: float = 0
+    # Bounded above by the int4 column (see POSITION_MAX_S): past it the flush was a 500.
+    position_seconds: float = Field(0, le=POSITION_MAX_S)
+    duration_seconds: float = Field(0, le=POSITION_MAX_S)
 
 
 @router.post("/videos/{video_id}/progress")
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index f0e03ef9..248855a3 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -15,13 +15,14 @@ from fastapi import (
     Response,
 )
 from fastapi.responses import FileResponse
-from pydantic import BaseModel, ConfigDict
+from pydantic import BaseModel, ConfigDict, Field
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.auth import current_user, resolved_user_id
 from app.db import SessionLocal, get_db
 from app.models import (
+    POSITION_MAX_S,
     PlexItem,
     PlexSeason,
     PlexShow,
@@ -293,8 +294,9 @@ class ItemProgressIn(BaseModel):
 
     # float, truncated in the handler — the player may post a raw currentTime (a float); a plain
     # `int` field would 422 it on the periodic progress checkpoint (the old `int(...)` truncated).
-    position_seconds: float = 0
-    duration_seconds: float = 0
+    # Bounded above by the int4 column (see POSITION_MAX_S): past it the flush was a 500.
+    position_seconds: float = Field(0, le=POSITION_MAX_S)
+    duration_seconds: float = Field(0, le=POSITION_MAX_S)
     final: bool = False
 
 
diff --git a/backend/tests/test_hls_reaper.py b/backend/tests/test_hls_reaper.py
new file mode 100644
index 00000000..51521ed5
--- /dev/null
+++ b/backend/tests/test_hls_reaper.py
@@ -0,0 +1,41 @@
+"""Idle HLS sessions are reaped on a timer, not only when the next session is requested.
+
+plex/stream.py promises "a periodic reaper kills idle ones", but `reap_idle` ran only inside
+POST /session: after the last playback, an abandoned session (its ffmpeg still working through the
+film, its directory a whole segmented copy of it) lived until somebody pressed play again.
+"""
+
+import asyncio
+
+import app.main as app_main
+from app.main import app
+
+
+class _Configured:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, *exc):
+        return False
+
+
+def test_idle_sessions_are_reaped_while_nobody_starts_a_new_one(monkeypatch):
+    async def _no_sweep():
+        return None
+
+    reaped: list[int] = []
+    monkeypatch.setattr(app_main, "SessionLocal", _Configured)
+    monkeypatch.setattr(app_main.state, "is_configured", lambda db: True)
+    monkeypatch.setattr(app_main, "_sweep_hls_orphans", _no_sweep)
+    monkeypatch.setattr(app_main, "start_scheduler", lambda: None)
+    monkeypatch.setattr(app_main, "shutdown_scheduler", lambda: None)
+    monkeypatch.setattr(app_main.plex_subtitles, "shutdown", lambda: None)
+    monkeypatch.setattr(app_main, "_HLS_REAP_EVERY_S", 0.01)
+    monkeypatch.setattr(app_main.plex_stream, "reap_idle", lambda: reaped.append(1) or 0)
+
+    async def _cycle():
+        async with app_main.lifespan(app):
+            await asyncio.sleep(0.2)
+
+    asyncio.run(_cycle())
+    assert len(reaped) >= 2, "no periodic reap ran while the app was up"
diff --git a/backend/tests/test_progress_bounds.py b/backend/tests/test_progress_bounds.py
index aea5dee5..7736cb7c 100644
--- a/backend/tests/test_progress_bounds.py
+++ b/backend/tests/test_progress_bounds.py
@@ -32,3 +32,32 @@ def test_a_non_finite_position_is_refused(client, path, raw):
         headers={"content-type": "application/json"},
     )
     assert r.status_code == 422, r.text
+
+
+@pytest.mark.parametrize("path", ["/api/videos/v1/progress", "/api/plex/item/98614/progress"])
+@pytest.mark.parametrize("field", ["position_seconds", "duration_seconds"])
+def test_a_position_past_the_int4_column_is_refused_not_a_500(client, path, field):
+    """Finite but past the int4 column: the flush was a DataError, i.e. a 500 with a traceback."""
+    body = {"position_seconds": 10, "duration_seconds": 3000, field: 2**31}
+    assert client.post(path, json=body).status_code == 422
+
+
+def test_the_refusal_keeps_the_shape_the_ui_reads(client):
+    """The handler replaces FastAPI's own for every validation error in the app, and the UI turns
+    exactly this shape — a LIST of errors — into its localized "check your input" sentence. The
+    refused value is echoed by its name, because JSON cannot carry NaN."""
+    r = client.post(
+        "/api/videos/v1/progress",
+        content='{"position_seconds": NaN, "duration_seconds": 3000}',
+        headers={"content-type": "application/json"},
+    )
+    detail = r.json()["detail"]
+    assert isinstance(detail, list) and detail[0]["loc"] == ["body", "position_seconds"]
+    assert detail[0]["input"] == "nan"
+
+
+@pytest.mark.parametrize("q", ["start=inf", "start=nan", "aoff=inf", "aoff=-inf", "aoff=nan"])
+def test_a_session_at_an_impossible_offset_is_refused(client, q):
+    """`start=inf` reached `int()` in the session builder (a 500); `aoff=inf` spawned an ffmpeg
+    with a non-finite offset."""
+    assert client.post(f"/api/plex/stream/98614/session?{q}").status_code == 422

From 31dc4184f597f8108cb0b72d0d0f08ef94d5f08c Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 23:08:11 +0200
Subject: [PATCH 30/52] fix(api): a paused viewer keeps its HLS session, a
 refused subtitle publish backs off, and a NUL is a 422 everywhere

Deep-review round 4, backend half.

- The periodic HLS reaper (round 3) applied the "finished and unfetched for 30 s" rule that only a
  NEW session request may apply. A remux finishes long before the film, and a paused player with a
  full buffer fetches nothing, so a one-minute pause killed the session and playback died ~30 s after
  resuming. The periodic pass is `reap_abandoned` now (the long idle limit, finished or not).
- A subtitle `publish` that could not keep its output (full / read-only cache volume) returned
  quietly, so every poll queued the window and the whole-container pass again. It reports failure
  and the pass is backed off like a failed read; a cached VTT that cannot be READ is answered
  `unavailable` (`cache_unreadable`) instead of scheduling reads that can never land.
- The subtitle routes bound `rating_key` / `sub_ord` (they become a cache file name: a 250-digit
  one was ENAMETOOLONG, which pathlib's exists() re-raises -> a 500), and the cache helpers no longer
  throw on such a name.
- One app-wide handler turns psycopg's "text fields cannot contain NUL" DataError into a 422: round 3
  guarded only the by-rating_key lookup, and `contains=`, `contains_group=`, reorder/bulk key lists
  and the collection search still 500'd.
- The hand-written `db.get(...) is None -> 404 "Unknown ..."` siblings use `get_or_404` with a
  `what` (channel / video / user), so the Hungarian UI no longer shows English for a gone row.
---
 backend/app/main.py                         | 22 ++++++-
 backend/app/plex/lookups.py                 |  5 +-
 backend/app/plex/stream.py                  | 26 +++++++-
 backend/app/plex/subtitles.py               | 43 +++++++++---
 backend/app/routes/channels.py              |  5 +-
 backend/app/routes/downloads.py             |  4 +-
 backend/app/routes/feed.py                  |  7 +-
 backend/app/routes/playlists.py             |  8 +--
 backend/app/routes/plex/playback.py         | 16 +++--
 backend/tests/test_hls_reaper.py            | 67 ++++++++++++++++++-
 backend/tests/test_not_found_detail.py      | 33 ++++++++++
 backend/tests/test_plex_subtitle_prepare.py | 72 +++++++++++++++++++++
 frontend/src/i18n/locales/en/errors.json    |  3 +-
 frontend/src/i18n/locales/hu/errors.json    |  3 +-
 14 files changed, 278 insertions(+), 36 deletions(-)

diff --git a/backend/app/main.py b/backend/app/main.py
index a8add1d1..ca70b442 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -24,6 +24,7 @@ log = logging.getLogger("siftlode.app")
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
 from fastapi.staticfiles import StaticFiles
+from sqlalchemy.exc import DataError
 from starlette.middleware.sessions import SessionMiddleware
 
 from app import state
@@ -109,11 +110,13 @@ async def _reap_hls_sessions() -> None:
     """The periodic reaper plex/stream.py's docstring promises. `reap_idle` used to run only inside
     the NEXT session request, so after the last playback of the day an abandoned session — its
     ffmpeg still working through the film, its directory a whole segmented copy of it — lived until
-    somebody pressed play again or the process restarted."""
+    somebody pressed play again or the process restarted.
+
+    `reap_abandoned`, not `reap_idle`: a finished session is also a paused viewer's."""
     while True:
         await asyncio.sleep(_HLS_REAP_EVERY_S)
         try:
-            await asyncio.to_thread(plex_stream.reap_idle)
+            await asyncio.to_thread(plex_stream.reap_abandoned)
         except Exception:
             log.exception("HLS session reap failed")
 
@@ -147,6 +150,21 @@ async def _validation_error(request: Request, exc: RequestValidationError) -> JS
     )
 
 
+@app.exception_handler(DataError)
+async def _nul_in_text(request: Request, exc: DataError) -> JSONResponse:
+    """A NUL byte in a string the request sent is a 422, on every route at once. Postgres cannot hold
+    NUL in text, so the driver refuses to even send the query — and a `%00` in a query parameter or
+    an escaped NUL in a JSON body (a playlist's `contains=`, a reorder's key list, a collection
+    search) was a 500 with a traceback wherever it reached a comparison. Guarding each site did not
+    hold: round 3 guarded the by-rating_key lookup and missed the rest. Any other DataError is left
+    alone — re-raised, it stays the 500 it always was."""
+    if "NUL (0x00)" not in str(exc.orig):
+        raise exc
+    return JSONResponse(
+        status_code=422, content={"detail": {"code": "invalid_input", "reason": "nul"}}
+    )
+
+
 app.add_middleware(
     SessionMiddleware,
     secret_key=settings.secret_key,
diff --git a/backend/app/plex/lookups.py b/backend/app/plex/lookups.py
index 4d2e4987..ff430253 100644
--- a/backend/app/plex/lookups.py
+++ b/backend/app/plex/lookups.py
@@ -13,8 +13,9 @@ def by_rating_key(db: Session, model: type[_M], rating_key: str) -> _M | None:
     tables (PlexItem / PlexShow / PlexSeason / PlexCollection); the return type is that model, so call
     sites keep their `Model | None` static type.
 
-    A key with a NUL in it (`%00` in a path segment) names no row — and Postgres refuses NUL in text,
-    so asking would be a DataError, i.e. a 500, from every route that looks an item up."""
+    A key with a NUL in it (`%00` in a path segment) names no row — a 404, like any unknown key.
+    Postgres refuses NUL in text, so asking would be a DataError; the app-wide handler turns the
+    places that DO ask (lists and filters compared to rating_key) into a 422 (see main.py)."""
     if "\x00" in str(rating_key):
         return None
     return db.execute(select(model).where(model.rating_key == str(rating_key))).scalars().first()
diff --git a/backend/app/plex/stream.py b/backend/app/plex/stream.py
index 3a18f9d3..fdb012a7 100644
--- a/backend/app/plex/stream.py
+++ b/backend/app/plex/stream.py
@@ -820,14 +820,36 @@ def sweep_orphans(older_than: float | None = None) -> int:
     return dropped
 
 
-def reap_idle() -> int:
+# How long a session whose ffmpeg has FINISHED may go unfetched before a new session request reaps
+# it (see reap_idle).
+_FINISHED_IDLE_S = 30
+
+
+def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
+    """Kill sessions nobody has fetched from for `_SESSION_IDLE_S` — or, once their ffmpeg has
+    finished, for `finished_idle_s`.
+
+    The short rule is only safe where a NEW session is being requested (the default, POST /session):
+    a finished session is also what a PAUSED viewer has. A remux runs far faster than realtime, so
+    ffmpeg is done a minute or two in and writes ENDLIST; hls.js then stops asking for the playlist,
+    and with its forward buffer full a paused player fetches nothing at all. The periodic reaper
+    therefore uses `reap_abandoned` — with the 30 s rule, a one-minute pause killed the session and
+    playback died ~30 s after resuming (deep-review round 4). A viewer paused for longer than
+    `_SESSION_IDLE_S` still loses it; the player restarts one at the playhead when a fetch 404s."""
     now = time.time()
     dropped = 0
     with _lock:
         for key, s in list(_sessions.items()):
             done = s.proc.poll() is not None
-            if now - s.last_access > _SESSION_IDLE_S or (done and now - s.last_access > 30):
+            idle = now - s.last_access
+            if idle > _SESSION_IDLE_S or (done and idle > finished_idle_s):
                 _kill(s)
                 _sessions.pop(key, None)
                 dropped += 1
     return dropped
+
+
+def reap_abandoned() -> int:
+    """The periodic reaper's pass: only what nobody has fetched from for `_SESSION_IDLE_S`, finished
+    or not (see reap_idle for why a finished session is not yet an abandoned one)."""
+    return reap_idle(finished_idle_s=_SESSION_IDLE_S)
diff --git a/backend/app/plex/subtitles.py b/backend/app/plex/subtitles.py
index 7948bb7b..132f476e 100644
--- a/backend/app/plex/subtitles.py
+++ b/backend/app/plex/subtitles.py
@@ -207,7 +207,17 @@ def read_meta(key: str) -> tuple[list[list[float]], bool]:
         raw = json.loads(_meta_path(key).read_text(encoding="utf-8"))
         return [[float(a), float(b)] for a, b in raw.get("ranges", [])], bool(raw.get("complete"))
     except (OSError, ValueError, TypeError):
-        return ([[0.0, _FULL_END_S]], True) if _vtt_path(key).exists() else ([], False)
+        return ([[0.0, _FULL_END_S]], True) if _exists(_vtt_path(key)) else ([], False)
+
+
+def _exists(p: Path) -> bool:
+    """`Path.exists` that answers False for a path the OS refuses outright: pathlib swallows only
+    ENOENT-like errors, so an over-long name (ENAMETOOLONG, from an absurd rating_key or ordinal)
+    escaped as a 500 from the status route."""
+    try:
+        return p.exists()
+    except (OSError, ValueError):
+        return False
 
 
 def _write_meta(key: str, ranges: list[list[float]], complete: bool) -> None:
@@ -305,8 +315,11 @@ def _last_cue_end(vtt: str) -> float:
     return end
 
 
-def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) -> None:
-    """Merge a freshly extracted region into the cached track and widen its covered ranges.
+def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) -> bool:
+    """Merge a freshly extracted region into the cached track and widen its covered ranges. False
+    when the region did not land (the cache is unwritable, or the VTT there cannot be read) — the
+    caller must then record a FAILED pass: returning quietly let the next poll schedule the same read
+    again, a whole-container pass every time, while the player said "preparing" for good.
 
     A read-merge-write, so it runs under `_PUBLISH_LOCK`: two jobs publish into the same keys (a
     window and the full pass, and every embedded track of the file rides each of them), and without
@@ -319,7 +332,7 @@ def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) ->
             # There, but unreadable (`cache_read` swallows the OSError). Merging into "" would replace
             # a whole track with this one region while its sidecar still claimed all of it.
             log.warning("subtitle cache %s unreadable; not publishing into it", key)
-            return
+            return False
         old_ranges, was_complete = read_meta(key)
         if old is None:
             # A sidecar with no VTT behind it claims cues that are not there, so it is not merged
@@ -330,8 +343,10 @@ def publish(key: str, vtt: str, covered: tuple[float, float], complete: bool) ->
             old_ranges, was_complete = [], False
             _write_meta(key, [], False)
         if not cache_write(key, merge_vtt(old or "", vtt)):
-            return  # the region never landed, so the sidecar must not claim it
+            log.warning("subtitle cache %s could not be written", key)
+            return False  # the region never landed, so the sidecar must not claim it
         _write_meta(key, merge_ranges(old_ranges + [list(covered)]), complete or was_complete)
+        return True
 
 
 # --- background extraction ----------------------------------------------------------------------
@@ -531,6 +546,12 @@ def ensure(rating_key: str, sub_ord: int, at: float = 0.0) -> dict:
     gen = generation(key)
     if complete and have:
         return {"state": "ready", "code": None, "gen": gen}
+    if not have and _exists(_vtt_path(key)):
+        # On disk but unreadable (permissions, a bad volume): nothing can serve it, and no extraction
+        # can help — `publish` refuses to merge into it, and a job whose sidecar covers the position
+        # skips as already done — so scheduling only kept the player on "preparing" for good. `gen` 0:
+        # there is nothing a <track> could fetch.
+        return {"state": "unavailable", "code": "cache_unreadable", "gen": 0}
     code = _recent_failure(key)
     if code and not covered:
         return {
@@ -616,7 +637,7 @@ def _already_done(key: str, window_start: float | None, at: float) -> bool:
     """A queued job looks again before it reads anything. While it waited, another job may have
     covered it: every embedded track rides each pass over its file, so a window for one language also
     publishes the others."""
-    if not _vtt_path(key).exists():
+    if not _exists(_vtt_path(key)):
         return False
     ranges, complete = read_meta(key)
     return complete or (window_start is not None and covers(ranges, at))
@@ -696,7 +717,8 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
             # identity is per ITEM (the embedded fan-out shares it), so a sidecar picked while an
             # embedded track's full pass was running sat behind that pass for minutes.
             vtt = _sidecar_vtt(db, want)
-            publish(cache_key(rating_key, sub_ord), vtt, (0.0, _FULL_END_S), True)
+            if not publish(cache_key(rating_key, sub_ord), vtt, (0.0, _FULL_END_S), True):
+                raise SubtitleUnavailable("extract_failed")
             return
         if want.get("index") is None:
             raise SubtitleUnavailable("not_fetchable")
@@ -721,13 +743,16 @@ def _extract_and_publish(rating_key: str, sub_ord: int, window_start: float | No
         # the track read "ready" for good while its subtitles stopped wherever ffmpeg did (the cache
         # has no eviction, so nothing would ever have extracted it again).
         covered_end = end if clean else start + _last_cue_end(vtt)
-        publish(
+        landed = publish(
             key,
             shift_vtt(vtt, -start),  # zero-based window clock → absolute cue times
             (start, covered_end),
             clean and length is None,
         )
-        if not clean:
+        if not landed:
+            # A read that could not be kept is a failed read (see publish) — backed off like one.
+            _pass_failed(rating_key, [key], window_start, (start, end))
+        elif not clean:
             _pass_failed(rating_key, [key], window_start, (covered_end, end))
 
 
diff --git a/backend/app/routes/channels.py b/backend/app/routes/channels.py
index f2c28603..85ef7a11 100644
--- a/backend/app/routes/channels.py
+++ b/backend/app/routes/channels.py
@@ -26,7 +26,7 @@ from app.models import (
     User,
     Video,
 )
-from app.routes._common import owned_or_404
+from app.routes._common import get_or_404, owned_or_404
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
@@ -663,8 +663,7 @@ def block_channel(
     """Block a channel for this user: its videos won't appear in their live search (and won't be
     ingested for them) and are hidden from their feed / explore. Idempotent. The now-hidden
     un-kept search/explore videos are reclaimed by the discovery-cleanup job in due course."""
-    if db.get(Channel, channel_id) is None:
-        raise HTTPException(status_code=404, detail="Unknown channel")
+    get_or_404(db, Channel, channel_id, what="channel")
     if not _is_blocked(db, user, channel_id):
         db.add(BlockedChannel(user_id=user.id, channel_id=channel_id))
         # Stop any active exploration of it so it can be cleaned up.
diff --git a/backend/app/routes/downloads.py b/backend/app/routes/downloads.py
index a6dbb662..417d7c72 100644
--- a/backend/app/routes/downloads.py
+++ b/backend/app/routes/downloads.py
@@ -38,6 +38,7 @@ from app.models import (
     MediaAsset,
     User,
 )
+from app.routes._common import get_or_404
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
@@ -1091,8 +1092,7 @@ def admin_set_quota(
     admin: User = Depends(admin_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    if db.get(User, user_id) is None:
-        raise HTTPException(status_code=404, detail="Unknown user")
+    get_or_404(db, User, user_id, what="user")
     cur = quota.resolve(db, user_id)
     row = db.get(DownloadQuota, user_id)
     if row is None:
diff --git a/backend/app/routes/feed.py b/backend/app/routes/feed.py
index a1a8a8c3..e037295b 100644
--- a/backend/app/routes/feed.py
+++ b/backend/app/routes/feed.py
@@ -29,6 +29,7 @@ from app.models import (
     Video,
     VideoState,
 )
+from app.routes._common import get_or_404
 from app.sync.videos import parse_iso8601_duration
 from app.utils import iso
 from app.youtube.client import YouTubeClient, YouTubeError
@@ -235,8 +236,7 @@ def set_video_state(
     status = body.status
     if status not in VALID_STATES:
         raise HTTPException(status_code=400, detail=f"status must be one of {VALID_STATES}")
-    if db.get(Video, video_id) is None:
-        raise HTTPException(status_code=404, detail="Unknown video")
+    get_or_404(db, Video, video_id, what="video")
 
     now = datetime.now(timezone.utc)
 
@@ -332,8 +332,7 @@ def set_video_progress(
     if position < 0:
         position = 0
 
-    if db.get(Video, video_id) is None:
-        raise HTTPException(status_code=404, detail="Unknown video")
+    get_or_404(db, Video, video_id, what="video")
 
     # Decide whether this position is worth keeping (else clear it).
     near_end = duration > 0 and position > duration - FINISH_MARGIN_SECONDS
diff --git a/backend/app/routes/playlists.py b/backend/app/routes/playlists.py
index a7083c95..c7617c50 100644
--- a/backend/app/routes/playlists.py
+++ b/backend/app/routes/playlists.py
@@ -23,7 +23,7 @@ from app.sync.playlists import (
     sync_user_playlists,
 )
 from app.ratelimit import RateLimiter
-from app.routes._common import not_found, owned_or_404
+from app.routes._common import get_or_404, owned_or_404
 from app.youtube.client import YouTubeClient, YouTubeError
 
 router = APIRouter(prefix="/api/playlists", tags=["playlists"])
@@ -292,8 +292,7 @@ def add_watch_later(
 ) -> dict:
     """Bookmark shortcut: add a video to the built-in Watch later playlist."""
     video_id = body.video_id
-    if db.get(Video, video_id) is None:
-        raise not_found("video")
+    get_or_404(db, Video, video_id, what="video")
     pl = _watch_later(db, user)
     _add_item(db, pl, video_id, mark_dirty=False)
     return {"saved": True, "playlist_id": pl.id}
@@ -513,8 +512,7 @@ def add_item(
 ) -> dict:
     pl = _own_playlist(db, user, playlist_id)
     video_id = body.video_id
-    if db.get(Video, video_id) is None:
-        raise not_found("video")
+    get_or_404(db, Video, video_id, what="video")
     _add_item(db, pl, video_id, mark_dirty=True)
     return {"playlist_id": pl.id, "video_id": video_id}
 
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 248855a3..3420b1d0 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -10,6 +10,7 @@ from fastapi import (
     BackgroundTasks,
     Depends,
     HTTPException,
+    Path,
     Query,
     Request,
     Response,
@@ -95,12 +96,19 @@ def image(rating_key: str, request: Request, variant: str = "thumb") -> Response
 # poster, not for a route that starts reads of the media library: a suspended or "log out
 # everywhere"-revoked cookie kept scheduling them. They are not bursty (one poll a second, one fetch
 # per track), so the DB user-load costs nothing that matters.
+#
+# Both path parameters are bounded, the same way on both routes: they become a cache FILE name
+# (`sub_<rating_key>_<ord>`), and an absurd one — a 250-digit key or ordinal — outgrew the OS's name
+# limit and turned the status poll into a 500. A Plex rating_key is a short number; the bound only
+# has to be generous.
+_RatingKey = Path(max_length=32)
+_SubOrd = Path(ge=0, le=9999)
 
 
 @router.get("/subtitle/{rating_key}/{sub_ord}/status")
 def subtitle_status(
-    rating_key: str,
-    sub_ord: int,
+    rating_key: str = _RatingKey,
+    sub_ord: int = _SubOrd,
     user: User = Depends(current_user),
     # Bounded both ways: a non-finite position used to reach the scheduler's arithmetic and 500, and
     # an absurd one reached ffmpeg's `-ss`, which refused it.
@@ -117,8 +125,8 @@ def subtitle_status(
 
 @router.get("/subtitle/{rating_key}/{sub_ord}")
 def subtitle(
-    rating_key: str,
-    sub_ord: int,
+    rating_key: str = _RatingKey,
+    sub_ord: int = _SubOrd,
     user: User = Depends(current_user),
     # Finite, like every float this router takes: `-inf` crashed the shift (a 500), `nan` stacked
     # every cue at 0. It can legitimately be negative (a subtitle nudged later than the session start).
diff --git a/backend/tests/test_hls_reaper.py b/backend/tests/test_hls_reaper.py
index 51521ed5..0c8d22ea 100644
--- a/backend/tests/test_hls_reaper.py
+++ b/backend/tests/test_hls_reaper.py
@@ -3,12 +3,20 @@
 plex/stream.py promises "a periodic reaper kills idle ones", but `reap_idle` ran only inside
 POST /session: after the last playback, an abandoned session (its ffmpeg still working through the
 film, its directory a whole segmented copy of it) lived until somebody pressed play again.
+
+And it must not take a PAUSED viewer's session: a remux finishes long before the film does, and a
+paused player with a full buffer fetches nothing — so "finished and unfetched for 30 s" (the rule a
+new session request applies) is not "abandoned".
 """
 
 import asyncio
+import time
+
+import pytest
 
 import app.main as app_main
 from app.main import app
+from app.plex import stream
 
 
 class _Configured:
@@ -31,7 +39,7 @@ def test_idle_sessions_are_reaped_while_nobody_starts_a_new_one(monkeypatch):
     monkeypatch.setattr(app_main, "shutdown_scheduler", lambda: None)
     monkeypatch.setattr(app_main.plex_subtitles, "shutdown", lambda: None)
     monkeypatch.setattr(app_main, "_HLS_REAP_EVERY_S", 0.01)
-    monkeypatch.setattr(app_main.plex_stream, "reap_idle", lambda: reaped.append(1) or 0)
+    monkeypatch.setattr(app_main.plex_stream, "reap_abandoned", lambda: reaped.append(1) or 0)
 
     async def _cycle():
         async with app_main.lifespan(app):
@@ -39,3 +47,60 @@ def test_idle_sessions_are_reaped_while_nobody_starts_a_new_one(monkeypatch):
 
     asyncio.run(_cycle())
     assert len(reaped) >= 2, "no periodic reap ran while the app was up"
+
+
+class _Proc:
+    def __init__(self, finished: bool):
+        self.finished = finished
+        self.killed = False
+
+    def poll(self):
+        return 0 if self.finished else None
+
+    def terminate(self):
+        self.killed = True
+
+    def wait(self, timeout=None):
+        return 0
+
+
+class _Session:
+    def __init__(self, tmp_path, name: str, finished: bool, idle_s: float):
+        self.dir = tmp_path / name
+        self.dir.mkdir()
+        self.proc = _Proc(finished)
+        self.last_access = time.time() - idle_s
+
+
+@pytest.fixture
+def sessions(monkeypatch):
+    live: dict = {}
+    monkeypatch.setattr(stream, "_sessions", live)
+    return live
+
+
+def test_the_periodic_pass_keeps_a_paused_viewers_finished_session(tmp_path, sessions):
+    # A remux that finished a minute ago, its viewer paused with a full buffer since.
+    s = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    sessions["12345"] = s
+    assert stream.reap_abandoned() == 0
+    assert "12345" in sessions and s.dir.exists() and not s.proc.killed
+
+
+def test_the_periodic_pass_still_reaps_what_nobody_has_touched_for_the_idle_limit(
+    tmp_path, sessions
+):
+    sessions["1"] = _Session(
+        tmp_path, "gone_done", finished=True, idle_s=stream._SESSION_IDLE_S + 5
+    )
+    sessions["2"] = _Session(
+        tmp_path, "gone_live", finished=False, idle_s=stream._SESSION_IDLE_S + 5
+    )
+    assert stream.reap_abandoned() == 2
+    assert sessions == {}
+
+
+def test_a_new_session_request_still_reaps_finished_sessions_quickly(tmp_path, sessions):
+    sessions["12345"] = _Session(tmp_path, "done", finished=True, idle_s=45)
+    assert stream.reap_idle() == 1
+    assert sessions == {}
diff --git a/backend/tests/test_not_found_detail.py b/backend/tests/test_not_found_detail.py
index c5eb78a2..b3616189 100644
--- a/backend/tests/test_not_found_detail.py
+++ b/backend/tests/test_not_found_detail.py
@@ -18,3 +18,36 @@ def test_a_gone_view_tag_or_pin_says_what_is_gone(db, make_user, as_user):
         r = getattr(client, method)(url, **({"json": {"name": "x"}} if method == "patch" else {}))
         assert r.status_code == 404, (url, r.text)
         assert r.json()["detail"] == {"code": "not_found", "reason": what}, url
+
+
+def test_a_gone_channel_video_or_user_says_what_is_gone(db, make_user, as_user):
+    """The siblings that still hand-wrote `db.get(...) is None → 404 "Unknown …"` (deep-review
+    round 4): the same gone row, but the Hungarian UI showed the English."""
+    admin = make_user(role="admin")
+    client = as_user(admin)
+    for method, url, body, what in [
+        ("post", "/api/channels/UCgone000000000000000000/block", None, "channel"),
+        ("post", "/api/videos/gone0000000/state", {"status": "watched"}, "video"),
+        (
+            "post",
+            "/api/videos/gone0000000/progress",
+            {"position_seconds": 60, "duration_seconds": 600},
+            "video",
+        ),
+        ("put", "/api/admin/downloads/quota/999999", {"max_bytes": 1}, "user"),
+    ]:
+        r = getattr(client, method)(url, **({"json": body} if body is not None else {}))
+        assert r.status_code == 404, (url, r.text)
+        assert r.json()["detail"] == {"code": "not_found", "reason": what}, url
+
+
+def test_a_nul_in_a_request_string_is_a_422_not_a_500(db, make_user, as_user):
+    """Postgres cannot hold NUL in text, so the driver refuses the query outright: a DataError, i.e.
+    a 500 with a traceback, wherever a `%00` or an escaped NUL reached a comparison (deep-review
+    round 4 — round 3 had guarded only the by-rating_key lookup). One app-wide handler now answers
+    all of them."""
+    client = as_user(make_user())
+    r = client.get("/api/plex/playlists?contains=%00")
+    assert r.status_code == 422, r.text
+    assert r.json()["detail"] == {"code": "invalid_input", "reason": "nul"}
+    assert client.get("/api/plex/playlists?contains_group=1,%00").status_code == 422
diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
index 0cd0c9b4..53085c17 100644
--- a/backend/tests/test_plex_subtitle_prepare.py
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -1002,3 +1002,75 @@ def test_a_nul_rating_key_names_no_row():
     from app.plex.lookups import by_rating_key
 
     assert by_rating_key(None, PlexItem, "12\x0034") is None  # type: ignore[arg-type]
+
+
+# --- the fourth deep-review round ---------------------------------------------------------------
+
+
+def test_a_pass_whose_output_could_not_be_kept_is_backed_off_like_a_failed_one(monkeypatch):
+    """`publish` refusing (a full or read-only cache volume) returned quietly, so `_run` recorded
+    nothing and every 1 s poll queued the window AND the whole-container pass again — the file read
+    end to end over and over, the player on "preparing" for good."""
+    _stub_item(monkeypatch)
+    pool = _manual_pool(monkeypatch)
+    monkeypatch.setattr(subtitles, "cache_write", lambda key, vtt: False)
+    assert subtitles.ensure("98614", 3, at=600.0)["state"] == "preparing"
+    assert [a[3] for _, a in pool.jobs] == [570.0, None]
+    pool.run_all()
+    after = subtitles.ensure("98614", 3, at=600.0)
+    assert (after["state"], after["code"]) == ("unavailable", "extract_failed")
+    for _ in range(3):
+        subtitles.ensure("98614", 3, at=600.0)
+    assert pool.jobs == [], "the same reads were queued again"
+
+
+def test_a_sidecar_that_could_not_be_kept_is_recorded_as_failed(monkeypatch):
+    _stub_item(monkeypatch)
+    pool = _manual_pool(monkeypatch)
+    monkeypatch.setattr(subtitles, "cache_write", lambda key, vtt: False)
+    subtitles.ensure("98614", 0, at=600.0)
+    pool.run_all()
+    subtitles.ensure("98614", 0, at=600.0)
+    assert pool.jobs == [], "a refused sidecar publish was queued again"
+
+
+def test_an_unreadable_cached_track_is_said_once_and_not_rescheduled(monkeypatch):
+    """A VTT on disk that cannot be read: `publish` will not merge into it and a job whose sidecar
+    covers the position skips as done, so scheduling could only ever leave the player on
+    "preparing"."""
+    pool = _manual_pool(monkeypatch)
+    key = subtitles.cache_key("98614", 0)
+    subtitles.publish(key, _vtt(_cue("16:20.000", "16:22.000", "x")), (970.0, 1300.0), False)
+    monkeypatch.setattr(subtitles, "cache_read", lambda k: None)  # an I/O error on the read
+    st = subtitles.ensure("98614", 0, at=1000.0)
+    assert (st["state"], st["code"], st["gen"]) == ("unavailable", "cache_unreadable", 0)
+    assert pool.jobs == []
+
+
+def test_an_absurd_rating_key_or_ordinal_is_refused_not_a_500(client, monkeypatch):
+    """They become a cache FILE name: a 250-digit key outgrew the OS name limit, and pathlib's
+    `exists()` re-raises that (ENAMETOOLONG) instead of answering False — a 500 on every poll."""
+    pool = _manual_pool(monkeypatch)
+    long_key = "9" * 250
+    for url in (
+        f"/api/plex/subtitle/{long_key}/0/status",
+        f"/api/plex/subtitle/98614/{long_key}/status",
+        f"/api/plex/subtitle/{long_key}/0",
+    ):
+        assert client.get(url).status_code == 422, url
+    assert pool.jobs == []
+    # …and the cache helpers themselves no longer throw on such a name.
+    assert subtitles.read_meta(subtitles.cache_key(long_key, 0)) == ([], False)
+
+
+def test_a_read_ahead_window_that_failed_is_not_queued_again(monkeypatch):
+    """Near a covered edge the probe moves just past it, and `_schedule` has no failed-span check of
+    its own: without the guard, every poll re-queued the same failing window read."""
+    pool = _manual_pool(monkeypatch)
+    subtitles._FULL_FAILED["98614"] = time.monotonic()
+    key = subtitles.cache_key("98614", 0)
+    subtitles.publish(key, _vtt(_cue("16:20.000", "16:22.000", "x")), (970.0, 1300.0), False)
+    subtitles._window_fail(key, (1271.0, 1601.0))
+    for at in (1250.0, 1252.0, 1254.0):
+        assert subtitles.ensure("98614", 0, at=at)["state"] == "partial"
+    assert pool.jobs == [], "the failed read-ahead window was queued again"
diff --git a/frontend/src/i18n/locales/en/errors.json b/frontend/src/i18n/locales/en/errors.json
index 2d1b8388..64c6d201 100644
--- a/frontend/src/i18n/locales/en/errors.json
+++ b/frontend/src/i18n/locales/en/errors.json
@@ -13,7 +13,8 @@
     "move_target": "The playlist you're moving it to doesn't exist any more.",
     "video": "This video isn't in the library any more.",
     "invite": "This invite doesn't exist any more.",
-    "user": "This user doesn't exist any more."
+    "user": "This user doesn't exist any more.",
+    "channel": "This channel isn't in the library any more."
   },
   "ok": "OK",
   "offline": {
diff --git a/frontend/src/i18n/locales/hu/errors.json b/frontend/src/i18n/locales/hu/errors.json
index 7fb3e5c8..14b0d867 100644
--- a/frontend/src/i18n/locales/hu/errors.json
+++ b/frontend/src/i18n/locales/hu/errors.json
@@ -13,7 +13,8 @@
     "move_target": "A lejátszási lista, ahová áthelyeznéd, már nem létezik.",
     "video": "Ez a videó már nincs a könyvtárban.",
     "invite": "Ez a meghívó már nem létezik.",
-    "user": "Ez a felhasználó már nem létezik."
+    "user": "Ez a felhasználó már nem létezik.",
+    "channel": "Ez a csatorna már nincs a könyvtárban."
   },
   "ok": "OK",
   "offline": {

From 6a925850981828498806ee945cb025ec9630d45f Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 23:18:33 +0200
Subject: [PATCH 31/52] fix(plex): the player restarts a reaped session,
 finishes a played-through item as watched, and starts each item once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 4, the Plex player.

- A 404 on an HLS session that WAS playing means the server reaped it (a long pause, a deploy);
  hls.js never retries a 4xx, so playback ended with "couldn't play". A new session at the playhead
  now takes its place (the frontend half of the paused-viewer reap fix). A session that 404s before
  its manifest is still a plain failure, so it cannot restart itself in a loop.
- Leaving an item that ended, or that the credits auto-skip left, sent a final checkpoint at the
  credits (racing the watched mark, and pushing a resume point to Plex after the scrobble) and
  patched "new, at 49:55" into the cache — Prev reopened it at its last seconds. `finish` settles it
  as watched at 0, said before the pause whose own checkpoint could land first.
- An audio switch, an A/V offset change and every seek control read `abs`, which is 0 until
  playback ticks: a resume at 20:00 restarted from 0:00. They use the shared `playhead`.
- A seek while a restart is pending always restarts (the old media's `seekable` described the old
  session, and the pending answer overrode the newer seek).
- A superseded direct-play session's loadedmetadata/canplay are generation-gated and detached (they
  seeked the next item to the previous one's resume point).
- The session starts once per item: a reconnect refetch, the info panel's watched toggle or a
  language switch no longer restarts the film at the last checkpoint.
- Tests for the session generation's failure paths and the item-change bump, which had none.
---
 .../components/PlexPlayer.hls.dom.test.tsx    | 164 +++++++++++++
 .../PlexPlayer.session.dom.test.tsx           | 224 +++++++++++++++++-
 frontend/src/components/PlexPlayer.tsx        | 137 ++++++++---
 frontend/src/lib/plexPlayerHooks.ts           |  81 +++++--
 4 files changed, 552 insertions(+), 54 deletions(-)
 create mode 100644 frontend/src/components/PlexPlayer.hls.dom.test.tsx

diff --git a/frontend/src/components/PlexPlayer.hls.dom.test.tsx b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
new file mode 100644
index 00000000..795a8869
--- /dev/null
+++ b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+//
+// The Plex player's HLS path, with hls.js replaced by a stand-in the test drives (jsdom has no
+// MediaSource, so the real one never runs here). Its own file because the module mock is file-wide.
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { render, cleanup, waitFor, screen, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+
+// Hoisted with the mock below (vi.mock runs before the module body).
+const { FakeHls, hlsInstances } = vi.hoisted(() => {
+  type Handler = (event: string, data: unknown) => void;
+  const hlsInstances: InstanceType<typeof FakeHls>[] = [];
+  class FakeHls {
+    handlers = new Map<string, Handler[]>();
+    audioTrack = 0;
+    constructor() {
+      hlsInstances.push(this);
+    }
+    on(event: string, fn: Handler) {
+      this.handlers.set(event, [...(this.handlers.get(event) ?? []), fn]);
+    }
+    emit(event: string, data: unknown = {}) {
+      for (const fn of this.handlers.get(event) ?? []) fn(event, data);
+    }
+    loadSource() {}
+    attachMedia() {}
+    destroy() {}
+  }
+  return { FakeHls, hlsInstances };
+});
+vi.mock("hls.js", async (importOriginal) => {
+  const actual = (await importOriginal<{ default: typeof import("hls.js").default }>()).default;
+  return {
+    default: Object.assign(FakeHls, {
+      isSupported: () => true,
+      Events: actual.Events,
+      ErrorTypes: actual.ErrorTypes,
+    }),
+  };
+});
+
+import Hls from "hls.js";
+import PlexPlayer from "./PlexPlayer";
+import { api, type PlexItemDetail } from "../lib/api";
+import { ACTIVE_ACCOUNT_KEY } from "../lib/activeAccount";
+
+type Media = HTMLMediaElement & { _t?: number };
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+  Object.defineProperty(HTMLMediaElement.prototype, "currentTime", {
+    configurable: true,
+    get(this: Media) {
+      return this._t ?? 0;
+    },
+    set(this: Media, v: number) {
+      this._t = v;
+    },
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "play", {
+    configurable: true,
+    value: () => Promise.resolve(),
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "pause", { configurable: true, value() {} });
+  Object.defineProperty(HTMLMediaElement.prototype, "load", { configurable: true, value() {} });
+  Object.defineProperty(HTMLMediaElement.prototype, "seekable", {
+    configurable: true,
+    get: () => ({ length: 0, end: () => 0 }),
+  });
+  Object.defineProperty(HTMLMediaElement.prototype, "textTracks", {
+    configurable: true,
+    get: () => Object.assign([], { addEventListener() {}, removeEventListener() {} }),
+  });
+});
+
+beforeEach(() => {
+  sessionStorage.setItem(ACTIVE_ACCOUNT_KEY, "7");
+  hlsInstances.length = 0;
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+  sessionStorage.clear();
+  localStorage.clear();
+});
+
+const detail = {
+  id: "A",
+  title: "Title A",
+  type: "movie",
+  duration_seconds: 3000,
+  status: "new",
+  position_seconds: 600,
+  audio_streams: [{ ord: 0, label: "English", language: "en", default: true }],
+  subtitle_streams: [],
+  markers: [],
+} as unknown as PlexItemDetail;
+
+function mount() {
+  vi.spyOn(api, "plexItem").mockResolvedValue(detail);
+  vi.spyOn(api, "plexProgress").mockResolvedValue(undefined as never);
+  const session = vi
+    .spyOn(api, "plexSession")
+    .mockResolvedValue({ mode: "hls", url: "/hls/A/index.m3u8", start_s: 600 } as never);
+  render(
+    <QueryClientProvider
+      client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}
+    >
+      <PlexPlayer itemId="A" onClose={() => {}} />
+    </QueryClientProvider>,
+  );
+  return session;
+}
+
+const lost404 = {
+  fatal: true,
+  type: Hls.ErrorTypes.NETWORK_ERROR,
+  details: "fragLoadError",
+  response: { code: 404, text: "No active playback session" },
+};
+
+describe("an HLS session the server no longer has", () => {
+  it("is restarted where the viewer is, instead of ending playback", async () => {
+    // The server reaps a session nobody fetches from (a long pause; a deploy). hls.js never retries
+    // a 4xx, so the next segment's 404 used to end playback with "couldn't play".
+    const session = mount();
+    await waitFor(() => expect(hlsInstances).toHaveLength(1));
+    act(() => hlsInstances[0]!.emit(Hls.Events.MANIFEST_PARSED));
+    const v = document.querySelector("video") as Media;
+    v._t = 700; // 600 + 700 − the HLS lag
+    act(() => void v.dispatchEvent(new Event("timeupdate")));
+    act(() => hlsInstances[0]!.emit(Hls.Events.ERROR, lost404));
+    await waitFor(() => expect(session).toHaveBeenCalledTimes(2));
+    expect(session.mock.calls[1]![1]).toBeCloseTo(1299, 0);
+    expect(screen.queryByText("plex.player.errGeneric")).toBeNull();
+  });
+
+  it("is a failure, not a restart, when the session never played", async () => {
+    // Otherwise a session that 404s from the start would restart itself in a loop.
+    const session = mount();
+    await waitFor(() => expect(hlsInstances).toHaveLength(1));
+    act(() => hlsInstances[0]!.emit(Hls.Events.ERROR, lost404));
+    await screen.findByText("plex.player.errGeneric");
+    expect(session).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/frontend/src/components/PlexPlayer.session.dom.test.tsx b/frontend/src/components/PlexPlayer.session.dom.test.tsx
index d2fecf9c..b33b0e86 100644
--- a/frontend/src/components/PlexPlayer.session.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.session.dom.test.tsx
@@ -18,7 +18,7 @@ vi.mock("react-i18next", async (importOriginal) => {
 });
 
 import PlexPlayer from "./PlexPlayer";
-import { api, type PlexItemDetail } from "../lib/api";
+import { api, HttpError, type PlexItemDetail } from "../lib/api";
 import { qk } from "../lib/queryKeys";
 import { notify } from "../lib/notifications";
 import { ACTIVE_ACCOUNT_KEY } from "../lib/activeAccount";
@@ -276,3 +276,225 @@ it("shows a toast raised while it is open inside itself, not under its scrim", a
   while (host && !host.contains(toast)) host = host.parentElement;
   expect(host).not.toBe(document.body); // the player's own host, beside its <video>
 });
+
+// --- deep-review round 4 ------------------------------------------------------------------------
+
+/** A session answer that FAILS when the test says so. */
+function deferredFailure() {
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<Awaited<ReturnType<typeof api.plexSession>>>((_r, j) => (reject = j));
+  return { promise, reject };
+}
+
+const startsAsked = (id: string) =>
+  vi
+    .mocked(api.plexSession)
+    .mock.calls.filter(([i]) => i === id)
+    .map(([, at]) => at);
+
+describe("leaving an item that was played through", () => {
+  const prefs = (p: object) =>
+    localStorage.setItem("siftlode.plexPlayerPrefs.7", JSON.stringify({ subLang: "en", ...p }));
+
+  it("settles it as watched when it ended, so Prev does not reopen it at its last seconds", async () => {
+    prefs({ upNext: false });
+    const { qc, progress } = mount({
+      details: { A: item("A"), B: item("B") },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    vi.spyOn(api, "plexSetState").mockResolvedValue(undefined as never);
+    await playingAt("/media/A", 2995);
+    act(() => void video().dispatchEvent(new Event("ended")));
+    await screen.findByText("Title B");
+    await tick();
+    const cached = qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"));
+    expect([cached?.status, cached?.position_seconds]).toEqual(["watched", 0]);
+    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([]);
+    fireEvent.click(screen.getByLabelText("plex.player.prev"));
+    await waitFor(() => expect(startsAsked("A")).toHaveLength(2));
+    expect(startsAsked("A")[1]).toBe(0);
+  });
+
+  it("sends no checkpoint at the credits when the auto-skip leaves it", async () => {
+    // A final checkpoint at the credits raced the watched mark: landing second, it left the row
+    // watched WITH a resume point, and pushed that point to Plex right after the scrobble.
+    prefs({ autoSkipCredits: true, autoSkipDelay: 0 });
+    const withCredits = {
+      ...item("A"),
+      markers: [{ type: "credits", start_s: 2900, end_s: 2995 }],
+    } as unknown as PlexItemDetail;
+    const { qc, progress } = mount({
+      details: { A: withCredits, B: item("B") },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    const setState = vi.spyOn(api, "plexSetState").mockResolvedValue(undefined as never);
+    await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+    // The 'pause' event (and its checkpoint) can land before the player has re-rendered for the
+    // next item — here it lands at once.
+    video().pause = function (this: HTMLMediaElement) {
+      this.dispatchEvent(new Event("pause"));
+    };
+    await playingAt("/media/A", 2910);
+    await screen.findByText("Title B");
+    await tick(); // the pause() that go() queued has fired its events by now
+    expect(setState).toHaveBeenCalledWith("A", "watched");
+    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([]);
+    const cached = qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"));
+    expect([cached?.status, cached?.position_seconds]).toEqual(["watched", 0]);
+  });
+});
+
+describe("restarting the session before playback has ticked", () => {
+  it("an audio switch or a keyboard seek keeps the resume point", async () => {
+    const twoAudio = {
+      ...item("A", 1200),
+      audio_streams: [
+        { ord: 0, label: "English", language: "en", default: true },
+        { ord: 1, label: "Magyar", language: "hu", default: false },
+      ],
+    } as unknown as PlexItemDetail;
+    mount({ details: { A: twoAudio }, sessions: { A: () => new Promise(() => {}) } });
+    await waitFor(() => expect(startsAsked("A")).toEqual([1200]));
+    fireEvent.keyDown(window, { key: "a" });
+    fireEvent.keyDown(window, { key: "ArrowRight" });
+    await waitFor(() => expect(startsAsked("A")).toHaveLength(3));
+    expect(startsAsked("A")).toEqual([1200, 1200, 1210]);
+  });
+});
+
+it("a seek made while a restart is pending wins over it", async () => {
+  let calls = 0;
+  const pending = deferred();
+  mount({
+    details: { A: item("A") },
+    sessions: {
+      A: () => {
+        calls++;
+        if (calls === 1) return Promise.resolve(direct("A"));
+        return calls === 2 ? pending.promise : new Promise(() => {});
+      },
+    },
+  });
+  await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+  Object.defineProperty(video(), "seekable", { get: () => ({ length: 1, end: () => 100 }) });
+  await playingAt("/media/A", 95);
+  fireEvent.click(screen.getByLabelText("plex.player.forward10")); // 105: past the buffer → restart
+  fireEvent.click(screen.getByLabelText("plex.player.rewind10")); // 95: inside the OLD buffer
+  await waitFor(() => expect(startsAsked("A")).toEqual([0, 105, 95]));
+  await act(async () => pending.resolve({ mode: "direct", url: "/media/A2", start_s: 0 } as never));
+  await tick();
+  expect(video().getAttribute("src")).toBe("/media/A"); // the superseded 105 answer never attached
+});
+
+it("a direct-play item left before its metadata does not seek the next one", async () => {
+  mount({
+    details: { A: item("A", 1200), B: item("B") },
+    sessions: { A: () => Promise.resolve(direct("A")), B: () => Promise.resolve(direct("B")) },
+    queue: ["A", "B"],
+  });
+  await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+  fireEvent.click(screen.getByLabelText("plex.player.next"));
+  await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/B"));
+  act(() => void video().dispatchEvent(new Event("loadedmetadata")));
+  expect(video().currentTime).toBe(0); // not A's resume point, 1200
+});
+
+it("a refetch of the playing item's detail does not restart it", async () => {
+  // react-query refetches it on reconnect, and the in-player info panel invalidates it after a
+  // watched toggle — each one restarted the film at the last saved checkpoint.
+  const details = { A: item("A", 100) };
+  const { qc } = mount({ details, sessions: { A: () => Promise.resolve(direct("A")) } });
+  await playingAt("/media/A", 1500);
+  details.A = item("A", 1490);
+  await act(async () => {
+    await qc.invalidateQueries({ queryKey: qk.plexItem("A") });
+  });
+  await tick();
+  expect(vi.mocked(api.plexItem).mock.calls.length).toBeGreaterThan(1); // it did refetch
+  expect(startsAsked("A")).toEqual([100]);
+});
+
+describe("a session request that fails", () => {
+  it("is not reported when it has been superseded", async () => {
+    const slowB = deferredFailure();
+    mount({
+      details: { A: item("A"), B: item("B"), C: item("C") },
+      sessions: {
+        A: () => Promise.resolve(direct("A")),
+        B: () => slowB.promise,
+        C: () => Promise.resolve(direct("C")),
+      },
+      queue: ["A", "B", "C"],
+    });
+    await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+    fireEvent.click(screen.getByLabelText("plex.player.next"));
+    await screen.findByText("Title B");
+    fireEvent.click(screen.getByLabelText("plex.player.next"));
+    await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/C"));
+    await act(async () => slowB.reject(new HttpError(404)));
+    await tick();
+    expect(screen.queryByText("plex.player.errNotFound")).toBeNull();
+  });
+
+  it("keeps following the old stream when a seek-restart fails", async () => {
+    let calls = 0;
+    const { progress, unmount } = mount({
+      details: { A: item("A") },
+      sessions: {
+        A: () =>
+          calls++ === 0 ? Promise.resolve(direct("A")) : Promise.reject(new HttpError(500)),
+      },
+    });
+    await playingAt("/media/A", 1500);
+    fireEvent.click(screen.getByLabelText("plex.player.forward10"));
+    await screen.findByText("plex.player.errGeneric");
+    await playingAt("/media/A", 1600); // the old stream plays on
+    unmount();
+    expect(progress.mock.calls).toContainEqual(["A", 1600, 3000, true]);
+  });
+
+  it("saves nothing of the previous item's position when moving to the next one fails", async () => {
+    const { progress, unmount } = mount({
+      details: { A: item("A"), B: item("B") },
+      sessions: {
+        A: () => Promise.resolve(direct("A")),
+        B: () => Promise.reject(new HttpError(404)),
+      },
+      queue: ["A", "B"],
+    });
+    await playingAt("/media/A", 1500);
+    fireEvent.click(screen.getByLabelText("plex.player.next"));
+    await screen.findByText("plex.player.errNotFound");
+    await tick();
+    await playingAt("/media/A", 1600); // A's media, still attached, ticks once more
+    unmount();
+    expect(progress.mock.calls.filter(([id]) => id === "B")).toEqual([]);
+  });
+});
+
+it("a session answer that lands while the next item's detail is still loading is dropped", async () => {
+  const slowB = deferred();
+  mount({
+    details: { A: item("A"), B: item("B"), C: item("C") },
+    sessions: {
+      A: () => Promise.resolve(direct("A")),
+      B: () => slowB.promise,
+      C: () => Promise.resolve(direct("C")),
+    },
+    queue: ["A", "B", "C"],
+  });
+  await waitFor(() => expect(video()?.getAttribute("src")).toBe("/media/A"));
+  const real = vi.mocked(api.plexItem).getMockImplementation()!;
+  vi.mocked(api.plexItem).mockImplementation((id: string, lang?: string) =>
+    id === "C" ? new Promise(() => {}) : real(id, lang),
+  );
+  fireEvent.click(screen.getByLabelText("plex.player.next"));
+  await waitFor(() => expect(startsAsked("B")).toHaveLength(1));
+  fireEvent.click(screen.getByLabelText("plex.player.next"));
+  await tick();
+  await act(async () => slowB.resolve(direct("B")));
+  await tick();
+  expect(video().getAttribute("src")).not.toBe("/media/B");
+});
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index e8b5a80b..e32b9b0c 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -45,6 +45,7 @@ import { createFragMeter } from "../lib/plexStats";
 import { UpNextCard } from "./UpNextCard";
 import Toaster from "./ui/Toaster";
 import {
+  playhead,
   useAutoSkip,
   useControlsVisibility,
   useFullscreen,
@@ -115,6 +116,12 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   // middle item under the last one's title and recorded its progress there) or attach a stream to the
   // detached <video> after Back, never destroyed, keeping the server session warm.
   const sessGenRef = useRef(0);
+  // Removes the media listeners the current session put on the <video> (its canplay / loadedmetadata
+  // handlers). A newer session, an item change and the unmount all call it: the generation check
+  // guards the `await`, and these fire LATER — a superseded direct-play item's loadedmetadata used to
+  // run on the next item's media and seek it to the old item's resume point (whose first checkpoint
+  // then saved it), or start the old media playing under the new title.
+  const detachSessionRef = useRef<() => void>(() => {});
   // Whether the <video>'s clock belongs to the session `sessionStartRef` describes. False from the
   // moment a session is asked for until it has answered: the media still attached meanwhile is the
   // OLD one, so `sessionStartRef + currentTime` was the previous item's position (go()'s pause() fires
@@ -263,6 +270,19 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       if (!video) return;
       const gen = ++sessGenRef.current;
       const current = () => gen === sessGenRef.current && aliveRef.current;
+      detachSessionRef.current();
+      detachSessionRef.current = () => {};
+      const listen = (type: string, fn: () => void, once = false) => {
+        const guarded = () => {
+          if (current()) fn();
+        };
+        video.addEventListener(type, guarded, { once });
+        const prev = detachSessionRef.current;
+        detachSessionRef.current = () => {
+          prev();
+          video.removeEventListener(type, guarded);
+        };
+      };
       clockLiveRef.current = false;
       loadStartRef.current = startAt;
       setReady(false);
@@ -319,10 +339,13 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       // the video paused after a seek even though the user was watching. Retry once the element can
       // actually play. Idempotent — only acts if still paused.
       if (resumePlay) {
-        const onCanPlay = () => {
-          if (aliveRef.current && videoRef.current?.paused) videoRef.current.play().catch(() => {});
-        };
-        video.addEventListener("canplay", onCanPlay, { once: true });
+        listen(
+          "canplay",
+          () => {
+            if (videoRef.current?.paused) videoRef.current.play().catch(() => {});
+          },
+          true,
+        );
       }
       if (hlsRef.current) {
         hlsRef.current.destroy();
@@ -353,7 +376,11 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         hls.loadSource(`${sess.url}?t=${Math.floor(startAt)}`);
         hls.attachMedia(video);
         // Subtitles are native <track>s (not muxed into the HLS), so nothing subtitle-related here.
+        // Whether this session has ever played. Only such a session can be "lost" (below): one that
+        // fails before its manifest is simply a failure, and must not restart itself in a loop.
+        let parsed = false;
         hls.on(Hls.Events.MANIFEST_PARSED, () => {
+          parsed = true;
           setReady(true);
           if (aliveRef.current && resumePlay) video.play().catch(() => {});
         });
@@ -374,20 +401,32 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         });
         // A fatal HLS error (e.g. the remux session died / the file became unreadable) would
         // otherwise leave the spinner up forever — surface it instead.
+        //
+        // Except a 404 on a session that WAS playing: the server has reaped it (a pause longer than
+        // its idle limit, a deploy) and the stream is simply gone, not broken. hls.js never retries a
+        // 4xx, so this used to end playback with "couldn't play" after the buffer ran out; a new
+        // session at the playhead is what closing and reopening the player did by hand.
         hls.on(Hls.Events.ERROR, (_e, data) => {
-          if (data.fatal) setLoadError(tRef.current("plex.player.errGeneric"));
+          if (!data.fatal || !current()) return;
+          if (parsed && data.type === Hls.ErrorTypes.NETWORK_ERROR && data.response?.code === 404) {
+            loadSession(playhead(absRef, loadStartRef), !video.paused);
+            return;
+          }
+          setLoadError(tRef.current("plex.player.errGeneric"));
         });
       } else {
         // direct file (or Safari native HLS)
         video.src = sess.url;
         video.load();
-        const onMeta = () => {
-          if (sess.mode === "direct" && startAt > 0) video.currentTime = startAt;
-          setReady(true);
-          if (aliveRef.current && resumePlay) video.play().catch(() => {});
-          video.removeEventListener("loadedmetadata", onMeta);
-        };
-        video.addEventListener("loadedmetadata", onMeta);
+        listen(
+          "loadedmetadata",
+          () => {
+            if (sess.mode === "direct" && startAt > 0) video.currentTime = startAt;
+            setReady(true);
+            if (resumePlay) video.play().catch(() => {});
+          },
+          true,
+        );
       }
     },
     [id], // NOT `t` — see tRef above (a language switch must not rebuild this / reload the session).
@@ -430,9 +469,18 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     loadStartRef,
   });
 
-  // Start playback when the detail arrives (resume from the saved position unless already watched).
+  // Start playback when the detail arrives (resume from the saved position unless already watched) —
+  // ONCE per item. The detail object changes under a playing item too: react-query refetches it on
+  // reconnect (Wi-Fi blips, the query is stale after 30 s and every checkpoint moved the position),
+  // the in-player info panel invalidates it after a watched toggle, a language switch fetches it
+  // again. Keyed on its identity, each of those restarted the film at the last saved checkpoint — or
+  // at 0 after marking it watched (deep-review round 4). The trade-off: a detail that was stale in
+  // the cache when the player opened is not corrected by the refetch that follows; the player's own
+  // leave-patch (usePlexProgress) keeps the cache honest for everything played here.
+  const startedForRef = useRef<string | null>(null);
   useEffect(() => {
-    if (!detail) return;
+    if (!detail || detail.id !== id || startedForRef.current === id) return;
+    startedForRef.current = id;
     // Restore the per-account audio/subtitle language choice, resolved to THIS item's tracks. Set the
     // audio ref synchronously so the loadSession below picks the right track on the first request.
     const aOrd = audioOrdForLang(detail.audio_streams ?? [], prefs.audioLang);
@@ -441,20 +489,24 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     setSubOrd(subOrdForLang(detail.subtitle_streams ?? [], prefs.subLang));
     const resume = detail.status !== "watched" ? detail.position_seconds || 0 : 0;
     loadSession(resume);
-    return () => {
-      // A session still in flight for this item must not land after it. The LIVE counter is the point
-      // (bumping it is what outdates the pending call), so the "ref may have changed" hint is moot.
-      // eslint-disable-next-line react-hooks/exhaustive-deps
+    // Prefs are applied at item load only; changing one via the picker must NOT re-run this (it would
+    // double-load the session — the picker handlers already reload/toggle).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [detail, id, loadSession]);
+  // Leaving the item: a session still in flight for it must not land after it, and its stream goes.
+  useEffect(
+    () => () => {
       sessGenRef.current++;
+      detachSessionRef.current();
+      detachSessionRef.current = () => {};
+      startedForRef.current = null;
       if (hlsRef.current) {
         hlsRef.current.destroy();
         hlsRef.current = null;
       }
-    };
-    // Prefs are applied at item load only; changing one via the picker must NOT re-run this (it would
-    // double-load the session — the picker handlers already reload/toggle).
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [detail, loadSession]);
+    },
+    [id],
+  );
 
   // Full media teardown on unmount (Back): stop + detach the <video> and destroy hls, so a late
   // play() can't leave audio playing on a detached element after leaving the player.
@@ -548,7 +600,13 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   }, [id]);
 
   // Periodic + on-unmount progress checkpoint (interval flush + pause/pagehide + reopen cache patch).
-  const { settle: settleProgress } = usePlexProgress({ id, qc, videoRef, absRef, durationRef });
+  const { settle: settleProgress, finish: finishProgress } = usePlexProgress({
+    id,
+    qc,
+    videoRef,
+    absRef,
+    durationRef,
+  });
 
   // --- seeking (native within the loaded region, else restart the session) ---------------------
   const seekTo = useCallback(
@@ -564,7 +622,14 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       absRef.current = T;
       setAbs(T);
       const rel = T - sessionStartRef.current;
-      if (rel >= 0 && rel <= (video.seekable.length ? video.seekable.end(0) : 0) + 0.5) {
+      // Native only when the attached media IS the current session. While one is still being asked
+      // for, `sessionStartRef` and `seekable` describe the OLD one: a native seek there left the
+      // pending restart current, and its answer then jumped to the earlier target.
+      if (
+        clockLiveRef.current &&
+        rel >= 0 &&
+        rel <= (video.seekable.length ? video.seekable.end(0) : 0) + 0.5
+      ) {
         video.currentTime = rel; // native seek within the loaded region keeps playing on its own
       } else {
         loadSession(T, wasPlaying); // session restart: only auto-resume if we were playing
@@ -593,8 +658,12 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   });
 
   const go = useCallback(
-    (otherId: string | null | undefined) => {
+    (otherId: string | null | undefined, finished = false) => {
       if (otherId) {
+        // A played-through item settles as watched, with no checkpoint at the credits (see
+        // usePlexProgress's `finish`) — said BEFORE the pause below, whose own checkpoint on the
+        // 'pause' event can land before the player has re-rendered for the next item.
+        if (finished) finishProgress();
         // Stop the outgoing media BEFORE switching. If the next item fails to load (e.g. no local
         // file), loadSession returns without replacing the <video> source, leaving the old episode
         // still playing — it would then fire 'ended' against the NEW id and mark the wrong item
@@ -613,7 +682,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         setId(otherId);
       }
     },
-    [settleProgress],
+    [settleProgress, finishProgress],
   );
 
   // Prev/next: from the playlist queue when playing one, else the item's own episode neighbours.
@@ -669,6 +738,8 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       // (absRef 0) — its stray 'ended' must not mark anything watched or cascade another advance.
       if (absRef.current <= 0) return;
       api.plexSetState(id, "watched").catch(() => {});
+      // Whatever follows (the up-next card, the next item, closing) leaves a FINISHED item.
+      finishProgress();
       // With a next item and the up-next pref on, surface the end-card (poster + countdown + Cancel)
       // and let IT advance — binge stays in the viewer's control (S4/D6-A). The card only appears here,
       // on play-to-the-end; credits-auto-skip advances earlier and this handler never fires for it.
@@ -680,7 +751,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     };
     video.addEventListener("ended", onEnded);
     return () => video.removeEventListener("ended", onEnded);
-  }, [id, nextId, go, onClose]);
+  }, [id, nextId, go, onClose, finishProgress]);
 
   // Up-next card actions: advance = go to the next item (it was already marked watched on 'ended');
   // cancel = dismiss and stay on the finished frame. Loading a new item closes any lingering card.
@@ -738,7 +809,8 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   useEffect(() => {
     const seekBy = (e: KeyboardEvent, dir: -1 | 1, fine: boolean) => {
       e.preventDefault();
-      seekTo(absRef.current + dir * (fine ? fineSeekStepRef.current : seekStepRef.current));
+      const step = fine ? fineSeekStepRef.current : seekStepRef.current;
+      seekTo(playhead(absRef, loadStartRef) + dir * step);
     };
     const step = (e: KeyboardEvent, id: string | null | undefined) => {
       e.preventDefault();
@@ -1176,7 +1248,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         <div className="flex items-center gap-3 text-white">
           <Ctrl
             label={t("plex.player.rewind10")}
-            onClick={() => seekTo(absRef.current - 10)}
+            onClick={() => seekTo(playhead(absRef, loadStartRef) - 10)}
             align="start"
           >
             <Skip10 dir="back" />
@@ -1184,7 +1256,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
           <Ctrl label={t("plex.player.playPause")} onClick={togglePlay}>
             {playing ? <Pause className="w-6 h-6" /> : <Play className="w-6 h-6" />}
           </Ctrl>
-          <Ctrl label={t("plex.player.forward10")} onClick={() => seekTo(absRef.current + 10)}>
+          <Ctrl
+            label={t("plex.player.forward10")}
+            onClick={() => seekTo(playhead(absRef, loadStartRef) + 10)}
+          >
             <Skip10 dir="forward" />
           </Ctrl>
           <Ctrl label={t("plex.player.restart")} onClick={() => seekTo(0)}>
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index d7e4decd..0a20383a 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -84,20 +84,31 @@ export function useControlsVisibility(opts: {
 // calls it itself BEFORE it moves to another item: by the time this effect's cleanup runs for the
 // outgoing id, the position has already been reset for the incoming one — so the cleanup found 0 and
 // skipped, and every Next dropped the last stretch watched of the episode being left.
+//
+// `finish` says the item was played THROUGH (it ended, or the credits auto-skip left it) and the
+// caller has marked it watched. From then on leaving it records no position: a checkpoint at the
+// credits raced the watched mark (landing second, it left a watched row with a resume point and put
+// that point back on Plex after the scrobble), and the reopen patch wrote "new, at 49:55" into the
+// cache — Prev within the next 30 s reopened the episode at its last seconds (or at the credits,
+// which auto-skipped straight back). The server stores a watched item at position 0, so the patch
+// says exactly that. Playing on from the finished frame takes the finish back.
 export function usePlexProgress(opts: {
   id: string;
   qc: QueryClient;
   videoRef: RefObject<HTMLVideoElement | null>;
   absRef: MutableRefObject<number>;
   durationRef: MutableRefObject<number>;
-}): { settle: () => void } {
+}): { settle: () => void; finish: () => void } {
   const { id, qc, videoRef, absRef, durationRef } = opts;
   const settleRef = useRef<() => void>(() => {});
+  const finishRef = useRef<() => void>(() => {});
   useEffect(() => {
+    let finished = false;
     // `final` = a settled checkpoint (pause / page-hide / leaving the player) vs. the periodic tick.
     // Only final checkpoints get mirrored to a linked Plex account (backend-side debounce), so Plex
     // sees the resume position when the user actually stops — not a timeline call every 10 seconds.
     const flush = (final = false) => {
+      if (finished) return;
       if (absRef.current > 0 && durationRef.current > 0)
         api
           .plexProgress(id, Math.floor(absRef.current), durationRef.current, final)
@@ -122,43 +133,72 @@ export function usePlexProgress(opts: {
     // so without this the resume point lags up to 10s — e.g. a seek right before F5 was lost. Uses a
     // keepalive beacon so the POST survives the unload (a final checkpoint — the user is leaving).
     const onHide = () => {
-      if (absRef.current > 0 && durationRef.current > 0)
+      if (!finished && absRef.current > 0 && durationRef.current > 0)
         api.plexProgressBeacon(id, Math.floor(absRef.current), durationRef.current, true);
     };
     window.addEventListener("pagehide", onHide);
+    const onPlayAgain = () => {
+      finished = false;
+    };
+    video?.addEventListener("play", onPlayAgain);
     // Back (unmount) persists the position server-side via flush(), but reopening the same item in
     // the SAME session read react-query's CACHED detail — whose position_seconds predated this watch —
     // so the resume landed at the old spot (the progress GET could also race the POST). So leaving
     // also patches the cached detail, and a reopen resumes from where we left off. (F5 was always fine:
-    // a reload starts with an empty cache and fetches the fresh position.) Safe to do only when leaving
-    // — patching while mounted would retrigger the loadSession effect and reseek mid-play. Reading the
-    // LATEST abs/duration is the whole point of the checkpoint (the resume point when leaving).
+    // a reload starts with an empty cache and fetches the fresh position.) Done when leaving, because
+    // that is when the position is final. Reading the LATEST abs/duration is the whole point of the
+    // checkpoint (the resume point when leaving).
     const settle = () => {
+      // Match the language-keyed detail query (E5 S6) so the optimistic resume patch lands.
+      const key = qk.plexItem(id, plexLang());
+      if (finished) {
+        qc.setQueryData(key, (old) =>
+          old ? { ...old, status: "watched", position_seconds: 0 } : old,
+        );
+        return;
+      }
       flush(true);
       if (absRef.current > 0 && durationRef.current > 0) {
         const pos = Math.floor(absRef.current);
-        // Match the language-keyed detail query (E5 S6) so the optimistic resume patch lands.
-        qc.setQueryData(qk.plexItem(id, plexLang()), (old) =>
-          old ? { ...old, position_seconds: pos } : old,
-        );
+        qc.setQueryData(key, (old) => (old ? { ...old, position_seconds: pos } : old));
       }
     };
     settleRef.current = settle;
+    finishRef.current = () => {
+      finished = true;
+    };
     return () => {
       window.clearInterval(iv);
       window.clearTimeout(seekTimer);
       window.removeEventListener("pagehide", onHide);
       video?.removeEventListener("pause", onPauseFlush);
       video?.removeEventListener("seeked", onSeekFlush);
+      video?.removeEventListener("play", onPlayAgain);
       settle();
       settleRef.current = () => {};
+      finishRef.current = () => {};
       qc.invalidateQueries({ queryKey: qk.plexLibrary() });
       qc.invalidateQueries({ queryKey: qk.plexShow() });
     };
     // absRef/durationRef/videoRef are stable ref objects — listed to satisfy exhaustive-deps without
     // changing when the effect re-runs (id/qc only), matching the original in-component effect.
   }, [id, qc, absRef, durationRef, videoRef]);
-  return { settle: useCallback(() => settleRef.current(), []) };
+  return {
+    settle: useCallback(() => settleRef.current(), []),
+    finish: useCallback(() => finishRef.current(), []),
+  };
+}
+
+/** Where the viewer is. `abs` only moves once playback has ticked — until then (a session still
+ *  loading, or a resumed one that has stayed paused) it reads 0 while the film is minutes in, so the
+ *  answer is where the session was ASKED to start. Anything that restarts the session "here" — an
+ *  audio switch, an A/V offset, a keyboard seek — must use this: reading `abs` restarted a resume at
+ *  20:00 from 0:00, and the next checkpoint saved that (deep-review round 4). */
+export function playhead(
+  absRef: MutableRefObject<number>,
+  loadStartRef: MutableRefObject<number>,
+): number {
+  return absRef.current > 0 ? absRef.current : loadStartRef.current;
 }
 
 // Volume/mute for the Plex player's HTML5 <video> (0..1 float, independent .muted flag). Persists to
@@ -242,7 +282,8 @@ export function useAutoSkip(opts: {
   autoSkipCredits: boolean;
   autoSkipDelay: number;
   nextId: string | null | undefined;
-  go: (id: string | null | undefined) => void;
+  /** `finished` = the item being left was played through (see usePlexProgress's `finish`). */
+  go: (id: string | null | undefined, finished?: boolean) => void;
   seekTo: (t: number) => void;
   videoRef: RefObject<HTMLVideoElement | null>;
 }): {
@@ -292,7 +333,7 @@ export function useAutoSkip(opts: {
         // Binge auto-advance: the episode we're leaving was watched through the credits, so mark IT
         // (the current id, captured here — not the reactive id, which go() is about to change).
         api.plexSetState(id, "watched").catch(() => {});
-        go(nextId);
+        go(nextId, true);
       } else seekTo(m.end_s);
     },
     [id, go, nextId, seekTo],
@@ -468,10 +509,11 @@ export function usePlexTracks(opts: {
           /* ignore */
         }
       } else {
-        loadSession(absRef.current); // single-audio: re-map the track server-side (session restart)
+        // Single audio (or the session has not answered yet): re-map the track server-side.
+        loadSession(playhead(absRef, loadStartRef));
       }
     },
-    [loadSession, detail, patchPrefs, audioRef, multiAudioRef, hlsRef, absRef],
+    [loadSession, detail, patchPrefs, audioRef, multiAudioRef, hlsRef, absRef, loadStartRef],
   );
   // Subtitles are native <track>s overlaid by the browser — switching one just flips TextTrack modes
   // (applied by the effect below), NO session restart. Off = null.
@@ -520,9 +562,9 @@ export function usePlexTracks(opts: {
       patchPrefs({ audioOffset: v });
       aoffRef.current = v;
       if (aoffTimer.current) window.clearTimeout(aoffTimer.current);
-      aoffTimer.current = window.setTimeout(() => loadSession(absRef.current), 500);
+      aoffTimer.current = window.setTimeout(() => loadSession(playhead(absRef, loadStartRef)), 500);
     },
-    [patchPrefs, loadSession, aoffRef, absRef],
+    [patchPrefs, loadSession, aoffRef, absRef, loadStartRef],
   );
 
   // --- is the selected track actually extractable yet? -------------------------------------------
@@ -541,12 +583,7 @@ export function usePlexTracks(opts: {
     // answer is where the session was asked to start. Not `sessionK`: that only lands once the
     // session request has answered, so the first poll of a fresh open read 0 from it, and after a
     // move to the next item it still held the PREVIOUS item's start.
-    queryFn: () =>
-      api.plexSubtitleStatus(
-        id,
-        subOrd as number,
-        absRef.current > 0 ? absRef.current : loadStartRef.current,
-      ),
+    queryFn: () => api.plexSubtitleStatus(id, subOrd as number, playhead(absRef, loadStartRef)),
     enabled: subOrd != null,
     // Keep polling until the track is COMPLETE, not just showable: each poll carries the current
     // position, so seeking past the extracted window is what asks for the next one. A settled

From 6d49da17fe8ef74448f95cd903a1a4f3bc75b4aa Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 23:27:08 +0200
Subject: [PATCH 32/52] fix(api): a write that hit a connection failure is
 still reported, and every failure is reported once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 4, the "one report per failure" contract round 3 introduced.

- `req` marked gateway (502/503/504) and network failures "already reported" because they raise
  the connection notice. But that notice is about connectivity and removes itself on the very next
  answer — which every caller's own resync refetch fetches at once — so a delete that hit a
  keepalive reset flashed the notice and was then reported nowhere, the list still there. Only the
  durable reports (the error dialog, the 401 sign-out) count now; the caller says the action failed.
- A connection notice the user closed swallowed every later one for the rest of the visit; it is
  raised again.
- `req` and `uploadReq` share one failure policy (`reportFailure`). The upload copy had drifted: a
  502 opened the blocking "Server error (502)" dialog and cleared a notice that was still true.
- A taken Plex collection name is a structured 409, localized, and the create/rename calls are
  quiet: it was an English dialog plus a Hungarian toast. `notifyCollectionEditError` is gone.
- The mutation onErrors that toasted unconditionally after a non-quiet request (invite approve /
  deny / add, demo whitelist, audit clear, scheduler, share, full history, edit, config tests, tag
  attach) go through `notifyActionError`; the playlist delete's hand-rolled copy of it too (it takes
  a level now). The user role / suspend / delete actions had no onError at all: a user deleted in
  another tab failed silently and stayed listed — now said, and the list refetched.
---
 backend/app/routes/plex/collections.py        |   4 +-
 backend/tests/test_plex_collections_filter.py |   1 +
 .../src/components/AdminUsers.dom.test.tsx    | 103 ++++++++++++++++++
 frontend/src/components/AdminUsers.tsx        |  28 +++--
 frontend/src/components/AuditLog.tsx          |   3 +-
 frontend/src/components/Channels.tsx          |   5 +-
 frontend/src/components/ConfigPanel.tsx       |   7 +-
 .../src/components/PlexCollectionEditor.tsx   |   8 +-
 .../src/components/PlexCollectionView.tsx     |   6 +-
 frontend/src/components/Scheduler.tsx         |   5 +-
 frontend/src/components/ShareDialog.tsx       |   3 +-
 frontend/src/components/Stats.tsx             |   3 +-
 frontend/src/components/VideoEditor.tsx       |   3 +-
 frontend/src/components/plexBrowseLists.tsx   |   7 +-
 frontend/src/components/usePlaylistActions.ts |  18 ++-
 frontend/src/i18n/locales/en/users.json       |   9 +-
 frontend/src/i18n/locales/hu/users.json       |   9 +-
 frontend/src/lib/actionErrors.test.ts         |  41 ++++---
 frontend/src/lib/actionErrors.ts              |  29 ++---
 frontend/src/lib/api/core.test.ts             |  58 +++++++++-
 frontend/src/lib/api/core.ts                  |  94 +++++++++-------
 frontend/src/lib/api/plex.ts                  |  21 ++--
 22 files changed, 328 insertions(+), 137 deletions(-)
 create mode 100644 frontend/src/components/AdminUsers.dom.test.tsx

diff --git a/backend/app/routes/plex/collections.py b/backend/app/routes/plex/collections.py
index ffcfa397..5719cf3a 100644
--- a/backend/app/routes/plex/collections.py
+++ b/backend/app/routes/plex/collections.py
@@ -347,7 +347,9 @@ def _reject_duplicate_name(
         .first()
     )
     if dup is not None and dup.rating_key != exclude_rk:
-        raise HTTPException(status_code=409, detail="A collection with this name already exists")
+        # Structured, so the bilingual UI says it in the reader's language (it was toasted in
+        # Hungarian beside an English error dialog saying the same thing).
+        raise HTTPException(status_code=409, detail={"code": "collection", "reason": "name_taken"})
 
 
 def _write_or_pending_error(wrote: bool, e: Exception) -> HTTPException:
diff --git a/backend/tests/test_plex_collections_filter.py b/backend/tests/test_plex_collections_filter.py
index 67707360..36668044 100644
--- a/backend/tests/test_plex_collections_filter.py
+++ b/backend/tests/test_plex_collections_filter.py
@@ -155,6 +155,7 @@ def test_create_collection_rejects_duplicate_name(db, monkeypatch):
             json={"library": "1", "title": "marvel", "item_rating_key": "m1"},
         )
         assert r.status_code == 409, r.text
+        assert r.json()["detail"] == {"code": "collection", "reason": "name_taken"}
     finally:
         app.dependency_overrides.clear()
 
diff --git a/frontend/src/components/AdminUsers.dom.test.tsx b/frontend/src/components/AdminUsers.dom.test.tsx
new file mode 100644
index 00000000..d94ad5e8
--- /dev/null
+++ b/frontend/src/components/AdminUsers.dom.test.tsx
@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+//
+// A failed user action is said once, and a user who is gone is not left listed (deep-review round 4).
+// setRole / suspend / delete had no onError at all — "the global error dialog says it" — but a 404
+// (the user was deleted in another tab) gets no dialog, so the click did nothing and the row stayed.
+// And the invite approve/deny toasted unconditionally on top of the dialog `req` opens for a 409.
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup, screen, fireEvent, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+vi.mock("../lib/useMe", () => ({
+  useMe: () => ({
+    id: 1,
+    email: "admin@x",
+    role: "admin",
+    pending_invites: 0,
+    pending_activations: 0,
+  }),
+}));
+vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
+const { notify } = vi.hoisted(() => ({
+  notify: vi.fn((_n: { level: string; message: string }) => 0),
+}));
+vi.mock("../lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/notifications")>()),
+  notify,
+}));
+vi.mock("../lib/errorDialog", () => ({ reportError: vi.fn() }));
+
+import AdminUsers from "./AdminUsers";
+import { api, type AdminUserRow } from "../lib/api";
+import i18n from "../i18n";
+
+const row = {
+  id: 2,
+  email: "gone@x",
+  role: "user",
+  is_suspended: false,
+  is_demo: false,
+  email_verified: true,
+  is_active: true,
+} as unknown as AdminUserRow;
+
+function answer(status: number, detail: unknown) {
+  return new Response(JSON.stringify({ detail }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+beforeEach(() => {
+  notify.mockClear();
+  localStorage.clear();
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function mount() {
+  const users = vi.spyOn(api, "adminUsers").mockResolvedValue([row] as never);
+  render(
+    <QueryClientProvider
+      client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}
+    >
+      <AdminUsers />
+    </QueryClientProvider>,
+  );
+  return users;
+}
+
+describe("a user action that fails", () => {
+  it("says a user who is gone, and refetches the list", async () => {
+    const users = mount();
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      answer(404, { code: "not_found", reason: "user" }),
+    );
+    fireEvent.click(await screen.findByText("users.roles.makeAdmin"));
+    await waitFor(() =>
+      expect(notify).toHaveBeenCalledWith({
+        level: "error",
+        message: i18n.t("errors.notFound.user"), // the request layer localizes a structured detail
+      }),
+    );
+    await waitFor(() => expect(users).toHaveBeenCalledTimes(2));
+  });
+
+  it("is not toasted on top of the error dialog the request already opened", async () => {
+    mount();
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(answer(409, "Cannot demote the last admin"));
+    fireEvent.click(await screen.findByText("users.roles.makeAdmin"));
+    const { reportError } = await import("../lib/errorDialog");
+    await waitFor(() => expect(reportError).toHaveBeenCalled());
+    expect(notify.mock.calls.filter(([n]) => n.level === "error")).toEqual([]);
+  });
+});
diff --git a/frontend/src/components/AdminUsers.tsx b/frontend/src/components/AdminUsers.tsx
index 55333a27..90ab5f27 100644
--- a/frontend/src/components/AdminUsers.tsx
+++ b/frontend/src/components/AdminUsers.tsx
@@ -38,6 +38,7 @@ import { useConfirm } from "./ConfirmProvider";
 import Tabs, { usePersistedTab } from "./ui/Tabs";
 import { PageToolbar } from "./ui/PageShell";
 import { useMe } from "../lib/useMe";
+import { notifyActionError } from "../lib/actionErrors";
 
 // Admin-only user & access management: roles, access requests (the Invite whitelist), and the
 // demo whitelist + reset. Each section is its own tab (persisted across reloads); the Access tab
@@ -120,6 +121,13 @@ function UsersRoles({ me }: { me: Me }) {
       n.delete(id);
       return n;
     });
+  // A failed user action: said once (notifyActionError skips what `req` already put in its dialog),
+  // and the list refetched — a user deleted in another tab would otherwise stay listed, every click
+  // on the row doing nothing.
+  const onGoneOrFailed = (e: unknown, fallback: string) => {
+    notifyActionError(e, fallback);
+    qc.invalidateQueries({ queryKey: qk.adminUsers() });
+  };
   const setRole = useMutation({
     mutationFn: ({ id, role }: { id: number; role: "user" | "admin"; email: string }) =>
       api.setUserRole(id, role),
@@ -129,7 +137,9 @@ function UsersRoles({ me }: { me: Me }) {
       notify({ level: "success", message: t("users.roles.updated", { email: vars.email }) });
     },
     onSettled: (_d, _e, vars) => endPending(vars.id),
-    // Errors (e.g. last-admin / self) surface via the global error dialog with the server's detail.
+    // Guards (last admin / self) surface via the global error dialog with the server's detail; what
+    // it does not show (a user deleted meanwhile, a 404) is said here — see onGoneOrFailed.
+    onError: (e) => onGoneOrFailed(e, t("users.roles.failed")),
   });
 
   const suspend = useMutation({
@@ -146,7 +156,8 @@ function UsersRoles({ me }: { me: Me }) {
       });
     },
     onSettled: (_d, _e, vars) => endPending(vars.id),
-    // Guards (demo / self / last admin) surface via the global error dialog.
+    // Guards (demo / self / last admin) surface via the global error dialog; the rest, as above.
+    onError: (e) => onGoneOrFailed(e, t("users.suspend.failed")),
   });
   const del = useMutation({
     mutationFn: ({ id }: { id: number; email: string }) => api.adminDeleteUser(id),
@@ -156,6 +167,7 @@ function UsersRoles({ me }: { me: Me }) {
       notify({ level: "success", message: t("users.delete.done", { email: vars.email }) });
     },
     onSettled: (_d, _e, vars) => endPending(vars.id),
+    onError: (e) => onGoneOrFailed(e, t("users.delete.failed")),
   });
 
   const onToggle = async (u: AdminUserRow) => {
@@ -518,7 +530,7 @@ function AdminInvites() {
       refresh();
       notify({ level: "success", message: t("settings.invites.approved", { email: vars.email }) });
     },
-    onError: () => notify({ level: "error", message: t("settings.invites.approveFailed") }),
+    onError: (e) => notifyActionError(e, t("settings.invites.approveFailed")),
   });
   const deny = useMutation({
     mutationFn: (id: number) => api.denyInvite(id),
@@ -526,7 +538,7 @@ function AdminInvites() {
       refresh();
       notify({ level: "success", message: t("settings.invites.denied") });
     },
-    onError: () => notify({ level: "error", message: t("settings.invites.denyFailed") }),
+    onError: (e) => notifyActionError(e, t("settings.invites.denyFailed")),
   });
   const onDeny = async (i: { id: number; email: string }) => {
     const ok = await confirm({
@@ -630,7 +642,7 @@ function AdminInvites() {
       refresh();
       notify({ level: "success", message: t("settings.invites.addedToWhitelist", { email }) });
     },
-    onError: () => notify({ level: "error", message: t("settings.invites.addFailed") }),
+    onError: (e) => notifyActionError(e, t("settings.invites.addFailed")),
   });
 
   const list = invites.data ?? [];
@@ -780,7 +792,7 @@ function AdminDemo() {
       qc.invalidateQueries({ queryKey: qk.demoWhitelist() });
       notify({ level: "success", message: t("settings.demo.added", { email }) });
     },
-    onError: () => notify({ level: "error", message: t("settings.demo.addFailed") }),
+    onError: (e) => notifyActionError(e, t("settings.demo.addFailed")),
   });
   const remove = useMutation({
     mutationFn: (id: number) => api.removeDemoWhitelist(id),
@@ -788,7 +800,7 @@ function AdminDemo() {
       qc.invalidateQueries({ queryKey: qk.demoWhitelist() });
       notify({ level: "success", message: t("settings.demo.removed") });
     },
-    onError: () => notify({ level: "error", message: t("settings.demo.removeFailed") }),
+    onError: (e) => notifyActionError(e, t("settings.demo.removeFailed")),
   });
   const onRemove = async (r: { id: number; email: string }) => {
     const ok = await confirm({
@@ -806,7 +818,7 @@ function AdminDemo() {
         level: "success",
         message: t("settings.demo.resetDone", { count: r.playlists_seeded }),
       }),
-    onError: () => notify({ level: "error", message: t("settings.demo.resetFailed") }),
+    onError: (e) => notifyActionError(e, t("settings.demo.resetFailed")),
   });
 
   const rows = list.data ?? [];
diff --git a/frontend/src/components/AuditLog.tsx b/frontend/src/components/AuditLog.tsx
index e382a24a..0fa2618e 100644
--- a/frontend/src/components/AuditLog.tsx
+++ b/frontend/src/components/AuditLog.tsx
@@ -12,6 +12,7 @@ import { useConfirm } from "./ConfirmProvider";
 import DataTable from "./ui/DataTable";
 import { LoadingState, StateMessage } from "./ui/QueryState";
 import { auditColumns } from "./auditColumns";
+import { notifyActionError } from "../lib/actionErrors";
 
 // Admin-only audit trail: an append-only who/what/when log of admin actions + scheduler run
 // summaries (never per-row). Read-only apart from Clear. Client-side sort/filter/paginate via
@@ -36,7 +37,7 @@ export default function AuditLog() {
       qc.invalidateQueries({ queryKey: qk.adminAudit() });
       notify({ level: "success", message: t("audit.cleared", { count: r.cleared }) });
     },
-    onError: () => notify({ level: "error", message: t("audit.clearFailed") }),
+    onError: (e) => notifyActionError(e, t("audit.clearFailed")),
   });
   const onClear = async () => {
     if (
diff --git a/frontend/src/components/Channels.tsx b/frontend/src/components/Channels.tsx
index 54799ea6..909c7874 100644
--- a/frontend/src/components/Channels.tsx
+++ b/frontend/src/components/Channels.tsx
@@ -6,6 +6,7 @@ import { Ban, Eye, EyeOff, History, LayoutGrid, Pencil, RefreshCw, Table, X } fr
 import ExcludedChannelList from "./ExcludedChannelList";
 import { api, NO_TAG_SENTINEL, type ManagedChannel } from "../lib/api";
 import { Sparkles } from "lucide-react";
+import { notifyActionError } from "../lib/actionErrors";
 import { notifyYouTubeActionError } from "../lib/youtubeErrors";
 import { accountKey, LS } from "../lib/storage";
 import { buildChannelColumns, applySyncFilter } from "./channelColumns";
@@ -182,10 +183,10 @@ export default function Channels() {
     // suggestions: acceptSuggestion optimistically dropped the channel from that cache, and on
     // failure the tag never actually attached — so the server still suggests it and the ghost chips
     // must come back rather than leaving an empty cell (honest states). Surface the write failure too.
-    onError: () => {
+    onError: (e) => {
       qc.invalidateQueries({ queryKey: qk.channels() });
       qc.invalidateQueries({ queryKey: qk.tagSuggestions() });
-      notify({ level: "error", message: t("channels.tags.updateFailed") });
+      notifyActionError(e, t("channels.tags.updateFailed"));
     },
   });
   // --- Suggested tags (E8·S4): learned from the user's own manual-tag pattern, shown as accept/dismiss
diff --git a/frontend/src/components/ConfigPanel.tsx b/frontend/src/components/ConfigPanel.tsx
index 0b8b35ee..a0300760 100644
--- a/frontend/src/components/ConfigPanel.tsx
+++ b/frontend/src/components/ConfigPanel.tsx
@@ -14,6 +14,7 @@ import { PageToolbar } from "./ui/PageShell";
 import { Switch } from "./ui/form";
 import { DraftSaveBar, type SaveState } from "./ui/DraftSaveBar";
 import { LS } from "../lib/storage";
+import { notifyActionError } from "../lib/actionErrors";
 
 // Admin Configuration page: edit DB-overridable operational settings (registry-driven from the
 // backend — adding a key there makes it appear here automatically). Edits are drafted and
@@ -125,7 +126,7 @@ export default function ConfigPanel() {
   const testEmail = useMutation({
     mutationFn: () => api.testEmail(),
     onSuccess: (r) => notify({ level: "success", message: t("config.testSent", { to: r.to }) }),
-    onError: () => notify({ level: "error", message: t("config.testFailed") }),
+    onError: (e) => notifyActionError(e, t("config.testFailed")),
   });
 
   // Plex "Test connection": verifies the server URL + token and returns the library sections,
@@ -138,9 +139,9 @@ export default function ConfigPanel() {
       setPlexResult(r);
       notify({ level: "success", message: t("config.plexTestOk", { name: r.server_name }) });
     },
-    onError: () => {
+    onError: (e) => {
       setPlexResult(null);
-      notify({ level: "error", message: t("config.plexTestFailed") });
+      notifyActionError(e, t("config.plexTestFailed"));
     },
   });
   const plexLibs = (draft["plex_libraries"] ?? "")
diff --git a/frontend/src/components/PlexCollectionEditor.tsx b/frontend/src/components/PlexCollectionEditor.tsx
index 6182d8b5..ab5dac28 100644
--- a/frontend/src/components/PlexCollectionEditor.tsx
+++ b/frontend/src/components/PlexCollectionEditor.tsx
@@ -4,7 +4,7 @@ import { useTranslation } from "react-i18next";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { Check, Plus } from "lucide-react";
 import { api } from "../lib/api";
-import { notifyCollectionEditError } from "../lib/actionErrors";
+import { notifyActionError } from "../lib/actionErrors";
 import { useScrollFade } from "../lib/useScrollFade";
 import { Button } from "./ui/Button";
 import Modal from "./ui/Modal";
@@ -103,9 +103,9 @@ export default function PlexCollectionEditor({
       setMembers((prev) => new Set(prev).add(col.id));
       refresh();
     } catch (e) {
-      // The backend rejects a duplicate name with 409 (Plex conflates same names) — localize it to
-      // nameTaken rather than surfacing the server's raw English detail.
-      notifyCollectionEditError(e, t("plex.collection.editFailed"), t("plex.collection.nameTaken"));
+      // The backend rejects a duplicate name with 409 (Plex conflates same names), structured — so
+      // it reads in the reader's language (see localizeDetail).
+      notifyActionError(e, t("plex.collection.editFailed"));
     } finally {
       setBusy(null);
     }
diff --git a/frontend/src/components/PlexCollectionView.tsx b/frontend/src/components/PlexCollectionView.tsx
index 02743cdc..8b9d88d4 100644
--- a/frontend/src/components/PlexCollectionView.tsx
+++ b/frontend/src/components/PlexCollectionView.tsx
@@ -5,7 +5,7 @@ import { Play, Shuffle, Pencil, Trash2, Plus, X, Lock, Check, Search } from "luc
 import { qk } from "../lib/queryKeys";
 import { api, isIntrinsicReadOnly, type PlexCard, type PlexCollectionDetail } from "../lib/api";
 import { formatRuntime } from "../lib/format";
-import { notifyActionError, notifyCollectionEditError } from "../lib/actionErrors";
+import { notifyActionError } from "../lib/actionErrors";
 import { notify } from "../lib/notifications";
 import { showEpisodeKeys } from "../lib/plexQueue";
 import { healPlexSort, plexSortOptions } from "../lib/plexSort";
@@ -187,8 +187,8 @@ export default function PlexCollectionView({
       invalidate();
       setRenaming(false);
     } catch (e) {
-      // The backend enforces per-library name uniqueness — localize its 409 to nameTaken.
-      notifyCollectionEditError(e, t("plex.collection.editFailed"), t("plex.collection.nameTaken"));
+      // The backend enforces per-library name uniqueness — a taken name comes back localized.
+      notifyActionError(e, t("plex.collection.editFailed"));
     } finally {
       setBusy(false);
     }
diff --git a/frontend/src/components/Scheduler.tsx b/frontend/src/components/Scheduler.tsx
index eb5cdd5b..b1d779c0 100644
--- a/frontend/src/components/Scheduler.tsx
+++ b/frontend/src/components/Scheduler.tsx
@@ -25,6 +25,7 @@ import { useConfirm } from "./ConfirmProvider";
 import { relativeTime } from "../lib/format";
 import { notify } from "../lib/notifications";
 import Tooltip from "./ui/Tooltip";
+import { notifyActionError } from "../lib/actionErrors";
 
 const POLL_MS = 4000;
 // While any job is running, poll faster so short scheduled runs aren't missed between ticks.
@@ -375,14 +376,14 @@ export default function Scheduler() {
   const pauseResume = useMutation({
     mutationFn: (paused: boolean) => (paused ? api.resumeSync() : api.pauseSync()),
     onSuccess: () => qc.invalidateQueries({ queryKey: qk.scheduler() }),
-    onError: () => notify({ level: "error", message: t("scheduler.toggleFailed") }),
+    onError: (e) => notifyActionError(e, t("scheduler.toggleFailed")),
   });
 
   const intervalMut = useMutation({
     mutationFn: (v: { jobId: string; minutes: number }) =>
       api.updateSchedulerJob(v.jobId, v.minutes),
     onSuccess: () => qc.invalidateQueries({ queryKey: qk.scheduler() }),
-    onError: () => notify({ level: "error", message: t("scheduler.intervalFailed") }),
+    onError: (e) => notifyActionError(e, t("scheduler.intervalFailed")),
   });
 
   // Manual "run now" triggers. The wrapper runs in a background thread server-side; the
diff --git a/frontend/src/components/ShareDialog.tsx b/frontend/src/components/ShareDialog.tsx
index 66b8a85f..67ec04b5 100644
--- a/frontend/src/components/ShareDialog.tsx
+++ b/frontend/src/components/ShareDialog.tsx
@@ -7,6 +7,7 @@ import clsx from "clsx";
 import Modal from "./ui/Modal";
 import { useConfirm } from "./ConfirmProvider";
 import { notify } from "../lib/notifications";
+import { notifyActionError } from "../lib/actionErrors";
 import { copyText } from "../lib/clipboard";
 import { api, type DownloadJob, type ShareLink } from "../lib/api";
 import { inputCls } from "./ui/form";
@@ -39,7 +40,7 @@ function UserShare({ job }: { job: DownloadJob }) {
       setQ("");
       setOpen(false);
     },
-    onError: () => notify({ level: "error", message: t("downloads.share.failed") }),
+    onError: (e) => notifyActionError(e, t("downloads.share.failed")),
   });
 
   return (
diff --git a/frontend/src/components/Stats.tsx b/frontend/src/components/Stats.tsx
index 7efc4342..d07d62c4 100644
--- a/frontend/src/components/Stats.tsx
+++ b/frontend/src/components/Stats.tsx
@@ -15,6 +15,7 @@ import FilterChipGroup from "./ui/FilterChipGroup";
 import Tabs from "./ui/Tabs";
 import { Section, SettingRow } from "./ui/form";
 import { useMe } from "../lib/useMe";
+import { notifyActionError } from "../lib/actionErrors";
 
 const RANGES = [7, 30, 90] as const;
 type StatsTab = "overview" | "system";
@@ -85,7 +86,7 @@ function Overview({ me }: { me: Me }) {
         message: t("stats.sync.fullHistoryRequested", { count: r.updated ?? 0 }),
       });
     },
-    onError: () => notify({ level: "error", message: t("stats.sync.fullHistoryFailed") }),
+    onError: (e) => notifyActionError(e, t("stats.sync.fullHistoryFailed")),
   });
 
   return (
diff --git a/frontend/src/components/VideoEditor.tsx b/frontend/src/components/VideoEditor.tsx
index 8b5f563e..ec5c33a3 100644
--- a/frontend/src/components/VideoEditor.tsx
+++ b/frontend/src/components/VideoEditor.tsx
@@ -10,6 +10,7 @@ import { api, type DownloadJob, type EditSpec } from "../lib/api";
 import { contentRect, cropToSourcePx, type Frac } from "../lib/cropGeometry";
 import { inputCls, btnCls } from "./ui/form";
 import { Button } from "./ui/Button";
+import { notifyActionError } from "../lib/actionErrors";
 
 // mm:ss.d timecode <-> seconds.
 function tc(s: number): string {
@@ -322,7 +323,7 @@ export default function VideoEditor({ job, onClose }: { job: DownloadJob; onClos
       notify({ level: "success", message: t("editor.created", { count: files }) });
       onClose();
     },
-    onError: () => notify({ level: "error", message: t("editor.failed") }),
+    onError: (e) => notifyActionError(e, t("editor.failed")),
   });
 
   const sel = segments.find((s) => s.id === selId) ?? segments[0];
diff --git a/frontend/src/components/plexBrowseLists.tsx b/frontend/src/components/plexBrowseLists.tsx
index 07187a74..036d78c8 100644
--- a/frontend/src/components/plexBrowseLists.tsx
+++ b/frontend/src/components/plexBrowseLists.tsx
@@ -6,7 +6,7 @@ import { Check, ListMusic, Lock, Plus, Search, X } from "lucide-react";
 import { qk } from "../lib/queryKeys";
 import { api, isIntrinsicReadOnly, type PlexCard, type PlexCollection } from "../lib/api";
 import { formatRuntime } from "../lib/format";
-import { notifyCollectionEditError } from "../lib/actionErrors";
+import { notifyActionError } from "../lib/actionErrors";
 import { useDebounced } from "../lib/useDebounced";
 import { LoadingState, StateMessage } from "./ui/QueryState";
 import PosterTile from "./PosterTile";
@@ -95,8 +95,9 @@ function NewCollectionPanel({
       const col = await api.plexCreateCollection("", trimmed, card.id); // backend derives the library
       onCreated(col.id);
     } catch (e) {
-      // The backend is authoritative on per-library name uniqueness — its 409 is localized to nameTaken.
-      notifyCollectionEditError(e, t("plex.collection.editFailed"), t("plex.collection.nameTaken"));
+      // The backend is authoritative on per-library name uniqueness — a taken name comes back
+      // structured, and so localized (see localizeDetail).
+      notifyActionError(e, t("plex.collection.editFailed"));
       setBusy(false);
     }
   }
diff --git a/frontend/src/components/usePlaylistActions.ts b/frontend/src/components/usePlaylistActions.ts
index 541f376e..731a7589 100644
--- a/frontend/src/components/usePlaylistActions.ts
+++ b/frontend/src/components/usePlaylistActions.ts
@@ -1,8 +1,8 @@
 import { useQueryClient } from "@tanstack/react-query";
 import { useTranslation } from "react-i18next";
 import { qk } from "../lib/queryKeys";
-import { alreadyReported, api, HttpError, type Playlist } from "../lib/api";
-import { notify } from "../lib/notifications";
+import { api, type Playlist } from "../lib/api";
+import { notifyActionError } from "../lib/actionErrors";
 import { notifyYouTubeActionError } from "../lib/youtubeErrors";
 import { playlistName } from "../lib/playlistName";
 import { useChoice } from "./ConfirmProvider";
@@ -71,14 +71,12 @@ export function usePlaylistActions() {
     } catch (err) {
       // Prefer the server's specific reason (e.g. a local vs YouTube-side failure) over a blanket
       // "couldn't delete on YouTube" that misleads when the failure wasn't the YouTube side — unless
-      // `req` already put it on screen (the error dialog, the connection notice): not twice.
-      if (!alreadyReported(err))
-        notify({
-          level: "warning",
-          message:
-            (err instanceof HttpError && err.detail) ||
-            (onYoutube ? t("playlists.deleteYtFailed") : t("playlists.deleteFailed")),
-        });
+      // `req` already put it in its error dialog: not twice (notifyActionError checks).
+      notifyActionError(
+        err,
+        onYoutube ? t("playlists.deleteYtFailed") : t("playlists.deleteFailed"),
+        "warning",
+      );
     }
     qc.removeQueries({ queryKey: qk.playlist(pl.id) });
     qc.invalidateQueries({ queryKey: qk.playlists() });
diff --git a/frontend/src/i18n/locales/en/users.json b/frontend/src/i18n/locales/en/users.json
index 1c2e4ff4..99f0ebec 100644
--- a/frontend/src/i18n/locales/en/users.json
+++ b/frontend/src/i18n/locales/en/users.json
@@ -39,7 +39,8 @@
     "promoteTitle": "Make admin?",
     "demoteTitle": "Remove admin?",
     "promoteConfirm": "Give {{email}} full admin access (settings, scheduler, user management)?",
-    "demoteConfirm": "Remove admin access from {{email}}? They'll become a regular user."
+    "demoteConfirm": "Remove admin access from {{email}}? They'll become a regular user.",
+    "failed": "Couldn't change the role."
   },
   "suspend": {
     "action": "Suspend",
@@ -51,14 +52,16 @@
     "done": "{{email}} suspended",
     "undone": "{{email}} unsuspended",
     "demoLocked": "The demo account can't be suspended.",
-    "selfLocked": "You can't suspend your own account."
+    "selfLocked": "You can't suspend your own account.",
+    "failed": "Couldn't change the suspension."
   },
   "delete": {
     "action": "Delete",
     "locked": "This account can't be deleted here.",
     "title": "Delete account?",
     "confirm": "Permanently delete {{email}} and all their data — subscriptions, tags, watch history, playlists and settings? This can't be undone.",
-    "done": "{{email}} deleted"
+    "done": "{{email}} deleted",
+    "failed": "Couldn't delete the account."
   },
   "account": {
     "access": "Access",
diff --git a/frontend/src/i18n/locales/hu/users.json b/frontend/src/i18n/locales/hu/users.json
index 80a6df7e..95e2591c 100644
--- a/frontend/src/i18n/locales/hu/users.json
+++ b/frontend/src/i18n/locales/hu/users.json
@@ -39,7 +39,8 @@
     "promoteTitle": "Adminná teszed?",
     "demoteTitle": "Elveszed az admin jogot?",
     "promoteConfirm": "Teljes admin hozzáférést adsz neki: {{email}} (beállítások, ütemező, felhasználókezelés)?",
-    "demoteConfirm": "Elveszed az admin jogot tőle: {{email}}? Sima felhasználó lesz."
+    "demoteConfirm": "Elveszed az admin jogot tőle: {{email}}? Sima felhasználó lesz.",
+    "failed": "Nem sikerült módosítani a szerepkört."
   },
   "suspend": {
     "action": "Felfüggeszt",
@@ -51,14 +52,16 @@
     "done": "{{email}} felfüggesztve",
     "undone": "{{email}} felfüggesztése feloldva",
     "demoLocked": "A demo fiók nem függeszthető fel.",
-    "selfLocked": "A saját fiókodat nem függesztheted fel."
+    "selfLocked": "A saját fiókodat nem függesztheted fel.",
+    "failed": "Nem sikerült módosítani a felfüggesztést."
   },
   "delete": {
     "action": "Törlés",
     "locked": "Ez a fiók itt nem törölhető.",
     "title": "Törlöd a fiókot?",
     "confirm": "Véglegesen törlöd: {{email}} és minden adatát — feliratkozások, címkék, megtekintési előzmény, lejátszási listák és beállítások? Ez nem visszavonható.",
-    "done": "{{email}} törölve"
+    "done": "{{email}} törölve",
+    "failed": "Nem sikerült törölni a fiókot."
   },
   "account": {
     "access": "Hozzáférés",
diff --git a/frontend/src/lib/actionErrors.test.ts b/frontend/src/lib/actionErrors.test.ts
index 721f9ab6..1f64c5b7 100644
--- a/frontend/src/lib/actionErrors.test.ts
+++ b/frontend/src/lib/actionErrors.test.ts
@@ -5,28 +5,37 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 
 // Spy on the toast sink so we can assert exactly what each error maps to.
 vi.mock("./notifications", () => ({ notify: vi.fn(() => 0) }));
+vi.mock("./errorDialog", () => ({ reportError: vi.fn() }));
 
 import { HttpError, api } from "./api";
 import { notify } from "./notifications";
-import { notifyActionError, notifyCollectionEditError } from "./actionErrors";
+import { reportError } from "./errorDialog";
+import { notifyActionError } from "./actionErrors";
+import i18n from "../i18n";
 
 const notifyMock = vi.mocked(notify);
-beforeEach(() => notifyMock.mockClear());
+beforeEach(() => {
+  notifyMock.mockClear();
+  vi.mocked(reportError).mockClear();
+});
 
-describe("notifyCollectionEditError", () => {
-  it("maps a backend 409 to the friendly nameTaken message (not the raw server detail)", () => {
-    notifyCollectionEditError(new HttpError(409, "already exists"), "EDIT_FAILED", "NAME_TAKEN");
-    expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "NAME_TAKEN" });
-  });
-
-  it("falls back to the server detail for a non-409 HttpError", () => {
-    notifyCollectionEditError(new HttpError(500, "server boom"), "EDIT_FAILED", "NAME_TAKEN");
-    expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "server boom" });
-  });
-
-  it("falls back to the generic edit-failed message for a non-HttpError", () => {
-    notifyCollectionEditError(new Error("network"), "EDIT_FAILED", "NAME_TAKEN");
-    expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "EDIT_FAILED" });
+describe("a Plex collection name that is already taken", () => {
+  it("is reported once, in the reader's language", async () => {
+    // The 409 was a bare English string: the global error dialog showed it in English, and the
+    // editor's own toast said the same thing again, translated (deep-review round 4).
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: { code: "collection", reason: "name_taken" } }), {
+        status: 409,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    const err = await api.plexCreateCollection("1", "Marvel", "m1").catch((e: unknown) => e);
+    notifyMock.mockClear();
+    notifyActionError(err, "EDIT_FAILED");
+    expect(notifyMock.mock.calls).toEqual([
+      [{ level: "error", message: i18n.t("plex.collection.nameTaken") }],
+    ]);
+    expect(reportError).not.toHaveBeenCalled();
   });
 });
 
diff --git a/frontend/src/lib/actionErrors.ts b/frontend/src/lib/actionErrors.ts
index 93fd8a6b..e2ad1d26 100644
--- a/frontend/src/lib/actionErrors.ts
+++ b/frontend/src/lib/actionErrors.ts
@@ -10,30 +10,15 @@ import { notify } from "./notifications";
  * the Plex watched-toggles and the saved-view ops, and delegated to by `notifyYouTubeActionError`
  * for its non-403 case.
  */
-export function notifyActionError(err: unknown, fallbackMessage: string): void {
-  // Already on screen (`req` opened the error dialog, or raised the connection notice): a toast on
+export function notifyActionError(
+  err: unknown,
+  fallbackMessage: string,
+  level: "error" | "warning" = "error",
+): void {
+  // Already on screen (`req` opened the error dialog, or the tab is being signed out): a toast on
   // top reported one fault twice. Playlists filtered this by status by hand; the watched toggles,
   // the saved views and a playlist delete did not.
   if (alreadyReported(err)) return;
   const detail = err instanceof HttpError ? err.detail : null;
-  notify({ level: "error", message: detail || fallbackMessage });
-}
-
-/**
- * Collection write errors. The backend enforces per-library name uniqueness and returns 409 on a
- * duplicate; localize that specific case to the friendly `nameTaken` copy (notifyActionError would
- * otherwise surface the server's raw English detail). Everything else falls back to the generic
- * edit-failed handling (which still prefers the server's reason when present). Both args are already
- * translated so this stays i18n-agnostic and unit-testable.
- */
-export function notifyCollectionEditError(
-  err: unknown,
-  editFailedMessage: string,
-  nameTakenMessage: string,
-): void {
-  if (err instanceof HttpError && err.status === 409) {
-    notify({ level: "error", message: nameTakenMessage });
-    return;
-  }
-  notifyActionError(err, editFailedMessage);
+  notify({ level, message: detail || fallbackMessage });
 }
diff --git a/frontend/src/lib/api/core.test.ts b/frontend/src/lib/api/core.test.ts
index ca5c2b79..dc614ed8 100644
--- a/frontend/src/lib/api/core.test.ts
+++ b/frontend/src/lib/api/core.test.ts
@@ -6,14 +6,15 @@
 // each lifecycle branch.
 import { describe, it, expect, beforeEach, vi } from "vitest";
 
-const { reportError, notify, remove } = vi.hoisted(() => ({
+const { reportError, notify, remove, getActiveToasts } = vi.hoisted(() => ({
   reportError: vi.fn(),
   notify: vi.fn(() => 1),
   remove: vi.fn(),
+  getActiveToasts: vi.fn((): { id: number }[] => []),
 }));
 
 vi.mock("../errorDialog", () => ({ reportError }));
-vi.mock("../notifications", () => ({ notify, remove }));
+vi.mock("../notifications", () => ({ notify, remove, getActiveToasts }));
 vi.mock("../../i18n", () => ({ default: { t: (k: string) => k, language: "en" } }));
 vi.mock("../activeAccount", () => ({
   activeAccountId: () => null,
@@ -54,6 +55,9 @@ class FakeXHR {
 beforeEach(() => {
   reportError.mockReset();
   notify.mockReset();
+  remove.mockReset();
+  getActiveToasts.mockReset();
+  getActiveToasts.mockReturnValue([]);
   setUnauthorizedHandler(null);
   vi.stubGlobal("XMLHttpRequest", FakeXHR as unknown as typeof XMLHttpRequest);
 });
@@ -167,17 +171,45 @@ describe("req — what it has already put in front of the user", () => {
     expect(alreadyReported(err)).toBe(true);
   });
 
-  it("marks a request that never reached the server (the connection notice says it)", async () => {
+  // The connection notice says the server is unreachable — not that THIS action failed — and it
+  // removes itself on the very next answer (the caller's own resync refetch). Marked as reported, a
+  // delete that hit a keepalive reset flashed the notice and was then reported nowhere at all.
+  it("raises the connection notice for a request that never reached the server, and leaves the failed action to the caller", async () => {
     vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("Failed to fetch"));
     const err = await req("/api/x", { method: "POST" }).catch((e: unknown) => e);
     expect(notify).toHaveBeenCalled();
-    expect(alreadyReported(err)).toBe(true);
+    expect(alreadyReported(err)).toBe(false);
+  });
+
+  it.each([502, 503, 504])(
+    "raises the connection notice for a %s, and leaves the failed action to the caller",
+    async (status) => {
+      answer(status);
+      const err = await req("/api/x", { method: "POST" }).catch((e: unknown) => e);
+      expect(notify).toHaveBeenCalled();
+      expect(reportError).not.toHaveBeenCalled();
+      expect(err).toMatchObject({ status });
+      expect(alreadyReported(err)).toBe(false);
+    },
+  );
+
+  it("raises the connection notice again after the user closed it", async () => {
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("Failed to fetch"));
+    notify.mockReturnValue(7);
+    await req("/api/x", { method: "POST" }).catch(() => {});
+    getActiveToasts.mockReturnValue([{ id: 7 }]); // still on screen: one notice, not a stack
+    notify.mockClear();
+    await req("/api/x", { method: "POST" }).catch(() => {});
+    expect(notify).not.toHaveBeenCalled();
+    getActiveToasts.mockReturnValue([]); // closed with its ✕
+    await req("/api/x", { method: "POST" }).catch(() => {});
+    expect(notify).toHaveBeenCalledOnce();
   });
 
   it("marks what the upload path reported the same way", async () => {
     const dead = uploadReq("/u", form());
     FakeXHR.last.onerror!();
-    expect(alreadyReported(await dead.catch((e: unknown) => e))).toBe(true);
+    expect(alreadyReported(await dead.catch((e: unknown) => e))).toBe(false);
     const refused = uploadReq("/u", form());
     FakeXHR.last.status = 500;
     FakeXHR.last.onload!();
@@ -187,4 +219,20 @@ describe("req — what it has already put in front of the user", () => {
     FakeXHR.last.onload!();
     expect(alreadyReported(await gone.catch((e: unknown) => e))).toBe(false);
   });
+
+  it("treats a gateway error on the upload path as the connection notice, not a blocking dialog", async () => {
+    // The upload path kept its own copy of this policy, and it had drifted: a 502 opened the
+    // blocking "Server error (502)" dialog and cleared a connection notice that was still true.
+    notify.mockReturnValue(9);
+    vi.spyOn(globalThis, "fetch").mockRejectedValue(new TypeError("Failed to fetch"));
+    await req("/api/x", { method: "POST" }).catch(() => {}); // a notice is up
+    getActiveToasts.mockReturnValue([{ id: 9 }]);
+    remove.mockClear();
+    const p = uploadReq("/u", form());
+    FakeXHR.last.status = 502;
+    FakeXHR.last.onload!();
+    await expect(p).rejects.toMatchObject({ status: 502 });
+    expect(reportError).not.toHaveBeenCalled();
+    expect(remove).not.toHaveBeenCalled();
+  });
 });
diff --git a/frontend/src/lib/api/core.ts b/frontend/src/lib/api/core.ts
index 7d598e92..2afc3e66 100644
--- a/frontend/src/lib/api/core.ts
+++ b/frontend/src/lib/api/core.ts
@@ -2,7 +2,7 @@
 // error, structured-error localization, the connectivity toast, the per-tab active-account plumbing,
 // and the keepalive beacon. Domain modules import from here; nothing here imports a domain module,
 // so the runtime graph is a clean barrel → domain → core with no cycles.
-import { notify, remove } from "../notifications";
+import { getActiveToasts, notify, remove } from "../notifications";
 import i18n from "../../i18n";
 import { formatBytes } from "../format";
 import { reportError } from "../errorDialog";
@@ -14,9 +14,15 @@ import { activeAccountId, ACTIVE_ACCOUNT_KEY, notifyActiveAccountChange } from "
  *  field nobody ever filled (E9.5 S6 → S7). */
 export const uiLang = (): string => i18n.language.split("-")[0] || "en";
 
-// Errors `req` has already put in front of the user — the blocking error dialog, or the connection
-// notice. A caller that toasts a failed action as well reported the same fault twice (a modal AND a
-// toast); `notifyActionError` asks this instead of each caller filtering statuses by hand.
+// Errors `req` has already put in front of the user for good — the blocking error dialog, or the
+// sign-out a 401 triggers. A caller that toasts a failed action as well reported the same fault twice
+// (a modal AND a toast); `notifyActionError` asks this instead of each caller filtering statuses by
+// hand.
+//
+// NOT the connection notice. It says the server is unreachable, not that this action failed, and it
+// removes itself on the next answer — which every caller's own resync refetch fetches at once. Marked
+// as reported, a delete that hit a keepalive reset (a 502) flashed the notice for a moment and was
+// then reported nowhere at all, the list still there (deep-review round 4).
 const reported = new WeakSet<object>();
 export function alreadyReported(err: unknown): boolean {
   return typeof err === "object" && err !== null && reported.has(err);
@@ -90,6 +96,11 @@ function localizeDetail(d: unknown): string {
   // unknown reason falls back to the plain failure rather than printing a key.
   if (o?.code === "playlist_move")
     return t(`playlists.moveErrors.${o.reason}`, t("playlists.moveFailed"));
+  // A Plex collection name already taken in that library (the one collection-edit refusal).
+  if (o?.code === "collection")
+    return o.reason === "name_taken"
+      ? t("plex.collection.nameTaken")
+      : t("plex.collection.editFailed");
   // A playlist action the server refused (Watch later can't be deleted, YouTube said no, …).
   if (o?.code === "playlist") return t(`playlists.errors.${o.reason}`, t("errors.generic"));
   // Any row that is gone — deleted in another tab or device, or never the caller's (a stranger's
@@ -109,7 +120,11 @@ function localizeDetail(d: unknown): string {
 // bursts of concurrent failures from stacking up — there's only ever one live handle.
 let connectivityNotifId: number | null = null;
 function markConnectivityLost(): void {
-  if (connectivityNotifId !== null) return;
+  // One live notice — but a notice the user closed is not live: it used to swallow every later
+  // "connection lost" for the rest of the visit.
+  const id = connectivityNotifId;
+  if (id !== null && getActiveToasts().some((n) => n.id === id)) return;
+  if (id !== null) remove(id);
   connectivityNotifId = notify({
     level: "error",
     title: i18n.t("errors.offline.title"),
@@ -129,6 +144,35 @@ function markConnectivityRestored(): void {
 const RETRIABLE_GATEWAY = new Set([502, 503, 504]);
 const delay = (ms: number) => new Promise((res) => window.setTimeout(res, ms));
 
+// What a failed answer puts on screen — ONE policy for `req` and `uploadReq` (the upload path kept
+// its own copy, and it had drifted: a 502 there opened the blocking "Server error" dialog and
+// cleared a connection notice that was still true).
+//
+// 502/503/504 mean the gateway couldn't reach the app (restarting / connection reset), not a
+// request the app refused — the soft, self-clearing connection notice rather than a blocking modal,
+// and still the caller's to report as a failed action (see `reported`). A genuine 500 (real fault,
+// carries a JSON detail) gets the modal, as do 400/409/422 (validation/conflict). 401 is the app
+// shell's; 403/404/429 are caller-handled control flow.
+function reportFailure(err: HttpError, quiet: boolean): void {
+  if (RETRIABLE_GATEWAY.has(err.status)) {
+    markConnectivityLost();
+  } else if (err.status === 401) {
+    // Session ended server-side (e.g. the account was suspended or deleted mid-visit). Let the app
+    // shell decide what to do (drop to the login page if we were signed in). Not a modal — but
+    // handled all the same, so not the caller's to toast either.
+    onUnauthorized?.();
+    reported.add(err);
+  } else if (quiet) {
+    /* caller handles the error inline — no global modal */
+  } else if (err.status >= 500) {
+    reportError(err.detail || `${i18n.t("errors.server")} (${err.status})`);
+    reported.add(err);
+  } else if (err.status === 400 || err.status === 409 || err.status === 422) {
+    reportError(err.detail);
+    reported.add(err);
+  }
+}
+
 // `idempotent`: may this request be replayed after a transient gateway/network failure?
 // GETs always can; non-GET callers opt in (e.g. the player's progress/state writes, which
 // are safe to repeat). Used to recover from the keepalive race without surfacing a 502.
@@ -235,8 +279,7 @@ export async function req<T = unknown>(
         await delay(250);
         continue;
       }
-      markConnectivityLost();
-      if (typeof e === "object" && e !== null) reported.add(e);
+      markConnectivityLost(); // the connection notice; the failed action is still the caller's
       throw e;
     }
 
@@ -266,30 +309,8 @@ export async function req<T = unknown>(
       } catch {
         /* no JSON body */
       }
-      // 502/503/504 mean the gateway couldn't reach the app (restarting / connection reset),
-      // not a request the app refused — treat them like a network blip with the soft,
-      // self-clearing toast rather than a blocking modal the user must acknowledge.
-      // A genuine 500 (real fault, carries a JSON detail) still gets the modal, as do
-      // 400/409/422 (validation/conflict). 401/403/404 are caller-handled control flow.
       const err = new HttpError(r.status, detail, detailData);
-      if (RETRIABLE_GATEWAY.has(r.status)) {
-        markConnectivityLost();
-        reported.add(err);
-      } else if (r.status === 401) {
-        // Session ended server-side (e.g. the account was suspended or deleted mid-visit). Let the
-        // app shell decide what to do (drop to the login page if we were signed in). Not a modal —
-        // but handled all the same, so not the caller's to toast either.
-        onUnauthorized?.();
-        reported.add(err);
-      } else if (cfg.quiet) {
-        /* caller handles the error inline — no global modal */
-      } else if (r.status >= 500) {
-        reportError(detail || `${i18n.t("errors.server")} (${r.status})`);
-        reported.add(err);
-      } else if (r.status === 400 || r.status === 409 || r.status === 422) {
-        reportError(detail);
-        reported.add(err);
-      }
+      reportFailure(err, !!cfg.quiet);
       throw err;
     }
     // The single audited cast in this layer: the server contract is asserted here, once, so
@@ -325,7 +346,7 @@ export function uploadReq<T = unknown>(
       cfg.signal.addEventListener("abort", () => xhr.abort());
     }
     xhr.onload = () => {
-      markConnectivityRestored();
+      if (!RETRIABLE_GATEWAY.has(xhr.status)) markConnectivityRestored(); // as in `req`
       if (xhr.status >= 200 && xhr.status < 300) {
         try {
           resolve((xhr.responseText ? JSON.parse(xhr.responseText) : null) as T);
@@ -347,20 +368,13 @@ export function uploadReq<T = unknown>(
         /* no JSON body */
       }
       const err = new HttpError(xhr.status, detail, detailData);
-      if (xhr.status === 401) onUnauthorized?.();
-      else if (xhr.status >= 500)
-        reportError(detail || `${i18n.t("errors.server")} (${xhr.status})`);
-      else if (xhr.status === 400 || xhr.status === 409 || xhr.status === 422) reportError(detail);
-      if (xhr.status === 401 || xhr.status >= 500 || [400, 409, 422].includes(xhr.status))
-        reported.add(err); // as in `req`: already on screen, not the caller's to toast again
+      reportFailure(err, false);
       reject(err);
     };
     // A network-level failure (server unreachable) — same soft "connection lost" status as `req`.
     xhr.onerror = () => {
       markConnectivityLost();
-      const err = new HttpError(0, i18n.t("errors.offline.body"));
-      reported.add(err);
-      reject(err);
+      reject(new HttpError(0, i18n.t("errors.offline.body")));
     };
     xhr.onabort = () => reject(new HttpError(0, "aborted"));
     xhr.send(form);
diff --git a/frontend/src/lib/api/plex.ts b/frontend/src/lib/api/plex.ts
index 9be6b783..5042a861 100644
--- a/frontend/src/lib/api/plex.ts
+++ b/frontend/src/lib/api/plex.ts
@@ -505,15 +505,19 @@ export const plexApi = {
     return req(`/api/plex/collections/${encodeURIComponent(rk)}${qs ? `?${qs}` : ""}`);
   },
   // --- Collection editing (admin only; writes back to Plex) ---
+  // `quiet`: the editor reports a failure itself, as a toast beside the name being typed (a taken
+  // name comes back structured and localized — see localizeDetail). Not quiet, it was reported twice:
+  // the global error dialog in English AND the editor's toast.
   plexCreateCollection: (
     library: string,
     title: string,
     item_rating_key: string,
   ): Promise<PlexCollection> =>
-    req(`/api/plex/collections`, {
-      method: "POST",
-      body: JSON.stringify({ library, title, item_rating_key }),
-    }),
+    req(
+      `/api/plex/collections`,
+      { method: "POST", body: JSON.stringify({ library, title, item_rating_key }) },
+      { quiet: true },
+    ),
   plexCollectionAddItem: (rk: string, itemRk: string): Promise<PlexCollection> =>
     req(`/api/plex/collections/${encodeURIComponent(rk)}/items/${encodeURIComponent(itemRk)}`, {
       method: "POST",
@@ -523,10 +527,11 @@ export const plexApi = {
       method: "DELETE",
     }),
   plexRenameCollection: (rk: string, title: string): Promise<PlexCollection> =>
-    req(`/api/plex/collections/${encodeURIComponent(rk)}`, {
-      method: "PATCH",
-      body: JSON.stringify({ title }),
-    }),
+    req(
+      `/api/plex/collections/${encodeURIComponent(rk)}`,
+      { method: "PATCH", body: JSON.stringify({ title }) },
+      { quiet: true }, // as plexCreateCollection
+    ),
   plexDeleteCollection: (rk: string): Promise<{ deleted: string }> =>
     req(`/api/plex/collections/${encodeURIComponent(rk)}`, { method: "DELETE" }),
   plexSetCollectionEditable: (rk: string, editable: boolean): Promise<PlexCollection> =>

From 267fd7f70f169644fa1368690bd139ae5db41ff6 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 23:34:33 +0200
Subject: [PATCH 33/52] fix(playlists): a refused edit is taken back on screen,
 and a gone list or tag is said, not swallowed
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 4, the playlist surfaces.

- A failed move or reorder relied on the resync to put the rows back — but the server's list is
  unchanged, so the refetch comes back deep-equal, react-query keeps the same `data` object, and the
  re-seed effect keyed on it never ran: the moved row stayed gone, the rejected order stayed on
  screen. Both restore from the cached detail now.
- A failed removal puts its row back itself: when the server is unreachable the resync fails too,
  and round 3's "keep the list on a failed refetch" guard then kept showing it as removed.
- The Plex playlist page (remove / rename / delete / reorder), the add-to-playlist popover and the
  tag manager had no failure handling at all: a list or tag deleted elsewhere (a 404, now a
  structured `not_found` the request layer leaves to the caller) failed in silence and an
  optimistic removal stayed removed. Each says it and resyncs; deleting a Plex playlist that is
  already gone just leaves the page.
- Playlists' own loading/error branches use the shared `LoadingState` / `StateMessage` (the loading
  line had no live region).
- The "player stays mounted" tests count mounts: a remount ended with the same flag as staying up.
---
 frontend/src/components/AddToPlaylist.tsx     |  12 +-
 .../PlaylistEditFailures.dom.test.tsx         | 127 ++++++++++++++++++
 .../src/components/Playlists.dom.test.tsx     |  76 ++++++++++-
 frontend/src/components/Playlists.tsx         |  55 +++++---
 frontend/src/components/PlexPlaylistView.tsx  |  41 +++++-
 frontend/src/components/TagManager.tsx        |   9 ++
 frontend/src/i18n/locales/en/playlists.json   |   3 +-
 frontend/src/i18n/locales/en/plex.json        |   6 +-
 frontend/src/i18n/locales/en/tagManager.json  |   4 +-
 frontend/src/i18n/locales/hu/playlists.json   |   3 +-
 frontend/src/i18n/locales/hu/plex.json        |   6 +-
 frontend/src/i18n/locales/hu/tagManager.json  |   4 +-
 12 files changed, 309 insertions(+), 37 deletions(-)
 create mode 100644 frontend/src/components/PlaylistEditFailures.dom.test.tsx

diff --git a/frontend/src/components/AddToPlaylist.tsx b/frontend/src/components/AddToPlaylist.tsx
index 716279ef..e795b38a 100644
--- a/frontend/src/components/AddToPlaylist.tsx
+++ b/frontend/src/components/AddToPlaylist.tsx
@@ -4,6 +4,7 @@ import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { qk } from "../lib/queryKeys";
 import { Check, ListPlus, Plus, Youtube } from "lucide-react";
 import { api, type Playlist } from "../lib/api";
+import { notifyActionError } from "../lib/actionErrors";
 import { useScrollFade } from "../lib/useScrollFade";
 import { playlistName } from "../lib/playlistName";
 import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./ui/AnchoredPopover";
@@ -49,14 +50,19 @@ export default function AddToPlaylist({
     qc.invalidateQueries({ queryKey: qk.playlist() });
   }
 
+  // A failure is said, and the list refreshed either way. With no catch, a playlist deleted on
+  // another device (a 404 `not_found/playlist` — still offered, from a cache up to 30 s old) was an
+  // unhandled rejection: the tick did not change, nothing was said, the gone row stayed.
   async function toggle(pl: Playlist) {
     if (busy) return;
     setBusy(true);
     try {
       if (pl.has_video) await api.removeFromPlaylist(pl.id, videoId);
       else await api.addToPlaylist(pl.id, videoId);
-      refresh();
+    } catch (e) {
+      notifyActionError(e, t(pl.has_video ? "playlists.removeFailed" : "playlists.addFailed"));
     } finally {
+      refresh();
       setBusy(false);
     }
   }
@@ -69,8 +75,10 @@ export default function AddToPlaylist({
       const pl = await api.createPlaylist(name);
       await api.addToPlaylist(pl.id, videoId);
       setNewName("");
-      refresh();
+    } catch (e) {
+      notifyActionError(e, t("playlists.addFailed"));
     } finally {
+      refresh();
       setBusy(false);
     }
   }
diff --git a/frontend/src/components/PlaylistEditFailures.dom.test.tsx b/frontend/src/components/PlaylistEditFailures.dom.test.tsx
new file mode 100644
index 00000000..dec28ea6
--- /dev/null
+++ b/frontend/src/components/PlaylistEditFailures.dom.test.tsx
@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+//
+// A playlist or tag edit that fails is said, and what the screen shows goes back to what is true
+// (deep-review round 4). The Plex playlist page, the add-to-playlist popover and the tag manager had
+// no failure handling at all: a 404 for a list or tag deleted elsewhere — now a structured
+// `not_found`, which the request layer leaves to the caller — failed in silence, and an optimistic
+// removal stayed removed.
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { render, cleanup, screen, fireEvent, waitFor, act } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
+const { notify } = vi.hoisted(() => ({
+  notify: vi.fn((_n: { level: string; message: string }) => 0),
+}));
+vi.mock("../lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/notifications")>()),
+  notify,
+}));
+
+import PlexPlaylistView from "./PlexPlaylistView";
+import AddToPlaylist from "./AddToPlaylist";
+import TagManager from "./TagManager";
+import { api, HttpError, type PlexCard } from "../lib/api";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+beforeEach(() => notify.mockClear());
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const gone = (what: string) =>
+  new HttpError(404, `gone ${what}`, { code: "not_found", reason: what });
+const errors = () => notify.mock.calls.filter(([n]) => n.level === "error").map(([n]) => n.message);
+const client = () => new QueryClient({ defaultOptions: { queries: { retry: false } } });
+
+const movie = (id: string) =>
+  ({ id, type: "movie", title: `Movie ${id}`, year: 2020, thumb: "" }) as unknown as PlexCard;
+
+describe("the Plex playlist page", () => {
+  it("puts back a row whose removal failed, and says why", async () => {
+    vi.spyOn(api, "plexPlaylist").mockResolvedValue({
+      id: 5,
+      title: "Films",
+      items: [movie("1"), movie("2")],
+    });
+    vi.spyOn(api, "plexPlaylistRemoveItem").mockRejectedValue(gone("playlist"));
+    render(
+      <QueryClientProvider client={client()}>
+        <PlexPlaylistView playlistId={5} onBack={() => {}} onPlay={() => {}} />
+      </QueryClientProvider>,
+    );
+    await screen.findByText("Movie 1");
+    fireEvent.click(screen.getAllByLabelText("remove")[0]!);
+    await waitFor(() => expect(errors()).toEqual(["gone playlist"]));
+    await act(async () => void (await new Promise((r) => setTimeout(r, 20))));
+    expect(screen.getByText("Movie 1")).toBeTruthy();
+  });
+
+  it("leaves a playlist that is already gone when asked to delete it", async () => {
+    vi.spyOn(api, "plexPlaylist").mockResolvedValue({ id: 5, title: "Films", items: [] });
+    vi.spyOn(api, "plexDeletePlaylist").mockRejectedValue(gone("playlist"));
+    const onBack = vi.fn();
+    render(
+      <QueryClientProvider client={client()}>
+        <PlexPlaylistView playlistId={5} onBack={onBack} onPlay={() => {}} />
+      </QueryClientProvider>,
+    );
+    fireEvent.click(await screen.findByTitle("plex.playlist.delete"));
+    await waitFor(() => expect(onBack).toHaveBeenCalled());
+  });
+});
+
+describe("the add-to-playlist popover", () => {
+  it("says so when the playlist ticked is gone, and refreshes the list", async () => {
+    const lists = vi
+      .spyOn(api, "playlists")
+      .mockResolvedValue([{ id: 3, name: "Gone", kind: "user", has_video: false }] as never);
+    vi.spyOn(api, "addToPlaylist").mockRejectedValue(gone("playlist"));
+    render(
+      <QueryClientProvider client={client()}>
+        <AddToPlaylist videoId="v1" />
+      </QueryClientProvider>,
+    );
+    fireEvent.click(screen.getByLabelText("playlists.addToPlaylist"));
+    fireEvent.click(await screen.findByRole("menuitemcheckbox", { hidden: true }));
+    await waitFor(() => expect(errors()).toEqual(["gone playlist"]));
+    await waitFor(() => expect(lists.mock.calls.length).toBeGreaterThan(1));
+  });
+});
+
+describe("the tag manager", () => {
+  it("says so when the tag deleted is gone, and refreshes the list", async () => {
+    const tags = vi
+      .spyOn(api, "tags")
+      .mockResolvedValue([{ id: 4, name: "Gone", system: false, channel_count: 0 }] as never);
+    vi.spyOn(api, "channels").mockResolvedValue([] as never);
+    vi.spyOn(api, "deleteTag").mockRejectedValue(gone("tag"));
+    render(
+      <QueryClientProvider client={client()}>
+        <TagManager onClose={() => {}} onFocusChannel={() => {}} />
+      </QueryClientProvider>,
+    );
+    fireEvent.click(await screen.findByLabelText("tagManager.delete"));
+    await waitFor(() => expect(errors()).toEqual(["gone tag"]));
+    await waitFor(() => expect(tags.mock.calls.length).toBeGreaterThan(1));
+  });
+});
diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
index 28a5860f..c3b7262d 100644
--- a/frontend/src/components/Playlists.dom.test.tsx
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -11,6 +11,7 @@ const h = vi.hoisted(() => ({
   notify: vi.fn(),
   selectedId: 1 as number | null,
   mounted: false,
+  mounts: 0,
   player: null as null | {
     video: { id: string; position_seconds: number };
     onClose: () => void;
@@ -43,6 +44,7 @@ vi.mock("./PlayerModal", async () => {
       h.player = props;
       useEffect(() => {
         h.mounted = true;
+        h.mounts++;
         return () => {
           h.mounted = false;
         };
@@ -95,7 +97,7 @@ const list = (id: number, items: Video[]) => ({
 
 let qc: QueryClient;
 
-function mount(lists: Record<number, Video[]>) {
+function mount(lists: Record<number, Video[]>, prefs: Record<string, unknown> = {}) {
   vi.spyOn(api, "playlists").mockResolvedValue(
     Object.entries(lists).map(([id, items]) => list(Number(id), items)) as never,
   );
@@ -103,7 +105,7 @@ function mount(lists: Record<number, Video[]>) {
     async (id: number) => list(id, lists[id] ?? []) as never,
   );
   qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
-  qc.setQueryData(qk.me(), { id: 1, can_write: true, prefs: {} });
+  qc.setQueryData(qk.me(), { id: 1, can_write: true, prefs: {}, preferences: prefs });
   const tree = () => (
     <QueryClientProvider client={qc}>
       <Playlists />
@@ -120,6 +122,7 @@ beforeEach(() => {
   h.selectedId = 1;
   h.player = null;
   h.mounted = false;
+  h.mounts = 0;
   h.notify.mockClear();
 });
 afterEach(() => {
@@ -248,8 +251,12 @@ describe("Playlists — the player outlives a change of selection", () => {
     vi.mocked(api.playlist).mockReturnValue(new Promise(() => {}));
     h.selectedId = 2;
     rerender();
-    await screen.findByText("playlists.loading");
+    // The shared loading state, which a screen reader hears (the old bare line had no live region).
+    expect(
+      (await screen.findByText("playlists.loading")).closest('[role="status"]'),
+    ).not.toBeNull();
     expect(h.mounted).toBe(true);
+    expect(h.mounts).toBe(1); // never went down — a remount would also end `mounted`
   });
 
   it("stays mounted when the newly selected list fails to load — a list deleted elsewhere", async () => {
@@ -261,6 +268,7 @@ describe("Playlists — the player outlives a change of selection", () => {
     rerender();
     await screen.findByText("playlists.loadFailed");
     expect(h.mounted).toBe(true);
+    expect(h.mounts).toBe(1);
   });
 
   it("stays mounted when nothing is selected any more", async () => {
@@ -271,6 +279,7 @@ describe("Playlists — the player outlives a change of selection", () => {
     rerender();
     await screen.findByText("playlists.pickOne");
     expect(h.mounted).toBe(true);
+    expect(h.mounts).toBe(1);
   });
 
   it("refreshes the list it was launched from when the viewer marks the video in it", async () => {
@@ -289,3 +298,64 @@ describe("Playlists — the player outlives a change of selection", () => {
     expect(qc.getQueryState(qk.playlist(1))?.isInvalidated).toBe(true);
   });
 });
+
+const rowsOnScreen = () =>
+  screen
+    .getAllByRole("button", { name: /^card\.play — / })
+    .map((b) => b.getAttribute("aria-label")?.replace("card.play — ", ""));
+
+async function rowMenu(title: string, item: string) {
+  const row = (await screen.findByRole("button", { name: `card.play — ${title}` })).closest("tr")!;
+  fireEvent.contextMenu(row);
+  await waitFor(() =>
+    expect(
+      screen.getAllByRole("menuitem", { hidden: true }).some((b) => b.textContent === item),
+    ).toBe(true),
+  );
+  fireEvent.click(
+    screen.getAllByRole("menuitem", { hidden: true }).find((b) => b.textContent === item)!,
+  );
+}
+
+describe("Playlists — a change the server refused is taken back on screen", () => {
+  // The resync refetch returns the SAME list the server had, react-query keeps the same `data`
+  // object for a deep-equal answer, and the page's re-seed effect is keyed on that object — so the
+  // optimistic change used to stay on screen for good.
+  it("puts back a row whose move failed", async () => {
+    vi.spyOn(api, "moveToPlaylist").mockRejectedValue(
+      new HttpError(404, "gone", { code: "not_found", reason: "move_target" }),
+    );
+    mount({ 1: [vid("V", 0), vid("W", 0)], 2: [] }, { lastMovePlaylistId: 2 });
+    await rowMenu("Video V", "playlists.moveToRecent");
+    await waitFor(() =>
+      expect(h.notify).toHaveBeenCalledWith(expect.objectContaining({ level: "error" })),
+    );
+    await act(async () => void (await new Promise((r) => setTimeout(r, 20))));
+    expect(rowsOnScreen()).toEqual(["Video V", "Video W"]);
+  });
+
+  it("puts back the order when saving a reorder failed", async () => {
+    vi.spyOn(api, "reorderPlaylist").mockRejectedValue(new HttpError(500, "boom"));
+    mount({ 1: [vid("V", 0), vid("W", 0)] });
+    await rowMenu("Video V", "playlists.orderDown");
+    await waitFor(() => expect(api.reorderPlaylist).toHaveBeenCalled());
+    await act(async () => void (await new Promise((r) => setTimeout(r, 20))));
+    expect(rowsOnScreen()).toEqual(["Video V", "Video W"]);
+  });
+
+  it("puts back a row whose removal failed, even when the resync fails too", async () => {
+    // A removal during an API restart: the DELETE fails, and so does the refetch meant to put the row
+    // back — the list kept showing it as removed while it was still in the playlist.
+    vi.spyOn(api, "removeFromPlaylist").mockRejectedValue(new TypeError("Failed to fetch"));
+    mount({ 1: [vid("V", 0), vid("W", 0)] });
+    await screen.findByRole("button", { name: "card.play — Video V" });
+    vi.mocked(api.playlist).mockRejectedValue(new TypeError("Failed to fetch"));
+    await rowMenu("Video V", "playlists.removeItem");
+    await waitFor(() => expect(api.removeFromPlaylist).toHaveBeenCalled());
+    await act(async () => void (await new Promise((r) => setTimeout(r, 20))));
+    expect(rowsOnScreen()).toEqual(["Video V", "Video W"]);
+    expect(h.notify).toHaveBeenCalledWith(
+      expect.objectContaining({ level: "error", message: "playlists.removeFailed" }),
+    );
+  });
+});
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 9f7439aa..583b3175 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -20,7 +20,6 @@ import {
 } from "@dnd-kit/sortable";
 import { CSS } from "@dnd-kit/utilities";
 import {
-  AlertTriangle,
   ArrowDown,
   ArrowDownToLine,
   ArrowUp,
@@ -51,6 +50,7 @@ import { formatRuntime } from "../lib/format";
 import { applyView, sameOrder } from "../lib/playlistView";
 const PlayerModal = lazy(() => import("./PlayerModal"));
 import { Button } from "./ui/Button";
+import { LoadingState, StateMessage } from "./ui/QueryState";
 import { type ActionMenuItem } from "./ui/ActionMenu";
 import { useComfortPin, pinVideo } from "./comfortPin";
 import { ContextMenu } from "./ui/ContextMenu";
@@ -184,9 +184,10 @@ export default function Playlists() {
   const order = useUndoable<Video[]>([], {
     onApply: (next) => {
       if (selectedId == null) return;
+      const listId = selectedId;
       api
         .reorderPlaylist(
-          selectedId,
+          listId,
           next.map((v) => v.id),
         )
         .then(() => {
@@ -198,13 +199,11 @@ export default function Playlists() {
         })
         .catch((e) => {
           // Was a bare .then(): a failed reorder left the UI showing an order the server had
-          // rejected, and produced an unhandled rejection. Say so and resync from the server.
+          // rejected, and produced an unhandled rejection. Say so, and put back the order the server
+          // still has — or the rejected one becomes the base for the next drag.
           notifyYouTubeActionError(e, t("playlists.reorderFailed"));
-          // Clear the membership guard first: a reorder never changes the id SET, so without this
-          // the arriving detail is judged "same list" and the rejected order stays on screen — and
-          // becomes the base for the next drag.
-          lastSetRef.current = "";
-          qc.invalidateQueries({ queryKey: qk.playlist(selectedId) });
+          restoreFromCache(listId);
+          qc.invalidateQueries({ queryKey: qk.playlist(listId) });
         });
     },
   });
@@ -220,6 +219,18 @@ export default function Playlists() {
   // The selection as of NOW, for code that runs after an await or on behalf of the open player.
   const selectedRef = useRef(selectedId);
   selectedRef.current = selectedId;
+  // Put the rows back to what the CACHED detail says — the server's list as last fetched. A failed
+  // reorder or move must not wait for the resync to do it: the server's list is unchanged, so the
+  // refetch comes back deep-equal, react-query keeps the same `data` object, and the effect below
+  // (keyed on it) never runs. The moved row stayed gone and the rejected order stayed on screen
+  // (deep-review round 4). Only for the list on screen: the selection may have moved meanwhile.
+  function restoreFromCache(listId: number) {
+    if (listId !== selectedRef.current) return;
+    const cur = qc.getQueryData<PlaylistDetail>(qk.playlist(listId));
+    if (!cur) return;
+    lastSetRef.current = `${listId}:${idsKey(cur.items)}`;
+    order.reset(cur.items);
+  }
   // What the player was LAUNCHED with, snapshotted when it opens: the video, the queue and the index
   // inside it. `shown` is derived (sort / filter / view), and the player freezes its queue and owns
   // its own cursor from mount — so deriving the mount from `shown` every render meant anything that
@@ -568,6 +579,7 @@ export default function Playlists() {
     // player's own progress checkpoint does exactly that when a removal steps it to the next item —
     // so the guard reset the order: the removed row came back and the undo history the rebase had
     // kept went with it. (A failure resyncs below, which puts the row back where it belongs.)
+    const before = qc.getQueryData<PlaylistDetail>(qk.playlist(listId));
     qc.setQueryData<PlaylistDetail>(qk.playlist(listId), (old) =>
       old ? { ...old, items: old.items.filter((v) => v.id !== video.id) } : old,
     );
@@ -578,9 +590,13 @@ export default function Playlists() {
     } catch (e) {
       // Said here, as moveItemTo does, or a confirmed removal fails in silence (inside the
       // full-screen player there is not even a row snapping back to show it) — unless `req` already
-      // said it (the error dialog, the connection notice), which `notifyActionError` checks.
+      // put it in its error dialog, which `notifyActionError` checks.
       notifyActionError(e, t("playlists.removeFailed"));
-      refreshAll(listId); // …and resync, which restores any row the optimistic removal took out
+      // …and the row goes back NOW, not when the resync lands: a removal that failed because the
+      // server was unreachable has a resync that fails too, and the list kept showing the row as
+      // removed while it was still in the playlist.
+      if (before) qc.setQueryData(qk.playlist(listId), before);
+      refreshAll(listId);
       return false;
     }
   }
@@ -611,9 +627,10 @@ export default function Playlists() {
       // every move failure a user can actually reach is a 404 (the 400 `same_playlist` case is already
       // impossible — the submenu never offers the current list). So the row used to snap back with no
       // explanation and the shipped moveErrors strings were unreachable (E10 review round 1).
-      // A fault `req` already reported (the error dialog, the connection notice) is not toasted
-      // again — `notifyActionError` checks (E10 review round 2 found it reported twice).
+      // A fault `req` already put in its error dialog is not toasted again — `notifyActionError`
+      // checks (E10 review round 2 found it reported twice).
       notifyActionError(e, t("playlists.moveFailed"));
+      restoreFromCache(selectedId); // the row is still in this list
     }
     // BOTH sides changed, and so did this video's membership. `qk.playlist(selectedId)` is an exact
     // key, so it cannot cover the target — invalidate the whole `["playlist"]` prefix, exactly as
@@ -819,15 +836,9 @@ export default function Playlists() {
   if (detailQuery.isError && !detail) {
     return (
       <>
-        <div role="alert" className="text-sm p-4 flex flex-col items-start gap-3">
-          <span className="inline-flex items-center gap-2 text-muted">
-            <AlertTriangle className="w-4 h-4 text-danger" />
-            {t("playlists.loadFailed")}
-          </span>
-          <Button variant="outline" size="xs" onClick={() => detailQuery.refetch()}>
-            {t("common.retry")}
-          </Button>
-        </div>
+        <StateMessage tone="error" onRetry={() => detailQuery.refetch()}>
+          {t("playlists.loadFailed")}
+        </StateMessage>
         {player}
       </>
     );
@@ -835,7 +846,7 @@ export default function Playlists() {
   if (!detail) {
     return (
       <>
-        <div className="text-muted text-sm p-4">{t("playlists.loading")}</div>
+        <LoadingState label={t("playlists.loading")} />
         {player}
       </>
     );
diff --git a/frontend/src/components/PlexPlaylistView.tsx b/frontend/src/components/PlexPlaylistView.tsx
index 00505e67..ffc97290 100644
--- a/frontend/src/components/PlexPlaylistView.tsx
+++ b/frontend/src/components/PlexPlaylistView.tsx
@@ -31,7 +31,8 @@ import {
   Trash2,
   X,
 } from "lucide-react";
-import { api, type PlexCard } from "../lib/api";
+import { api, HttpError, type PlexCard } from "../lib/api";
+import { notifyActionError } from "../lib/actionErrors";
 import { formatRuntime } from "../lib/format";
 import { getAccountRaw, LS, setAccountRaw } from "../lib/storage";
 import { useConfirm } from "./ConfirmProvider";
@@ -401,6 +402,17 @@ export default function PlexPlaylistView({
     qc.invalidateQueries({ queryKey: qk.plexPlaylists() });
   };
 
+  // Every edit here is optimistic on the local copy, and none of them used to handle a failure: a
+  // removal that failed stayed removed on screen (the resync never ran), and a 404 — the playlist
+  // deleted on another device, now a structured `not_found` — was an unhandled rejection that said
+  // nothing at all (deep-review round 4; the YouTube side was fixed in round 3). A failure is said,
+  // and the rows are put back from what the server last sent — explicitly, because a resync that
+  // returns the same list keeps the same `q.data` and the re-sync effect above never runs.
+  const putBack = () => {
+    if (q.data) setItems(q.data.items);
+    invalidate();
+  };
+
   function commit(next: PlexCard[]) {
     setItems(next);
     api
@@ -408,7 +420,11 @@ export default function PlexPlaylistView({
         playlistId,
         next.map((i) => i.id),
       )
-      .then(() => qc.invalidateQueries({ queryKey: qk.plexPlaylists() }));
+      .then(() => qc.invalidateQueries({ queryKey: qk.plexPlaylists() }))
+      .catch((e: unknown) => {
+        notifyActionError(e, t("plex.playlist.reorderFailed"));
+        putBack();
+      });
   }
 
   async function onRemove(keys: string[]) {
@@ -420,6 +436,9 @@ export default function PlexPlaylistView({
       if (keys.length === 1) await api.plexPlaylistRemoveItem(playlistId, keys[0]!);
       else await api.plexPlaylistRemoveBulk(playlistId, keys);
       invalidate();
+    } catch (e) {
+      notifyActionError(e, t("plex.playlist.removeFailed"));
+      putBack();
     } finally {
       setBusy(false);
     }
@@ -428,7 +447,12 @@ export default function PlexPlaylistView({
   async function rename() {
     const title = name.trim();
     if (!title) return;
-    await api.plexRenamePlaylist(playlistId, title);
+    try {
+      await api.plexRenamePlaylist(playlistId, title);
+    } catch (e) {
+      notifyActionError(e, t("plex.playlist.renameFailed")); // the field stays open to try again
+      return;
+    }
     setRenaming(false);
     invalidate();
   }
@@ -440,7 +464,16 @@ export default function PlexPlaylistView({
       }))
     )
       return;
-    await api.plexDeletePlaylist(playlistId);
+    try {
+      await api.plexDeletePlaylist(playlistId);
+    } catch (e) {
+      // Gone already (deleted on another device): what was asked for is true — leave the dead page.
+      // Anything else is a real failure, and the page stays.
+      if (!(e instanceof HttpError && e.status === 404)) {
+        notifyActionError(e, t("plex.playlist.deleteFailed"));
+        return;
+      }
+    }
     qc.invalidateQueries({ queryKey: qk.plexPlaylists() });
     onBack();
   }
diff --git a/frontend/src/components/TagManager.tsx b/frontend/src/components/TagManager.tsx
index 3870887c..a377abd4 100644
--- a/frontend/src/components/TagManager.tsx
+++ b/frontend/src/components/TagManager.tsx
@@ -5,6 +5,7 @@ import { qk } from "../lib/queryKeys";
 import { Plus, Trash2 } from "lucide-react";
 import { api, type Tag } from "../lib/api";
 import { notify } from "../lib/notifications";
+import { notifyActionError } from "../lib/actionErrors";
 import { useScrollFade } from "../lib/useScrollFade";
 import { Button } from "./ui/Button";
 import Modal from "./ui/Modal";
@@ -133,9 +134,16 @@ export default function TagManager({
       invalidate();
     },
   });
+  // A failure is said and the list refetched — a tag deleted in another tab used to fail in silence
+  // (a 404 `not_found/tag` gets no global dialog) and stay listed.
+  const onFailed = (e: unknown, fallback: string) => {
+    notifyActionError(e, fallback);
+    invalidate();
+  };
   const rename = useMutation({
     mutationFn: (v: { id: number; name: string }) => api.updateTag(v.id, { name: v.name }),
     onSuccess: invalidate,
+    onError: (e) => onFailed(e, t("tagManager.renameFailed")),
   });
   const del = useMutation({
     mutationFn: (v: { id: number; name: string }) => api.deleteTag(v.id),
@@ -143,6 +151,7 @@ export default function TagManager({
       invalidate();
       notify({ level: "success", message: t("tagManager.deleted", { name: v.name }) });
     },
+    onError: (e) => onFailed(e, t("tagManager.deleteFailed")),
   });
 
   // Picking a channel from a tag's popover: close the dialog, then focus it in the manager.
diff --git a/frontend/src/i18n/locales/en/playlists.json b/frontend/src/i18n/locales/en/playlists.json
index 2b2d6ddb..b29ed906 100644
--- a/frontend/src/i18n/locales/en/playlists.json
+++ b/frontend/src/i18n/locales/en/playlists.json
@@ -124,5 +124,6 @@
   "viewGroupedAnd": "grouped by channel, {{sort}}",
   "viewDiffers": "Temporary view ({{view}}) — the playlist's saved order is unchanged. Save it to keep this order.",
   "viewMatches": "This view ({{view}}) already matches the playlist's saved order, so there is nothing to save.",
-  "viewFiltered": "Filtered view — {{shown}} of {{total}} shown. The order can't be saved while a filter is on."
+  "viewFiltered": "Filtered view — {{shown}} of {{total}} shown. The order can't be saved while a filter is on.",
+  "addFailed": "Couldn't add it to the playlist."
 }
diff --git a/frontend/src/i18n/locales/en/plex.json b/frontend/src/i18n/locales/en/plex.json
index 12136fb0..7970e9de 100644
--- a/frontend/src/i18n/locales/en/plex.json
+++ b/frontend/src/i18n/locales/en/plex.json
@@ -320,7 +320,11 @@
     "seasonUnknown": "Episodes",
     "addShow": "Add whole show to a playlist",
     "addSeason": "Add season to a playlist",
-    "addEpisode": "Add episode to a playlist"
+    "addEpisode": "Add episode to a playlist",
+    "removeFailed": "Couldn't remove it from the playlist.",
+    "renameFailed": "Couldn't rename the playlist.",
+    "deleteFailed": "Couldn't delete the playlist.",
+    "reorderFailed": "Couldn't save the new order."
   },
   "people": {
     "count_one": "{{count}} title",
diff --git a/frontend/src/i18n/locales/en/tagManager.json b/frontend/src/i18n/locales/en/tagManager.json
index 64b33aef..d6f2709f 100644
--- a/frontend/src/i18n/locales/en/tagManager.json
+++ b/frontend/src/i18n/locales/en/tagManager.json
@@ -8,5 +8,7 @@
   "confirmDelete": "Delete the tag “{{name}}”? It will be removed from every channel it's on.",
   "empty": "No tags yet — add one below.",
   "newPlaceholder": "New tag name…",
-  "add": "Add"
+  "add": "Add",
+  "renameFailed": "Couldn't rename the tag.",
+  "deleteFailed": "Couldn't delete the tag."
 }
diff --git a/frontend/src/i18n/locales/hu/playlists.json b/frontend/src/i18n/locales/hu/playlists.json
index 44f0b30a..def08c4a 100644
--- a/frontend/src/i18n/locales/hu/playlists.json
+++ b/frontend/src/i18n/locales/hu/playlists.json
@@ -124,5 +124,6 @@
   "viewGroupedAnd": "csatorna szerint csoportosítva, {{sort}}",
   "viewDiffers": "Ideiglenes nézet ({{view}}) — a lista mentett sorrendje változatlan. Mentsd, ha ez maradjon.",
   "viewMatches": "Ez a nézet ({{view}}) megegyezik a lista mentett sorrendjével, így nincs mit menteni.",
-  "viewFiltered": "Szűrt nézet — {{total}} elemből {{shown}} látszik. Szűrés közben a sorrend nem menthető."
+  "viewFiltered": "Szűrt nézet — {{total}} elemből {{shown}} látszik. Szűrés közben a sorrend nem menthető.",
+  "addFailed": "Nem sikerült hozzáadni a lejátszási listához."
 }
diff --git a/frontend/src/i18n/locales/hu/plex.json b/frontend/src/i18n/locales/hu/plex.json
index 4edd3cde..e85ab902 100644
--- a/frontend/src/i18n/locales/hu/plex.json
+++ b/frontend/src/i18n/locales/hu/plex.json
@@ -320,7 +320,11 @@
     "seasonUnknown": "Epizódok",
     "addShow": "Egész sorozat listához adása",
     "addSeason": "Évad listához adása",
-    "addEpisode": "Epizód listához adása"
+    "addEpisode": "Epizód listához adása",
+    "removeFailed": "Nem sikerült eltávolítani a lejátszási listáról.",
+    "renameFailed": "Nem sikerült átnevezni a lejátszási listát.",
+    "deleteFailed": "Nem sikerült törölni a lejátszási listát.",
+    "reorderFailed": "Nem sikerült menteni az új sorrendet."
   },
   "people": {
     "count_one": "{{count}} cím",
diff --git a/frontend/src/i18n/locales/hu/tagManager.json b/frontend/src/i18n/locales/hu/tagManager.json
index 4a57382a..543fc1cc 100644
--- a/frontend/src/i18n/locales/hu/tagManager.json
+++ b/frontend/src/i18n/locales/hu/tagManager.json
@@ -8,5 +8,7 @@
   "confirmDelete": "Törlöd a(z) „{{name}}” címkét? Minden csatornáról lekerül, amin rajta van.",
   "empty": "Még nincs címke — adj hozzá lentebb.",
   "newPlaceholder": "Új címke neve…",
-  "add": "Hozzáad"
+  "add": "Hozzáad",
+  "renameFailed": "Nem sikerült átnevezni a címkét.",
+  "deleteFailed": "Nem sikerült törölni a címkét."
 }

From 545996f80797f7612c9c5df8f17ad151c66e695b Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Fri, 11 Sep 2026 23:43:23 +0200
Subject: [PATCH 34/52] fix(ui): a toast host ranks by when its overlay opened,
 and an overlay keeps its Escape, its dialog and its navigation straight
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 4, the overlays.

- Toast hosts were ranked by mount time, and PlayerModal swaps its host on every fullscreen change:
  leaving true fullscreen with the download dialog open put the player's host back on top, so toasts
  were drawn under that dialog's scrim and a click on one closed the dialog. Each overlay takes a
  rank once, when it opens (`useOverlayOrder`), and hands it to every host it renders.
- A dialog open while fullscreen is left keeps a stable portal container (moved, not re-created):
  React tore the portal down when `fsRoot` changed, resetting a half-filled form and dropping focus
  to <body>. Focus is put back after the move.
- The onboarding wizard is a layer, not a raw document listener: one Escape used to dismiss the
  error dialog over it AND end onboarding, skipping the write-scope step.
- `navigateTo` (a toast's "View", clicked inside the player's own host) goes over the overlays it
  unmounts, so the player's Back-to-close cleanup no longer pops the page it just opened — the same
  fix Shift+W already had. The access-requests toast action too.
- The live region arms itself a task after it takes over inherited toasts: React flushes effects in
  the same task as that render, so the "silent inheritance" arming was a no-op.
- The overlay-host guard matches class tokens in any order (PlexPlayer's root was never checked),
  globs `ui/` too (ui/Modal was not checked either), and requires the rank.
---
 frontend/src/App.tsx                          |  3 +-
 .../OnboardingWizard.escape.dom.test.tsx      | 63 +++++++++++++++
 frontend/src/components/OnboardingWizard.tsx  | 18 ++---
 frontend/src/components/PlayerModal.tsx       | 15 ++--
 frontend/src/components/PlexPlayer.tsx        |  6 +-
 .../ui/Modal.fullscreen.dom.test.tsx          | 52 +++++++++++++
 frontend/src/components/ui/Modal.tsx          | 26 ++++++-
 .../src/components/ui/Toaster.dom.test.tsx    | 44 ++++++++++-
 .../src/components/ui/Toaster.hosts.test.ts   | 76 +++++++++++++++----
 frontend/src/components/ui/Toaster.tsx        | 59 ++++++++++----
 frontend/src/lib/nav.dom.test.ts              | 40 ++++++++++
 frontend/src/lib/nav.ts                       | 11 ++-
 12 files changed, 358 insertions(+), 55 deletions(-)
 create mode 100644 frontend/src/components/OnboardingWizard.escape.dom.test.tsx
 create mode 100644 frontend/src/components/ui/Modal.fullscreen.dom.test.tsx
 create mode 100644 frontend/src/lib/nav.dom.test.ts

diff --git a/frontend/src/App.tsx b/frontend/src/App.tsx
index 8d9de728..707e07c6 100644
--- a/frontend/src/App.tsx
+++ b/frontend/src/App.tsx
@@ -279,7 +279,8 @@ export default function App() {
           label: t("common.accessRequestsReview"),
           onClick: () => {
             focusAccessRequestsTab();
-            setPage("users");
+            // Over whatever overlay the toast was clicked in — as navigateTo does (see lib/nav).
+            navigateOverOverlays(() => setPage("users"));
           },
         },
       });
diff --git a/frontend/src/components/OnboardingWizard.escape.dom.test.tsx b/frontend/src/components/OnboardingWizard.escape.dom.test.tsx
new file mode 100644
index 00000000..87bb4b78
--- /dev/null
+++ b/frontend/src/components/OnboardingWizard.escape.dom.test.tsx
@@ -0,0 +1,63 @@
+// @vitest-environment jsdom
+//
+// Escape closes the topmost layer only — the wizard included (deep-review round 4). Its own Escape
+// was a raw `document` listener with no layer check, and document listeners run before the window
+// listener ui/Modal uses: a sync that failed inside the wizard opens the global error dialog, and one
+// Esc dismissed the error AND ended onboarding, skipping the write-scope step.
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup, screen, fireEvent } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+    Trans: ({ i18nKey }: { i18nKey: string }) => i18nKey,
+  };
+});
+vi.mock("../lib/onboarding", () => ({ beginGrant: vi.fn(), endOnboarding: vi.fn() }));
+
+import OnboardingWizard from "./OnboardingWizard";
+import Modal from "./ui/Modal";
+import { api, type Me } from "../lib/api";
+
+const me = { id: 1, email: "a@b", can_read: false, can_write: false } as unknown as Me;
+
+beforeEach(() => {
+  vi.spyOn(api, "myStatus").mockResolvedValue({ channels_total: 0 } as never);
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe("the onboarding wizard's Escape", () => {
+  const mount = (onClose: () => void, dialog: boolean) =>
+    render(
+      <QueryClientProvider
+        client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}
+      >
+        <OnboardingWizard me={me} onClose={onClose} />
+        {dialog && (
+          <Modal title="boom" onClose={() => {}}>
+            <p>the sync failed</p>
+          </Modal>
+        )}
+      </QueryClientProvider>,
+    );
+
+  it("closes the wizard when nothing is open above it", () => {
+    const onClose = vi.fn();
+    mount(onClose, false);
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("leaves the wizard alone while a dialog is open over it", () => {
+    const onClose = vi.fn();
+    mount(onClose, true);
+    fireEvent.keyDown(screen.getByText("the sync failed"), { key: "Escape" });
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});
diff --git a/frontend/src/components/OnboardingWizard.tsx b/frontend/src/components/OnboardingWizard.tsx
index b57c57a5..e8a7de83 100644
--- a/frontend/src/components/OnboardingWizard.tsx
+++ b/frontend/src/components/OnboardingWizard.tsx
@@ -7,7 +7,8 @@ import { api, type Me } from "../lib/api";
 import { beginGrant, endOnboarding } from "../lib/onboarding";
 import { Button } from "./ui/Button";
 import Overlay from "./ui/Overlay";
-import Toaster from "./ui/Toaster";
+import Toaster, { useOverlayOrder } from "./ui/Toaster";
+import { useLayer } from "../lib/layerStack";
 
 // A first-login wizard that walks the user through granting YouTube access one scope at a
 // time, each with a plain explanation and an up-front heads-up about Google's "unverified
@@ -103,15 +104,12 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
     endOnboarding(!me.can_read);
     onClose();
   };
+  const overlayOrder = useOverlayOrder(); // this overlay's toast-host rank (see ui/Toaster)
 
-  useEffect(() => {
-    function onKey(e: KeyboardEvent) {
-      if (e.key === "Escape") close();
-    }
-    document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [me.can_read]);
+  // A layer in the shared stack, so Escape closes the wizard only when it is on top: a raw document
+  // listener ran BEFORE the error dialog's (a sync that failed inside the wizard opens one), and one
+  // Esc closed the error AND ended onboarding, skipping the write-scope step (deep-review round 4).
+  useLayer(true, close);
 
   // Are we currently importing (or about to)? Show a progress screen instead of the
   // "you're connected" step until the first import settles.
@@ -265,7 +263,7 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
         </div>
         {/* Toasts raised while the wizard is up (the connection notice among them) show above its
             scrim, not under it — see ui/Toaster. */}
-        <Toaster overlay />
+        <Toaster overlay order={overlayOrder} />
       </div>
     </Overlay>
   );
diff --git a/frontend/src/components/PlayerModal.tsx b/frontend/src/components/PlayerModal.tsx
index 47b73975..6b71e37f 100644
--- a/frontend/src/components/PlayerModal.tsx
+++ b/frontend/src/components/PlayerModal.tsx
@@ -48,7 +48,7 @@ import { fullscreenElement } from "../lib/fullscreen";
 import { dispatch, isActivationTarget, useKeyScope } from "../lib/keymap";
 import { closeThenNavigate, useBackToClose } from "../lib/history";
 import ChannelNameLink from "./ChannelNameLink";
-import Toaster from "./ui/Toaster";
+import Toaster, { useOverlayOrder } from "./ui/Toaster";
 import { afterRemoval } from "../lib/playerQueue";
 import {
   useNativeControlsYield,
@@ -379,6 +379,10 @@ export default function PlayerModal({
     staleTime: 5 * 60_000,
   });
 
+  // Its toast hosts' rank (see ui/Toaster): the player's two hosts — the stage one in true fullscreen,
+  // the outer one otherwise — swap on every fullscreen change, and must not outrank a dialog opened
+  // over the player by doing so.
+  const overlayOrder = useOverlayOrder();
   // This player is a dismissable layer: register it so a Modal or popover opened ABOVE it (e.g. the
   // download dialog, or — after S4 — an anchored menu) takes Escape first and this player defers.
   const layerIdRef = useRef<number | null>(null);
@@ -583,10 +587,9 @@ export default function PlayerModal({
               bar — that stays reachable by hovering the video's bottom edge, just above ours. Always
               visible (no auto-hide) so there's no guessing whether it will appear and no fight with the
               seek bar over the same pixels. stopPropagation so a click here doesn't toggle playback;
-              the exit button also re-arms our shortcuts. Add-to-playlist works in true fullscreen (its
-              popover portals INTO the fullscreen element); download stays hidden there because it opens
-              a Modal, which still portals to <body> — outside the fullscreen element. */}
-            {isFullscreen && <Toaster overlay />}
+              the exit button also re-arms our shortcuts. Both of its dialogs work in true fullscreen:
+              add-to-playlist's popover and download's Modal portal INTO the fullscreen element. */}
+            {isFullscreen && <Toaster overlay order={overlayOrder} />}
             {(maximized || isFullscreen) && (
               <div
                 onClick={(e) => e.stopPropagation()}
@@ -965,7 +968,7 @@ export default function PlayerModal({
       {/* Toasts raised while the player is open (a failed Remove, a lost connection) — the app's own
           Toaster is underneath this scrim. See ui/Toaster. In true fullscreen it moves into the
           stage, the element holding the lock: out here it was painted under it, i.e. not at all. */}
-      {!isFullscreen && <Toaster overlay />}
+      {!isFullscreen && <Toaster overlay order={overlayOrder} />}
     </div>,
     document.body,
   );
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index e32b9b0c..a35b9023 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -43,7 +43,7 @@ import { PlexPlayerSettings } from "./PlexPlayerSettings";
 import { PlexStatsOverlay } from "./PlexStatsOverlay";
 import { createFragMeter } from "../lib/plexStats";
 import { UpNextCard } from "./UpNextCard";
-import Toaster from "./ui/Toaster";
+import Toaster, { useOverlayOrder } from "./ui/Toaster";
 import {
   playhead,
   useAutoSkip,
@@ -793,6 +793,8 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   useKeyScope("plexPlayer");
   useHelpConditions({ episode: detail?.kind === "episode" });
 
+  // Its toast host's rank among open overlays (see ui/Toaster).
+  const overlayOrder = useOverlayOrder();
   // This player is a dismissable layer: register it so a Modal or popover opened ABOVE it (its own
   // settings/tracks menus included) takes Escape first and this player defers (R8 S3).
   const layerIdRef = useRef<number | null>(null);
@@ -1515,7 +1517,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       )}
       {/* The app's Toaster is underneath this full-screen player (and outside it in native
           fullscreen), so toasts raised while watching show here instead. See ui/Toaster. */}
-      <Toaster overlay />
+      <Toaster overlay order={overlayOrder} />
     </div>,
     document.body,
   );
diff --git a/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx b/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx
new file mode 100644
index 00000000..42e1fb87
--- /dev/null
+++ b/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx
@@ -0,0 +1,52 @@
+// @vitest-environment jsdom
+//
+// A dialog opened from a player in true fullscreen portals INTO the fullscreen element (a node under
+// <body> is painted beneath it, i.e. invisible). Leaving fullscreen changes that container — and a
+// React portal whose container changes is torn down and recreated, so everything the dialog held went
+// with it: a half-filled download form reset to its defaults and focus fell to <body> (a verifier's
+// side finding in deep-review round 4).
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup, screen, fireEvent, act } from "@testing-library/react";
+import { vi } from "vitest";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
+});
+
+import Modal from "./Modal";
+
+const setFullscreen = (el: Element | null) =>
+  act(() => {
+    Object.defineProperty(document, "fullscreenElement", { value: el, configurable: true });
+    document.dispatchEvent(new Event("fullscreenchange"));
+  });
+
+afterEach(() => {
+  cleanup();
+  setFullscreen(null);
+});
+
+describe("a dialog open while fullscreen is left", () => {
+  it("keeps what the viewer had typed in it, and the focus inside it", async () => {
+    const stage = document.createElement("div");
+    document.body.appendChild(stage);
+    await setFullscreen(stage);
+    render(
+      <Modal title="Download" onClose={() => {}}>
+        <input aria-label="name" defaultValue="" />
+      </Modal>,
+    );
+    const field = screen.getByLabelText("name") as HTMLInputElement;
+    fireEvent.change(field, { target: { value: "my cut" } });
+    field.focus();
+    expect(stage.contains(field)).toBe(true);
+
+    await setFullscreen(null); // the browser's own Esc leaves fullscreen; the dialog stays open
+
+    const after = screen.getByLabelText("name") as HTMLInputElement;
+    expect(after.value).toBe("my cut");
+    expect(document.activeElement).toBe(after);
+    stage.remove();
+  });
+});
diff --git a/frontend/src/components/ui/Modal.tsx b/frontend/src/components/ui/Modal.tsx
index fa38737c..4cdc113a 100644
--- a/frontend/src/components/ui/Modal.tsx
+++ b/frontend/src/components/ui/Modal.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useId, useRef, useState, type ReactNode } from "react";
+import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { useTranslation } from "react-i18next";
 import { X } from "lucide-react";
@@ -6,7 +6,7 @@ import { useBackToClose } from "../../lib/history";
 import { pushLayer, removeLayer, isTopmost } from "../../lib/layerStack";
 import { useFullscreenElement } from "../../lib/fullscreen";
 import { Button } from "./Button";
-import Toaster from "./Toaster";
+import Toaster, { useOverlayOrder } from "./Toaster";
 
 // Tabbable elements inside the dialog, in DOM order. `:not([tabindex="-1"])` drops programmatically
 // focusable-only nodes; the visibility filter (offsetParent) drops display:none ones (e.g. a
@@ -45,6 +45,23 @@ export default function Modal({
   // Browser/mouse Back closes the topmost modal instead of navigating away.
   useBackToClose(onClose);
   const fsRoot = useFullscreenElement();
+  // ONE container element for the dialog's whole life, MOVED between <body> and the fullscreen
+  // element rather than handed to `createPortal` as a changing container: React tears a portal down
+  // and builds it again when its container changes, and the dialog's contents went with it — a
+  // half-filled download form reset to its defaults, and focus fell to <body>, the moment the viewer
+  // left true fullscreen (deep-review round 4).
+  const [host] = useState(() => document.createElement("div"));
+  useLayoutEffect(() => {
+    const parent = fsRoot ?? document.body;
+    if (host.parentNode === parent) return;
+    // appendChild MOVES the node: the browser blurs whatever was focused inside it on the way out.
+    const focused = host.contains(document.activeElement)
+      ? (document.activeElement as HTMLElement)
+      : null;
+    parent.appendChild(host);
+    focused?.focus();
+  }, [fsRoot, host]);
+  useEffect(() => () => host.remove(), [host]);
   const panelRef = useRef<HTMLDivElement>(null);
   const titleId = useId();
   // Capture the trigger to restore focus to, during THIS render — i.e. before commit runs the
@@ -52,6 +69,7 @@ export default function Modal({
   // it later (in the effect) would capture a now-inside element that unmounts on close, stranding
   // focus on <body>. useState initializer runs exactly once, on first render.
   const [restoreTo] = useState(() => document.activeElement as HTMLElement | null);
+  const overlayOrder = useOverlayOrder();
 
   // Backdrop-click close must only fire when the press STARTED on the backdrop too. Otherwise a
   // drag that begins inside the dialog (e.g. selecting text in an input) and is released out on
@@ -170,8 +188,8 @@ export default function Modal({
       {/* Toasts raised while a dialog is open show inside it: the app's own host is under this
           scrim, where a failed share or rename was unreadable and a click on it closed the dialog
           (see ui/Toaster). */}
-      <Toaster overlay />
+      <Toaster overlay order={overlayOrder} />
     </div>,
-    fsRoot ?? document.body,
+    host,
   );
 }
diff --git a/frontend/src/components/ui/Toaster.dom.test.tsx b/frontend/src/components/ui/Toaster.dom.test.tsx
index ca13a1e0..44a3a53e 100644
--- a/frontend/src/components/ui/Toaster.dom.test.tsx
+++ b/frontend/src/components/ui/Toaster.dom.test.tsx
@@ -41,7 +41,8 @@ describe("Toaster — one host shows the toasts", () => {
     expect(screen.getByTestId("app").textContent).not.toContain("Couldn't remove the video.");
     // Both live regions stay mounted — a polite region has to pre-exist to be announced.
     expect(hosts()).toHaveLength(2);
-    expect(hosts().map((h) => h.getAttribute("aria-live"))).toEqual(["off", "polite"]);
+    // The taking-over host arms itself a task later (see the "inherits" test below).
+    expect(hosts().map((h) => h.getAttribute("aria-live"))).toEqual(["off", "off"]);
 
     overlay.unmount();
     expect(screen.getByTestId("app").textContent).toContain("Couldn't remove the video.");
@@ -74,6 +75,47 @@ describe("Toaster — handing the toasts to another host", () => {
     expect(screen.getByText("fresh").closest(".toast-card")!.getAttribute("role")).toBe("alert");
   });
 
+  it("keeps its live region off while the inherited toasts go in, and arms it a task later", async () => {
+    // The other half of "silently": a region that is already polite when the inherited nodes are
+    // inserted announces them anyway. React flushes effects in the SAME task as that render, so the
+    // arming has to wait for the next one — a screen reader reads the region's state after the task.
+    render(<Toaster />);
+    act(() => void notify({ level: "info", message: "saved" }));
+    const overlay = render(<Toaster overlay />);
+    const region = overlay.container.firstElementChild!;
+    expect(region.textContent).toContain("saved"); // it took the toast over…
+    expect(region.getAttribute("aria-live")).toBe("off"); // …while still off
+    await act(async () => void (await new Promise((r) => setTimeout(r, 0))));
+    expect(region.getAttribute("aria-live")).toBe("polite"); // and polite for what comes next
+  });
+
+  it("ranks hosts by when their OVERLAY opened, not by when the host mounted", async () => {
+    // PlayerModal's host moves into the fullscreen stage and back: remounted, it used to jump over a
+    // dialog opened above the player, and the toasts went back under that dialog's scrim.
+    const player = render(
+      <div data-testid="player">
+        <Toaster overlay order={1} />
+      </div>,
+    );
+    render(
+      <div data-testid="dialog">
+        <Toaster overlay order={2} />
+      </div>,
+    );
+    act(() => void notify({ level: "error", message: "boom" }));
+    expect(screen.getByTestId("dialog").textContent).toContain("boom");
+    // The player swaps its host (leaving true fullscreen) while the dialog stays open.
+    player.rerender(
+      <div data-testid="player">
+        <span />
+        <Toaster overlay order={1} />
+      </div>,
+    );
+    await act(async () => void (await new Promise((r) => setTimeout(r, 0))));
+    expect(screen.getByTestId("dialog").textContent).toContain("boom");
+    expect(screen.getByTestId("player").textContent).not.toContain("boom");
+  });
+
   it("keeps the countdown where it was, instead of starting it again from full", () => {
     // The bar is a CSS animation on the node; the dismiss timer was armed once, at notify time. A
     // new node restarted the bar, and the toast vanished with it still two-thirds full.
diff --git a/frontend/src/components/ui/Toaster.hosts.test.ts b/frontend/src/components/ui/Toaster.hosts.test.ts
index 874d03b0..e77650f5 100644
--- a/frontend/src/components/ui/Toaster.hosts.test.ts
+++ b/frontend/src/components/ui/Toaster.hosts.test.ts
@@ -3,31 +3,77 @@
 // The app's Toaster lives in the content column, a stacking context: anything that covers the
 // viewport at z-overlay paints over it, so a toast raised while that overlay is open is unreadable and
 // a click on it lands on the overlay's backdrop. The fix is a convention — the overlay mounts
-// `<Toaster overlay />` inside itself — and a convention stated in a comment is one the next overlay
-// forgets (deep-review round 3 found every ui/Modal and the onboarding wizard without one). So it is
-// checked here: a component that renders a viewport-covering z-overlay layer mounts an overlay host.
+// `<Toaster overlay order={useOverlayOrder()} />` inside itself — and a convention stated in a comment
+// is one the next overlay forgets (deep-review round 3 found every ui/Modal and the onboarding wizard
+// without one). So it is checked here: a component that renders a viewport-covering layer at
+// z-overlay or above mounts an overlay host, ranked by when the overlay opened.
+//
+// The class TOKENS are matched in any order, and the layer need not be `inset-0`: the first version
+// matched the exact string "fixed inset-0 z-overlay", so PlexPlayer's own root (`fixed left-0 top-0
+// z-overlay`) was never checked at all, and a new viewer copying it would have slipped past
+// (deep-review round 4).
 import { describe, it, expect } from "vitest";
 
-const sources = import.meta.glob("../**/*.tsx", { query: "?raw", import: "default", eager: true });
+// BOTH patterns: `../**/*.tsx` from this directory does not match the siblings in `ui/` itself, so
+// ui/Modal.tsx — the overlay behind every dialog in the app — was never checked by this guard at all
+// (deep-review round 4).
+const sources = import.meta.glob(["../**/*.tsx", "./*.tsx"], {
+  query: "?raw",
+  import: "default",
+  eager: true,
+});
 
-// Covers the viewport for a moment with nothing a toast could be about (a lazy chunk's black
-// placeholder while the player loads).
-const EXEMPT = new Set(["../PlexBrowse.tsx"]);
+// Overlays with nothing a toast could be about: a lazy chunk's black placeholder while the player
+// loads, and the signed-out landing page's screenshot zoom (the app's Toaster is not even mounted
+// there — App renders Welcome instead of the shell).
+const EXEMPT = new Set(["../PlexBrowse.tsx", "../Welcome.tsx"]);
+
+/** Every class string in the file (quoted or templated), including multi-line ones. */
+const classStrings = (src: string): string[] =>
+  [...src.matchAll(/className=\{?[`"']([^`"']*)[`"']/g)].map((m) => m[1]!);
+
+const coversTheViewport = (src: string) =>
+  classStrings(src).some(
+    (cls) =>
+      /(^|\s)fixed(\s|$)/.test(cls) &&
+      /(^|\s)z-(overlay|popover|tooltip)(\s|$)/.test(cls) &&
+      (/(^|\s)inset-0(\s|$)/.test(cls) ||
+        (/(^|\s)left-0(\s|$)/.test(cls) && /(^|\s)top-0(\s|$)/.test(cls))),
+  );
+
+const overlays = () =>
+  Object.entries(sources)
+    .filter(([path]) => !path.endsWith(".test.tsx") && !EXEMPT.has(path))
+    .filter(([, src]) => coversTheViewport(src as string));
 
 describe("full-screen overlays host their own toasts", () => {
-  it("every one that covers the viewport at z-overlay mounts <Toaster overlay />", () => {
-    const missing = Object.entries(sources)
-      .filter(([path]) => !path.endsWith(".test.tsx") && !EXEMPT.has(path))
-      .filter(([, src]) => /fixed inset-0 z-overlay/.test(src as string))
-      .filter(([, src]) => !(src as string).includes("<Toaster overlay />"))
+  it("every one that covers the viewport mounts an overlay host", () => {
+    const missing = overlays()
+      .filter(([, src]) => !(src as string).includes("<Toaster overlay"))
       .map(([path]) => path);
     expect(missing).toEqual([]);
   });
 
+  it("and ranks it by when the overlay opened, not by when the host mounted", () => {
+    // A host that takes its own rank jumps to the top whenever it remounts — which PlayerModal's does
+    // on every fullscreen change, putting it back over a dialog opened above the player.
+    const unranked = overlays()
+      .filter(([, src]) => !(src as string).includes("useOverlayOrder()"))
+      .map(([path]) => path);
+    expect(unranked).toEqual([]);
+  });
+
   it("finds the overlays it is meant to check", () => {
-    const covered = Object.entries(sources).filter(([, src]) =>
-      /fixed inset-0 z-overlay/.test(src as string),
+    // Modal, PlayerModal, PlexPlayer and the wizard at least — PlexPlayer is the one the exact-string
+    // check used to miss.
+    const paths = overlays().map(([p]) => p);
+    expect(paths).toEqual(
+      expect.arrayContaining([
+        "./Modal.tsx",
+        "../PlayerModal.tsx",
+        "../PlexPlayer.tsx",
+        "../OnboardingWizard.tsx",
+      ]),
     );
-    expect(covered.length).toBeGreaterThanOrEqual(3); // Modal, PlayerModal, the wizard at least
   });
 });
diff --git a/frontend/src/components/ui/Toaster.tsx b/frontend/src/components/ui/Toaster.tsx
index 3e471194..56d52e63 100644
--- a/frontend/src/components/ui/Toaster.tsx
+++ b/frontend/src/components/ui/Toaster.tsx
@@ -16,24 +16,48 @@ export const LEVEL_STYLE: Record<NotifLevel, { icon: typeof Info; color: string;
 // context (its `@container` implies layout containment) — so anything portalled to <body> at the
 // same z-overlay painted over every toast: a failure raised while watching was drawn under an 80%
 // black, blurred scrim, and a click on it closed the player. So every full-screen overlay mounts its
-// OWN `<Toaster overlay />` inside itself — ui/Modal does it for every dialog, the players for
-// themselves — and exactly one host shows the toasts: the most recently mounted overlay, else the
-// app's. Same component, same look — and inside the overlay's aria-modal dialog, where a screen
+// OWN `<Toaster overlay order={…} />` inside itself — ui/Modal does it for every dialog, the players
+// for themselves — and exactly one host shows the toasts: the one of the overlay OPENED last, else
+// the app's. Same component, same look — and inside the overlay's aria-modal dialog, where a screen
 // reader can still reach it.
-const overlayHosts = createStore<readonly string[]>([]);
+//
+// "Opened last", not "host mounted last": a host can remount while its overlay stays open —
+// PlayerModal's moves into the fullscreen stage and back — and ranked by mount time it came back on
+// top of a dialog opened over the player (the download dialog after leaving true fullscreen), so the
+// toasts were drawn under that dialog's scrim again (deep-review round 4). So the OVERLAY takes its
+// rank once, when it opens (`useOverlayOrder`), and hands it to every host it renders.
+let overlaySeq = 0;
+/** This overlay's rank among open overlays — taken once, when it mounts. Call it in the overlay
+ *  itself, never in a component that can remount while the overlay stays open. */
+export function useOverlayOrder(): number {
+  const [order] = useState(() => ++overlaySeq);
+  return order;
+}
+type Host = { id: string; order: number };
+const overlayHosts = createStore<readonly Host[]>([]);
 const topHost = () => {
-  const hosts = overlayHosts.get();
-  return hosts[hosts.length - 1] ?? null;
+  let top: Host | null = null;
+  for (const h of overlayHosts.get()) if (!top || h.order >= top.order) top = h;
+  return top?.id ?? null;
 };
 
-export default function Toaster({ overlay = false }: { overlay?: boolean }) {
+export default function Toaster({
+  overlay = false,
+  order,
+}: {
+  overlay?: boolean;
+  /** The owning overlay's `useOverlayOrder()`. Without one, the host ranks by its own mount. */
+  order?: number;
+}) {
   const { t } = useTranslation();
   const id = useId();
+  const ownOrder = useOverlayOrder();
+  const rank = order ?? ownOrder;
   useEffect(() => {
     if (!overlay) return;
-    overlayHosts.set((hosts) => [...hosts, id]);
-    return () => overlayHosts.set((hosts) => hosts.filter((h) => h !== id));
-  }, [overlay, id]);
+    overlayHosts.set((hosts) => [...hosts, { id, order: rank }]);
+    return () => overlayHosts.set((hosts) => hosts.filter((h) => h.id !== id));
+  }, [overlay, id, rank]);
   const top = useSyncExternalStore(overlayHosts.subscribe, topHost, topHost);
   const active = useSyncExternalStore(subscribe, getActiveToasts, getActiveToasts);
   const isTop = top === (overlay ? id : null);
@@ -41,14 +65,23 @@ export default function Toaster({ overlay = false }: { overlay?: boolean }) {
   // A host that takes over (an overlay opening, or the app's own once it closes) receives the toasts
   // that were already up as NEW nodes — and a screen reader announced every one of them again, an
   // error assertively. So the ones it inherits are shown silently: no `role="alert"`, and the region
-  // stays `aria-live="off"` until they are in, turning polite (for the toasts that come after) once
-  // they have been rendered.
+  // stays `aria-live="off"` until they are in, turning polite (for the toasts that come after) in a
+  // LATER task. Not in an effect: React flushes those in the same task as the render that inserted the
+  // toasts, and a screen reader reads the region's state after the task — by which time it was polite
+  // again, i.e. the arming did nothing.
   const inherited = useMemo(
     () => new Set(isTop ? getActiveToasts().map((n) => n.id) : []),
     [isTop],
   );
   const [armed, setArmed] = useState(false);
-  useEffect(() => setArmed(isTop), [isTop]);
+  useEffect(() => {
+    if (!isTop) {
+      setArmed(false);
+      return;
+    }
+    const timer = window.setTimeout(() => setArmed(true), 0);
+    return () => window.clearTimeout(timer);
+  }, [isTop]);
 
   return (
     // Stable, always-mounted live region — a polite region must PRE-EXIST in the DOM for a screen
diff --git a/frontend/src/lib/nav.dom.test.ts b/frontend/src/lib/nav.dom.test.ts
new file mode 100644
index 00000000..eead88e2
--- /dev/null
+++ b/frontend/src/lib/nav.dom.test.ts
@@ -0,0 +1,40 @@
+// @vitest-environment jsdom
+//
+// `navigateTo` is what a toast's action calls ("Download added — View"), and that click happens
+// INSIDE an overlay's toast host. The page change unmounts the page-owned overlay (the player), whose
+// Back-to-close cleanup then reclaimed the history entry the navigation had just pushed — so the user
+// landed back where they started with the player closed instead of on the Downloads page
+// (deep-review round 4). Same trap, and the same fix, as the global Shift+W shortcut.
+//
+// Its own file: `lib/history`'s depth bookkeeping is module state.
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useBackToClose } from "./history";
+import { navigateTo, setNavigator } from "./nav";
+
+const settle = () =>
+  act(async () => {
+    await Promise.resolve();
+  });
+
+describe("navigateTo from inside an overlay", () => {
+  it("buries the overlay's entry, so closing it does not pop the page just opened", async () => {
+    const overlay = renderHook(() => useBackToClose(() => {}));
+    await settle();
+    const back = vi.spyOn(window.history, "back");
+    try {
+      setNavigator(() => {
+        window.history.pushState({ sfPage: "downloads" }, "");
+        return true; // as App's setPage reports: it really pushed
+      });
+      act(() => navigateTo("downloads"));
+      overlay.unmount(); // the page change unmounts the player
+      await settle();
+      expect(back).not.toHaveBeenCalled();
+      expect(window.history.state).toMatchObject({ sfPage: "downloads" });
+    } finally {
+      back.mockRestore();
+      setNavigator(() => {});
+    }
+  });
+});
diff --git a/frontend/src/lib/nav.ts b/frontend/src/lib/nav.ts
index 61f07057..c2d2b622 100644
--- a/frontend/src/lib/nav.ts
+++ b/frontend/src/lib/nav.ts
@@ -1,16 +1,21 @@
+import { navigateOverOverlays } from "./history";
 import type { Page } from "./urlState";
 
 // Tiny decoupled navigator so deep components (a feed card's download toast, the Download
 // Center) can switch pages without threading setPage through the whole tree. App registers
 // its setPage on mount; navigateTo is a no-op until then.
-let _navigate: ((p: Page) => void) | null = null;
+let _navigate: ((p: Page) => boolean | void) | null = null;
 
-export function setNavigator(fn: (p: Page) => void): void {
+export function setNavigator(fn: (p: Page) => boolean | void): void {
   _navigate = fn;
 }
 
+/** Over whatever overlay is open: the "View" on a "Download added" toast is clicked INSIDE the player
+ *  (its toast host), and the page change unmounts the page-owned player, whose Back-to-close cleanup
+ *  then popped the entry the navigation had just pushed — the user landed back on the feed with the
+ *  player gone (deep-review round 4). Same trap, same fix as Shift+W (see `navigateOverOverlays`). */
 export function navigateTo(p: Page): void {
-  _navigate?.(p);
+  navigateOverOverlays(() => _navigate?.(p));
 }
 
 /** Should this click be handled IN-APP, or left to the browser?

From 41b652f8fd6408da585484c43c5ebc03ac06e77a Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 03:41:37 +0200
Subject: [PATCH 35/52] fix(ui): a dialog opens focused where it said it would,
 and the wizard is a dialog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 5, over round 4's own fixes.

- Round 4 gave `ui/Modal` a persistent portal host so a fullscreen transition would stop tearing
  the dialog down. The host was attached in a `useLayoutEffect` — one commit phase AFTER React
  runs `autoFocus` in `commitMount`, and `focus()` on a disconnected node is a no-op. Every
  autoFocus in every dialog was dead: Mod+K opened the command palette with the focus on the ✕,
  so typing searched nothing and Enter closed it; the same for the download rename field and
  every non-danger confirm. The host is attached in a `useInsertionEffect` now, a whole phase
  earlier, and the whole re-parent — including the focus save/restore across the move, which
  `appendChild` needs because it is remove-then-insert — lives in one `useFullscreenPortalHost`.
  `ui/AnchoredPopover` had a second copy of that re-parent WITHOUT the focus restore, and a
  comment claiming focus survived it; both now come from the hook.

- `ui/Toaster` classified a toast raised in the SAME commit as a host takeover among the ones it
  inherits, because it read the store live at the takeover render. A dialog that notifies and
  closes in one handler (UploadDialog) therefore put its toast up with no role, into a region
  still `aria-live="off"` — announced by neither path. "Inherited" is now what the outgoing host
  last had on screen, and a toast that is NOT inherited is announced even inside the unarmed
  window.

- The onboarding wizard renders its own shell, and Escape ordering was all of the dialog contract
  it had: no role, no label, no initial focus, no trap, no restore. A keyboard user tabbed out of
  the first-login wizard into the app behind the scrim. The focus half of the contract is now one
  shared `ui/dialogFocus` that both `ui/Modal` and the wizard use.

Every fix has a regression test, each mutation-checked (6 mutations, all red on the assertion
they are named after).
---
 .../OnboardingWizard.dialog.dom.test.tsx      | 87 +++++++++++++++++++
 frontend/src/components/OnboardingWizard.tsx  | 49 +++++++++--
 .../src/components/ui/AnchoredPopover.tsx     | 24 ++---
 .../ui/Modal.fullscreen.dom.test.tsx          | 35 ++++++++
 frontend/src/components/ui/Modal.tsx          | 79 +++--------------
 .../src/components/ui/Toaster.dom.test.tsx    | 36 ++++++++
 frontend/src/components/ui/Toaster.tsx        | 28 ++++--
 frontend/src/components/ui/dialogFocus.ts     | 72 +++++++++++++++
 frontend/src/lib/fullscreen.ts                | 55 ++++++++++--
 9 files changed, 366 insertions(+), 99 deletions(-)
 create mode 100644 frontend/src/components/OnboardingWizard.dialog.dom.test.tsx
 create mode 100644 frontend/src/components/ui/dialogFocus.ts

diff --git a/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx b/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx
new file mode 100644
index 00000000..d7bc0bca
--- /dev/null
+++ b/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx
@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+//
+// The wizard is a modal overlay in every way that matters to a user, but it renders its own shell
+// instead of going through `ui/Modal` — and for a keyboard or screen-reader user it had nothing of
+// the dialog contract: no role, no label, no initial focus, no trap, no restore. Tab past its last
+// control walked into the app behind the scrim, where the focus ring is invisible (round 5).
+//
+// `focusablesIn` filters on `el.offsetParent !== null` and jsdom reports null for everything, so the
+// trap is untestable as written without the same stub `ui/Modal.dom.test.tsx` uses.
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup, screen, fireEvent } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+    Trans: ({ i18nKey }: { i18nKey: string }) => i18nKey,
+  };
+});
+vi.mock("../lib/onboarding", () => ({ beginGrant: vi.fn(), endOnboarding: vi.fn() }));
+
+import OnboardingWizard from "./OnboardingWizard";
+import { api, type Me } from "../lib/api";
+
+const me = { id: 1, email: "a@b", can_read: false, can_write: false } as unknown as Me;
+
+let origDesc: PropertyDescriptor | undefined;
+beforeEach(() => {
+  vi.spyOn(api, "myStatus").mockResolvedValue({ channels_total: 0 } as never);
+  origDesc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetParent");
+  Object.defineProperty(HTMLElement.prototype, "offsetParent", {
+    configurable: true,
+    get(this: HTMLElement) {
+      return this.isConnected ? document.body : null;
+    },
+  });
+});
+afterEach(() => {
+  cleanup();
+  if (origDesc) Object.defineProperty(HTMLElement.prototype, "offsetParent", origDesc);
+  else delete (HTMLElement.prototype as unknown as Record<string, unknown>).offsetParent;
+  vi.restoreAllMocks();
+});
+
+const mount = () =>
+  render(
+    <QueryClientProvider
+      client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}
+    >
+      <OnboardingWizard me={me} onClose={() => {}} />
+    </QueryClientProvider>,
+  );
+
+describe("the onboarding wizard as a dialog", () => {
+  it("announces itself as a labelled modal dialog", () => {
+    mount();
+    const panel = screen.getByRole("dialog");
+    expect(panel.getAttribute("aria-modal")).toBe("true");
+    // The label is the step's own heading — the wizard has no header row to take a title from.
+    const heading = document.getElementById(panel.getAttribute("aria-labelledby")!);
+    expect(heading?.textContent).toBe("onboarding.read.title");
+  });
+
+  it("opens focused inside itself and keeps Tab from leaving", () => {
+    const outside = document.createElement("button");
+    outside.textContent = "behind the scrim";
+    document.body.appendChild(outside);
+    outside.focus();
+
+    const { unmount } = mount();
+    const panel = screen.getByRole("dialog");
+    expect(panel.contains(document.activeElement)).toBe(true);
+
+    // From the last control, Tab wraps back to the first instead of reaching the page behind.
+    const stops = [...panel.querySelectorAll<HTMLElement>("button, a[href]")];
+    stops[stops.length - 1]!.focus();
+    fireEvent.keyDown(window, { key: "Tab" });
+    expect(document.activeElement).toBe(stops[0]);
+
+    // …and closing hands the focus back to whatever opened it.
+    unmount();
+    expect(document.activeElement).toBe(outside);
+    outside.remove();
+  });
+});
diff --git a/frontend/src/components/OnboardingWizard.tsx b/frontend/src/components/OnboardingWizard.tsx
index e8a7de83..57b1d377 100644
--- a/frontend/src/components/OnboardingWizard.tsx
+++ b/frontend/src/components/OnboardingWizard.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useRef } from "react";
+import { useEffect, useId, useRef } from "react";
 import { Trans, useTranslation } from "react-i18next";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { qk } from "../lib/queryKeys";
@@ -9,6 +9,7 @@ import { Button } from "./ui/Button";
 import Overlay from "./ui/Overlay";
 import Toaster, { useOverlayOrder } from "./ui/Toaster";
 import { useLayer } from "../lib/layerStack";
+import { trapTab, useDialogChrome } from "./ui/dialogFocus";
 
 // A first-login wizard that walks the user through granting YouTube access one scope at a
 // time, each with a plain explanation and an up-front heads-up about Google's "unverified
@@ -109,7 +110,26 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
   // A layer in the shared stack, so Escape closes the wizard only when it is on top: a raw document
   // listener ran BEFORE the error dialog's (a sync that failed inside the wizard opens one), and one
   // Esc closed the error AND ended onboarding, skipping the write-scope step (deep-review round 4).
-  useLayer(true, close);
+  const layer = useLayer(true, close);
+
+  // The rest of the dialog contract. This is a modal overlay in every way that matters to a user, but
+  // it renders its own shell (it is not a titled dialog with a header row), so Escape ordering was all
+  // it had: focus started on <body>, nothing announced a dialog, and Tab past the last control walked
+  // into the app behind the scrim — where the focus ring is invisible (deep-review round 5). The trap
+  // and the roles come from the same place `ui/Modal` gets them, not from a second hand-written copy.
+  const panelRef = useRef<HTMLDivElement>(null);
+  const titleId = useId();
+  useDialogChrome(panelRef);
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      // Only while nothing is above us: an error dialog opened from inside the wizard owns the Tab.
+      if (e.key !== "Tab" || !layer.isTopmost()) return;
+      const panel = panelRef.current;
+      if (panel) trapTab(e, panel);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [layer]);
 
   // Are we currently importing (or about to)? Show a progress screen instead of the
   // "you're connected" step until the first import settles.
@@ -130,7 +150,14 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
           className="absolute inset-0 bg-black/50 animate-[overlayIn_0.2s_ease]"
           onClick={close}
         />
-        <div className="glass relative w-[min(94vw,460px)] rounded-2xl p-7 text-center animate-[panelIn_0.26s_cubic-bezier(0.22,1,0.36,1)]">
+        <div
+          ref={panelRef}
+          tabIndex={-1}
+          role="dialog"
+          aria-modal="true"
+          aria-labelledby={titleId}
+          className="glass relative w-[min(94vw,460px)] rounded-2xl p-7 text-center outline-none animate-[panelIn_0.26s_cubic-bezier(0.22,1,0.36,1)]"
+        >
           <button
             onClick={close}
             className="absolute top-3 right-3 p-2 rounded-lg text-muted hover:text-fg hover:bg-card/60 transition"
@@ -144,7 +171,9 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
               <div className="mx-auto mb-4 grid place-items-center w-12 h-12 rounded-2xl bg-accent/15 text-accent">
                 <Youtube className="w-6 h-6" />
               </div>
-              <h2 className="text-lg font-semibold">{t("onboarding.read.title")}</h2>
+              <h2 id={titleId} className="text-lg font-semibold">
+                {t("onboarding.read.title")}
+              </h2>
               <p className="text-sm text-muted leading-relaxed mt-2 mb-4">
                 <Trans
                   i18nKey="onboarding.read.body"
@@ -172,7 +201,9 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
               <div className="mx-auto mb-4 grid place-items-center w-12 h-12 rounded-2xl bg-accent/15 text-accent">
                 <Loader2 className="w-6 h-6 animate-spin" />
               </div>
-              <h2 className="text-lg font-semibold">{t("onboarding.importing.title")}</h2>
+              <h2 id={titleId} className="text-lg font-semibold">
+                {t("onboarding.importing.title")}
+              </h2>
               <p className="text-sm text-muted leading-relaxed mt-2 mb-2">
                 {t("onboarding.importing.body")}
               </p>
@@ -184,7 +215,9 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
               <div className="mx-auto mb-4 grid place-items-center w-12 h-12 rounded-2xl bg-accent/15 text-accent">
                 <Check className="w-6 h-6" />
               </div>
-              <h2 className="text-lg font-semibold">{t("onboarding.write.title")}</h2>
+              <h2 id={titleId} className="text-lg font-semibold">
+                {t("onboarding.write.title")}
+              </h2>
               <p className="text-sm text-muted leading-relaxed mt-2 mb-4">
                 {importSubs.isError ? (
                   <>{t("onboarding.write.importFailed")}</>
@@ -241,7 +274,9 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
               <div className="mx-auto mb-4 grid place-items-center w-12 h-12 rounded-2xl bg-accent/15 text-accent">
                 <Check className="w-6 h-6" />
               </div>
-              <h2 className="text-lg font-semibold">{t("onboarding.done.title")}</h2>
+              <h2 id={titleId} className="text-lg font-semibold">
+                {t("onboarding.done.title")}
+              </h2>
               <p className="text-sm text-muted leading-relaxed mt-2 mb-5">
                 {t("onboarding.done.body")}
               </p>
diff --git a/frontend/src/components/ui/AnchoredPopover.tsx b/frontend/src/components/ui/AnchoredPopover.tsx
index 2e0daabb..deb95573 100644
--- a/frontend/src/components/ui/AnchoredPopover.tsx
+++ b/frontend/src/components/ui/AnchoredPopover.tsx
@@ -3,7 +3,6 @@ import {
   useContext,
   useEffect,
   useId,
-  useLayoutEffect,
   useRef,
   useState,
   type ButtonHTMLAttributes,
@@ -37,7 +36,7 @@ import {
   type UseRoleProps,
 } from "@floating-ui/react";
 import { useLayer } from "../../lib/layerStack";
-import { useFullscreenElement } from "../../lib/fullscreen";
+import { useFullscreenPortalHost } from "../../lib/fullscreen";
 
 // R8 popover platform. ONE anchored-popover primitive over @floating-ui/react, replacing the ~9
 // hand-rolled positioning engines (measured flip / width clamp / rAF scroll-follow / scroller-relative
@@ -528,19 +527,14 @@ function PopoverSurfaceInner({
 
   // A node portaled to <body> is painted UNDERNEATH whatever holds the fullscreen lock, so a popover
   // opened from a player's control bar in fullscreen would be invisible; it must portal INTO the
-  // fullscreen element. We own one persistent container div and re-parent it (body ↔ fullscreen
-  // element) with appendChild, which MOVES the node atomically — no detach, so the open panel's
-  // focus, caret, scroll offset and animation state survive a fullscreen transition, and an element
-  // SWAP (A→B without exiting) is handled by the element-identity dependency. (Keying the portal to
-  // remount instead would rebuild the subtree and lose all of that.)
-  const fsRoot = useFullscreenElement();
-  const [container] = useState<HTMLDivElement | null>(() =>
-    typeof document === "undefined" ? null : document.createElement("div"),
-  );
-  useLayoutEffect(() => {
-    if (container) (fsRoot ?? document.body).appendChild(container);
-  }, [container, fsRoot]);
-  useEffect(() => () => container?.remove(), [container]);
+  // fullscreen element. One persistent container div is re-parented (body ↔ fullscreen element)
+  // rather than handed to the portal as a changing container, so the open panel's caret, scroll
+  // offset and animation state survive the transition, and an element SWAP (A→B without exiting) is
+  // handled by the element-identity dependency. (Keying the portal to remount instead would rebuild
+  // the subtree and lose all of that.) Focus does NOT survive on its own — `appendChild` on an
+  // already-parented node is remove-then-insert, which blurs to <body>; the hook saves and restores
+  // it. This used to be a second copy of Modal's re-parent that lacked exactly that (round 5).
+  const container = useFullscreenPortalHost();
 
   const { style: floatingPropStyle, ...floatingProps } = getFloatingProps() as {
     style?: CSSProperties;
diff --git a/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx b/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx
index 42e1fb87..816fd154 100644
--- a/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx
+++ b/frontend/src/components/ui/Modal.fullscreen.dom.test.tsx
@@ -50,3 +50,38 @@ describe("a dialog open while fullscreen is left", () => {
     stage.remove();
   });
 });
+
+describe("a dialog with an autoFocus child", () => {
+  it("opens with the focus in that child, not on the close button", () => {
+    // The portal host is created detached and attached by the hook. If it is attached a phase too
+    // late (a `useLayoutEffect` instead of `useInsertionEffect`), every descendant's `autoFocus`
+    // has already called `.focus()` on a disconnected node — a no-op — and Modal's own fallback
+    // then puts the focus on the first focusable in the panel, the header's ✕. That is what the
+    // command palette, the download rename dialog and every non-danger confirm shipped with after
+    // deep-review round 4 (found in round 5).
+    render(
+      <Modal title="Search" onClose={() => {}}>
+        <input aria-label="query" autoFocus />
+      </Modal>,
+    );
+    expect(document.activeElement).toBe(screen.getByLabelText("query"));
+  });
+
+  it("still has it after a fullscreen transition moves the host", async () => {
+    const stage = document.createElement("div");
+    document.body.appendChild(stage);
+    render(
+      <Modal title="Search" onClose={() => {}}>
+        <input aria-label="query" autoFocus />
+      </Modal>,
+    );
+    const field = screen.getByLabelText("query");
+    expect(document.activeElement).toBe(field);
+
+    await setFullscreen(stage); // the player goes fullscreen under the open dialog
+
+    expect(stage.contains(field)).toBe(true);
+    expect(document.activeElement).toBe(field);
+    stage.remove();
+  });
+});
diff --git a/frontend/src/components/ui/Modal.tsx b/frontend/src/components/ui/Modal.tsx
index 4cdc113a..cdb062ab 100644
--- a/frontend/src/components/ui/Modal.tsx
+++ b/frontend/src/components/ui/Modal.tsx
@@ -1,21 +1,14 @@
-import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { useEffect, useId, useRef, type ReactNode } from "react";
 import { createPortal } from "react-dom";
 import { useTranslation } from "react-i18next";
 import { X } from "lucide-react";
 import { useBackToClose } from "../../lib/history";
 import { pushLayer, removeLayer, isTopmost } from "../../lib/layerStack";
-import { useFullscreenElement } from "../../lib/fullscreen";
+import { useFullscreenPortalHost } from "../../lib/fullscreen";
+import { trapTab, useDialogChrome } from "./dialogFocus";
 import { Button } from "./Button";
 import Toaster, { useOverlayOrder } from "./Toaster";
 
-// Tabbable elements inside the dialog, in DOM order. `:not([tabindex="-1"])` drops programmatically
-// focusable-only nodes; the visibility filter (offsetParent) drops display:none ones (e.g. a
-// collapsed disclosure) so the trap never lands focus on something the user can't see.
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-const focusablesIn = (root: HTMLElement): HTMLElement[] =>
-  [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((el) => el.offsetParent !== null);
-
 // Small centered modal shell: backdrop + ESC + scroll-lock close. Each open modal is a layer in the
 // shared `layerStack` so ESC only closes the topmost one — e.g. an error dialog over the tag editor
 // dismisses just the error and returns to the editor underneath, and a player below defers to it
@@ -44,31 +37,13 @@ export default function Modal({
   const { t } = useTranslation();
   // Browser/mouse Back closes the topmost modal instead of navigating away.
   useBackToClose(onClose);
-  const fsRoot = useFullscreenElement();
-  // ONE container element for the dialog's whole life, MOVED between <body> and the fullscreen
-  // element rather than handed to `createPortal` as a changing container: React tears a portal down
-  // and builds it again when its container changes, and the dialog's contents went with it — a
-  // half-filled download form reset to its defaults, and focus fell to <body>, the moment the viewer
-  // left true fullscreen (deep-review round 4).
-  const [host] = useState(() => document.createElement("div"));
-  useLayoutEffect(() => {
-    const parent = fsRoot ?? document.body;
-    if (host.parentNode === parent) return;
-    // appendChild MOVES the node: the browser blurs whatever was focused inside it on the way out.
-    const focused = host.contains(document.activeElement)
-      ? (document.activeElement as HTMLElement)
-      : null;
-    parent.appendChild(host);
-    focused?.focus();
-  }, [fsRoot, host]);
-  useEffect(() => () => host.remove(), [host]);
+  // ONE container element for the dialog's whole life, re-parented between <body> and the fullscreen
+  // element (deep-review round 4) — and attached before the children commit, so an `autoFocus` child
+  // still gets the focus (round 5). Both rules live in the hook; `ui/AnchoredPopover` shares it.
+  const host = useFullscreenPortalHost();
   const panelRef = useRef<HTMLDivElement>(null);
   const titleId = useId();
-  // Capture the trigger to restore focus to, during THIS render — i.e. before commit runs the
-  // dialog's autoFocus (or our own initial-focus) and moves activeElement into the dialog. Reading
-  // it later (in the effect) would capture a now-inside element that unmounts on close, stranding
-  // focus on <body>. useState initializer runs exactly once, on first render.
-  const [restoreTo] = useState(() => document.activeElement as HTMLElement | null);
+  useDialogChrome(panelRef);
   const overlayOrder = useOverlayOrder();
 
   // Backdrop-click close must only fire when the press STARTED on the backdrop too. Otherwise a
@@ -96,50 +71,20 @@ export default function Modal({
         if (!panel) return;
         // The whole dialog, not just the panel: its toast host sits beside the panel (see ui/Toaster),
         // and a toast's Undo or dismiss must be reachable from the keyboard like everything else.
-        const scope = rootRef.current ?? panel;
-        const items = focusablesIn(scope);
-        const first = items[0];
-        const last = items[items.length - 1];
-        if (!first || !last) {
-          e.preventDefault();
-          return;
-        }
-        const active = document.activeElement;
-        if (!scope.contains(active) || active === panel) {
-          // Focus escaped the dialog, OR sits on the panel container itself (tabIndex=-1, reached by
-          // clicking dialog dead space) — Node.contains(self) is true, so `active === panel` must be
-          // checked explicitly or Shift+Tab from the panel would leak to the background. Pull it back.
-          e.preventDefault();
-          (e.shiftKey ? last : first).focus();
-        } else if (e.shiftKey && active === first) {
-          e.preventDefault();
-          last.focus();
-        } else if (!e.shiftKey && active === last) {
-          e.preventDefault();
-          first.focus();
-        }
+        trapTab(e, rootRef.current ?? panel, panel);
       }
     };
     window.addEventListener("keydown", onKey);
-    const prev = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    // Initial focus: unless an autoFocus child already placed it inside (e.g. a rename input), move
-    // focus to the first control so the dialog opens focused, not stranded on the background.
-    const panel = panelRef.current;
-    if (panel && !panel.contains(document.activeElement)) {
-      (focusablesIn(panel)[0] ?? panel).focus();
-    }
     return () => {
       window.removeEventListener("keydown", onKey);
       removeLayer(id);
-      document.body.style.overflow = prev;
-      // Restore focus to the trigger, if it's still in the document and focusable.
-      if (restoreTo && restoreTo.isConnected) restoreTo.focus();
     };
-  }, [restoreTo]);
+  }, []);
 
   const drawer = placement === "drawer";
   const top = placement === "top";
+  // Only on a server render, where the hook has no `document` to build a host from.
+  if (!host) return null;
   return createPortal(
     <div
       ref={rootRef}
diff --git a/frontend/src/components/ui/Toaster.dom.test.tsx b/frontend/src/components/ui/Toaster.dom.test.tsx
index 44a3a53e..149bd759 100644
--- a/frontend/src/components/ui/Toaster.dom.test.tsx
+++ b/frontend/src/components/ui/Toaster.dom.test.tsx
@@ -6,6 +6,7 @@
 // the player. An overlay mounts its own host, and exactly one host shows the toasts.
 import { describe, it, expect, vi, afterEach } from "vitest";
 import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
+import { useState } from "react";
 
 vi.mock("react-i18next", async (importOriginal) => {
   const actual = await importOriginal<typeof import("react-i18next")>();
@@ -89,6 +90,41 @@ describe("Toaster — handing the toasts to another host", () => {
     expect(region.getAttribute("aria-live")).toBe("polite"); // and polite for what comes next
   });
 
+  it("announces a toast RAISED in the same commit as the takeover, and still not the inherited ones", () => {
+    // A dialog that notifies and closes in ONE handler (UploadDialog: "added to the queue" + close)
+    // puts its toast into the very batch that hands the app host the top spot. Classifying it from
+    // the store live at the takeover render counted it among the inherited, so it went in with no
+    // role into a region that was still `aria-live="off"` — announced by neither path (round 5).
+    function Stage() {
+      const [open, setOpen] = useState(true);
+      return (
+        <>
+          <Toaster />
+          {open && (
+            <>
+              <Toaster overlay />
+              <button
+                onClick={() => {
+                  notify({ level: "success", message: "upload queued" });
+                  setOpen(false);
+                }}
+              >
+                upload
+              </button>
+            </>
+          )}
+        </>
+      );
+    }
+    render(<Stage />);
+    act(() => void notify({ level: "error", message: "old news" }));
+    fireEvent.click(screen.getByText("upload"));
+
+    const card = (text: string) => screen.getByText(text).closest(".toast-card")!;
+    expect(card("upload queued").getAttribute("role")).toBe("status");
+    expect(card("old news").getAttribute("role")).toBeNull();
+  });
+
   it("ranks hosts by when their OVERLAY opened, not by when the host mounted", async () => {
     // PlayerModal's host moves into the fullscreen stage and back: remounted, it used to jump over a
     // dialog opened above the player, and the toasts went back under that dialog's scrim.
diff --git a/frontend/src/components/ui/Toaster.tsx b/frontend/src/components/ui/Toaster.tsx
index 56d52e63..497d0608 100644
--- a/frontend/src/components/ui/Toaster.tsx
+++ b/frontend/src/components/ui/Toaster.tsx
@@ -41,6 +41,9 @@ const topHost = () => {
   return top?.id ?? null;
 };
 
+// What the host that is currently top last rendered, for the next host to inherit. See `inherited`.
+let lastTopIds: number[] = [];
+
 export default function Toaster({
   overlay = false,
   order,
@@ -69,10 +72,19 @@ export default function Toaster({
   // LATER task. Not in an effect: React flushes those in the same task as the render that inserted the
   // toasts, and a screen reader reads the region's state after the task — by which time it was polite
   // again, i.e. the arming did nothing.
-  const inherited = useMemo(
-    () => new Set(isTop ? getActiveToasts().map((n) => n.id) : []),
-    [isTop],
-  );
+  //
+  // "Inherited" is what the PREVIOUS top host last had on screen — not whatever is in the store at
+  // the takeover render. Reading the store live also silenced a toast RAISED in the same commit as
+  // the takeover: a dialog that notifies and closes in one handler (UploadDialog) put its success
+  // toast up in the very batch that handed the app host the top spot, so it was classified as
+  // inherited and announced by neither path (deep-review round 5). Written during render on purpose
+  // — the handover must be readable by the taking-over host in the SAME commit, and an effect
+  // cleanup runs one phase too late; only the host that IS top writes, so the value is the losing
+  // host's last screen either way.
+  const inherited = useMemo(() => new Set(isTop ? lastTopIds : []), [isTop]);
+  // AFTER the memo above has read the outgoing host's screen — this host's own first render as top
+  // would otherwise overwrite the handover with the toasts it is about to classify.
+  if (isTop) lastTopIds = toasts.map((n) => n.id);
   const [armed, setArmed] = useState(false);
   useEffect(() => {
     if (!isTop) {
@@ -110,7 +122,13 @@ export default function Toaster({
         return (
           <div
             key={toast.id}
-            role={urgent && !inherited.has(toast.id) ? "alert" : undefined}
+            // A toast this host did not inherit must be announced even in the unarmed window, where
+            // the region is still `off`: urgent ones assertively, the rest with their own polite
+            // `role="status"` (single-element, so its implied atomic re-read is just this toast).
+            // Once armed, the region itself does the announcing and the role comes back off.
+            role={
+              inherited.has(toast.id) ? undefined : urgent ? "alert" : armed ? undefined : "status"
+            }
             className="toast-card glass pointer-events-auto relative overflow-hidden rounded-xl px-3 py-3 flex items-start gap-3 animate-[popIn_0.16s_ease]"
           >
             <Icon className={`w-5 h-5 shrink-0 mt-0.5 ${color}`} />
diff --git a/frontend/src/components/ui/dialogFocus.ts b/frontend/src/components/ui/dialogFocus.ts
new file mode 100644
index 00000000..25626aa0
--- /dev/null
+++ b/frontend/src/components/ui/dialogFocus.ts
@@ -0,0 +1,72 @@
+import { useEffect, useState, type RefObject } from "react";
+
+// The focus half of the dialog contract, in ONE place. `ui/Modal` owns it for every dialog that goes
+// through the shell; the onboarding wizard renders its own shell (a bare `ui/Overlay`, because it is
+// not a titled dialog with a header row) and used to have NONE of this — no trap, no initial focus,
+// no restore — so a keyboard user tabbed straight out of the first-login wizard into the app behind
+// the scrim, where the focus ring is invisible (deep-review round 5). A second hand-written copy is
+// how two shells drift apart; this is the shared one.
+
+// Tabbable elements inside the dialog, in DOM order. `:not([tabindex="-1"])` drops programmatically
+// focusable-only nodes; the visibility filter (offsetParent) drops display:none ones (e.g. a
+// collapsed disclosure) so the trap never lands focus on something the user can't see.
+const FOCUSABLE =
+  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+const focusablesIn = (root: HTMLElement): HTMLElement[] =>
+  [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter((el) => el.offsetParent !== null);
+
+/** Keep Tab / Shift+Tab cycling inside `scope` instead of reaching the inert page behind the
+ *  backdrop. Call from a keydown handler that has already decided this dialog is the topmost layer —
+ *  a nested dialog must defer to its child. `container` is the scope's own tabIndex=-1 panel, if it
+ *  has one: focus can land there by clicking dialog dead space, and `Node.contains(self)` is true, so
+ *  without naming it a Shift+Tab from the panel would leak to the background. */
+export function trapTab(
+  e: KeyboardEvent,
+  scope: HTMLElement,
+  container?: HTMLElement | null,
+): void {
+  const items = focusablesIn(scope);
+  const first = items[0];
+  const last = items[items.length - 1];
+  if (!first || !last) {
+    e.preventDefault();
+    return;
+  }
+  const active = document.activeElement;
+  if (!scope.contains(active) || (container != null && active === container)) {
+    e.preventDefault();
+    (e.shiftKey ? last : first).focus();
+  } else if (e.shiftKey && active === first) {
+    e.preventDefault();
+    last.focus();
+  } else if (!e.shiftKey && active === last) {
+    e.preventDefault();
+    first.focus();
+  }
+}
+
+/** The rest of the contract: lock the page behind, open focused, hand the focus back on close.
+ *  `scopeRef` is the panel the focus should land in. */
+export function useDialogChrome(scopeRef: RefObject<HTMLElement | null>): void {
+  // Capture the trigger to restore focus to, during THIS render — i.e. before commit runs the
+  // dialog's autoFocus (or our own initial focus) and moves activeElement into the dialog. Reading it
+  // later (in the effect) would capture a now-inside element that unmounts on close, stranding focus
+  // on <body>. useState initializer runs exactly once, on first render.
+  const [restoreTo] = useState(() => document.activeElement as HTMLElement | null);
+  useEffect(() => {
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    // Initial focus: unless an autoFocus child already placed it inside (e.g. a rename input), move
+    // focus to the first control so the dialog opens focused, not stranded on the background.
+    const scope = scopeRef.current;
+    if (scope && !scope.contains(document.activeElement)) {
+      (focusablesIn(scope)[0] ?? scope).focus();
+    }
+    return () => {
+      document.body.style.overflow = prev;
+      // Restore focus to the trigger, if it's still in the document and focusable.
+      if (restoreTo && restoreTo.isConnected) restoreTo.focus();
+    };
+  }, [restoreTo, scopeRef]);
+}
diff --git a/frontend/src/lib/fullscreen.ts b/frontend/src/lib/fullscreen.ts
index 7b907665..054ddb6b 100644
--- a/frontend/src/lib/fullscreen.ts
+++ b/frontend/src/lib/fullscreen.ts
@@ -1,4 +1,10 @@
-import { useSyncExternalStore } from "react";
+import {
+  useEffect,
+  useInsertionEffect,
+  useLayoutEffect,
+  useState,
+  useSyncExternalStore,
+} from "react";
 
 // The browser's Fullscreen API, WebKit included.
 //
@@ -56,9 +62,48 @@ const fsSnapshot = () => fullscreenElement() as HTMLElement | null;
 const fsServerSnapshot = () => null;
 
 /** The fullscreen element as reactive state, for code that must RENDER differently while something
- *  holds the lock — chiefly the popover platform, which has to portal INTO that element (a node
- *  portaled to <body> is painted underneath the fullscreen element, i.e. invisible). Components that
- *  merely react to the transition should keep using `onFullscreenChange` directly. */
-export function useFullscreenElement(): HTMLElement | null {
+ *  holds the lock — today only `useFullscreenPortalHost` below, which has to portal INTO that element
+ *  (a node portaled to <body> is painted underneath the fullscreen element, i.e. invisible).
+ *  Components that merely react to the transition should keep using `onFullscreenChange` directly. */
+function useFullscreenElement(): HTMLElement | null {
   return useSyncExternalStore(onFullscreenChange, fsSnapshot, fsServerSnapshot);
 }
+
+/** ONE container div for an overlay's whole life, re-parented between `<body>` and the fullscreen
+ *  element instead of handed to `createPortal` as a changing container: React tears a portal down
+ *  and builds it again when its container changes, and the overlay's contents go with it (a
+ *  half-filled form reset to its defaults the moment the viewer left true fullscreen).
+ *
+ *  Two rules this owns, which the two hand-written copies it replaced disagreed about (deep-review
+ *  round 5):
+ *
+ *  1. **It is attached BEFORE the portal's children commit.** `useInsertionEffect` runs in the
+ *     mutation phase, and React handles `autoFocus` in `commitMount` during the LAYOUT phase — one
+ *     whole phase later. Attaching in a `useLayoutEffect` is too late: layout effects commit
+ *     children-before-parent, so every `autoFocus` descendant called `.focus()` on a node that was
+ *     still disconnected, where `focus()` is a no-op. Every autoFocus in every dialog was dead.
+ *  2. **`appendChild` MOVES the node, it does not teleport it.** Per the DOM spec an already-parented
+ *     node is removed and re-inserted, and removing a focused element's ancestor resets focus to
+ *     `<body>` — so the focused element is saved and re-focused across the move.
+ */
+export function useFullscreenPortalHost(): HTMLElement | null {
+  const fsRoot = useFullscreenElement();
+  const [host] = useState<HTMLElement | null>(() =>
+    typeof document === "undefined" ? null : document.createElement("div"),
+  );
+  useInsertionEffect(() => {
+    if (host && !host.parentNode) document.body.appendChild(host);
+  }, [host]);
+  useLayoutEffect(() => {
+    if (!host) return;
+    const parent = fsRoot ?? document.body;
+    if (host.parentNode === parent) return;
+    const focused = host.contains(document.activeElement)
+      ? (document.activeElement as HTMLElement)
+      : null;
+    parent.appendChild(host);
+    focused?.focus();
+  }, [fsRoot, host]);
+  useEffect(() => () => host?.remove(), [host]);
+  return host;
+}

From 8a83bc0e9f3d9f4c696462f27206f1d95a4c1084 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 03:47:42 +0200
Subject: [PATCH 36/52] fix(plex): a finished item is finished when the server
 says so, and a lost session is reclaimed a bounded number of times
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 5, over round 4's own fixes.

- Round 4 added a `finish` latch so a played-through item records no checkpoint at the credits.
  On a NATURAL play-through it was raised a beat too late: per the HTML spec the browser sets
  `paused` and fires 'pause' BEFORE 'ended', so the pause checkpoint went out while the latch was
  still down and raced the watched mark — both requests read "not watched yet" from their own
  snapshot, so Plex counted one watch twice, and where Plex's reported duration runs more than the
  finish margin past the real media the checkpoint wrote a resume position AFTER the scrobble. The
  pause that ends the media no longer flushes. The regression test that was meant to cover this
  modelled the end as a bare 'ended' event — a browser that does not exist — and is now the real
  order.

- The watched mark was fired and forgotten (`.catch(() => {})`) while the latch patched the cached
  detail to watched / position 0 regardless, and round 4's once-per-id start guard meant the
  corrected detail arriving later was never used: an episode whose mark failed reopened at 0:00
  with a Watched badge the server disagreed with. `finish` now takes the in-flight write and takes
  itself back if the server refuses it — the real position is reported, the lying cache entry is
  dropped, and the failure is said out loud instead of swallowed. Both callers (the natural end
  and the credits auto-skip) hand it over.

- The reclaim of a 404'd HLS session had no bound. `parsed` cannot provide one — it belongs to one
  hls instance and every restart builds a fresh one — and the server answers 404 both for "the
  session is gone" and for "that segment is not there yet", so a transcode falling behind realtime,
  or two viewers of one item taking turns, respawned ffmpeg forever behind a spinner that never
  became an error. Two consecutive reclaims, reset by the first fragment that actually loads, then
  the honest failure.

Five regression tests, each mutation-checked red on the assertion it is named after.
---
 .../components/PlexPlayer.hls.dom.test.tsx    | 42 ++++++++++++
 .../PlexPlayer.session.dom.test.tsx           | 67 ++++++++++++++++++-
 frontend/src/components/PlexPlayer.tsx        | 50 +++++++++++---
 frontend/src/lib/plexPlayerHooks.ts           | 55 ++++++++++++---
 4 files changed, 194 insertions(+), 20 deletions(-)

diff --git a/frontend/src/components/PlexPlayer.hls.dom.test.tsx b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
index 795a8869..abc0dae7 100644
--- a/frontend/src/components/PlexPlayer.hls.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
@@ -153,6 +153,48 @@ describe("an HLS session the server no longer has", () => {
     expect(screen.queryByText("plex.player.errGeneric")).toBeNull();
   });
 
+  it("gives up and says so when the reclaimed session keeps 404ing", async () => {
+    // `parsed` cannot bound this: it lives on ONE hls instance and every restart builds a fresh one,
+    // so a session that parses its manifest and then 404s re-arms the guard every cycle. The server
+    // also answers 404 for "that segment is not there YET" (a transcode falling behind realtime),
+    // which is indistinguishable on the wire — so the player respawned ffmpeg forever behind a
+    // spinner that never became an error (round 5).
+    const session = mount();
+    const v = () => document.querySelector("video") as Media;
+    // The first session plus the two it is allowed to reclaim; the third 404 has nothing left.
+    for (let i = 0; i < 3; i++) {
+      await waitFor(() => expect(hlsInstances).toHaveLength(i + 1));
+      act(() => hlsInstances[i]!.emit(Hls.Events.MANIFEST_PARSED));
+      v()._t = 700;
+      act(() => void v().dispatchEvent(new Event("timeupdate")));
+      act(() => hlsInstances[i]!.emit(Hls.Events.ERROR, lost404));
+    }
+    await screen.findByText("plex.player.errGeneric");
+    // Two reclaims, then the honest answer — not a fourth, fifth, hundredth session.
+    expect(session).toHaveBeenCalledTimes(3);
+  });
+
+  it("starts the budget over once a fragment actually loads", async () => {
+    // A session lost once an hour is not a session that cannot be served; the only proof a reclaim
+    // worked is a fragment arriving.
+    const session = mount();
+    for (let i = 0; i < 4; i++) {
+      await waitFor(() => expect(hlsInstances).toHaveLength(i + 1));
+      act(() => hlsInstances[i]!.emit(Hls.Events.MANIFEST_PARSED));
+      const v = document.querySelector("video") as Media;
+      v._t = 700;
+      act(() => void v.dispatchEvent(new Event("timeupdate")));
+      act(() =>
+        hlsInstances[i]!.emit(Hls.Events.FRAG_LOADED, {
+          frag: { type: "main", duration: 6, stats: { total: 1000 } },
+        }),
+      );
+      act(() => hlsInstances[i]!.emit(Hls.Events.ERROR, lost404));
+    }
+    expect(screen.queryByText("plex.player.errGeneric")).toBeNull();
+    expect(session).toHaveBeenCalledTimes(5);
+  });
+
   it("is a failure, not a restart, when the session never played", async () => {
     // Otherwise a session that 404s from the start would restart itself in a loop.
     const session = mount();
diff --git a/frontend/src/components/PlexPlayer.session.dom.test.tsx b/frontend/src/components/PlexPlayer.session.dom.test.tsx
index b33b0e86..fd37d9c8 100644
--- a/frontend/src/components/PlexPlayer.session.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.session.dom.test.tsx
@@ -296,6 +296,17 @@ describe("leaving an item that was played through", () => {
   const prefs = (p: object) =>
     localStorage.setItem("siftlode.plexPlayerPrefs.7", JSON.stringify({ subLang: "en", ...p }));
 
+  // The end of the media, in the order the HTML spec mandates: the browser sets `paused`, fires
+  // 'pause', and only THEN fires 'ended'. Dispatching a bare 'ended' models a browser that does not
+  // exist, and hid the fact that the pause checkpoint goes out before the finish latch is up
+  // (deep-review round 5).
+  const endMedia = () => {
+    const el = video();
+    Object.defineProperty(el, "ended", { configurable: true, get: () => true });
+    act(() => void el.dispatchEvent(new Event("pause")));
+    act(() => void el.dispatchEvent(new Event("ended")));
+  };
+
   it("settles it as watched when it ended, so Prev does not reopen it at its last seconds", async () => {
     prefs({ upNext: false });
     const { qc, progress } = mount({
@@ -305,7 +316,7 @@ describe("leaving an item that was played through", () => {
     });
     vi.spyOn(api, "plexSetState").mockResolvedValue(undefined as never);
     await playingAt("/media/A", 2995);
-    act(() => void video().dispatchEvent(new Event("ended")));
+    endMedia();
     await screen.findByText("Title B");
     await tick();
     const cached = qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"));
@@ -344,6 +355,60 @@ describe("leaving an item that was played through", () => {
     const cached = qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"));
     expect([cached?.status, cached?.position_seconds]).toEqual(["watched", 0]);
   });
+  it("takes the finish back when the server refuses the watched mark", async () => {
+    // The mark was fired and forgotten (`.catch(() => {})`) while the cache was patched to
+    // watched / position 0 regardless, and the once-per-id start guard meant the corrected detail
+    // arriving later was never used: the episode reopened at 0:00 with a Watched badge the server
+    // disagreed with (round 5).
+    prefs({ upNext: false });
+    const { qc, progress } = mount({
+      details: { A: item("A"), B: item("B") },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    vi.spyOn(api, "plexSetState").mockRejectedValue(new Error("offline"));
+    await playingAt("/media/A", 2995);
+    endMedia();
+    await screen.findByText("Title B");
+    await tick();
+    // The position the viewer actually reached is reported, not suppressed by a finish that the
+    // server never confirmed…
+    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([
+      ["A", 2995, 3000, true],
+    ]);
+    // …and the cached detail is not left claiming watched: only the server is honest now.
+    const cached = qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"));
+    expect(cached?.status).not.toBe("watched");
+  });
+
+  it("records a second viewing when the viewer plays on from the finished frame", async () => {
+    // `finished` is a latch that makes every checkpoint a no-op; the only thing that lowers it is
+    // the video's own 'play' event. Nothing tested that, so dropping the listener would have
+    // discarded a whole rewatch with the gate green (round 5).
+    prefs({ upNext: true });
+    const { progress } = mount({
+      details: { A: item("A"), B: item("B") },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    vi.spyOn(api, "plexSetState").mockResolvedValue(undefined as never);
+    await playingAt("/media/A", 2995);
+    endMedia(); // the up-next card is up; the item is finished
+    await tick();
+    progress.mockClear();
+
+    // The viewer cancels the card and rewinds: playing again takes the finish back.
+    const el = video() as Media;
+    Object.defineProperty(el, "ended", { configurable: true, get: () => false });
+    act(() => void el.dispatchEvent(new Event("play")));
+    el._t = 2400;
+    act(() => void el.dispatchEvent(new Event("timeupdate")));
+    act(() => void el.dispatchEvent(new Event("pause")));
+    await tick();
+    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([
+      ["A", 2400, 3000, true],
+    ]);
+  });
 });
 
 describe("restarting the session before playback has ticked", () => {
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index a35b9023..6e815cc8 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -27,6 +27,7 @@ import {
   VolumeX,
 } from "lucide-react";
 import { api, HttpError } from "../lib/api";
+import { notifyActionError } from "../lib/actionErrors";
 import {
   audioOrdForLang,
   clamp01,
@@ -74,6 +75,11 @@ import { pushLayer, removeLayer, anyLayerAbove, escapeHandled } from "../lib/lay
 // The rich info overlay (poster/cast/ratings) reuses the same component as the card's info page.
 const PlexInfo = lazy(() => import("./PlexInfo"));
 
+// Consecutive reclaims of a 404'd HLS session before the player stops and says so. Two covers the
+// real case (the session was reaped, once) without letting a server that cannot serve the stream
+// keep the viewer on a spinner (see the ERROR handler).
+const MAX_SESSION_RECLAIMS = 2;
+
 // The Plex module's rich, full-page player. Plays the LOCAL file: direct-playable files stream raw
 // (native <video>), remux files stream via the seek-restart HLS session (hls.js). The visible
 // timeline is ABSOLUTE (0…duration); the HLS session is relative to its start offset, so we map
@@ -154,6 +160,9 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   // Where the current session was ASKED to start — set before the request goes out, so the subtitle
   // poll has a position before `sessionK` (the session's answer) and before the first timeupdate.
   const loadStartRef = useRef(0);
+  // How many times in a row this player may reclaim a session the server answered 404 for, before it
+  // stops and says playback failed. Reset by the first fragment that loads (see FRAG_LOADED).
+  const restartsRef = useRef({ n: 0 });
   const [seekableEnd, setSeekableEnd] = useState(0); // absolute end of the loaded region
   const { fs, toggleFs } = useFullscreen(wrapRef);
   const [ready, setReady] = useState(false);
@@ -367,6 +376,9 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         // rolling window starts empty rather than carrying the previous session's numbers over.
         fragMeterRef.current.reset();
         hls.on(Hls.Events.FRAG_LOADED, (_e, data) => {
+          // A fragment actually arriving is the only proof a reclaimed session works; the budget is
+          // for a session that keeps being lost, not for one that was lost once an hour.
+          restartsRef.current.n = 0;
           fragMeterRef.current.add({
             type: data.frag.type,
             bytes: data.frag.stats?.total || data.frag.stats?.loaded || 0,
@@ -406,11 +418,22 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         // its idle limit, a deploy) and the stream is simply gone, not broken. hls.js never retries a
         // 4xx, so this used to end playback with "couldn't play" after the buffer ran out; a new
         // session at the playhead is what closing and reopening the player did by hand.
+        //
+        // Bounded, because `parsed` cannot bound it: it belongs to ONE hls instance and every restart
+        // builds a fresh one, so it only ever blocks a session that died before its manifest. The
+        // server also answers 404 for "that segment is not there YET" — indistinguishable from "the
+        // session is gone" on the wire — so a transcode that falls behind realtime, or two viewers of
+        // one item taking turns reclaiming its session, restarted ffmpeg forever behind a spinner
+        // that never became an error (deep-review round 5). A couple of reclaims is what a genuine
+        // reap needs; past that the honest answer is that playback failed.
         hls.on(Hls.Events.ERROR, (_e, data) => {
           if (!data.fatal || !current()) return;
           if (parsed && data.type === Hls.ErrorTypes.NETWORK_ERROR && data.response?.code === 404) {
-            loadSession(playhead(absRef, loadStartRef), !video.paused);
-            return;
+            if (restartsRef.current.n < MAX_SESSION_RECLAIMS) {
+              restartsRef.current.n += 1;
+              loadSession(playhead(absRef, loadStartRef), !video.paused);
+              return;
+            }
           }
           setLoadError(tRef.current("plex.player.errGeneric"));
         });
@@ -657,13 +680,19 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     helpOpenRef,
   });
 
+  const reportWatchedError = useCallback(
+    (e: unknown) => notifyActionError(e, tRef.current("plex.watchedFailed")),
+    [],
+  );
+
   const go = useCallback(
-    (otherId: string | null | undefined, finished = false) => {
+    (otherId: string | null | undefined, watchedWrite?: Promise<unknown>) => {
       if (otherId) {
         // A played-through item settles as watched, with no checkpoint at the credits (see
         // usePlexProgress's `finish`) — said BEFORE the pause below, whose own checkpoint on the
-        // 'pause' event can land before the player has re-rendered for the next item.
-        if (finished) finishProgress();
+        // 'pause' event can land before the player has re-rendered for the next item. The write is
+        // handed over so a REFUSED one takes the finish back instead of leaving the cache lying.
+        if (watchedWrite) finishProgress(watchedWrite);
         // Stop the outgoing media BEFORE switching. If the next item fails to load (e.g. no local
         // file), loadSession returns without replacing the <video> source, leaving the old episode
         // still playing — it would then fire 'ended' against the NEW id and mark the wrong item
@@ -707,6 +736,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     go,
     seekTo,
     videoRef,
+    reportWatchedError,
   });
 
   // Download the ORIGINAL physical file (no re-encode/repackage). One user gesture, direct link.
@@ -737,9 +767,11 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
       // Only a genuine play-to-the-end counts. A next episode that failed to load never played
       // (absRef 0) — its stray 'ended' must not mark anything watched or cascade another advance.
       if (absRef.current <= 0) return;
-      api.plexSetState(id, "watched").catch(() => {});
-      // Whatever follows (the up-next card, the next item, closing) leaves a FINISHED item.
-      finishProgress();
+      const watchedWrite = api.plexSetState(id, "watched");
+      watchedWrite.catch(reportWatchedError);
+      // Whatever follows (the up-next card, the next item, closing) leaves a FINISHED item — unless
+      // the server refuses the mark, in which case `finish` takes itself back (see usePlexProgress).
+      finishProgress(watchedWrite);
       // With a next item and the up-next pref on, surface the end-card (poster + countdown + Cancel)
       // and let IT advance — binge stays in the viewer's control (S4/D6-A). The card only appears here,
       // on play-to-the-end; credits-auto-skip advances earlier and this handler never fires for it.
@@ -751,7 +783,7 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
     };
     video.addEventListener("ended", onEnded);
     return () => video.removeEventListener("ended", onEnded);
-  }, [id, nextId, go, onClose, finishProgress]);
+  }, [id, nextId, go, onClose, finishProgress, reportWatchedError]);
 
   // Up-next card actions: advance = go to the next item (it was already marked watched on 'ended');
   // cancel = dismiss and stay on the finished frame. Loading a new item closes any lingering card.
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index 0a20383a..bca36f2d 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -98,10 +98,10 @@ export function usePlexProgress(opts: {
   videoRef: RefObject<HTMLVideoElement | null>;
   absRef: MutableRefObject<number>;
   durationRef: MutableRefObject<number>;
-}): { settle: () => void; finish: () => void } {
+}): { settle: () => void; finish: (confirmed?: Promise<unknown>) => void } {
   const { id, qc, videoRef, absRef, durationRef } = opts;
   const settleRef = useRef<() => void>(() => {});
-  const finishRef = useRef<() => void>(() => {});
+  const finishRef = useRef<(confirmed?: Promise<unknown>) => void>(() => {});
   useEffect(() => {
     let finished = false;
     // `final` = a settled checkpoint (pause / page-hide / leaving the player) vs. the periodic tick.
@@ -116,7 +116,18 @@ export function usePlexProgress(opts: {
     };
     const iv = window.setInterval(flush, 10000);
     // Pausing is a settled position — push it to Plex now rather than waiting for unmount/unload.
-    const onPauseFlush = () => flush(true);
+    // Except the pause that ENDS the media: per the HTML spec the browser sets `paused` and fires
+    // `pause` BEFORE `ended`, so this ran while the finish latch was still down and sent a final
+    // checkpoint that raced the watched mark the 'ended' handler was about to send. Both requests
+    // then read "not watched yet" from their own snapshot and both scrobbled — Plex counted one
+    // watch twice — and where Plex's reported duration runs more than the finish margin past the
+    // real media, the checkpoint was not near-end either, so it wrote a resume position AFTER the
+    // scrobble. That race is what `finish` exists to prevent; on a natural play-through it was
+    // raised a beat too late (deep-review round 5).
+    const onPauseFlush = () => {
+      if (videoRef.current?.ended) return;
+      flush(true);
+    };
     const video = videoRef.current;
     video?.addEventListener("pause", onPauseFlush);
     // A seek is a settled position too (S2: Plex is the source of truth, so it must see the new spot
@@ -164,8 +175,23 @@ export function usePlexProgress(opts: {
       }
     };
     settleRef.current = settle;
-    finishRef.current = () => {
+    finishRef.current = (confirmed?: Promise<unknown>) => {
       finished = true;
+      // The latch has to go up BEFORE the media pauses, so it cannot wait for the server. If the
+      // watched write is then refused, the latch is taken back: the cached detail said watched /
+      // position 0 while the server still had the item unwatched at the last checkpoint, and the
+      // once-per-id start guard meant the corrected detail arriving later was never used — the
+      // episode reopened at 0:00 with a Watched badge the server disagreed with (round 5).
+      const pos = Math.floor(absRef.current);
+      const dur = durationRef.current;
+      void confirmed?.catch(() => {
+        finished = false;
+        if (pos > 0 && dur > 0) api.plexProgress(id, pos, dur, true).catch(() => {});
+        // `settle` may already have patched the detail to watched / 0 on the way out. Dropping that
+        // entry rather than invalidating it: an invalidated query with no observer keeps serving its
+        // stale data, and this one is a lie — no data is better, the next open fetches the truth.
+        qc.removeQueries({ queryKey: qk.plexItem(id, plexLang()) });
+      });
     };
     return () => {
       window.clearInterval(iv);
@@ -185,7 +211,7 @@ export function usePlexProgress(opts: {
   }, [id, qc, absRef, durationRef, videoRef]);
   return {
     settle: useCallback(() => settleRef.current(), []),
-    finish: useCallback(() => finishRef.current(), []),
+    finish: useCallback((confirmed?: Promise<unknown>) => finishRef.current(confirmed), []),
   };
 }
 
@@ -282,10 +308,13 @@ export function useAutoSkip(opts: {
   autoSkipCredits: boolean;
   autoSkipDelay: number;
   nextId: string | null | undefined;
-  /** `finished` = the item being left was played through (see usePlexProgress's `finish`). */
-  go: (id: string | null | undefined, finished?: boolean) => void;
+  /** `watchedWrite` = the in-flight watched mark for the item being left, which played through (see
+   *  usePlexProgress's `finish`); a refused one takes the finish back. */
+  go: (id: string | null | undefined, watchedWrite?: Promise<unknown>) => void;
   seekTo: (t: number) => void;
   videoRef: RefObject<HTMLVideoElement | null>;
+  /** Says a refused watched mark out loud; the translated string belongs to the component layer. */
+  reportWatchedError: (e: unknown) => void;
 }): {
   activeMarker: PlexMarker | undefined;
   skipProgress: number | null;
@@ -326,14 +355,20 @@ export function useAutoSkip(opts: {
   // The running countdown interval, so cancelAutoSkip can actually STOP it — clearing skipProgress
   // alone left the interval ticking, which re-set the progress ~100ms later and skipped anyway.
   const skipTimerRef = useRef<number | null>(null);
+  const reportWatchedErrorRef = useRef(opts.reportWatchedError);
+  reportWatchedErrorRef.current = opts.reportWatchedError;
   const doSkip = useCallback(
     (m: PlexMarker) => {
       setSkipProgress(null);
       if (m.type === "credits" && nextId) {
         // Binge auto-advance: the episode we're leaving was watched through the credits, so mark IT
-        // (the current id, captured here — not the reactive id, which go() is about to change).
-        api.plexSetState(id, "watched").catch(() => {});
-        go(nextId, true);
+        // (the current id, captured here — not the reactive id, which go() is about to change). The
+        // write is handed to go() so a refusal takes the finish back: this path has no near-end
+        // checkpoint to corroborate it, so one failed request used to leave the cache claiming
+        // watched / position 0 while the server still had the credits position (round 5).
+        const watchedWrite = api.plexSetState(id, "watched");
+        watchedWrite.catch(reportWatchedErrorRef.current);
+        go(nextId, watchedWrite);
       } else seekTo(m.end_s);
     },
     [id, go, nextId, seekTo],

From 47af4d5c054fed62e2c53613a3be7c10ddc65a2f Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 03:57:52 +0200
Subject: [PATCH 37/52] fix(plex): an HLS artifact names the session it belongs
 to, and a paused viewer says so
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 5, over round 4's own fixes.

- Sessions are keyed by rating_key alone while a session's DIRECTORY is per (key, offset, tag), and
  the artifact URL carried no session identity — so once a seek-restart or a second viewer of the
  same item took the registry slot, the old viewer's request for `seg_12.ts` was answered 200 with
  the new session's twelfth segment: bytes from a different `-ss` offset under `-copyts`, on a
  timeline the client is not on. Wrong content with a success status is the one failure a player
  cannot notice, and round 4's reclaim-on-404 could never fire on it. The id is in the path now (so
  the playlist's relative names resolve back into the same session), a mismatch is a 404, and the
  player reclaims at the playhead. The entry playlist's auto-start is gone with it: it could only
  ever begin at 0, silently discarding the viewer's position.

- Round 4 exempted paused viewers from the reaper by keeping EVERY finished session for the full
  ten-minute idle window — one whole segmented copy of a film per item, on the volume the download
  center shares. The signal it needed already existed: an open player checkpoints its position every
  10 s whether or not it is playing, so that route now touches the session and the periodic pass is
  back on the short rule.

- POST /session's opportunistic reap was never scoped to the key being started: it walked the whole
  registry with the 30 s finished rule, so pressing play on ANY item — even a direct-play one, the
  call ran before that early return — killed another viewer's paused session. It is gone; the
  periodic pass owns reaping.

- A segment that can never arrive no longer polls out the full 20 s: the producer's handle is passed
  to `wait_for`, so a finished ffmpeg answers at once. This is a sync route, so each such wait parked
  a threadpool worker AND a pooled DB connection, and an ordinary seek past the produced region was
  enough to do it.

- The DataError handler's re-raise branch — the half that keeps a genuine DataError a 500 — is
  pinned, so simplifying it to an unconditional 422 cannot pass in silence.

Six regression tests (two route-level, in the DB lane), each mutation-checked red on the assertion
it is named after. pytest 1124, vitest 999.
---
 backend/app/main.py                         |   7 +-
 backend/app/plex/stream.py                  |  40 ++++--
 backend/app/routes/plex/playback.py         |  47 ++++---
 backend/tests/test_hls_reaper.py            | 132 +++++++++++++++---
 backend/tests/test_not_found_detail.py      |  21 +++
 backend/tests/test_plex_hls_file_route.py   | 145 ++++++++++++++++++++
 backend/tests/test_plex_playback_session.py |   7 +-
 7 files changed, 348 insertions(+), 51 deletions(-)
 create mode 100644 backend/tests/test_plex_hls_file_route.py

diff --git a/backend/app/main.py b/backend/app/main.py
index ca70b442..792d9335 100644
--- a/backend/app/main.py
+++ b/backend/app/main.py
@@ -112,11 +112,14 @@ async def _reap_hls_sessions() -> None:
     ffmpeg still working through the film, its directory a whole segmented copy of it — lived until
     somebody pressed play again or the process restarted.
 
-    `reap_abandoned`, not `reap_idle`: a finished session is also a paused viewer's."""
+    A FINISHED session is reaped on the short rule here, not kept for the full idle window: an open
+    player checkpoints every 10 s and that route touches the session, so a paused viewer is no longer
+    invisible to this pass (see `reap_idle`). Keeping every finished session for ten minutes instead
+    held one whole segmented copy of a film per item on the download volume (round 5)."""
     while True:
         await asyncio.sleep(_HLS_REAP_EVERY_S)
         try:
-            await asyncio.to_thread(plex_stream.reap_abandoned)
+            await asyncio.to_thread(plex_stream.reap_idle)
         except Exception:
             log.exception("HLS session reap failed")
 
diff --git a/backend/app/plex/stream.py b/backend/app/plex/stream.py
index fdb012a7..224ff5a9 100644
--- a/backend/app/plex/stream.py
+++ b/backend/app/plex/stream.py
@@ -21,6 +21,7 @@ CPU-only prod host; only P3's full transcode is CPU-heavy.
 import logging
 import os
 import re
+import secrets
 import shutil
 import subprocess
 import threading
@@ -99,6 +100,14 @@ class HlsSession:
         hw: bool = False,
         tonemap: bool = False,
     ):
+        # Unguessable per-session id, carried in the URLs the client is handed. Sessions are keyed
+        # by rating_key alone, so a seek-restart or a SECOND viewer of the same item replaces the
+        # registered one — and the old viewer's next request for `seg_12.ts`, resolved by rating_key,
+        # was answered 200 with the NEW session's twelfth segment, produced from a different offset
+        # under `-copyts`. Wrong bytes, not an error, so the client's reclaim never fired on it
+        # (deep-review round 5). A request naming a session that is no longer registered is a 404,
+        # which the player recovers from by restarting at the playhead.
+        self.id = secrets.token_urlsafe(9)
         self.key = key
         self.dir = directory
         self.proc = proc
@@ -826,16 +835,19 @@ _FINISHED_IDLE_S = 30
 
 
 def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
-    """Kill sessions nobody has fetched from for `_SESSION_IDLE_S` — or, once their ffmpeg has
-    finished, for `finished_idle_s`.
+    """Kill sessions nobody has said they still want for `_SESSION_IDLE_S` — or, once their ffmpeg
+    has finished, for `finished_idle_s`.
 
-    The short rule is only safe where a NEW session is being requested (the default, POST /session):
-    a finished session is also what a PAUSED viewer has. A remux runs far faster than realtime, so
+    A finished session is also what a PAUSED viewer has: a remux runs far faster than realtime, so
     ffmpeg is done a minute or two in and writes ENDLIST; hls.js then stops asking for the playlist,
-    and with its forward buffer full a paused player fetches nothing at all. The periodic reaper
-    therefore uses `reap_abandoned` — with the 30 s rule, a one-minute pause killed the session and
-    playback died ~30 s after resuming (deep-review round 4). A viewer paused for longer than
-    `_SESSION_IDLE_S` still loses it; the player restarts one at the playhead when a fetch 404s."""
+    and with its forward buffer full a paused player fetches nothing at all. With the 30 s rule that
+    killed a one-minute pause, and playback died ~30 s after resuming (deep-review round 4).
+
+    What makes the short rule safe again is that fetching is no longer the only signal: an open
+    player checkpoints its position every 10 s, and that route calls `touch_session`, so a viewer who
+    is merely paused says so far more often than this rule asks (round 5). Round 4's blanket
+    `reap_abandoned` bought the same safety by keeping every finished session for ten minutes — each
+    one a whole segmented copy of the film on a volume shared with the download center."""
     now = time.time()
     dropped = 0
     with _lock:
@@ -849,7 +861,11 @@ def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
     return dropped
 
 
-def reap_abandoned() -> int:
-    """The periodic reaper's pass: only what nobody has fetched from for `_SESSION_IDLE_S`, finished
-    or not (see reap_idle for why a finished session is not yet an abandoned one)."""
-    return reap_idle(finished_idle_s=_SESSION_IDLE_S)
+def touch_session(key: str) -> None:
+    """Say a viewer is still there for `key`, without fetching anything. `last_access` used to move
+    only on an HLS file fetch, which a paused player does not do — so the only way to keep a paused
+    viewer's session alive was to keep EVERY abandoned one just as long."""
+    with _lock:
+        s = _sessions.get(key)
+        if s is not None:
+            s.last_access = time.time()
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 3420b1d0..769bf8bd 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -323,6 +323,10 @@ def item_progress(
     `_should_push_resume`). `final` (sent on pause / seek / pagehide / unmount) pushes immediately and
     resets the throttle window, so Plex sees a settled position the instant the user pauses or seeks."""
     it = item_or_404(db, rating_key)
+    # An open player checkpoints every 10 s whether or not it is playing, so this is the signal that a
+    # PAUSED viewer still wants their HLS session — the one thing `last_access` could not see, since
+    # it moved only on a file fetch and a paused player fetches nothing (see stream.reap_idle).
+    plex_stream.touch_session(str(rating_key))
     position = max(0, int(body.position_seconds))
     duration = int(body.duration_seconds)
     final = body.final
@@ -561,7 +565,6 @@ def stream_session(
     HEVC/VP9/AV1/…) take the same HLS path but with the video re-encoded to H.264 (VAAPI or libx264).
     Selecting a non-default audio track (`audio` = stream ordinal) forces the HLS path so the chosen audio
     can be muxed in. Subtitles are independent WebVTT tracks (GET /subtitle) — no session restart."""
-    plex_stream.reap_idle()  # opportunistic cleanup of idle sessions on each new playback
     it = item_or_404(db, rating_key)
     transcode = it.playable == "transcode"
     # `multi` (item has ≥2 audio tracks) forces the HLS path so ALL audio tracks ship as renditions and
@@ -585,7 +588,9 @@ def stream_session(
     return {
         "mode": "hls",
         "start_s": s.media_start_s,
-        "url": f"/api/plex/stream/{it.rating_key}/hls/{s.entry}",
+        # The session id is part of the path (not a query param) so the playlist's RELATIVE segment
+        # names resolve back into the same session — see `stream_hls_file` for why it has to.
+        "url": f"/api/plex/stream/{it.rating_key}/hls/{s.id}/{s.entry}",
         "transcode": s.transcode,
         "hw": s.hw,
         "tonemap": s.tonemap,
@@ -624,35 +629,39 @@ _HLS_CT = {
 }
 
 
-@router.get("/stream/{rating_key}/hls/{filename}")
+@router.get("/stream/{rating_key}/hls/{session_id}/{filename}")
 def stream_hls_file(
     rating_key: str,
+    session_id: str,
     filename: str,
     user: User = Depends(current_user),
-    db: Session = Depends(get_db),
 ) -> Response:
-    """Serve a file (playlist / segment / subtitle) from the current HLS session directory. The
-    playlist references its segments/subtitles by relative name, all resolving back here."""
+    """Serve a file (playlist / segment / subtitle) from ONE HLS session's directory. The playlist
+    references its segments/subtitles by relative name, all resolving back here.
+
+    The session id in the path is what makes "back here" mean the same session. Sessions are keyed by
+    rating_key alone and a seek-restart or a second viewer of the same item replaces the registered
+    one, while the DIRECTORY is per (key, offset, tag) — so resolving by rating_key handed the old
+    viewer the new session's `seg_12.ts`, produced from a different offset under `-copyts`: wrong
+    bytes with a 200, which the player has no way to notice (deep-review round 5). A request for a
+    session that is no longer the registered one is a 404, and the player reclaims at the playhead.
+
+    That reclaim is also why a request with no live session is no longer auto-started here: the
+    auto-start could only ever begin at 0, silently throwing away the viewer's position."""
     # Filename must be a plain hls artifact — no path separators, only the expected extensions.
     ext = "." + filename.rsplit(".", 1)[-1] if "." in filename else ""
     if ext not in _HLS_CT or "/" in filename or "\\" in filename or ".." in filename:
         raise HTTPException(status_code=404, detail="Not found")
     s = plex_stream.current_session(str(rating_key))
-    if s is None:
-        # No session yet (e.g. reaped): the ENTRY playlist may auto-start one at 0 — master.m3u8 for a
-        # multi-audio item, index.m3u8 for a single-audio remux item.
-        it = item_or_404(db, rating_key)
-        if filename == "master.m3u8":
-            s = plex_stream.start_session(db, it, 0.0, multi=True)
-        elif filename == "index.m3u8" and it.playable == "remux":
-            s = plex_stream.start_session(db, it, 0.0)
-        else:
-            raise HTTPException(status_code=404, detail="No active playback session")
-        if s is None:
-            raise HTTPException(status_code=404, detail="Media file not found on disk")
+    if s is None or s.id != session_id:
+        raise HTTPException(status_code=404, detail="No active playback session")
     path = s.dir / filename
     timeout = 30 if ext == ".m3u8" else 20
-    if not plex_stream.wait_for(path, timeout):
+    # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
+    # whole timeout: this is a SYNC route on the ~40-slot threadpool, holding a pooled DB connection
+    # with it, so every such wait is a worker (and a connection) parked for 20 s — an ordinary seek
+    # past the produced region was enough to do it (round 5).
+    if not plex_stream.wait_for(path, timeout, proc=s.proc):
         raise HTTPException(status_code=404, detail="Not available yet")
     return Response(
         content=path.read_bytes(),
diff --git a/backend/tests/test_hls_reaper.py b/backend/tests/test_hls_reaper.py
index 0c8d22ea..667474cc 100644
--- a/backend/tests/test_hls_reaper.py
+++ b/backend/tests/test_hls_reaper.py
@@ -1,21 +1,35 @@
-"""Idle HLS sessions are reaped on a timer, not only when the next session is requested.
+"""Idle HLS sessions are reaped on a timer, and a viewer who is merely PAUSED keeps theirs.
 
 plex/stream.py promises "a periodic reaper kills idle ones", but `reap_idle` ran only inside
 POST /session: after the last playback, an abandoned session (its ffmpeg still working through the
-film, its directory a whole segmented copy of it) lived until somebody pressed play again.
+film, its directory a whole segmented copy of it) lived until somebody pressed play again
+(deep-review round 4).
 
 And it must not take a PAUSED viewer's session: a remux finishes long before the film does, and a
-paused player with a full buffer fetches nothing — so "finished and unfetched for 30 s" (the rule a
-new session request applies) is not "abandoned".
+paused player with a full buffer fetches nothing, so "finished and unfetched for 30 s" does not mean
+"abandoned". Round 4 bought that safety by keeping EVERY finished session for the full ten-minute
+idle window — one segmented copy of a film per item, on the volume the download center shares. Round
+5 replaced the blanket retention with the signal that already existed: an open player checkpoints its
+position every 10 s whether or not it is playing, and that route says "still here".
+
+Both call sites are pinned here, because the bug each time was that only one of them moved: the
+periodic pass, and the fact that starting a session no longer sweeps OTHER viewers' sessions at all.
 """
 
 import asyncio
 import time
+from types import SimpleNamespace
 
 import pytest
+from fastapi.testclient import TestClient
 
 import app.main as app_main
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
 from app.main import app
+from app.models import PlexItem, PlexLibrary, User
+from app.plex import paths as plex_paths
 from app.plex import stream
 
 
@@ -27,7 +41,7 @@ class _Configured:
         return False
 
 
-def test_idle_sessions_are_reaped_while_nobody_starts_a_new_one(monkeypatch):
+def test_the_periodic_pass_is_the_one_that_runs_and_it_uses_the_short_rule(monkeypatch):
     async def _no_sweep():
         return None
 
@@ -39,7 +53,9 @@ def test_idle_sessions_are_reaped_while_nobody_starts_a_new_one(monkeypatch):
     monkeypatch.setattr(app_main, "shutdown_scheduler", lambda: None)
     monkeypatch.setattr(app_main.plex_subtitles, "shutdown", lambda: None)
     monkeypatch.setattr(app_main, "_HLS_REAP_EVERY_S", 0.01)
-    monkeypatch.setattr(app_main.plex_stream, "reap_abandoned", lambda: reaped.append(1) or 0)
+    # `reap_idle`, i.e. the SHORT finished rule: a finished session nobody has said they still want
+    # is a whole copy of a film sitting on the download volume.
+    monkeypatch.setattr(app_main.plex_stream, "reap_idle", lambda: reaped.append(1) or 0)
 
     async def _cycle():
         async with app_main.lifespan(app):
@@ -79,12 +95,10 @@ def sessions(monkeypatch):
     return live
 
 
-def test_the_periodic_pass_keeps_a_paused_viewers_finished_session(tmp_path, sessions):
-    # A remux that finished a minute ago, its viewer paused with a full buffer since.
-    s = _Session(tmp_path, "paused", finished=True, idle_s=90)
-    sessions["12345"] = s
-    assert stream.reap_abandoned() == 0
-    assert "12345" in sessions and s.dir.exists() and not s.proc.killed
+def test_the_periodic_pass_reaps_a_finished_session_nobody_has_claimed(tmp_path, sessions):
+    sessions["12345"] = _Session(tmp_path, "done", finished=True, idle_s=45)
+    assert stream.reap_idle() == 1
+    assert sessions == {}
 
 
 def test_the_periodic_pass_still_reaps_what_nobody_has_touched_for_the_idle_limit(
@@ -96,11 +110,95 @@ def test_the_periodic_pass_still_reaps_what_nobody_has_touched_for_the_idle_limi
     sessions["2"] = _Session(
         tmp_path, "gone_live", finished=False, idle_s=stream._SESSION_IDLE_S + 5
     )
-    assert stream.reap_abandoned() == 2
+    assert stream.reap_idle() == 2
     assert sessions == {}
 
 
-def test_a_new_session_request_still_reaps_finished_sessions_quickly(tmp_path, sessions):
-    sessions["12345"] = _Session(tmp_path, "done", finished=True, idle_s=45)
-    assert stream.reap_idle() == 1
-    assert sessions == {}
+def test_touching_a_session_keeps_it_through_the_short_rule(tmp_path, sessions):
+    s = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    sessions["12345"] = s
+    stream.touch_session("12345")
+    assert stream.reap_idle() == 0
+    assert "12345" in sessions and s.dir.exists() and not s.proc.killed
+
+
+# --- the two call sites, driven through the real routes (DB lane) -------------------------------
+
+
+def _library_item(db, rating_key: str, *, playable: str = "remux"):
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    it = PlexItem(
+        rating_key=rating_key,
+        library_id=lib.id,
+        kind="movie",
+        title="A Movie",
+        file_path="/media/a.mkv",
+        playable=playable,
+    )
+    db.add(it)
+    db.commit()
+    return it
+
+
+def _client(db, user):
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: user
+    return TestClient(app)
+
+
+def test_a_paused_viewers_checkpoint_keeps_their_session_alive(db, monkeypatch, tmp_path, sessions):
+    """The whole reason the short rule is safe again: a paused player fetches nothing, so
+    `last_access` never moved on its own — but it does keep checkpointing its position."""
+    monkeypatch.setattr(state, "_configured_cache", True)
+    it = _library_item(db, "paused1")
+    user = User(email="paused@example.com")
+    db.add(user)
+    db.commit()
+    s = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    sessions["paused1"] = s
+    try:
+        resp = _client(db, user).post(
+            f"/api/plex/item/{it.rating_key}/progress",
+            json={"position_seconds": 600, "duration_seconds": 3000, "final": False},
+        )
+    finally:
+        app.dependency_overrides.clear()
+    assert resp.status_code == 200, resp.text
+    assert stream.reap_idle() == 0, "the checkpoint did not say the viewer is still there"
+    assert "paused1" in sessions and not s.proc.killed
+
+
+def test_starting_a_session_leaves_another_viewers_paused_one_alone(
+    db, monkeypatch, tmp_path, sessions
+):
+    """The opportunistic sweep this route used to run was not scoped to the key being started: it
+    walked the WHOLE registry with the 30 s finished rule, so pressing play on any item killed a
+    paused viewer's session — the very case round 4 set out to protect (found in round 5)."""
+    monkeypatch.setattr(state, "_configured_cache", True)
+    monkeypatch.setattr(plex_paths, "local_media_path", lambda db_, fp: "/local/a.mkv")
+    started = _library_item(db, "starting")
+    user = User(email="starter@example.com")
+    db.add(user)
+    db.commit()
+    paused = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    sessions["someone-else"] = paused
+
+    def fake_start(db_, item, start, audio=None, aoff=0.0, multi=False, transcode=False):
+        return SimpleNamespace(
+            id="sid",
+            media_start_s=start,
+            entry="index.m3u8",
+            transcode=transcode,
+            hw=False,
+            tonemap=False,
+        )
+
+    monkeypatch.setattr(stream, "start_session", fake_start)
+    try:
+        resp = _client(db, user).post(f"/api/plex/stream/{started.rating_key}/session")
+    finally:
+        app.dependency_overrides.clear()
+    assert resp.status_code == 200, resp.text
+    assert "someone-else" in sessions and not paused.proc.killed
diff --git a/backend/tests/test_not_found_detail.py b/backend/tests/test_not_found_detail.py
index b3616189..1510fff9 100644
--- a/backend/tests/test_not_found_detail.py
+++ b/backend/tests/test_not_found_detail.py
@@ -51,3 +51,24 @@ def test_a_nul_in_a_request_string_is_a_422_not_a_500(db, make_user, as_user):
     assert r.status_code == 422, r.text
     assert r.json()["detail"] == {"code": "invalid_input", "reason": "nul"}
     assert client.get("/api/plex/playlists?contains_group=1,%00").status_code == 422
+
+
+def test_any_other_data_error_is_still_a_500():
+    """The other half of the app-wide handler, and the half a refactor can delete in silence: it is
+    registered for EVERY DataError on every route and decides on a substring of the driver's message,
+    so only a NUL may become a 422. Without this, simplifying it to an unconditional 422 — it reads
+    like dead defensive code — would answer a numeric overflow or an over-long ingested title with
+    "your input was bad", losing the traceback that names the real fault (deep-review round 5)."""
+    import asyncio
+
+    import pytest
+    from sqlalchemy.exc import DataError
+
+    from app.main import _nul_in_text
+
+    overflow = DataError("SELECT 1", {}, Exception("numeric field overflow"))
+    with pytest.raises(DataError):
+        asyncio.run(_nul_in_text(None, overflow))  # re-raised: it stays the 500 it always was
+
+    nul = DataError("SELECT 1", {}, Exception("invalid byte sequence: NUL (0x00)"))
+    assert asyncio.run(_nul_in_text(None, nul)).status_code == 422
diff --git a/backend/tests/test_plex_hls_file_route.py b/backend/tests/test_plex_hls_file_route.py
new file mode 100644
index 00000000..8be286c7
--- /dev/null
+++ b/backend/tests/test_plex_hls_file_route.py
@@ -0,0 +1,145 @@
+"""An HLS artifact request names the session it belongs to, and gets nothing else.
+
+Sessions are keyed by rating_key ALONE, while a session's directory is per (key, offset, tag). So a
+seek-restart — or a second viewer of the same item — replaces the registered session, and the old
+viewer's next request for `seg_12.ts`, resolved by rating_key, was answered 200 with the NEW
+session's twelfth segment: bytes produced from a different `-ss` offset under `-copyts`, i.e. a
+timeline the client is not on. Wrong content with a success status is the one failure a player cannot
+notice, and the reclaim-on-404 added in round 4 could never fire on it (deep-review round 5).
+
+DB lane (`db` fixture) — skipped when no Postgres is reachable.
+"""
+
+import time
+
+import pytest
+from fastapi.testclient import TestClient
+
+import app.state as state
+from app.auth import current_user
+from app.db import get_db
+from app.main import app
+from app.models import PlexItem, PlexLibrary, User
+from app.plex import stream as plex_stream
+
+
+class _Proc:
+    def poll(self):
+        return 0  # finished: `wait_for` may not poll out its whole timeout on a missing file
+
+    def terminate(self):
+        pass
+
+    def wait(self, timeout=None):
+        return 0
+
+
+class _Session:
+    def __init__(self, session_id: str, directory):
+        self.id = session_id
+        self.dir = directory
+        self.proc = _Proc()
+        self.last_access = time.time()
+
+
+@pytest.fixture
+def sessions(monkeypatch):
+    live: dict = {}
+    monkeypatch.setattr(plex_stream, "_sessions", live)
+    return live
+
+
+def _client(db, monkeypatch):
+    monkeypatch.setattr(state, "_configured_cache", True)
+    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
+    db.add(lib)
+    db.flush()
+    db.add(
+        PlexItem(
+            rating_key="m1",
+            library_id=lib.id,
+            kind="movie",
+            title="A Movie",
+            file_path="/media/a.mkv",
+            playable="remux",
+        )
+    )
+    user = User(email="hls@example.com")
+    db.add(user)
+    db.commit()
+    app.dependency_overrides[get_db] = lambda: db
+    app.dependency_overrides[current_user] = lambda: user
+    return TestClient(app)
+
+
+def test_a_segment_is_served_from_the_session_the_url_names(db, monkeypatch, tmp_path, sessions):
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    (d / "seg_12.ts").write_bytes(b"mine")
+    sessions["m1"] = _Session("sid-a", d)
+    client = _client(db, monkeypatch)
+    try:
+        r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
+    finally:
+        app.dependency_overrides.clear()
+    assert r.status_code == 200, r.text
+    assert r.content == b"mine"
+
+
+def test_a_segment_of_a_replaced_session_is_a_404_not_the_new_sessions_bytes(
+    db, monkeypatch, tmp_path, sessions
+):
+    """Viewer A is at 0:00; viewer B seeks to 25:00 and their session takes the registry slot. A's
+    next segment must fail honestly — the player reclaims at the playhead — not arrive as B's."""
+    theirs = tmp_path / "m1_1500_0_+0.00"
+    theirs.mkdir()
+    (theirs / "seg_12.ts").write_bytes(b"theirs")
+    sessions["m1"] = _Session("sid-b", theirs)
+    client = _client(db, monkeypatch)
+    try:
+        r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
+    finally:
+        app.dependency_overrides.clear()
+    assert r.status_code == 404, r.text
+    assert b"theirs" not in r.content
+
+
+def test_a_playlist_with_no_live_session_is_a_404_not_a_silent_restart_at_zero(
+    db, monkeypatch, sessions
+):
+    """The entry playlist used to auto-start a session when none was registered — always at 0.0,
+    silently throwing away the viewer's position. A 404 sends the player through its own reclaim,
+    which restarts at the playhead."""
+    started: list[float] = []
+    monkeypatch.setattr(
+        plex_stream,
+        "start_session",
+        lambda *a, **k: started.append(a[2] if len(a) > 2 else 0.0),
+    )
+    client = _client(db, monkeypatch)
+    try:
+        r = client.get("/api/plex/stream/m1/hls/sid-gone/index.m3u8")
+    finally:
+        app.dependency_overrides.clear()
+    assert r.status_code == 404, r.text
+    assert started == []
+
+
+def test_a_segment_that_will_never_arrive_fails_at_once(db, monkeypatch, tmp_path, sessions):
+    """`stream_hls_file` is a SYNC route: it runs on the ~40-slot threadpool and holds a pooled DB
+    connection while it waits. Waiting without the producer's handle polled out the whole 20 s even
+    when that ffmpeg had already exited and no segment could ever appear — one ordinary seek past the
+    produced region parked a worker and a connection for 20 s (deep-review round 5)."""
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    sessions["m1"] = _Session("sid-a", d)  # its _Proc.poll() reports a finished ffmpeg
+    client = _client(db, monkeypatch)
+    started = time.monotonic()
+    try:
+        r = client.get("/api/plex/stream/m1/hls/sid-a/seg_99999.ts")
+    finally:
+        app.dependency_overrides.clear()
+    elapsed = time.monotonic() - started
+    assert r.status_code == 404, r.text
+    # The wait is 20 s; anything in that neighbourhood means the producer's exit was not consulted.
+    assert elapsed < 2.0, f"waited {elapsed:.1f}s for a segment that can never arrive"
diff --git a/backend/tests/test_plex_playback_session.py b/backend/tests/test_plex_playback_session.py
index 51a952ac..ec5d7331 100644
--- a/backend/tests/test_plex_playback_session.py
+++ b/backend/tests/test_plex_playback_session.py
@@ -58,7 +58,12 @@ def _post(db, user, monkeypatch, rating_key, *, captured):
     def fake_start(db_, it, start, audio, aoff, multi, transcode=False):
         captured["transcode"] = transcode
         return SimpleNamespace(
-            media_start_s=start, entry="index.m3u8", transcode=transcode, hw=False, tonemap=False
+            id="sid",
+            media_start_s=start,
+            entry="index.m3u8",
+            transcode=transcode,
+            hw=False,
+            tonemap=False,
         )
 
     monkeypatch.setattr(plex_stream, "start_session", fake_start)

From 4a7b65d187fdd53ee9e6c13272406e39b8d2a1ef Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 04:07:25 +0200
Subject: [PATCH 38/52] fix(api): a refused write is named, in the reader's
 language
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 5, over round 4's own fixes.

- `notifyActionError` preferred the server's `detail` over the caller's translated fallback, and
  `reportFailure` deliberately leaves 403/404/429 to the caller — so for exactly those statuses the
  dozen call sites round 4 converted started printing whatever English a route hand-wrote into an
  otherwise Hungarian UI ("No user with that email.", "Not subscribed to this channel", "Unknown
  job"). A STRUCTURED detail is still preferred: `req` has already run it through `localizeDetail`,
  so it is both localized and more specific. A plain string is not.

- The other half of the same defect, on the backend: round 4's `get_or_404(what="channel")` sweep
  reached exactly ONE of the five identical sites in channels.py and shipped the HU/EN string with
  it, so the Block button said it in Hungarian and the four controls beside it in English. All five
  are converted, and the subscription / share-recipient / scheduler-job 404s with them (two new
  reasons in both locales).

- `PlexCollectionEditor`'s add/remove, take-over and delete were try/finally with no catch — in the
  very file round 4 edited to give `createNew` one. 403 and 404 are the caller's to report, so the
  tick simply never appeared and a CONFIRMED "delete collection" did nothing, silently.

- `UploadDialog` is the only `uploadReq` caller and kept an empty catch whose comment still claimed
  the global error modal had it. It had not since `reportFailure` became shared: a proxy 502 raised
  only the self-clearing connection notice and a 413/403/404 nothing at all, so the dialog snapped
  back to its pre-upload state with no error named. The user's own Cancel stays silent — and since
  a cancel and a network drop both carry status 0, that difference is now a named `isAborted`
  rather than a string literal at each end.

Regression tests for each (5 vitest, 2 pytest, plus two existing assertions corrected), all
mutation-checked: 6 mutations, each red on the assertion it is named after. vitest 1007,
pytest 1127.
---
 backend/app/routes/channels.py                |  20 +--
 backend/app/routes/downloads.py               |   4 +-
 backend/app/routes/scheduler.py               |   5 +-
 backend/tests/test_not_found_detail.py        |  33 ++++
 .../src/components/PlexCollectionEditor.tsx   |  11 ++
 frontend/src/components/UploadDialog.tsx      |  14 +-
 .../WriteFailureReporting.dom.test.tsx        | 146 ++++++++++++++++++
 .../usePlaylistActions.dom.test.tsx           |  21 ++-
 frontend/src/i18n/locales/en/downloads.json   |   3 +-
 frontend/src/i18n/locales/en/errors.json      |   5 +-
 frontend/src/i18n/locales/en/plex.json        |   3 +-
 frontend/src/i18n/locales/hu/downloads.json   |   3 +-
 frontend/src/i18n/locales/hu/errors.json      |   5 +-
 frontend/src/i18n/locales/hu/plex.json        |   3 +-
 frontend/src/lib/actionErrors.test.ts         |  24 ++-
 frontend/src/lib/actionErrors.ts              |  16 +-
 frontend/src/lib/api/core.ts                  |  14 +-
 17 files changed, 291 insertions(+), 39 deletions(-)
 create mode 100644 frontend/src/components/WriteFailureReporting.dom.test.tsx

diff --git a/backend/app/routes/channels.py b/backend/app/routes/channels.py
index 85ef7a11..4c868976 100644
--- a/backend/app/routes/channels.py
+++ b/backend/app/routes/channels.py
@@ -26,7 +26,7 @@ from app.models import (
     User,
     Video,
 )
-from app.routes._common import get_or_404, owned_or_404
+from app.routes._common import get_or_404, not_found, owned_or_404
 from app.sync.explore import explore_ingest_page
 from app.sync.runner import backfill_channel_now, run_recent_backfill
 from app.sync.subscriptions import apply_channel_details
@@ -287,9 +287,7 @@ def channel_detail(
     needed — a stub, or a channel last enriched before those fields existed (published_at is a
     reliable sentinel: every real channel has a creation date). The enrich uses the API key
     (1 unit, cached after), so it's skipped for the quota-less demo account."""
-    channel = db.get(Channel, channel_id)
-    if channel is None:
-        raise HTTPException(status_code=404, detail="Unknown channel")
+    channel = get_or_404(db, Channel, channel_id, what="channel")
     if channel.published_at is None and not user.is_demo:
         try:
             with (
@@ -366,9 +364,7 @@ def explore_channel(
     it, then ingests one page of its uploads (newest-first) marked via_explore + enriched.
     Returns the next page token so the page can "load more". Guarded against the shared
     backfill quota reserve; blocked for the demo account (it spends shared quota)."""
-    channel = db.get(Channel, channel_id)
-    if channel is None:
-        raise HTTPException(status_code=404, detail="Unknown channel")
+    channel = get_or_404(db, Channel, channel_id, what="channel")
     if _is_blocked(db, user, channel_id):
         raise HTTPException(status_code=403, detail="You've blocked this channel.")
     if quota.backfill_reserve_reached():
@@ -426,7 +422,7 @@ def _user_subscription(db: Session, user: User, channel_id: str) -> Subscription
         )
     ).scalar_one_or_none()
     if sub is None:
-        raise HTTPException(status_code=404, detail="Not subscribed to this channel")
+        raise not_found("subscription")
     return sub
 
 
@@ -512,9 +508,7 @@ def reset_backfill(
     state (a "reset" trigger). Clears the channel's backfill markers, opts it back into deep
     backfill, and re-runs its recent pull immediately; the deep scheduler re-pages the full
     back-catalog on its next run. Idempotent — videos upsert by id, so nothing duplicates."""
-    channel = db.get(Channel, channel_id)
-    if channel is None:
-        raise HTTPException(status_code=404, detail="Unknown channel")
+    channel = get_or_404(db, Channel, channel_id, what="channel")
     channel.backfill_done = False
     channel.backfill_cursor = None
     channel.recent_synced_at = None
@@ -544,9 +538,7 @@ def subscribe(
     local subscription with YouTube's returned resource id and enriches the channel's metadata
     if it's still a stub, so the new row renders properly in the manager. It does NOT pull the
     channel's videos — the scheduler picks those up on its next run, like any subscribed channel."""
-    channel = db.get(Channel, channel_id)
-    if channel is None:
-        raise HTTPException(status_code=404, detail="Unknown channel")
+    channel = get_or_404(db, Channel, channel_id, what="channel")
     existing = db.execute(
         select(Subscription).where(
             Subscription.user_id == user.id, Subscription.channel_id == channel_id
diff --git a/backend/app/routes/downloads.py b/backend/app/routes/downloads.py
index 417d7c72..01a56f56 100644
--- a/backend/app/routes/downloads.py
+++ b/backend/app/routes/downloads.py
@@ -38,7 +38,7 @@ from app.models import (
     MediaAsset,
     User,
 )
-from app.routes._common import get_or_404
+from app.routes._common import get_or_404, not_found
 from app.security import hash_password
 from app.userscope import is_messageable_user, messageable_clauses
 from app.utils import iso
@@ -802,7 +802,7 @@ def share_download(
     # Uniform "no user" for a missing OR non-messageable (demo/suspended/deactivated) target, so
     # sharing can't be used to probe which addresses exist or to reach a suspended account.
     if not is_messageable_user(recipient):
-        raise HTTPException(status_code=404, detail="No user with that email.")
+        raise not_found("recipient")
     if recipient.id == user.id:
         raise HTTPException(status_code=400, detail="That's already your download.")
     exists = db.execute(
diff --git a/backend/app/routes/scheduler.py b/backend/app/routes/scheduler.py
index b605fea6..c5a39258 100644
--- a/backend/app/routes/scheduler.py
+++ b/backend/app/routes/scheduler.py
@@ -23,6 +23,7 @@ from app.scheduler import (
     trigger_job,
 )
 from app.sync.runner import estimate_deep_backfill
+from app.routes._common import not_found
 
 router = APIRouter(prefix="/api/admin/scheduler", tags=["admin"])
 
@@ -41,7 +42,7 @@ def set_job_interval(
     """Change how often a scheduler job runs (minutes). Persisted as an override and applied
     to the live scheduler immediately."""
     if job_id not in JOB_INTERVALS:
-        raise HTTPException(status_code=404, detail="Unknown job")
+        raise not_found("job")
     minutes = body.interval_minutes
     if not (MIN_INTERVAL <= minutes <= MAX_INTERVAL):
         raise HTTPException(
@@ -73,7 +74,7 @@ def run_job_now(
     try:
         result = trigger_job(job_id, actor_id=user.id)
     except KeyError:
-        raise HTTPException(status_code=404, detail="Unknown job")
+        raise not_found("job")
     if result == "already_running":
         raise HTTPException(status_code=409, detail="Job is already running")
     return {"id": job_id, "started": True}
diff --git a/backend/tests/test_not_found_detail.py b/backend/tests/test_not_found_detail.py
index 1510fff9..6f177d98 100644
--- a/backend/tests/test_not_found_detail.py
+++ b/backend/tests/test_not_found_detail.py
@@ -41,6 +41,39 @@ def test_a_gone_channel_video_or_user_says_what_is_gone(db, make_user, as_user):
         assert r.json()["detail"] == {"code": "not_found", "reason": what}, url
 
 
+def test_every_gone_channel_route_says_it_the_same_way(db, make_user, as_user):
+    """The round-4 sweep converted ONE of the five `db.get(Channel, …) is None -> 404 "Unknown
+    channel"` sites (block), and shipped the HU/EN string with it — so the Hungarian UI said it in
+    Hungarian on the Block button and in English on the four beside it (deep-review round 5). The
+    asymmetric fix is the smell this repo bans, so all five are pinned together."""
+    admin = make_user(role="admin")
+    client = as_user(admin)
+    gone = "UCgone000000000000000000"
+    # Subscribe is behind the write-scope gate, so it is covered by the tags route below instead.
+    for method, url in [
+        ("get", f"/api/channels/{gone}"),
+        ("post", f"/api/channels/{gone}/reset-backfill"),
+        ("post", f"/api/channels/{gone}/block"),
+    ]:
+        r = getattr(client, method)(url)
+        assert r.status_code == 404, (url, r.text)
+        assert r.json()["detail"] == {"code": "not_found", "reason": "channel"}, url
+
+
+def test_a_gone_subscription_recipient_or_job_says_what_is_gone(db, make_user, as_user):
+    """The three bare-English 404s the same sweep left behind, which `notifyActionError` printed
+    verbatim into an otherwise Hungarian UI: "Not subscribed to this channel", "No user with that
+    email.", "Unknown job"."""
+    admin = make_user(role="admin")
+    client = as_user(admin)
+    r = client.post("/api/channels/UCgone000000000000000000/tags", json={"tag_id": 1})
+    assert r.status_code == 404, r.text
+    assert r.json()["detail"] == {"code": "not_found", "reason": "subscription"}
+    r = client.patch("/api/admin/scheduler/jobs/no_such_job", json={"interval_minutes": 30})
+    assert r.status_code == 404, r.text
+    assert r.json()["detail"] == {"code": "not_found", "reason": "job"}
+
+
 def test_a_nul_in_a_request_string_is_a_422_not_a_500(db, make_user, as_user):
     """Postgres cannot hold NUL in text, so the driver refuses the query outright: a DataError, i.e.
     a 500 with a traceback, wherever a `%00` or an escaped NUL reached a comparison (deep-review
diff --git a/frontend/src/components/PlexCollectionEditor.tsx b/frontend/src/components/PlexCollectionEditor.tsx
index ab5dac28..f6091804 100644
--- a/frontend/src/components/PlexCollectionEditor.tsx
+++ b/frontend/src/components/PlexCollectionEditor.tsx
@@ -77,6 +77,11 @@ export default function PlexCollectionEditor({
         return next;
       });
       refresh();
+    } catch (e) {
+      // 403/404 are left to the caller by `req` (see reportFailure), so without this the tick
+      // simply never appeared and the user clicked again — a collection deleted on the Plex server
+      // or flipped read-only failed in silence (deep-review round 5).
+      notifyActionError(e, t("plex.collection.editFailed"));
     } finally {
       setBusy(null);
     }
@@ -88,6 +93,8 @@ export default function PlexCollectionEditor({
     try {
       await api.plexSetCollectionEditable(id, true);
       refresh();
+    } catch (e) {
+      notifyActionError(e, t("plex.collection.editFailed"));
     } finally {
       setBusy(null);
     }
@@ -123,6 +130,10 @@ export default function PlexCollectionEditor({
         return next;
       });
       refresh();
+    } catch (e) {
+      // The worst of the three to lose: the user has just confirmed a destructive dialog, and the
+      // row stayed where it was with nothing said.
+      notifyActionError(e, t("plex.collection.deleteFailed"));
     } finally {
       setBusy(null);
     }
diff --git a/frontend/src/components/UploadDialog.tsx b/frontend/src/components/UploadDialog.tsx
index 7b586b07..c46951aa 100644
--- a/frontend/src/components/UploadDialog.tsx
+++ b/frontend/src/components/UploadDialog.tsx
@@ -5,6 +5,8 @@ import { UploadCloud, File as FileIcon } from "lucide-react";
 import Modal from "./ui/Modal";
 import { Button } from "./ui/Button";
 import { api } from "../lib/api";
+import { isAborted } from "../lib/api/core";
+import { notifyActionError } from "../lib/actionErrors";
 import { invalidateDownloads } from "../lib/downloads";
 import { notify } from "../lib/notifications";
 import { navigateTo } from "../lib/nav";
@@ -54,9 +56,15 @@ export default function UploadDialog({ onClose }: { onClose: () => void }) {
         action: { label: t("downloads.dialog.view"), onClick: () => navigateTo("downloads") },
       });
       onClose();
-    } catch {
-      // An aborted upload (Cancel) or a server rejection (cap/quota — already surfaced by the global
-      // error modal, like every other req call). Re-arm the form so the user can retry or pick again.
+    } catch (e) {
+      // Everything except the user's own Cancel is said out loud. `uploadReq` shares `reportFailure`
+      // with `req`, which deliberately leaves 403/404/429 to the caller and answers a 502/503/504
+      // with only the transient "connection lost" notice — so this empty catch meant a proxy 502 on
+      // a long upload, or an nginx 413, snapped the dialog back to its pre-upload state with nothing
+      // named and no job in the list. The comment here claimed the global error modal had it; it
+      // had not since the shared `reportFailure` landed (deep-review round 5).
+      if (!isAborted(e)) notifyActionError(e, t("downloads.upload.failed"));
+      // Re-arm the form so the user can retry or pick again.
       setPct(null);
       abortRef.current = null;
     }
diff --git a/frontend/src/components/WriteFailureReporting.dom.test.tsx b/frontend/src/components/WriteFailureReporting.dom.test.tsx
new file mode 100644
index 00000000..b76e1555
--- /dev/null
+++ b/frontend/src/components/WriteFailureReporting.dom.test.tsx
@@ -0,0 +1,146 @@
+// @vitest-environment jsdom
+//
+// A write that fails is named, wherever it fails. `req`/`uploadReq` deliberately leave 403/404/429
+// to the caller (see reportFailure) and answer a 502/503/504 with only the transient "connection
+// lost" notice — so a handler with no `catch` reports nothing at all. Round 4 swept a dozen such
+// call sites and missed these two: the collection editor's three siblings, in the very file it
+// edited, and the one `uploadReq` caller, whose empty catch still claimed the global error modal had
+// it (deep-review round 5).
+import { describe, it, expect, vi, beforeAll, beforeEach, afterEach } from "vitest";
+import { render, cleanup, screen, fireEvent, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+vi.mock("./ConfirmProvider", () => ({ useConfirm: () => async () => true }));
+const { notify } = vi.hoisted(() => ({
+  notify: vi.fn((_n: { level: string; message: string }) => 0),
+}));
+vi.mock("../lib/notifications", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../lib/notifications")>()),
+  notify,
+}));
+
+import PlexCollectionEditor from "./PlexCollectionEditor";
+import UploadDialog from "./UploadDialog";
+import { api, HttpError } from "../lib/api";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+beforeEach(() => notify.mockClear());
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const errors = () => notify.mock.calls.filter(([n]) => n.level === "error").map(([n]) => n.message);
+const client = () => new QueryClient({ defaultOptions: { queries: { retry: false } } });
+
+describe("the Plex collection editor", () => {
+  const collections = [
+    { id: "c1", title: "Marathon", can_edit: true, child_count: 3, smart: false },
+    // Not marked "mine to edit" yet, so it offers the take-over button.
+    {
+      id: "c2",
+      title: "Theirs",
+      can_edit: false,
+      child_count: 9,
+      smart: false,
+      source: "collection",
+    },
+  ];
+  const mount = () =>
+    render(
+      <QueryClientProvider client={client()}>
+        <PlexCollectionEditor
+          item={{ id: "m1", title: "A Movie" }}
+          library="1"
+          memberOf={[]}
+          onClose={() => {}}
+          onChanged={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+
+  it("says so when adding to a collection that is gone, instead of nothing happening", async () => {
+    vi.spyOn(api, "plexCollections").mockResolvedValue({ collections } as never);
+    vi.spyOn(api, "plexCollectionAddItem").mockRejectedValue(
+      new HttpError(404, "Unknown collection"),
+    );
+    mount();
+    fireEvent.click(await screen.findByText("Marathon"));
+    await waitFor(() => expect(errors()).toEqual(["plex.collection.editFailed"]));
+  });
+
+  it("says so when enabling editing is refused", async () => {
+    vi.spyOn(api, "plexCollections").mockResolvedValue({ collections } as never);
+    vi.spyOn(api, "plexSetCollectionEditable").mockRejectedValue(
+      new HttpError(403, "This collection is read-only"),
+    );
+    mount();
+    fireEvent.click(await screen.findByText("plex.collEditor.makeEditable"));
+    await waitFor(() => expect(errors()).toEqual(["plex.collection.editFailed"]));
+  });
+
+  it("says so when a CONFIRMED delete does not happen", async () => {
+    // The worst of the three to lose: the user has just confirmed a destructive dialog.
+    vi.spyOn(api, "plexCollections").mockResolvedValue({ collections } as never);
+    vi.spyOn(api, "plexDeleteCollection").mockRejectedValue(
+      new HttpError(404, "Unknown collection"),
+    );
+    mount();
+    fireEvent.click(await screen.findByText("plex.collEditor.delete"));
+    await waitFor(() => expect(errors()).toEqual(["plex.collection.deleteFailed"]));
+  });
+});
+
+describe("the upload dialog", () => {
+  const pick = () => {
+    const input = document.querySelector('input[type="file"]') as HTMLInputElement;
+    const file = new File(["x"], "clip.mp4", { type: "video/mp4" });
+    Object.defineProperty(input, "files", { value: [file], configurable: true });
+    fireEvent.change(input);
+  };
+  const mount = () =>
+    render(
+      <QueryClientProvider client={client()}>
+        <UploadDialog onClose={() => {}} />
+      </QueryClientProvider>,
+    );
+
+  it("names an upload the server refused", async () => {
+    // A 502 from the proxy raises only the self-clearing connection notice; the next successful poll
+    // wipes it, and the dialog snapped back with no error and no job in the list.
+    vi.spyOn(api, "uploadDownload").mockRejectedValue(new HttpError(502, "Bad Gateway"));
+    mount();
+    pick();
+    fireEvent.click(screen.getByText("downloads.upload.submit"));
+    await waitFor(() => expect(errors()).toEqual(["downloads.upload.failed"]));
+  });
+
+  it("says nothing when the user cancelled it themselves", async () => {
+    // A cancel is not a failure — and it rejects with the same status 0 a genuine network drop does,
+    // which is why the difference is a named sentinel (`isAborted`) and not a status check.
+    const upload = vi.spyOn(api, "uploadDownload").mockRejectedValue(new HttpError(0, "aborted"));
+    mount();
+    pick();
+    fireEvent.click(screen.getByText("downloads.upload.submit"));
+    await waitFor(() => expect(upload).toHaveBeenCalled());
+    expect(errors()).toEqual([]);
+  });
+});
diff --git a/frontend/src/components/usePlaylistActions.dom.test.tsx b/frontend/src/components/usePlaylistActions.dom.test.tsx
index 32f43c3c..5ab31b77 100644
--- a/frontend/src/components/usePlaylistActions.dom.test.tsx
+++ b/frontend/src/components/usePlaylistActions.dom.test.tsx
@@ -60,10 +60,25 @@ describe("usePlaylistActions — deleting a list", () => {
     expect(h.notify).not.toHaveBeenCalled();
   });
 
-  it("does say one it was left to handle", async () => {
-    vi.spyOn(api, "deletePlaylist").mockRejectedValue(new HttpError(404, "gone"));
+  it("does say one it was left to handle — in the reader's language", async () => {
+    // A plain-string `detail` is whatever English the route hand-wrote; the caller's own translated
+    // fallback is the one a Hungarian reader can read (deep-review round 5).
+    vi.spyOn(api, "deletePlaylist").mockRejectedValue(new HttpError(404, "Unknown playlist"));
     const { result } = mount();
     await act(() => result.current.remove(linked));
-    expect(h.notify).toHaveBeenCalledWith(expect.objectContaining({ message: "gone" }));
+    expect(h.notify).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "playlists.deleteYtFailed" }),
+    );
+  });
+
+  it("prefers a STRUCTURED reason, which the request layer has already localized", async () => {
+    vi.spyOn(api, "deletePlaylist").mockRejectedValue(
+      new HttpError(404, "Ez a lista már nem létezik.", { code: "not_found", reason: "playlist" }),
+    );
+    const { result } = mount();
+    await act(() => result.current.remove(linked));
+    expect(h.notify).toHaveBeenCalledWith(
+      expect.objectContaining({ message: "Ez a lista már nem létezik." }),
+    );
   });
 });
diff --git a/frontend/src/i18n/locales/en/downloads.json b/frontend/src/i18n/locales/en/downloads.json
index 693adfb3..e0cc6b04 100644
--- a/frontend/src/i18n/locales/en/downloads.json
+++ b/frontend/src/i18n/locales/en/downloads.json
@@ -34,7 +34,8 @@
     "submit": "Upload",
     "uploading": "Uploading… {{pct}}%",
     "uploadProgress": "Upload progress",
-    "added": "File uploaded"
+    "added": "File uploaded",
+    "failed": "The upload failed."
   },
   "tabs": {
     "queue": "Queue",
diff --git a/frontend/src/i18n/locales/en/errors.json b/frontend/src/i18n/locales/en/errors.json
index 64c6d201..05c6e9c2 100644
--- a/frontend/src/i18n/locales/en/errors.json
+++ b/frontend/src/i18n/locales/en/errors.json
@@ -14,7 +14,10 @@
     "video": "This video isn't in the library any more.",
     "invite": "This invite doesn't exist any more.",
     "user": "This user doesn't exist any more.",
-    "channel": "This channel isn't in the library any more."
+    "channel": "This channel isn't in the library any more.",
+    "subscription": "You're not subscribed to this channel any more.",
+    "recipient": "There's no user with that email address.",
+    "job": "This job doesn't exist any more."
   },
   "ok": "OK",
   "offline": {
diff --git a/frontend/src/i18n/locales/en/plex.json b/frontend/src/i18n/locales/en/plex.json
index 7970e9de..f4d4c768 100644
--- a/frontend/src/i18n/locales/en/plex.json
+++ b/frontend/src/i18n/locales/en/plex.json
@@ -29,7 +29,8 @@
     "namePlaceholder": "Collection name",
     "nameTaken": "A collection with this name already exists.",
     "newHint": "Pick the first title to add — a collection needs at least one.",
-    "createWith": "Create"
+    "createWith": "Create",
+    "deleteFailed": "Couldn't delete the collection."
   },
   "searchPlaceholder": "Search Plex…",
   "searchField": {
diff --git a/frontend/src/i18n/locales/hu/downloads.json b/frontend/src/i18n/locales/hu/downloads.json
index f845cc2c..a396d465 100644
--- a/frontend/src/i18n/locales/hu/downloads.json
+++ b/frontend/src/i18n/locales/hu/downloads.json
@@ -34,7 +34,8 @@
     "submit": "Feltöltés",
     "uploading": "Feltöltés… {{pct}}%",
     "uploadProgress": "Feltöltés folyamata",
-    "added": "Fájl feltöltve"
+    "added": "Fájl feltöltve",
+    "failed": "A feltöltés nem sikerült."
   },
   "tabs": {
     "queue": "Sor",
diff --git a/frontend/src/i18n/locales/hu/errors.json b/frontend/src/i18n/locales/hu/errors.json
index 14b0d867..0971ba85 100644
--- a/frontend/src/i18n/locales/hu/errors.json
+++ b/frontend/src/i18n/locales/hu/errors.json
@@ -14,7 +14,10 @@
     "video": "Ez a videó már nincs a könyvtárban.",
     "invite": "Ez a meghívó már nem létezik.",
     "user": "Ez a felhasználó már nem létezik.",
-    "channel": "Ez a csatorna már nincs a könyvtárban."
+    "channel": "Ez a csatorna már nincs a könyvtárban.",
+    "subscription": "Már nem vagy feliratkozva erre a csatornára.",
+    "recipient": "Nincs felhasználó ezzel az e-mail címmel.",
+    "job": "Ez a feladat már nem létezik."
   },
   "ok": "OK",
   "offline": {
diff --git a/frontend/src/i18n/locales/hu/plex.json b/frontend/src/i18n/locales/hu/plex.json
index e85ab902..61da094c 100644
--- a/frontend/src/i18n/locales/hu/plex.json
+++ b/frontend/src/i18n/locales/hu/plex.json
@@ -29,7 +29,8 @@
     "namePlaceholder": "Kollekció neve",
     "nameTaken": "Már létezik ilyen nevű kollekció.",
     "newHint": "Válaszd ki az első címet — egy kollekcióhoz legalább egy elem kell.",
-    "createWith": "Létrehozás"
+    "createWith": "Létrehozás",
+    "deleteFailed": "Nem sikerült törölni a gyűjteményt."
   },
   "searchPlaceholder": "Keresés a Plexben…",
   "searchField": {
diff --git a/frontend/src/lib/actionErrors.test.ts b/frontend/src/lib/actionErrors.test.ts
index 1f64c5b7..f46cb78a 100644
--- a/frontend/src/lib/actionErrors.test.ts
+++ b/frontend/src/lib/actionErrors.test.ts
@@ -57,6 +57,28 @@ describe("notifyActionError", () => {
 
   it("does toast one the caller was left to handle", () => {
     notifyActionError(new HttpError(404, "gone"), "FAILED");
-    expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "gone" });
+    expect(notifyMock).toHaveBeenCalled();
+  });
+
+  it("says a bare-English server reason in the reader's language, not the server's", () => {
+    // `reportFailure` leaves 403/404/429 to the caller, so for exactly those statuses whatever
+    // English a route hand-wrote went straight into the toast — "No user with that email." in an
+    // otherwise Hungarian UI, while the caller's translated fallback sat unused (round 5).
+    notifyActionError(new HttpError(404, "No user with that email."), "TRANSLATED");
+    expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "TRANSLATED" });
+  });
+
+  it("still prefers a STRUCTURED reason, which the request layer has already localized", () => {
+    // `req` runs `{code, reason}` through localizeDetail, so `detail` is in the reader's language
+    // AND more specific than the caller's generic fallback — quota numbers, which row is gone.
+    const err = new HttpError(404, "Ez a csatorna már nincs a könyvtárban.", {
+      code: "not_found",
+      reason: "channel",
+    });
+    notifyActionError(err, "TRANSLATED FALLBACK");
+    expect(notifyMock).toHaveBeenCalledWith({
+      level: "error",
+      message: "Ez a csatorna már nincs a könyvtárban.",
+    });
   });
 });
diff --git a/frontend/src/lib/actionErrors.ts b/frontend/src/lib/actionErrors.ts
index e2ad1d26..5a8949f2 100644
--- a/frontend/src/lib/actionErrors.ts
+++ b/frontend/src/lib/actionErrors.ts
@@ -5,10 +5,14 @@ import { notify } from "./notifications";
 
 /**
  * Surface a failed write action as an error toast instead of the click silently doing nothing.
- * Prefers the server's own reason (`HttpError.detail` — e.g. "Not enough quota left today", a
- * 404/429 message) over the caller's already-translated generic fallback. Domain-agnostic: used by
- * the Plex watched-toggles and the saved-view ops, and delegated to by `notifyYouTubeActionError`
- * for its non-403 case.
+ * Prefers the server's own reason over the caller's already-translated generic fallback — but only
+ * when the server sent a STRUCTURED detail (`{code, reason}`), which `req` has already run through
+ * `localizeDetail`. A plain-string `detail` is whatever English the route hand-wrote, and
+ * `reportFailure` deliberately leaves 403/404/429 to the caller, so exactly those statuses used to
+ * put the route's English sentence into an otherwise Hungarian UI — "No user with that email.",
+ * "Not subscribed to this channel" — where the caller's own translated fallback was right there
+ * (deep-review round 5). Domain-agnostic: used by the Plex watched-toggles and the saved-view ops,
+ * and delegated to by `notifyYouTubeActionError` for its non-403 case.
  */
 export function notifyActionError(
   err: unknown,
@@ -19,6 +23,6 @@ export function notifyActionError(
   // top reported one fault twice. Playlists filtered this by status by hand; the watched toggles,
   // the saved views and a playlist delete did not.
   if (alreadyReported(err)) return;
-  const detail = err instanceof HttpError ? err.detail : null;
-  notify({ level, message: detail || fallbackMessage });
+  const localized = err instanceof HttpError && err.detailData != null ? err.detail : null;
+  notify({ level, message: localized || fallbackMessage });
 }
diff --git a/frontend/src/lib/api/core.ts b/frontend/src/lib/api/core.ts
index 2afc3e66..a8cce25f 100644
--- a/frontend/src/lib/api/core.ts
+++ b/frontend/src/lib/api/core.ts
@@ -28,6 +28,16 @@ export function alreadyReported(err: unknown): boolean {
   return typeof err === "object" && err !== null && reported.has(err);
 }
 
+/** What an upload the USER cancelled rejects with. A cancel is not a failure to report, and the
+ *  only other rejection carrying status 0 is a genuine network drop, which IS worth reporting — so
+ *  the difference has to be a named thing both sides agree on, not a string literal in each. */
+const ABORTED = "aborted";
+
+/** True for the rejection of a request the user cancelled (see `ABORTED`). */
+export function isAborted(err: unknown): boolean {
+  return err instanceof HttpError && err.status === 0 && err.detail === ABORTED;
+}
+
 export class HttpError extends Error {
   status: number;
   detail?: string; // server-provided reason (FastAPI's `detail`), when present
@@ -342,7 +352,7 @@ export function uploadReq<T = unknown>(
       };
     }
     if (cfg.signal) {
-      if (cfg.signal.aborted) return reject(new HttpError(0, "aborted"));
+      if (cfg.signal.aborted) return reject(new HttpError(0, ABORTED));
       cfg.signal.addEventListener("abort", () => xhr.abort());
     }
     xhr.onload = () => {
@@ -376,7 +386,7 @@ export function uploadReq<T = unknown>(
       markConnectivityLost();
       reject(new HttpError(0, i18n.t("errors.offline.body")));
     };
-    xhr.onabort = () => reject(new HttpError(0, "aborted"));
+    xhr.onabort = () => reject(new HttpError(0, ABORTED));
     xhr.send(form);
   });
 }

From 12121255dd681b94d94a1710590c6cccd7f0025d Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 04:15:15 +0200
Subject: [PATCH 39/52] fix(playlists): a rejected reorder goes back to the
 order the server accepted
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 5, over round 4's own fixes.

- Round 4 made a failed reorder roll the rows back to the CACHED detail, because a resync cannot do
  it (the server's list is unchanged, so the refetch is deep-equal, react-query keeps the same
  `data` object and the effect keyed on it never runs). But nothing wrote an ACCEPTED order into
  that cache — only the refetch that follows a successful reorder did. So a second reorder rejected
  while that refetch was still in flight rolled the rows back past the first one, which the server
  had accepted; the membership guard cannot correct an order (its key is the sorted id set), so the
  wrong order stayed on screen for good and the next drag persisted it. `onApply` now writes the
  accepted order into the cache before invalidating.

- `PlexPlaylistView.rename` had a `catch` no test could reach, and `commit` (reorder) was not gated
  by `busy` the way its siblings are — a reorder in flight while a removal completes is what makes a
  rollback ambiguous in the first place. The rename failure path is now covered; `commit` defers.

- `putBack` read `q.data` from the render that bound the failing handler instead of the cache at
  rollback time, unlike the sibling `restoreFromCache`. Aligned. Stated plainly: I could NOT drive
  that staleness in jsdom — a mutation that restores the old shape leaves every candidate test green
  — so this one ships as an alignment with the proven sibling, not as a fix with a red test behind
  it. The scenario and the harness limit are on ROADMAP.md.

Two regression tests, both mutation-checked red (the cache write, the rename catch). The
drag-reorder failure path still has no test: dnd-kit's pointer and keyboard sensors do not activate
under jsdom even with geometry and scrollIntoView stubbed, so a test there would have pinned the
harness, not the code. Logged, not faked.

vitest 1009.
---
 .../PlaylistEditFailures.dom.test.tsx         | 17 +++++++++++++
 .../src/components/Playlists.dom.test.tsx     | 25 +++++++++++++++++++
 frontend/src/components/Playlists.tsx         | 10 +++++++-
 frontend/src/components/PlexPlaylistView.tsx  |  9 ++++++-
 4 files changed, 59 insertions(+), 2 deletions(-)

diff --git a/frontend/src/components/PlaylistEditFailures.dom.test.tsx b/frontend/src/components/PlaylistEditFailures.dom.test.tsx
index dec28ea6..304982b5 100644
--- a/frontend/src/components/PlaylistEditFailures.dom.test.tsx
+++ b/frontend/src/components/PlaylistEditFailures.dom.test.tsx
@@ -76,6 +76,23 @@ describe("the Plex playlist page", () => {
     expect(screen.getByText("Movie 1")).toBeTruthy();
   });
 
+  it("says so when a rename is refused, and keeps the field open", async () => {
+    vi.spyOn(api, "plexPlaylist").mockResolvedValue({ id: 5, title: "Films", items: [] });
+    vi.spyOn(api, "plexRenamePlaylist").mockRejectedValue(gone("playlist"));
+    render(
+      <QueryClientProvider client={client()}>
+        <PlexPlaylistView playlistId={5} onBack={() => {}} onPlay={() => {}} />
+      </QueryClientProvider>,
+    );
+    await screen.findByText("Films");
+    fireEvent.click(screen.getByTitle("plex.playlist.rename"));
+    const field = screen.getByDisplayValue("Films");
+    fireEvent.change(field, { target: { value: "Movies" } });
+    fireEvent.keyDown(field, { key: "Enter" });
+    await waitFor(() => expect(errors()).toEqual(["gone playlist"]));
+    expect(screen.getByDisplayValue("Movies")).toBeTruthy(); // still open to try again
+  });
+
   it("leaves a playlist that is already gone when asked to delete it", async () => {
     vi.spyOn(api, "plexPlaylist").mockResolvedValue({ id: 5, title: "Films", items: [] });
     vi.spyOn(api, "plexDeletePlaylist").mockRejectedValue(gone("playlist"));
diff --git a/frontend/src/components/Playlists.dom.test.tsx b/frontend/src/components/Playlists.dom.test.tsx
index c3b7262d..38ec9004 100644
--- a/frontend/src/components/Playlists.dom.test.tsx
+++ b/frontend/src/components/Playlists.dom.test.tsx
@@ -343,6 +343,31 @@ describe("Playlists — a change the server refused is taken back on screen", ()
     expect(rowsOnScreen()).toEqual(["Video V", "Video W"]);
   });
 
+  it("puts back the order the server ACCEPTED, not the one it had two reorders ago", async () => {
+    // The rollback reads the cached detail, and nothing wrote the accepted order into it — only the
+    // refetch that follows a successful reorder did. So a second reorder rejected while that refetch
+    // was still in flight rolled the rows back past the FIRST one, which the server had accepted.
+    // The membership guard cannot correct an order (its key is the sorted id set), so the wrong
+    // order stayed on screen for good and the next drag persisted it (deep-review round 5).
+    const reorder = vi
+      .spyOn(api, "reorderPlaylist")
+      .mockResolvedValueOnce(undefined as never)
+      .mockRejectedValue(new HttpError(500, "boom"));
+    mount({ 1: [vid("V", 0), vid("W", 0), vid("X", 0)] });
+    await screen.findByRole("button", { name: "card.play — Video V" });
+    // From here no refetch ever lands, so the cache is whatever the page itself put there.
+    vi.mocked(api.playlist).mockReturnValue(new Promise(() => {}) as never);
+
+    await rowMenu("Video V", "playlists.orderDown");
+    await waitFor(() => expect(reorder).toHaveBeenCalledTimes(1));
+    expect(rowsOnScreen()).toEqual(["Video W", "Video V", "Video X"]);
+
+    await rowMenu("Video X", "playlists.orderUp");
+    await waitFor(() => expect(reorder).toHaveBeenCalledTimes(2));
+    await act(async () => void (await new Promise((r) => setTimeout(r, 20))));
+    expect(rowsOnScreen()).toEqual(["Video W", "Video V", "Video X"]);
+  });
+
   it("puts back a row whose removal failed, even when the resync fails too", async () => {
     // A removal during an API restart: the DELETE fails, and so does the refetch meant to put the row
     // back — the list kept showing it as removed while it was still in the playlist.
diff --git a/frontend/src/components/Playlists.tsx b/frontend/src/components/Playlists.tsx
index 583b3175..f30f7d98 100644
--- a/frontend/src/components/Playlists.tsx
+++ b/frontend/src/components/Playlists.tsx
@@ -191,11 +191,19 @@ export default function Playlists() {
           next.map((v) => v.id),
         )
         .then(() => {
+          // Write the accepted order into the cache BEFORE the refetch. The cache is what
+          // `restoreFromCache` rolls back to, and until this refetch landed it still held the order
+          // from before this reorder — so a SECOND reorder failing in that window rolled the rows
+          // back to an order the server does not have, permanently (the membership guard cannot
+          // correct an order). One accepted write, one cache entry that matches it (round 5).
+          qc.setQueryData<PlaylistDetail>(qk.playlist(listId), (old) =>
+            old ? { ...old, items: next } : old,
+          );
           // Refresh the sidebar (cover may change) and the detail (so the now-dirty state,
           // and the Reset/Unsynced indicators, show without an F5). The membership guard
           // keeps the refetch from wiping the undo history on a pure reorder.
           qc.invalidateQueries({ queryKey: qk.playlists() });
-          qc.invalidateQueries({ queryKey: qk.playlist(selectedId) });
+          qc.invalidateQueries({ queryKey: qk.playlist(listId) });
         })
         .catch((e) => {
           // Was a bare .then(): a failed reorder left the UI showing an order the server had
diff --git a/frontend/src/components/PlexPlaylistView.tsx b/frontend/src/components/PlexPlaylistView.tsx
index ffc97290..9e3f33f3 100644
--- a/frontend/src/components/PlexPlaylistView.tsx
+++ b/frontend/src/components/PlexPlaylistView.tsx
@@ -408,12 +408,19 @@ export default function PlexPlaylistView({
   // nothing at all (deep-review round 4; the YouTube side was fixed in round 3). A failure is said,
   // and the rows are put back from what the server last sent — explicitly, because a resync that
   // returns the same list keeps the same `q.data` and the re-sync effect above never runs.
+  // Read the cache AT ROLLBACK TIME, not the `q.data` of the render that bound the failing handler:
+  // a removal completing while a reorder was in flight refreshed the list, and the reorder's stale
+  // closure then put the removed row back on screen — where the deep-equal refetch could not clear
+  // it, and the next drag persisted an order containing it (deep-review round 5). `Playlists.tsx`'s
+  // sibling `restoreFromCache` reads it live for the same reason.
   const putBack = () => {
-    if (q.data) setItems(q.data.items);
+    const cur = qc.getQueryData<{ items: PlexCard[] }>(qk.plexPlaylist(playlistId));
+    if (cur) setItems(cur.items);
     invalidate();
   };
 
   function commit(next: PlexCard[]) {
+    if (busy) return; // a reorder racing a removal is what makes a rollback ambiguous
     setItems(next);
     api
       .plexReorderPlaylist(

From 33fddacee23e0a9e17e417980cdcc211932f689b Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 04:18:35 +0200
Subject: [PATCH 40/52] test(plex): the over-long-name guard is asserted the
 same way on every OS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Deep-review round 5. The assertion behind `subtitles._exists` was only red where pathlib re-raises
ENAMETOOLONG: on Linux it does, on Windows the same stat fails with ERROR_INVALID_NAME, which
pathlib's `exists()` already swallows — so the assertion passed with the fix reverted. It forces the
errno now instead of relying on the filesystem. (The gate's pytest lane is the Linux container, so
the branch was never actually unguarded; the test was just dishonest about why it passed.)
---
 backend/tests/test_plex_subtitle_prepare.py | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/backend/tests/test_plex_subtitle_prepare.py b/backend/tests/test_plex_subtitle_prepare.py
index 53085c17..fcaa4aa0 100644
--- a/backend/tests/test_plex_subtitle_prepare.py
+++ b/backend/tests/test_plex_subtitle_prepare.py
@@ -22,6 +22,7 @@ conftest refuses to run without ffmpeg rather than let it skip.
 """
 
 import asyncio
+import errno
 import shutil
 import subprocess
 import sys
@@ -1059,7 +1060,17 @@ def test_an_absurd_rating_key_or_ordinal_is_refused_not_a_500(client, monkeypatc
     ):
         assert client.get(url).status_code == 422, url
     assert pool.jobs == []
-    # …and the cache helpers themselves no longer throw on such a name.
+
+    # …and the cache helpers themselves no longer throw on such a name. Asserted against a forced
+    # ENAMETOOLONG rather than the real filesystem: on Linux pathlib re-raises it (the defect), but
+    # Windows reports ERROR_INVALID_NAME, which pathlib's `exists()` already swallows — so on a dev
+    # machine this assertion passed with `_exists` reverted and only the container lane was honest
+    # about it (deep-review round 5).
+    def _too_long(self):
+        raise OSError(errno.ENAMETOOLONG, "File name too long")
+
+    monkeypatch.setattr(Path, "exists", _too_long)
+    assert subtitles._exists(Path("whatever")) is False
     assert subtitles.read_meta(subtitles.cache_key(long_key, 0)) == ([], False)
 
 

From 1f81684b6e4b6b12aefddf9d730db1b4008db101 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 04:31:51 +0200
Subject: [PATCH 41/52] fix(ui,plex): a dialog keeps the focus its child asked
 for, and a hopeless segment fails at once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both found by UAT in a real browser, after the tests for them were already green — which is the
whole reason this repo settles focus and timing claims by running them.

- **The autoFocus fix worked, and then the dialog took the focus back.** React 18's StrictMode runs
  every effect mount→cleanup→mount in development: the cleanup handed focus back to the trigger, and
  the second mount, finding the focus outside the dialog, moved it to the first focusable — off the
  `autoFocus` field a beat after the browser had put it there. Chrome measured it: INPUT (commitMount)
  → BODY (cleanup) → ✕ (re-mount). The effect is idempotent now — it remembers what the dialog was
  focused on and restores THAT on a re-mount — and the close-time restore is conditional on the
  dialog still holding the focus, which it tracks as it changes rather than computing at cleanup,
  where the panel is already out of the document. A dialog no longer yanks focus back from wherever
  the user has since moved it.

- **Passing ffmpeg's handle to the segment wait only shortened the FINISHED case.** Measured against
  the running localdev API: a request for `seg_99999.ts` on a live session still took 20 195 ms,
  because that ffmpeg has not exited and the wait has no other reason to stop. ffmpeg writes segments
  in order, so a segment whose predecessor does not exist is not the next one and cannot arrive —
  and that is knowable at once. Same request now: 45 ms.

Verified on localdev against the real library (Westworld S01E06, remux, multi-audio): Mod+K opens the
command palette with the focus in its search field and typing reaches it; playback runs on the new
session-scoped HLS URL; a request naming a stale session id is a 404; and a viewer paused for longer
than the finished-session rule keeps their 2.4 GB session across two reaper passes — the progress
checkpoint touches it — and resumes cleanly.

vitest 1009, pytest 1127.
---
 backend/app/plex/stream.py                | 30 ++++++++++++++++++
 backend/app/routes/plex/playback.py       |  6 ++++
 backend/tests/test_plex_hls_file_route.py | 22 ++++++++-----
 frontend/src/components/ui/dialogFocus.ts | 38 ++++++++++++++++++++---
 4 files changed, 84 insertions(+), 12 deletions(-)

diff --git a/backend/app/plex/stream.py b/backend/app/plex/stream.py
index 224ff5a9..6ab7a95d 100644
--- a/backend/app/plex/stream.py
+++ b/backend/app/plex/stream.py
@@ -758,6 +758,36 @@ def current_session(key: str) -> HlsSession | None:
         return s
 
 
+# A segment file, single-audio (`seg_12.ts`) or one rendition of a multi-audio session
+# (`seg_12_0.ts`). ffmpeg writes them strictly in order, which is what makes `segment_may_arrive`
+# exact rather than a heuristic.
+_SEG_NAME_RE = re.compile(r"^seg_(\d+)(_\d+)?\.ts$")
+
+
+def segment_may_arrive(directory: Path, filename: str) -> bool:
+    """Whether waiting for `filename` can possibly end in a file.
+
+    ffmpeg produces segments sequentially, so a segment whose PREDECESSOR does not exist yet is not
+    the next one — it is somewhere beyond the generated region, and no amount of waiting will
+    conjure it. Saying so at once matters because the route that waits is a SYNC one: it holds a
+    thread off the ~40-slot pool, and a pooled DB connection with it, for the whole timeout. An
+    ordinary seek past the produced region was enough to park one for 20 s, and forty concurrent
+    requests for a name that will never exist parked the whole API (deep-review round 5).
+
+    Anything that is not a segment (a playlist, a WebVTT track) is left to the timeout: those are
+    rewritten continuously and have no ordering to read."""
+    m = _SEG_NAME_RE.match(filename)
+    if m is None:
+        return True
+    idx = int(m.group(1))
+    if idx == 0:
+        return True
+    try:
+        return (directory / f"seg_{idx - 1}{m.group(2) or ''}.ts").exists()
+    except OSError:
+        return False
+
+
 def wait_for(path: Path, timeout: float = 20.0, proc: subprocess.Popen | None = None) -> bool:
     """Wait until a session file (playlist / segment) exists and is non-empty. Segments are
     produced ~faster than realtime, so a segment just ahead of playback appears quickly; a segment
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 769bf8bd..5cd12387 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -656,6 +656,12 @@ def stream_hls_file(
     if s is None or s.id != session_id:
         raise HTTPException(status_code=404, detail="No active playback session")
     path = s.dir / filename
+    # A segment beyond the generated region can never arrive: ffmpeg writes them in order, so if the
+    # predecessor is not there this one is not next. Answering now instead of waiting it out is what
+    # keeps a seek past the produced region — or a deliberate flood of hopeless names — from parking
+    # threadpool workers and their DB connections (see `segment_may_arrive`).
+    if not plex_stream.segment_may_arrive(s.dir, filename):
+        raise HTTPException(status_code=404, detail="Not available yet")
     timeout = 30 if ext == ".m3u8" else 20
     # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
     # whole timeout: this is a SYNC route on the ~40-slot threadpool, holding a pooled DB connection
diff --git a/backend/tests/test_plex_hls_file_route.py b/backend/tests/test_plex_hls_file_route.py
index 8be286c7..17c3ab72 100644
--- a/backend/tests/test_plex_hls_file_route.py
+++ b/backend/tests/test_plex_hls_file_route.py
@@ -24,8 +24,11 @@ from app.plex import stream as plex_stream
 
 
 class _Proc:
+    def __init__(self, running: bool = False):
+        self.running = running
+
     def poll(self):
-        return 0  # finished: `wait_for` may not poll out its whole timeout on a missing file
+        return None if self.running else 0
 
     def terminate(self):
         pass
@@ -35,10 +38,10 @@ class _Proc:
 
 
 class _Session:
-    def __init__(self, session_id: str, directory):
+    def __init__(self, session_id: str, directory, running: bool = False):
         self.id = session_id
         self.dir = directory
-        self.proc = _Proc()
+        self.proc = _Proc(running)
         self.last_access = time.time()
 
 
@@ -75,6 +78,7 @@ def _client(db, monkeypatch):
 def test_a_segment_is_served_from_the_session_the_url_names(db, monkeypatch, tmp_path, sessions):
     d = tmp_path / "m1_0_0_+0.00"
     d.mkdir()
+    (d / "seg_11.ts").write_bytes(b"")  # its predecessor, so seg_12 is the next one
     (d / "seg_12.ts").write_bytes(b"mine")
     sessions["m1"] = _Session("sid-a", d)
     client = _client(db, monkeypatch)
@@ -93,6 +97,7 @@ def test_a_segment_of_a_replaced_session_is_a_404_not_the_new_sessions_bytes(
     next segment must fail honestly — the player reclaims at the playhead — not arrive as B's."""
     theirs = tmp_path / "m1_1500_0_+0.00"
     theirs.mkdir()
+    (theirs / "seg_11.ts").write_bytes(b"")
     (theirs / "seg_12.ts").write_bytes(b"theirs")
     sessions["m1"] = _Session("sid-b", theirs)
     client = _client(db, monkeypatch)
@@ -127,12 +132,15 @@ def test_a_playlist_with_no_live_session_is_a_404_not_a_silent_restart_at_zero(
 
 def test_a_segment_that_will_never_arrive_fails_at_once(db, monkeypatch, tmp_path, sessions):
     """`stream_hls_file` is a SYNC route: it runs on the ~40-slot threadpool and holds a pooled DB
-    connection while it waits. Waiting without the producer's handle polled out the whole 20 s even
-    when that ffmpeg had already exited and no segment could ever appear — one ordinary seek past the
-    produced region parked a worker and a connection for 20 s (deep-review round 5)."""
+    connection while it waits. It used to poll out the whole 20 s for a name that could never appear
+    — an ordinary seek past the produced region was enough to park a worker and a connection, and
+    forty hopeless names parked the API (deep-review round 5). ffmpeg writes segments in order, so a
+    segment whose predecessor is absent is not the next one, and that is knowable at once — even
+    while ffmpeg is still running, which is the case `proc` alone cannot shorten."""
     d = tmp_path / "m1_0_0_+0.00"
     d.mkdir()
-    sessions["m1"] = _Session("sid-a", d)  # its _Proc.poll() reports a finished ffmpeg
+    (d / "seg_0.ts").write_bytes(b"x")  # the session is producing; seg_99999 is simply not next
+    sessions["m1"] = _Session("sid-a", d, running=True)
     client = _client(db, monkeypatch)
     started = time.monotonic()
     try:
diff --git a/frontend/src/components/ui/dialogFocus.ts b/frontend/src/components/ui/dialogFocus.ts
index 25626aa0..f52e5b3a 100644
--- a/frontend/src/components/ui/dialogFocus.ts
+++ b/frontend/src/components/ui/dialogFocus.ts
@@ -1,4 +1,4 @@
-import { useEffect, useState, type RefObject } from "react";
+import { useEffect, useRef, useState, type RefObject } from "react";
 
 // The focus half of the dialog contract, in ONE place. `ui/Modal` owns it for every dialog that goes
 // through the shell; the onboarding wizard renders its own shell (a bare `ui/Overlay`, because it is
@@ -54,19 +54,47 @@ export function useDialogChrome(scopeRef: RefObject<HTMLElement | null>): void {
   // later (in the effect) would capture a now-inside element that unmounts on close, stranding focus
   // on <body>. useState initializer runs exactly once, on first render.
   const [restoreTo] = useState(() => document.activeElement as HTMLElement | null);
+  // What the dialog is focused ON, so a RE-mount can put the focus back where it was rather than on
+  // the first control. React 18's StrictMode runs every effect mount→cleanup→mount in development:
+  // the cleanup hands focus back to the trigger, and the second mount then found the focus outside
+  // the dialog and moved it to the first focusable — taking it off the `autoFocus` field a beat
+  // after the browser had put it there. Measured in Chrome: the command palette opened with the
+  // focus on its ✕ in dev and on its search field in prod, from the same code (round 5).
+  const focusedRef = useRef<HTMLElement | null>(null);
+  // Whether the dialog still holds the focus. Read at cleanup rather than computed there: by the
+  // time a passive cleanup runs on a real unmount the panel is already out of the document and the
+  // focus has fallen to <body>, so "does the panel contain activeElement" answers false for both a
+  // close and a user who clicked away — and those two want opposite things.
+  const heldRef = useRef(true);
   useEffect(() => {
     const prev = document.body.style.overflow;
     document.body.style.overflow = "hidden";
     // Initial focus: unless an autoFocus child already placed it inside (e.g. a rename input), move
-    // focus to the first control so the dialog opens focused, not stranded on the background.
+    // focus to where this dialog was focused before — or, the first time, to the first control, so
+    // the dialog opens focused rather than stranded on the background.
     const scope = scopeRef.current;
     if (scope && !scope.contains(document.activeElement)) {
-      (focusablesIn(scope)[0] ?? scope).focus();
+      const back = focusedRef.current;
+      const target =
+        (back?.isConnected && scope.contains(back) ? back : null) ??
+        focusablesIn(scope)[0] ??
+        scope;
+      target.focus();
     }
+    const onFocusIn = () => {
+      const inside = scopeRef.current?.contains(document.activeElement) ?? false;
+      heldRef.current = inside;
+      if (inside) focusedRef.current = document.activeElement as HTMLElement;
+    };
+    onFocusIn();
+    document.addEventListener("focusin", onFocusIn);
     return () => {
+      document.removeEventListener("focusin", onFocusIn);
       document.body.style.overflow = prev;
-      // Restore focus to the trigger, if it's still in the document and focusable.
-      if (restoreTo && restoreTo.isConnected) restoreTo.focus();
+      // Restore focus to the trigger, if it's still in the document and focusable — and only if the
+      // dialog still held the focus. Once the user has moved it elsewhere, taking it back is the
+      // rudest thing a closing dialog can do.
+      if (heldRef.current && restoreTo && restoreTo.isConnected) restoreTo.focus();
     };
   }, [restoreTo, scopeRef]);
 }

From 7f17b17c13d1b497333a6bac55e97b7acc28d4ba Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 05:49:38 +0200
Subject: [PATCH 42/52] fix(plex): an HLS session's file names are one
 vocabulary, and a name it cannot produce fails at once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 5 added a guard so a request for a segment beyond the produced region
answers instead of polling out the full timeout — the route is a SYNC one, so
every such wait parks a threadpool worker and, through `current_user`, a pooled
DB connection. Measured against real ffmpeg, the guard could not fire where it
mattered.

`-hls_segment_filename seg_%v_%d.ts` substitutes the VARIANT first: a dual-audio
session writes seg_0_0.ts (video) and seg_a0_0.ts / seg_a1_0.ts (the `name:aN`
renditions). The regex read those as sequence-first, so every video segment
parsed as segment 0 and every audio segment did not parse at all — the guard was
inert on every multi-audio item, which is most of this library. `_seg()` carried
the same inversion: the warm-up waited 8 s for `seg_1_0.ts`, a name ffmpeg never
writes, on every multi-audio session start AND every seek-restart.

The layout is now one constant plus one parser (`segment_name` /
`_SEG_NAME_RE`), with a test pinning them to each other, instead of three
comments that could drift — and they had drifted, all three ways.

The guard is also a positive rule now. It was a blocklist, so anything that was
not a single-audio segment name was waved through: `GET …/anything.m3u8` still
parked a worker for 30 s, while the route's comment claimed a flood of hopeless
names was what it prevented. A session produces its playlists and its segments
and nothing else. `.vtt` leaves `_HLS_CT` with it — ffmpeg runs with `-sn` and
subtitles are a separate route, so that extension could only ever name a file
that will not arrive.

Also here:
- A 5000-digit segment index reached the client as a 500: `int()` on an
  unbounded digit run raises past 4300 digits and only OSError was caught. The
  name is bounded on the route and the index in the regex — the same bug class
  the subtitle routes were bounded for.
- A session torn down between the wait and the read is a 404, not a 500. `_kill`
  rmtrees the directory and no lock spans those two steps; the player's recovery
  is keyed on the STATUS, so a 500 skipped the reclaim and ended playback with
  "couldn't play" instead of restarting at the playhead. The trigger is ordinary
  — `loadSession` awaits the new session before destroying the old hls instance.
- Two comments claimed an open player checkpoints every 10 s "whether or not it
  is playing", which is the stated reason the 30 s finished-idle reap is safe.
  `flush` sends nothing once the finish latch is up, or before a position is
  known. The states it does cover — playing or paused mid-item — are the ones
  the rule needs; the comments now say that instead of more.
- The route's tests leave the DB lane: the route reads nothing from the database
  since the auto-start was removed, and there those four regressions SKIP on a
  machine with no Postgres while pytest prints green.

14 tests, mutation-checked: the old parse, the old warm-up name, the blocklist,
both bounds off the absurd name, the unguarded read, and the route dropping
`proc` — each red on the test that names it.
---
 backend/app/plex/stream.py                |  74 ++++++---
 backend/app/routes/plex/playback.py       |  51 +++++--
 backend/tests/test_plex_hls_file_route.py | 176 ++++++++++++++++------
 3 files changed, 222 insertions(+), 79 deletions(-)

diff --git a/backend/app/plex/stream.py b/backend/app/plex/stream.py
index 6ab7a95d..b6b51161 100644
--- a/backend/app/plex/stream.py
+++ b/backend/app/plex/stream.py
@@ -56,6 +56,10 @@ _SEG_SECONDS = 6
 # worse than the old zero-buffer behaviour).
 _WARMUP_SEGMENTS = 3
 _WARMUP_SEG_TIMEOUT_S = 8.0
+# The HLS variant ffmpeg gives the VIDEO rendition of a multi-audio session. `-var_stream_map` names
+# each audio rendition (`name:a0`, `a1`, …) but leaves the video one unnamed, so ffmpeg falls back to
+# its index for that one. See `segment_name` for why this is a constant and not a comment.
+_VIDEO_VARIANT = "0"
 _SESSION_IDLE_S = 600  # reap a session with no access for this long
 # A session directory is named `{rating_key}_{int(start_s)}_{tag}_{aoff:+.2f}` (see start_session);
 # before multi-audio it was just `{rating_key}_{int(start_s)}`. `sweep_orphans` deletes ONLY names
@@ -503,7 +507,9 @@ def _ffmpeg_cmd(
     if audio_langs:
         # MULTI-RENDITION: map EVERY audio track as an alternate HLS rendition in one group, so hls.js
         # switches audio CLIENT-SIDE on the same timeline (no session restart, no drift) — the premium
-        # audio-switch path. Produces master.m3u8 + stream_%v.m3u8 (v0=video, v1..=audio) + seg_%v_%d.ts.
+        # audio-switch path. Produces master.m3u8 + one stream_%v.m3u8 and seg_%v_*.ts per variant,
+        # where %v is the video rendition's index ("0") and each audio rendition's `name:` (a0, a1,
+        # …) — see `_SEG_NAME_RE`, which is the one place that layout is written down.
         args += ["-map", "0:v:0"]
         for i in range(len(audio_langs)):
             args += ["-map", f"{ai}:a:{i}?"]
@@ -630,8 +636,7 @@ def start_session(
     directory = _HLS_ROOT / f"{key}_{int(start_s)}_{tag}_{aoff:+.2f}"
 
     def _seg(i: int) -> Path:
-        # multi-audio: the video rendition is variant v0 → seg_{i}_0.ts; single-audio → seg_{i}.ts
-        return directory / (f"seg_{i}_0.ts" if is_multi else f"seg_{i}.ts")
+        return directory / segment_name(i, is_multi)
 
     def _spawn(
         hw: bool, tonemap: bool = False, *, replace_only: "HlsSession | None" = None
@@ -758,32 +763,51 @@ def current_session(key: str) -> HlsSession | None:
         return s
 
 
-# A segment file, single-audio (`seg_12.ts`) or one rendition of a multi-audio session
-# (`seg_12_0.ts`). ffmpeg writes them strictly in order, which is what makes `segment_may_arrive`
-# exact rather than a heuristic.
-_SEG_NAME_RE = re.compile(r"^seg_(\d+)(_\d+)?\.ts$")
+# The names ffmpeg writes into a session directory, in ONE place. Getting this wrong is invisible —
+# every path that reads a name falls back to "wait and see" — so it is a constant plus a matching
+# parser, not three comments that can drift (they did: deep-review round 6 found the regex, `_seg`
+# and the comment above `_ffmpeg_cmd` all disagreeing).
+#
+# MEASURED (ffmpeg 8.1.1, this repo's own argv): `-hls_segment_filename seg_%v_%d.ts` substitutes
+# `%v` with the VARIANT and `%d` with the SEQUENCE — variant FIRST. A dual-audio session writes
+# seg_0_0.ts… (video, the unnamed variant) plus seg_a0_0.ts… / seg_a1_0.ts… (the `name:aN` audio
+# renditions), and the playlists beside them are master.m3u8 + stream_0/a0/a1.m3u8. Single-audio
+# uses `seg_%d.ts` + index.m3u8, with no variant field at all.
+_SEG_NAME_RE = re.compile(r"^seg_(?:([0-9a-z]{1,4})_)?(\d{1,9})\.ts$")
+_PLAYLIST_NAME_RE = re.compile(r"^(?:master|index|stream_[0-9a-z]{1,4})\.m3u8$")
 
 
-def segment_may_arrive(directory: Path, filename: str) -> bool:
+def segment_name(seq: int, is_multi: bool) -> str:
+    """The file ffmpeg writes for the `seq`-th VIDEO segment of a session."""
+    return f"seg_{_VIDEO_VARIANT}_{seq}.ts" if is_multi else f"seg_{seq}.ts"
+
+
+def artifact_may_arrive(directory: Path, filename: str) -> bool:
     """Whether waiting for `filename` can possibly end in a file.
 
-    ffmpeg produces segments sequentially, so a segment whose PREDECESSOR does not exist yet is not
-    the next one — it is somewhere beyond the generated region, and no amount of waiting will
-    conjure it. Saying so at once matters because the route that waits is a SYNC one: it holds a
-    thread off the ~40-slot pool, and a pooled DB connection with it, for the whole timeout. An
-    ordinary seek past the produced region was enough to park one for 20 s, and forty concurrent
-    requests for a name that will never exist parked the whole API (deep-review round 5).
+    Positive rule, not a blocklist: a session produces segments and playlists and NOTHING else, so
+    any other name is refused at once. ffmpeg also produces segments strictly in order, so a segment
+    whose PREDECESSOR does not exist yet is not the next one — it is beyond the generated region,
+    and no amount of waiting will conjure it. Playlists are the one thing that must still be waited
+    for: they are rewritten continuously and have no ordering to read.
 
-    Anything that is not a segment (a playlist, a WebVTT track) is left to the timeout: those are
-    rewritten continuously and have no ordering to read."""
+    Saying no at once matters because the route that waits is a SYNC one: it holds a thread off the
+    ~40-slot pool, and a pooled DB connection with it, for the whole timeout. An ordinary seek past
+    the produced region was enough to park one for 20 s, and forty concurrent requests for a name
+    that will never exist parked the whole API (deep-review round 5). Round 5's guard read only
+    single-audio segment names, so both halves of that were still fully reachable: every multi-audio
+    name fell through, and so did any `.m3u8`/`.vtt` name at all."""
+    if _PLAYLIST_NAME_RE.match(filename):
+        return True
     m = _SEG_NAME_RE.match(filename)
     if m is None:
+        return False
+    variant, seq = m.group(1), int(m.group(2))
+    if seq == 0:
         return True
-    idx = int(m.group(1))
-    if idx == 0:
-        return True
+    prev = f"seg_{variant}_{seq - 1}.ts" if variant else f"seg_{seq - 1}.ts"
     try:
-        return (directory / f"seg_{idx - 1}{m.group(2) or ''}.ts").exists()
+        return (directory / prev).exists()
     except OSError:
         return False
 
@@ -873,9 +897,13 @@ def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
     and with its forward buffer full a paused player fetches nothing at all. With the 30 s rule that
     killed a one-minute pause, and playback died ~30 s after resuming (deep-review round 4).
 
-    What makes the short rule safe again is that fetching is no longer the only signal: an open
-    player checkpoints its position every 10 s, and that route calls `touch_session`, so a viewer who
-    is merely paused says so far more often than this rule asks (round 5). Round 4's blanket
+    What makes the short rule safe again is that fetching is no longer the only signal: a player
+    parked MID-ITEM checkpoints its position every 10 s, and that route calls `touch_session`, so a
+    viewer who is merely paused says so far more often than this rule asks (round 5). The heartbeat
+    stops once the item is finished or before a position is known (`usePlexProgress.flush`) — both
+    states where reaping is correct, and where the player's 404 → reclaim recovers a viewer who
+    scrubs back in anyway. Do not restate this as "every 10 s whether or not it is playing": round 6
+    found that claim in two comments and not in the code. Round 4's blanket
     `reap_abandoned` bought the same safety by keeping every finished session for ten minutes — each
     one a whole segmented copy of the film on a volume shared with the download center."""
     now = time.time()
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 5cd12387..42105e09 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -323,9 +323,13 @@ def item_progress(
     `_should_push_resume`). `final` (sent on pause / seek / pagehide / unmount) pushes immediately and
     resets the throttle window, so Plex sees a settled position the instant the user pauses or seeks."""
     it = item_or_404(db, rating_key)
-    # An open player checkpoints every 10 s whether or not it is playing, so this is the signal that a
-    # PAUSED viewer still wants their HLS session — the one thing `last_access` could not see, since
-    # it moved only on a file fetch and a paused player fetches nothing (see stream.reap_idle).
+    # A player parked mid-item — playing or PAUSED — checkpoints every 10 s, so this is the signal
+    # that such a viewer still wants their HLS session: the one thing `last_access` could not see,
+    # since it moved only on a file fetch and a paused player fetches nothing (see
+    # stream.reap_idle). It is NOT every open player: `usePlexProgress.flush` sends nothing once the
+    # finish latch is up, or before the first position is known. Those are the states in which
+    # reaping is the right answer anyway, and a viewer who scrubs back into a reaped session gets
+    # the same 404 → reclaim the player already handles.
     plex_stream.touch_session(str(rating_key))
     position = max(0, int(body.position_seconds))
     duration = int(body.duration_seconds)
@@ -622,11 +626,18 @@ def stream_file(
     return FileResponse(str(src))  # Starlette honours the Range header (206)
 
 
+# What a session directory can contain, and nothing else. No `.vtt`: ffmpeg runs with `-sn` and
+# subtitles are independent tracks served by GET /subtitle, so a WebVTT name here could only ever be
+# a name that will not arrive — and accepting it cost a 20 s parked worker per request.
 _HLS_CT = {
     ".m3u8": "application/vnd.apple.mpegurl",
     ".ts": "video/mp2t",
-    ".vtt": "text/vtt",
 }
+# A real artifact name is ~20 characters. The bound is what keeps an absurd one out of the parser:
+# `int()` on an unbounded digit run raises ValueError past 4300 digits (CPython's
+# `sys.get_int_max_str_digits`), which reached the client as a 500 — the same shape of bug the
+# subtitle routes were bounded for (`_RatingKey`, above).
+_HLS_NAME_MAX = 128
 
 
 @router.get("/stream/{rating_key}/hls/{session_id}/{filename}")
@@ -650,17 +661,24 @@ def stream_hls_file(
     auto-start could only ever begin at 0, silently throwing away the viewer's position."""
     # Filename must be a plain hls artifact — no path separators, only the expected extensions.
     ext = "." + filename.rsplit(".", 1)[-1] if "." in filename else ""
-    if ext not in _HLS_CT or "/" in filename or "\\" in filename or ".." in filename:
+    if (
+        len(filename) > _HLS_NAME_MAX
+        or ext not in _HLS_CT
+        or "/" in filename
+        or "\\" in filename
+        or ".." in filename
+    ):
         raise HTTPException(status_code=404, detail="Not found")
     s = plex_stream.current_session(str(rating_key))
     if s is None or s.id != session_id:
         raise HTTPException(status_code=404, detail="No active playback session")
     path = s.dir / filename
-    # A segment beyond the generated region can never arrive: ffmpeg writes them in order, so if the
-    # predecessor is not there this one is not next. Answering now instead of waiting it out is what
-    # keeps a seek past the produced region — or a deliberate flood of hopeless names — from parking
-    # threadpool workers and their DB connections (see `segment_may_arrive`).
-    if not plex_stream.segment_may_arrive(s.dir, filename):
+    # Only a name this session can actually produce is worth waiting for: the playlists, and a
+    # segment whose predecessor is already on disk (ffmpeg writes them in order, so if it is not
+    # there this one is not next). Answering now instead of waiting it out is what keeps a seek past
+    # the produced region — or a deliberate flood of hopeless names — from parking threadpool
+    # workers and their DB connections (see `artifact_may_arrive`).
+    if not plex_stream.artifact_may_arrive(s.dir, filename):
         raise HTTPException(status_code=404, detail="Not available yet")
     timeout = 30 if ext == ".m3u8" else 20
     # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
@@ -669,8 +687,19 @@ def stream_hls_file(
     # past the produced region was enough to do it (round 5).
     if not plex_stream.wait_for(path, timeout, proc=s.proc):
         raise HTTPException(status_code=404, detail="Not available yet")
+    try:
+        content = path.read_bytes()
+    except OSError:
+        # The session was torn down between the wait and the read — `_kill` rmtrees the whole
+        # directory, and nothing holds `_lock` across those two steps. It has to present as the same
+        # 404 a gone session does: the player's recovery is keyed on the STATUS (`code === 404`), so
+        # a 500 here skipped the reclaim and ended playback with "couldn't play" instead of
+        # restarting at the playhead. Ordinary trigger: `loadSession` awaits the new session — which
+        # kills and rmtrees the old one — before destroying the old hls instance, so the outgoing
+        # instance's in-flight segment request races the rmtree on every seek-restart.
+        raise HTTPException(status_code=404, detail="No active playback session") from None
     return Response(
-        content=path.read_bytes(),
+        content=content,
         media_type=_HLS_CT[ext],
         headers={"Cache-Control": "no-store"},
     )
diff --git a/backend/tests/test_plex_hls_file_route.py b/backend/tests/test_plex_hls_file_route.py
index 17c3ab72..448b2bfc 100644
--- a/backend/tests/test_plex_hls_file_route.py
+++ b/backend/tests/test_plex_hls_file_route.py
@@ -7,7 +7,9 @@ session's twelfth segment: bytes produced from a different `-ss` offset under `-
 timeline the client is not on. Wrong content with a success status is the one failure a player cannot
 notice, and the reclaim-on-404 added in round 4 could never fire on it (deep-review round 5).
 
-DB lane (`db` fixture) — skipped when no Postgres is reachable.
+No `db` fixture: the route reads nothing from the database (its own `Depends(get_db)` went with the
+removed auto-start, and `current_user` is overridden wholesale), so these must not sit in the DB
+lane — there they SKIP on a machine with no Postgres while pytest prints green (round 6).
 """
 
 import time
@@ -17,9 +19,8 @@ from fastapi.testclient import TestClient
 
 import app.state as state
 from app.auth import current_user
-from app.db import get_db
 from app.main import app
-from app.models import PlexItem, PlexLibrary, User
+from app.models import User
 from app.plex import stream as plex_stream
 
 
@@ -52,46 +53,30 @@ def sessions(monkeypatch):
     return live
 
 
-def _client(db, monkeypatch):
+@pytest.fixture
+def client(monkeypatch):
     monkeypatch.setattr(state, "_configured_cache", True)
-    lib = PlexLibrary(plex_key="1", title="Movies", kind="movie", enabled=True)
-    db.add(lib)
-    db.flush()
-    db.add(
-        PlexItem(
-            rating_key="m1",
-            library_id=lib.id,
-            kind="movie",
-            title="A Movie",
-            file_path="/media/a.mkv",
-            playable="remux",
-        )
-    )
     user = User(email="hls@example.com")
-    db.add(user)
-    db.commit()
-    app.dependency_overrides[get_db] = lambda: db
     app.dependency_overrides[current_user] = lambda: user
-    return TestClient(app)
+    try:
+        yield TestClient(app)
+    finally:
+        app.dependency_overrides.pop(current_user, None)
 
 
-def test_a_segment_is_served_from_the_session_the_url_names(db, monkeypatch, tmp_path, sessions):
+def test_a_segment_is_served_from_the_session_the_url_names(client, tmp_path, sessions):
     d = tmp_path / "m1_0_0_+0.00"
     d.mkdir()
     (d / "seg_11.ts").write_bytes(b"")  # its predecessor, so seg_12 is the next one
     (d / "seg_12.ts").write_bytes(b"mine")
     sessions["m1"] = _Session("sid-a", d)
-    client = _client(db, monkeypatch)
-    try:
-        r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
-    finally:
-        app.dependency_overrides.clear()
+    r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
     assert r.status_code == 200, r.text
     assert r.content == b"mine"
 
 
 def test_a_segment_of_a_replaced_session_is_a_404_not_the_new_sessions_bytes(
-    db, monkeypatch, tmp_path, sessions
+    client, tmp_path, sessions
 ):
     """Viewer A is at 0:00; viewer B seeks to 25:00 and their session takes the registry slot. A's
     next segment must fail honestly — the player reclaims at the playhead — not arrive as B's."""
@@ -100,17 +85,13 @@ def test_a_segment_of_a_replaced_session_is_a_404_not_the_new_sessions_bytes(
     (theirs / "seg_11.ts").write_bytes(b"")
     (theirs / "seg_12.ts").write_bytes(b"theirs")
     sessions["m1"] = _Session("sid-b", theirs)
-    client = _client(db, monkeypatch)
-    try:
-        r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
-    finally:
-        app.dependency_overrides.clear()
+    r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
     assert r.status_code == 404, r.text
     assert b"theirs" not in r.content
 
 
 def test_a_playlist_with_no_live_session_is_a_404_not_a_silent_restart_at_zero(
-    db, monkeypatch, sessions
+    client, monkeypatch, sessions
 ):
     """The entry playlist used to auto-start a session when none was registered — always at 0.0,
     silently throwing away the viewer's position. A 404 sends the player through its own reclaim,
@@ -121,16 +102,12 @@ def test_a_playlist_with_no_live_session_is_a_404_not_a_silent_restart_at_zero(
         "start_session",
         lambda *a, **k: started.append(a[2] if len(a) > 2 else 0.0),
     )
-    client = _client(db, monkeypatch)
-    try:
-        r = client.get("/api/plex/stream/m1/hls/sid-gone/index.m3u8")
-    finally:
-        app.dependency_overrides.clear()
+    r = client.get("/api/plex/stream/m1/hls/sid-gone/index.m3u8")
     assert r.status_code == 404, r.text
     assert started == []
 
 
-def test_a_segment_that_will_never_arrive_fails_at_once(db, monkeypatch, tmp_path, sessions):
+def test_a_segment_that_will_never_arrive_fails_at_once(client, tmp_path, sessions):
     """`stream_hls_file` is a SYNC route: it runs on the ~40-slot threadpool and holds a pooled DB
     connection while it waits. It used to poll out the whole 20 s for a name that could never appear
     — an ordinary seek past the produced region was enough to park a worker and a connection, and
@@ -141,13 +118,122 @@ def test_a_segment_that_will_never_arrive_fails_at_once(db, monkeypatch, tmp_pat
     d.mkdir()
     (d / "seg_0.ts").write_bytes(b"x")  # the session is producing; seg_99999 is simply not next
     sessions["m1"] = _Session("sid-a", d, running=True)
-    client = _client(db, monkeypatch)
     started = time.monotonic()
-    try:
-        r = client.get("/api/plex/stream/m1/hls/sid-a/seg_99999.ts")
-    finally:
-        app.dependency_overrides.clear()
+    r = client.get("/api/plex/stream/m1/hls/sid-a/seg_99999.ts")
     elapsed = time.monotonic() - started
     assert r.status_code == 404, r.text
     # The wait is 20 s; anything in that neighbourhood means the producer's exit was not consulted.
     assert elapsed < 2.0, f"waited {elapsed:.1f}s for a segment that can never arrive"
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        "seg_0_9000.ts",  # the VIDEO rendition of a multi-audio session: variant 0, segment 9000
+        "seg_a0_9000.ts",  # the first audio rendition: `name:a0` from -var_stream_map
+    ],
+)
+def test_a_multi_audio_segment_beyond_the_region_fails_at_once_too(
+    client, tmp_path, sessions, name
+):
+    """The round-5 guard read `seg_<seq>_<variant>.ts`, but ffmpeg substitutes `%v` FIRST — so the
+    real names are `seg_<variant>_<seq>.ts` and every multi-audio request fell through to the full
+    20 s wait: the video rendition because its variant "0" parsed as segment 0, the audio renditions
+    (`a0`, `a1`) because they did not parse at all. Dual-audio is the common shape in this library,
+    so the guard was inert exactly where it was needed (round 6)."""
+    d = tmp_path / "m1_0_multi_+0.00"
+    d.mkdir()
+    (d / "seg_0_0.ts").write_bytes(b"x")
+    (d / "seg_a0_0.ts").write_bytes(b"x")
+    sessions["m1"] = _Session("sid-a", d, running=True)
+    started = time.monotonic()
+    r = client.get(f"/api/plex/stream/m1/hls/sid-a/{name}")
+    elapsed = time.monotonic() - started
+    assert r.status_code == 404, r.text
+    assert elapsed < 2.0, f"waited {elapsed:.1f}s for {name}"
+
+
+def test_a_multi_audio_segment_whose_predecessor_exists_is_served(client, tmp_path, sessions):
+    """The other half of the same rule: reading the names correctly must not start refusing real
+    ones. `seg_a0_1.ts` follows `seg_a0_0.ts` — the previous SEGMENT of that rendition, not the
+    previous variant."""
+    d = tmp_path / "m1_0_multi_+0.00"
+    d.mkdir()
+    (d / "seg_a0_0.ts").write_bytes(b"x")
+    (d / "seg_a0_1.ts").write_bytes(b"audio")
+    sessions["m1"] = _Session("sid-a", d, running=True)
+    r = client.get("/api/plex/stream/m1/hls/sid-a/seg_a0_1.ts")
+    assert r.status_code == 200, r.text
+    assert r.content == b"audio"
+
+
+def test_a_name_the_session_cannot_produce_fails_at_once(client, tmp_path, sessions):
+    """The guard was a blocklist: anything that was not a single-audio segment name was waved
+    through to the timeout, so `GET …/anything.m3u8` still parked a worker for the full 30 s — and
+    the route comment claimed a flood of hopeless names was what it prevented. A session produces
+    its playlists and its segments and nothing else, so any other name is answerable now."""
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    sessions["m1"] = _Session("sid-a", d, running=True)
+    started = time.monotonic()
+    r = client.get("/api/plex/stream/m1/hls/sid-a/nope.m3u8")
+    elapsed = time.monotonic() - started
+    assert r.status_code == 404, r.text
+    assert elapsed < 2.0, f"waited {elapsed:.1f}s for a playlist this session never writes"
+
+
+@pytest.mark.parametrize("digits", [100, 5000])
+def test_an_absurd_segment_index_is_a_404_not_a_500(client, tmp_path, sessions, digits):
+    """`int()` on an unbounded digit run raises ValueError past 4300 digits, and only OSError was
+    caught — so a long enough name reached the client as a 500 with a traceback. Same bug class the
+    subtitle routes were bounded for; the answer is the same 404 any other unproducible name gets."""
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    sessions["m1"] = _Session("sid-a", d, running=True)
+    r = client.get(f"/api/plex/stream/m1/hls/sid-a/seg_{'9' * digits}.ts")
+    assert r.status_code == 404, r.text
+
+
+def test_a_session_torn_down_during_the_read_is_a_404_not_a_500(
+    client, monkeypatch, tmp_path, sessions
+):
+    """`_kill` rmtrees the whole directory and nothing holds `_lock` across the wait and the read,
+    so the file can vanish in between — on every seek-restart, since `loadSession` awaits the new
+    session before destroying the old hls instance. The player's recovery is keyed on the 404
+    STATUS, so a 500 here skipped the reclaim and ended playback with "couldn't play"."""
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    (d / "seg_11.ts").write_bytes(b"")
+    sessions["m1"] = _Session("sid-a", d)
+    # The file existed when the wait checked, and is gone by the time the route reads it.
+    monkeypatch.setattr(plex_stream, "wait_for", lambda *a, **k: True)
+    r = client.get("/api/plex/stream/m1/hls/sid-a/seg_12.ts")
+    assert r.status_code == 404, r.text
+
+
+def test_a_dead_producer_is_not_waited_out(client, tmp_path, sessions):
+    """The route passes `proc` to `wait_for`. Without it a session whose ffmpeg has already exited
+    — a finished remux, a VAAPI init refusal — polls the whole 20 s for a segment that will never
+    be written, holding a threadpool worker and its pooled DB connection. The predecessor IS on
+    disk here, so `artifact_may_arrive` says yes and only `proc` can end the wait."""
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    (d / "seg_5.ts").write_bytes(b"x")
+    sessions["m1"] = _Session("sid-a", d, running=False)
+    started = time.monotonic()
+    r = client.get("/api/plex/stream/m1/hls/sid-a/seg_6.ts")
+    elapsed = time.monotonic() - started
+    assert r.status_code == 404, r.text
+    assert elapsed < 2.0, f"waited {elapsed:.1f}s on a producer that had already exited"
+
+
+@pytest.mark.parametrize("is_multi", [False, True])
+def test_the_name_ffmpeg_is_asked_for_is_a_name_the_guard_understands(tmp_path, is_multi):
+    """One vocabulary, enforced. `segment_name` is what the warm-up and the PTS probe wait for, and
+    `artifact_may_arrive` is what the route parses — they were three separate statements of the
+    layout and two of them were wrong. Pin them to each other instead."""
+    name = plex_stream.segment_name(3, is_multi)
+    prev = plex_stream.segment_name(2, is_multi)
+    assert not plex_stream.artifact_may_arrive(tmp_path, name)
+    (tmp_path / prev).write_bytes(b"x")
+    assert plex_stream.artifact_may_arrive(tmp_path, name)

From f8a31d48cfb774e4a47cf89f89900d14d8a3a819 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 05:49:58 +0200
Subject: [PATCH 43/52] fix(ui): a dialog keeps the focus it was given, and
 hands it back where it took it from
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 5 extracted `ui/dialogFocus` so no shell would hand-roll the focus
contract, then introduced four ways to lose the focus anyway — all four measured
in jsdom against the real components.

**Ownership was narrower than the trap.** `ui/Modal` traps Tab over the whole
dialog on purpose, so a toast's Undo or ✕ stays reachable; ownership was tracked
over the panel alone. Tabbing to that ✕ therefore read as "the user left the
dialog", and since removing a toast fires no `focusin` to re-arm, closing
afterwards skipped the restore and left the focus on <body>. Before this hook
existed the restore was unconditional, so it was a regression.

**A dialog stacked above us is still ours.** A nested `ui/Modal` portals into its
own host, so it is outside the outer dialog's root however wide that scope is
drawn — widening alone could not fix it. Both closing in one commit left the
focus on <body>: the outer skipped its restore, and the child's own target (a
control inside the outer panel) was already detached, because passive cleanups
run parent-first. Ownership now means "inside my dialog, or inside a modal layer
above it", which is what the rule always intended.

**The wizard disagreed with `ui/Modal` on its first line.** `trapTab(e, panel)`,
with neither the dialog-root scope (so its own toast host was outside the cycle
— the connection notice never auto-dismisses, and its ✕ was unreachable from the
keyboard) nor the `container` argument the JSDoc exists for: `panel.contains(
panel)` is true, so focus sitting ON the tabIndex=-1 panel matched no branch and
a Shift+Tab walked into the app behind the scrim. Both call sites now pass the
same three arguments.

**The toast handover was a render-phase read-modify-write.** A `useMemo` read a
module global that the next line overwrote; React re-invokes a component body
and every `useMemo` factory in it on a StrictMode double render, and the LAST
invocation commits — so the second pass re-read what the first had just written,
the takeover host classified its OWN new toast as inherited, and the dev build
behaved exactly like the code round 5 replaced. Snapshotted through a ref keyed
on `isTop`, so a repeated invocation of one render is a no-op.

And the fourth `aria-modal` shell, `Welcome`'s screenshot lightbox, is finally
swept into the same contract: it declared itself a modal dialog while leaving
the focus on the thumbnail behind an 80%-black scrim and letting Tab walk the
landing page underneath.

The headline fix of the previous commit — StrictMode's re-mount taking the focus
off an `autoFocus` field — had no test at all; deleting it left all 1009 green.
It has one now.

9 tests, mutation-checked against 8 mutations, each red on the test that names it.
---
 .../OnboardingWizard.dialog.dom.test.tsx      | 60 ++++++++++++++-
 frontend/src/components/OnboardingWizard.tsx  | 14 +++-
 frontend/src/components/Welcome.tsx           | 21 ++++--
 frontend/src/components/ui/Modal.dom.test.tsx | 73 +++++++++++++++++++
 .../ui/Modal.strictmode.dom.test.tsx          | 54 ++++++++++++++
 frontend/src/components/ui/Modal.tsx          |  7 +-
 .../ui/Toaster.strictmode.dom.test.tsx        | 66 +++++++++++++++++
 frontend/src/components/ui/Toaster.tsx        | 24 +++++-
 frontend/src/components/ui/dialogFocus.ts     | 36 +++++++--
 .../welcomeMode.render.dom.test.tsx           | 47 +++++++++++-
 10 files changed, 378 insertions(+), 24 deletions(-)
 create mode 100644 frontend/src/components/ui/Modal.strictmode.dom.test.tsx
 create mode 100644 frontend/src/components/ui/Toaster.strictmode.dom.test.tsx

diff --git a/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx b/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx
index d7bc0bca..5e3194bd 100644
--- a/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx
+++ b/frontend/src/components/OnboardingWizard.dialog.dom.test.tsx
@@ -8,7 +8,7 @@
 // `focusablesIn` filters on `el.offsetParent !== null` and jsdom reports null for everything, so the
 // trap is untestable as written without the same stub `ui/Modal.dom.test.tsx` uses.
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { render, cleanup, screen, fireEvent } from "@testing-library/react";
+import { render, cleanup, screen, fireEvent, act } from "@testing-library/react";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 
 vi.mock("react-i18next", async (importOriginal) => {
@@ -23,6 +23,7 @@ vi.mock("../lib/onboarding", () => ({ beginGrant: vi.fn(), endOnboarding: vi.fn(
 
 import OnboardingWizard from "./OnboardingWizard";
 import { api, type Me } from "../lib/api";
+import { clearAll, notify } from "../lib/notifications";
 
 const me = { id: 1, email: "a@b", can_read: false, can_write: false } as unknown as Me;
 
@@ -84,4 +85,61 @@ describe("the onboarding wizard as a dialog", () => {
     expect(document.activeElement).toBe(outside);
     outside.remove();
   });
+
+  it("holds a Shift+Tab that starts on the panel itself", () => {
+    // `Node.contains(self)` is true, so focus sitting ON the tabIndex=-1 panel — where a click on
+    // its dead space puts it — matched no branch of `trapTab` and the browser's native Shift+Tab
+    // ran, into the app behind the scrim. That is what the third argument exists for, and this
+    // caller was written without it on the very commit that extracted the helper (round 6).
+    mount();
+    const panel = screen.getByRole("dialog");
+    panel.focus();
+    expect(document.activeElement).toBe(panel);
+    const stops = [...panel.querySelectorAll<HTMLElement>("button, a[href]")];
+    fireEvent.keyDown(window, { key: "Tab", shiftKey: true });
+    expect(document.activeElement).toBe(stops[stops.length - 1]);
+  });
+
+  it("still hands the focus back after it visited the wizard's own toast", () => {
+    // Ownership has to be measured over the same scope the Tab trap uses. The wizard's toast host
+    // sits beside the panel and INSIDE the dialog, so tabbing to a toast's ✕ is legal — but read
+    // against the panel alone it said "the user left", and since removing the toast fires no
+    // focusin to re-arm, closing afterwards stranded the focus on <body> (round 6). Unlike
+    // `ui/Modal`, whose root carries the aria-modal attribute, nothing else can rescue this one.
+    const outside = document.createElement("button");
+    document.body.appendChild(outside);
+    outside.focus();
+    const { unmount } = mount();
+    act(() => void notify({ level: "error", message: "offline" }));
+    const dismissToast = screen.getByTitle("notifications.dismiss");
+    dismissToast.focus();
+    expect(document.activeElement).toBe(dismissToast);
+    act(() => clearAll()); // the toast goes away under the focus — no focusin follows
+    unmount();
+    expect(document.activeElement).toBe(outside);
+    outside.remove();
+  });
+
+  it("keeps its own toast's dismiss button inside the Tab cycle", () => {
+    // The wizard renders its own `<Toaster overlay>` beside the panel, and the connection notice it
+    // can raise never auto-dismisses — so a trap scoped to the panel alone left that ✕ permanently
+    // unreachable from the keyboard. `ui/Modal` spans the whole dialog for exactly this reason.
+    mount();
+    const panel = screen.getByRole("dialog");
+    act(() => void notify({ level: "error", message: "offline" }));
+    try {
+      const dismissToast = screen.getByTitle("notifications.dismiss");
+      expect(panel.contains(dismissToast)).toBe(false);
+      const stops = [...panel.querySelectorAll<HTMLElement>("button, a[href]")];
+      stops[stops.length - 1]!.focus();
+      fireEvent.keyDown(window, { key: "Tab" });
+      // No longer the edge: Tab carries on (natively) towards the toast instead of wrapping.
+      expect(document.activeElement).toBe(stops[stops.length - 1]);
+      dismissToast.focus();
+      fireEvent.keyDown(window, { key: "Tab" });
+      expect(document.activeElement).toBe(stops[0]);
+    } finally {
+      act(() => clearAll());
+    }
+  });
 });
diff --git a/frontend/src/components/OnboardingWizard.tsx b/frontend/src/components/OnboardingWizard.tsx
index 57b1d377..863b11d8 100644
--- a/frontend/src/components/OnboardingWizard.tsx
+++ b/frontend/src/components/OnboardingWizard.tsx
@@ -118,14 +118,22 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
   // into the app behind the scrim — where the focus ring is invisible (deep-review round 5). The trap
   // and the roles come from the same place `ui/Modal` gets them, not from a second hand-written copy.
   const panelRef = useRef<HTMLDivElement>(null);
+  const rootRef = useRef<HTMLDivElement>(null);
   const titleId = useId();
-  useDialogChrome(panelRef);
+  useDialogChrome(panelRef, rootRef);
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       // Only while nothing is above us: an error dialog opened from inside the wizard owns the Tab.
       if (e.key !== "Tab" || !layer.isTopmost()) return;
       const panel = panelRef.current;
-      if (panel) trapTab(e, panel);
+      // The SAME three arguments `ui/Modal` passes, for the same two reasons — and this call had
+      // neither of them (round 6, on the commit that extracted the helper so the two shells could
+      // not disagree). Scope is the whole dialog, so the toast host beside the panel stays in the
+      // Tab cycle (a sticky connection notice's ✕ was unreachable from the keyboard); `container`
+      // is the tabIndex=-1 panel, because `panel.contains(panel)` is true, so focus sitting ON the
+      // panel — where a click on its dead space puts it — matched no branch at all and a Shift+Tab
+      // walked out into the app behind the scrim.
+      if (panel) trapTab(e, rootRef.current ?? panel, panel);
     };
     window.addEventListener("keydown", onKey);
     return () => window.removeEventListener("keydown", onKey);
@@ -145,7 +153,7 @@ export default function OnboardingWizard({ me, onClose }: { me: Me; onClose: ()
 
   return (
     <Overlay>
-      <div className="fixed inset-0 z-overlay grid place-items-center p-4">
+      <div ref={rootRef} className="fixed inset-0 z-overlay grid place-items-center p-4">
         <div
           className="absolute inset-0 bg-black/50 animate-[overlayIn_0.2s_ease]"
           onClick={close}
diff --git a/frontend/src/components/Welcome.tsx b/frontend/src/components/Welcome.tsx
index 52b1edd2..68362b41 100644
--- a/frontend/src/components/Welcome.tsx
+++ b/frontend/src/components/Welcome.tsx
@@ -29,6 +29,7 @@ import { HttpError } from "../lib/api";
 import { setLanguage, type LangCode } from "../i18n";
 import LanguageSwitcher from "./LanguageSwitcher";
 import { Button } from "./ui/Button";
+import { trapTab, useDialogChrome } from "./ui/dialogFocus";
 import { inputCls } from "./ui/form";
 import { entryHash, entrySearch } from "../lib/entryUrl";
 import type { VerifyEntry } from "../lib/useVerifyEntry";
@@ -266,21 +267,27 @@ function Preview({
 // (aspect ratio preserved via object-contain). Closes on backdrop click, the ✕, or Escape.
 function Lightbox({ src, label, onClose }: { src: string; label: string; onClose: () => void }) {
   const { t } = useTranslation();
+  // The fourth `aria-modal` shell in the app, and the one the round-5 extraction did not sweep in:
+  // it declared itself a modal dialog while leaving focus on the thumbnail behind an 80%-black
+  // scrim, announcing nothing, and letting Tab walk the landing page underneath — the ✕ reachable
+  // only after tabbing past every remaining gallery shot (deep-review round 6). The contract comes
+  // from the same place `ui/Modal` and the wizard get theirs; the body-scroll lock moved with it.
+  const panelRef = useRef<HTMLDivElement>(null);
+  useDialogChrome(panelRef);
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       if (e.key === "Escape") onClose();
+      const panel = panelRef.current;
+      if (e.key === "Tab" && panel) trapTab(e, panel, panel);
     };
     window.addEventListener("keydown", onKey);
-    const prev = document.body.style.overflow;
-    document.body.style.overflow = "hidden"; // no background scroll while open
-    return () => {
-      window.removeEventListener("keydown", onKey);
-      document.body.style.overflow = prev;
-    };
+    return () => window.removeEventListener("keydown", onKey);
   }, [onClose]);
   return (
     <div
-      className="fixed inset-0 z-popover grid place-items-center bg-black/80 overlay-backdrop p-4 sm:p-8"
+      ref={panelRef}
+      tabIndex={-1}
+      className="fixed inset-0 z-popover grid place-items-center bg-black/80 overlay-backdrop p-4 sm:p-8 outline-none"
       onClick={onClose}
       role="dialog"
       aria-modal="true"
diff --git a/frontend/src/components/ui/Modal.dom.test.tsx b/frontend/src/components/ui/Modal.dom.test.tsx
index 7e5571ce..07e1816c 100644
--- a/frontend/src/components/ui/Modal.dom.test.tsx
+++ b/frontend/src/components/ui/Modal.dom.test.tsx
@@ -10,6 +10,7 @@
 // The overlay/history machinery (useBackToClose) is exercised in history.dom.test.ts, so it's mocked
 // out here to isolate the focus-trap behaviour from its module-global history side-effects.
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { useState } from "react";
 import { render, screen, act, cleanup } from "@testing-library/react";
 
 vi.mock("react-i18next", async (importOriginal) => {
@@ -199,6 +200,78 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
     expect(document.activeElement).toBe(trigger);
     document.body.removeChild(trigger);
   });
+
+  it("still restores the trigger after the focus visited the dialog's own toast", () => {
+    // The Tab trap deliberately spans the dialog ROOT so a toast's Undo/✕ is reachable; ownership
+    // was tracked over the PANEL, so touching that ✕ read as "the user left the dialog" and the
+    // restore was skipped — and removing the toast fires no focusin to re-arm it. Measured landing
+    // on <body> (deep-review round 6).
+    const trigger = document.createElement("button");
+    document.body.appendChild(trigger);
+    trigger.focus();
+    const { unmount } = render(
+      <Modal title="t" onClose={() => {}}>
+        <Body />
+      </Modal>,
+    );
+    act(() => void notify({ level: "error", message: "Nope" }));
+    const dismissToast = screen.getByTitle("notifications.dismiss");
+    dismissToast.focus();
+    expect(document.activeElement).toBe(dismissToast); // the scenario is actually being driven
+    act(() => clearAll()); // the toast goes away under the focus — no focusin follows
+    expect(document.activeElement).toBe(document.body);
+    unmount();
+    expect(document.activeElement).toBe(trigger);
+    document.body.removeChild(trigger);
+  });
+
+  it("restores the trigger when a dialog and the dialog stacked on it close together", () => {
+    // A nested Modal portals into its OWN host, so it is outside the outer dialog's root however
+    // wide that scope is drawn — reading that as "the user walked away" left the focus on <body>.
+    // The child cannot cover for it: passive cleanups run parent-first, and by then its own restore
+    // target (a control INSIDE the outer panel, captured when it opened) is already detached.
+    const trigger = document.createElement("button");
+    document.body.appendChild(trigger);
+    trigger.focus();
+    function Nested() {
+      const [open, setOpen] = useState(false);
+      return (
+        <Modal title="outer" onClose={() => {}}>
+          <button onClick={() => setOpen(true)}>open inner</button>
+          {open && (
+            <Modal title="inner" onClose={() => {}}>
+              <button>inner-body</button>
+            </Modal>
+          )}
+        </Modal>
+      );
+    }
+    const { unmount } = render(<Nested />);
+    act(() => void screen.getByText("open inner").click());
+    screen.getByText("inner-body").focus();
+    unmount();
+    expect(document.activeElement).toBe(trigger);
+    document.body.removeChild(trigger);
+  });
+
+  it("leaves the focus alone when the user moved it out of the dialog themselves", () => {
+    // The other half of the same rule, and the branch nothing drove: taking focus back from where
+    // the user deliberately put it is the rudest thing a closing dialog can do.
+    const trigger = document.createElement("button");
+    const elsewhere = document.createElement("button");
+    document.body.append(trigger, elsewhere);
+    trigger.focus();
+    const { unmount } = render(
+      <Modal title="t" onClose={() => {}}>
+        <Body />
+      </Modal>,
+    );
+    elsewhere.focus();
+    unmount();
+    expect(document.activeElement).toBe(elsewhere);
+    document.body.removeChild(trigger);
+    document.body.removeChild(elsewhere);
+  });
 });
 
 describe("Modal focus trap (raw jsdom — every offsetParent null)", () => {
diff --git a/frontend/src/components/ui/Modal.strictmode.dom.test.tsx b/frontend/src/components/ui/Modal.strictmode.dom.test.tsx
new file mode 100644
index 00000000..29d818da
--- /dev/null
+++ b/frontend/src/components/ui/Modal.strictmode.dom.test.tsx
@@ -0,0 +1,54 @@
+// @vitest-environment jsdom
+//
+// The dialog's focus behaviour under React 18 StrictMode — its own file because StrictMode's
+// mount→cleanup→mount is what the code under test reacts to, and the module-level layer stack in
+// ui/Modal (and the overlay-host registry in ui/Toaster) leaks between tests in one file.
+//
+// Round 5 fixed this in Chrome and shipped it with NO test: the second mount found the focus
+// outside the dialog (its own cleanup had just handed it back to the trigger) and moved it to the
+// first focusable — taking it off an `autoFocus` field a beat after the browser had put it there.
+// The command palette opened focused on its ✕ in dev and on its search field in prod, from the same
+// code. Round 6 measured that deleting the fix left all 1009 tests green, which is why this exists.
+//
+// Same offsetParent stub as Modal.dom.test.tsx: jsdom never lays out, so every element reports
+// offsetParent null and `focusablesIn` would see nothing.
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { StrictMode } from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
+});
+vi.mock("../../lib/history", () => ({ useBackToClose: () => {} }));
+
+import Modal from "./Modal";
+
+describe("Modal focus under StrictMode", () => {
+  let origDesc: PropertyDescriptor | undefined;
+  beforeEach(() => {
+    origDesc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetParent");
+    Object.defineProperty(HTMLElement.prototype, "offsetParent", {
+      configurable: true,
+      get(this: HTMLElement) {
+        return this.isConnected ? document.body : null;
+      },
+    });
+  });
+  afterEach(() => {
+    cleanup();
+    if (origDesc) Object.defineProperty(HTMLElement.prototype, "offsetParent", origDesc);
+  });
+
+  it("keeps the focus its autoFocus child asked for across the double mount", () => {
+    render(
+      <StrictMode>
+        <Modal title="t" onClose={() => {}}>
+          <input aria-label="field" autoFocus />
+        </Modal>
+      </StrictMode>,
+    );
+    // Without the remembered focus the second mount lands on the first focusable — the header ✕.
+    expect(document.activeElement).toBe(screen.getByLabelText("field"));
+  });
+});
diff --git a/frontend/src/components/ui/Modal.tsx b/frontend/src/components/ui/Modal.tsx
index cdb062ab..068baf70 100644
--- a/frontend/src/components/ui/Modal.tsx
+++ b/frontend/src/components/ui/Modal.tsx
@@ -42,15 +42,18 @@ export default function Modal({
   // still gets the focus (round 5). Both rules live in the hook; `ui/AnchoredPopover` shares it.
   const host = useFullscreenPortalHost();
   const panelRef = useRef<HTMLDivElement>(null);
+  const rootRef = useRef<HTMLDivElement>(null);
   const titleId = useId();
-  useDialogChrome(panelRef);
+  // Focus lands in the panel; OWNERSHIP is the whole dialog — the same element the Tab trap below
+  // is scoped to, toast host included. Tracking ownership over the panel alone meant tabbing to an
+  // in-dialog toast counted as leaving, and the close-time restore was then skipped (round 6).
+  useDialogChrome(panelRef, rootRef);
   const overlayOrder = useOverlayOrder();
 
   // Backdrop-click close must only fire when the press STARTED on the backdrop too. Otherwise a
   // drag that begins inside the dialog (e.g. selecting text in an input) and is released out on
   // the backdrop wrongly dismisses — the click event bubbles to the common ancestor (the backdrop).
   const pressedOnBackdrop = useRef(false);
-  const rootRef = useRef<HTMLDivElement>(null);
 
   // Keep a stable handler across renders so the stack id is assigned once per mount.
   const onCloseRef = useRef(onClose);
diff --git a/frontend/src/components/ui/Toaster.strictmode.dom.test.tsx b/frontend/src/components/ui/Toaster.strictmode.dom.test.tsx
new file mode 100644
index 00000000..877d3b93
--- /dev/null
+++ b/frontend/src/components/ui/Toaster.strictmode.dom.test.tsx
@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+//
+// The toast handover under React 18 StrictMode — its own file, because `lastTopIds` is module-level
+// state that leaks between tests.
+//
+// Round 5 made a taking-over host inherit "what the PREVIOUS top host last had on screen" by reading
+// a module global in a `useMemo` and overwriting it in the same render pass. React re-invokes a
+// component body — and every `useMemo` factory in it — on a StrictMode double render, and the LAST
+// invocation is what commits: so the second pass re-read what the first had just written, the host
+// classified its OWN new toast as inherited, and the dev build behaved exactly like the code round 5
+// replaced. Measured in Chrome and in jsdom: role "status" without StrictMode, null with it.
+//
+// The named case is UploadDialog's — notify and close the overlay in ONE handler, so the toast is
+// raised in the very commit that hands the app's host the top spot.
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { StrictMode, useState } from "react";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return { ...actual, useTranslation: () => ({ t: (key: string) => key }) };
+});
+
+import Toaster, { useOverlayOrder } from "./Toaster";
+import { clearAll, notify } from "../../lib/notifications";
+
+afterEach(() => {
+  cleanup();
+  clearAll();
+});
+
+/** An overlay with its own toast host, plus the app's — the shape every dialog produces. */
+function Harness() {
+  const [open, setOpen] = useState(true);
+  return (
+    <>
+      <button
+        onClick={() => {
+          notify({ level: "success", message: "Uploaded" });
+          setOpen(false); // …in the SAME handler: one batch, one commit
+        }}
+      >
+        finish
+      </button>
+      {open && <Overlay />}
+      <Toaster />
+    </>
+  );
+}
+function Overlay() {
+  const order = useOverlayOrder();
+  return <Toaster overlay order={order} />;
+}
+
+describe("the toast handover", () => {
+  it("announces a toast raised in the takeover commit, even under StrictMode", () => {
+    render(
+      <StrictMode>
+        <Harness />
+      </StrictMode>,
+    );
+    fireEvent.click(screen.getByText("finish"));
+    // Not inherited → it carries its own role, because the live region is not armed yet.
+    expect(screen.getByText("Uploaded").closest("[role]")?.getAttribute("role")).toBe("status");
+  });
+});
diff --git a/frontend/src/components/ui/Toaster.tsx b/frontend/src/components/ui/Toaster.tsx
index 497d0608..d2c83aeb 100644
--- a/frontend/src/components/ui/Toaster.tsx
+++ b/frontend/src/components/ui/Toaster.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useId, useMemo, useState, useSyncExternalStore } from "react";
+import { useEffect, useId, useRef, useState, useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { AlertCircle, AlertTriangle, CheckCircle2, Info, X, XCircle } from "lucide-react";
 import { dismiss, getActiveToasts, subscribe, type NotifLevel } from "../../lib/notifications";
@@ -43,6 +43,7 @@ const topHost = () => {
 
 // What the host that is currently top last rendered, for the next host to inherit. See `inherited`.
 let lastTopIds: number[] = [];
+const EMPTY_IDS: ReadonlySet<number> = new Set<number>();
 
 export default function Toaster({
   overlay = false,
@@ -81,9 +82,24 @@ export default function Toaster({
   // — the handover must be readable by the taking-over host in the SAME commit, and an effect
   // cleanup runs one phase too late; only the host that IS top writes, so the value is the losing
   // host's last screen either way.
-  const inherited = useMemo(() => new Set(isTop ? lastTopIds : []), [isTop]);
-  // AFTER the memo above has read the outgoing host's screen — this host's own first render as top
-  // would otherwise overwrite the handover with the toasts it is about to classify.
+  //
+  // Snapshotted through a ref keyed on `isTop`, not a `useMemo`: React re-invokes a component body
+  // — and every `useMemo` factory in it — on a StrictMode double render and on a restarted one, and
+  // the LAST invocation is what commits. With a memo the second pass re-read `lastTopIds` after the
+  // first pass had already overwritten it on the line below, so the takeover host classified its
+  // OWN new toast as inherited and the dev build behaved exactly like the code this replaced
+  // (measured in jsdom: role "status" without StrictMode, null with it — round 6). The ref only
+  // recomputes when `isTop` actually flips, so a repeated invocation of one render is a no-op.
+  const handover = useRef<{ top: boolean; ids: ReadonlySet<number> }>({
+    top: false,
+    ids: EMPTY_IDS,
+  });
+  if (handover.current.top !== isTop)
+    handover.current = { top: isTop, ids: new Set(isTop ? lastTopIds : []) };
+  const inherited = handover.current.ids;
+  // AFTER the snapshot above has read the outgoing host's screen — this host's own first render as
+  // top would otherwise overwrite the handover with the toasts it is about to classify. Writing the
+  // same value twice is harmless; that is the point of the ref.
   if (isTop) lastTopIds = toasts.map((n) => n.id);
   const [armed, setArmed] = useState(false);
   useEffect(() => {
diff --git a/frontend/src/components/ui/dialogFocus.ts b/frontend/src/components/ui/dialogFocus.ts
index f52e5b3a..00d444ab 100644
--- a/frontend/src/components/ui/dialogFocus.ts
+++ b/frontend/src/components/ui/dialogFocus.ts
@@ -47,8 +47,13 @@ export function trapTab(
 }
 
 /** The rest of the contract: lock the page behind, open focused, hand the focus back on close.
- *  `scopeRef` is the panel the focus should land in. */
-export function useDialogChrome(scopeRef: RefObject<HTMLElement | null>): void {
+ *  `scopeRef` is the panel the focus should land in; `ownerRef`, when the dialog is bigger than its
+ *  panel, is that whole dialog — it must be the SAME element `trapTab` is scoped to, or the two
+ *  disagree about what counts as "inside" (see `heldRef`). */
+export function useDialogChrome(
+  scopeRef: RefObject<HTMLElement | null>,
+  ownerRef?: RefObject<HTMLElement | null>,
+): void {
   // Capture the trigger to restore focus to, during THIS render — i.e. before commit runs the
   // dialog's autoFocus (or our own initial focus) and moves activeElement into the dialog. Reading it
   // later (in the effect) would capture a now-inside element that unmounts on close, stranding focus
@@ -65,6 +70,13 @@ export function useDialogChrome(scopeRef: RefObject<HTMLElement | null>): void {
   // time a passive cleanup runs on a real unmount the panel is already out of the document and the
   // focus has fallen to <body>, so "does the panel contain activeElement" answers false for both a
   // close and a user who clicked away — and those two want opposite things.
+  //
+  // Measured against the DIALOG, not the panel. The two scopes must be the same one the Tab trap
+  // uses, and `ui/Modal`'s trap deliberately spans the dialog root so an in-dialog toast's Undo/✕
+  // stays reachable — so tabbing to that ✕ read as "the user left the dialog", and since removing
+  // the toast fires no `focusin` to re-arm, closing the dialog afterwards stranded the focus on
+  // <body> instead of handing it back to the trigger. Measured in jsdom, and a regression: before
+  // this hook existed the restore was unconditional (deep-review round 6).
   const heldRef = useRef(true);
   useEffect(() => {
     const prev = document.body.style.overflow;
@@ -82,9 +94,21 @@ export function useDialogChrome(scopeRef: RefObject<HTMLElement | null>): void {
       target.focus();
     }
     const onFocusIn = () => {
-      const inside = scopeRef.current?.contains(document.activeElement) ?? false;
-      heldRef.current = inside;
-      if (inside) focusedRef.current = document.activeElement as HTMLElement;
+      const owner = ownerRef?.current ?? scopeRef.current;
+      const active = document.activeElement;
+      // "Still ours" also means a dialog stacked ABOVE us. A nested `ui/Modal` portals into its own
+      // host on <body>, so it is outside our root BY CONSTRUCTION — widening the scope cannot see
+      // it — and while it held the focus we read that as the user walking away. Then both closing
+      // together left the focus on <body>: ours skipped the restore, and the child's own
+      // `restoreTo` was already detached (passive cleanups run parent-first). Measured in jsdom,
+      // and it is the ordinary case — an error dialog raised over a dialog (round 6).
+      heldRef.current =
+        (owner?.contains(active) ?? false) ||
+        (active instanceof Element && active.closest('[aria-modal="true"]') != null);
+      // Where to put the focus back on a re-mount, though: the PANEL's own last focus. A toast is
+      // gone by then, so restoring onto it would strand the focus exactly as before.
+      if (scopeRef.current?.contains(document.activeElement))
+        focusedRef.current = document.activeElement as HTMLElement;
     };
     onFocusIn();
     document.addEventListener("focusin", onFocusIn);
@@ -96,5 +120,5 @@ export function useDialogChrome(scopeRef: RefObject<HTMLElement | null>): void {
       // rudest thing a closing dialog can do.
       if (heldRef.current && restoreTo && restoreTo.isConnected) restoreTo.focus();
     };
-  }, [restoreTo, scopeRef]);
+  }, [restoreTo, scopeRef, ownerRef]);
 }
diff --git a/frontend/src/components/welcomeMode.render.dom.test.tsx b/frontend/src/components/welcomeMode.render.dom.test.tsx
index 2705bf23..1f2cced3 100644
--- a/frontend/src/components/welcomeMode.render.dom.test.tsx
+++ b/frontend/src/components/welcomeMode.render.dom.test.tsx
@@ -9,7 +9,7 @@
 // i18n is mocked to a key-passthrough so queries read stable keys, and the API module is stubbed —
 // the card probes /auth/config on mount and must not reach the network.
 import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
-import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
+import { render, screen, fireEvent, cleanup, act, waitFor } from "@testing-library/react";
 
 vi.mock("react-i18next", async (importOriginal) => {
   const actual = await importOriginal<typeof import("react-i18next")>();
@@ -134,3 +134,48 @@ describe("the verification outcome handed down from App", () => {
     expect(screen.queryByText("welcome.auth.verifyInvalid")).toBeNull();
   });
 });
+
+describe("the screenshot lightbox", () => {
+  // The fourth `aria-modal` surface in the app, and the one the round-5 focus extraction did not
+  // sweep in: it declared itself a modal dialog while leaving focus on the thumbnail behind an
+  // 80%-black scrim and letting Tab walk the landing page underneath (round 6).
+  let origDesc: PropertyDescriptor | undefined;
+  beforeEach(() => {
+    origDesc = Object.getOwnPropertyDescriptor(HTMLElement.prototype, "offsetParent");
+    Object.defineProperty(HTMLElement.prototype, "offsetParent", {
+      configurable: true,
+      get(this: HTMLElement) {
+        return this.isConnected ? document.body : null;
+      },
+    });
+  });
+  afterEach(() => {
+    if (origDesc) Object.defineProperty(HTMLElement.prototype, "offsetParent", origDesc);
+  });
+
+  const openIt = async () => {
+    render(<Welcome verify={noVerify} />);
+    const shot = (await screen.findAllByLabelText("welcome.preview.feed"))[0]!;
+    shot.focus();
+    fireEvent.click(shot);
+    return { shot, panel: await screen.findByRole("dialog") };
+  };
+
+  it("opens focused inside itself and holds the Tab instead of letting it walk the page", async () => {
+    const { panel } = await openIt();
+    expect(panel.getAttribute("aria-modal")).toBe("true");
+    expect(panel.contains(document.activeElement)).toBe(true);
+    // Assert the trap ACTED (the keydown was cancelled), not where focus ended up: jsdom never
+    // performs the browser's default Tab traversal, so "focus is still inside" is true with no trap
+    // at all — a green assertion about nothing (the mutation check caught exactly that).
+    screen.getByLabelText("common.close").focus();
+    const notCancelled = fireEvent.keyDown(window, { key: "Tab", cancelable: true });
+    expect(notCancelled).toBe(false);
+  });
+
+  it("hands the focus back to the thumbnail that opened it", async () => {
+    const { shot } = await openIt();
+    fireEvent.keyDown(window, { key: "Escape" });
+    await waitFor(() => expect(document.activeElement).toBe(shot));
+  });
+});

From d89d887a9b45d0c95491c8ec6fcd12cddf1a1f5e Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 05:50:11 +0200
Subject: [PATCH 44/52] fix(plex): the reclaim budget bounds what it says it
 bounds, and a refused finish is not performed anyway
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`MAX_SESSION_RECLAIMS` was cleared by the first fragment of any session, and a
reclaimed session essentially always delivers one — `start_session` does not
return until its first segment exists. So the budget only ever bit where a
session parsed its manifest and then died before a single fragment, which is not
either case its own comment names. Measured: 40 loss cycles produced 41 sessions
and never an error. A transcode falling behind realtime, or two viewers of one
rating_key taking turns, respawned ffmpeg indefinitely — the round-5 behaviour,
still there behind the guard added to stop it.

It counts within a rolling window now. Two losses inside two minutes is a
session that keeps being lost; one an hour apart is not. And the window is reset
per item, because the player stays mounted across a queue advance — otherwise a
budget spent on one episode would deny the next its first legitimate reclaim.

Separately: `finish`'s rollback re-performed the write it was taking back. On
the play-to-the-end path the position it restores IS the end of the media, and
the backend reads a position within its finish margin as a finish — so the
branch named "take the finish back" set watched, cleared the position and
scrobbled to Plex through a second route, while the caller's error toast was
already on screen saying the mark had failed. There is no resume point at the
end of the media to restore; the cache drop is the whole of the rollback there.
The credits-skip caller captures a mid-episode position and still restores it,
which is the case that needs it.

7 tests, mutation-checked: the FRAG_LOADED reset, the missing window, and the
unguarded rollback each red on the test that names them.
---
 .../components/PlexPlayer.hls.dom.test.tsx    | 43 +++++++++++++++----
 .../PlexPlayer.session.dom.test.tsx           | 37 +++++++++++++---
 frontend/src/components/PlexPlayer.tsx        | 30 +++++++++----
 frontend/src/lib/plexPlayerHooks.ts           | 17 +++++++-
 4 files changed, 102 insertions(+), 25 deletions(-)

diff --git a/frontend/src/components/PlexPlayer.hls.dom.test.tsx b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
index abc0dae7..cc78a1fd 100644
--- a/frontend/src/components/PlexPlayer.hls.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
@@ -174,16 +174,19 @@ describe("an HLS session the server no longer has", () => {
     expect(session).toHaveBeenCalledTimes(3);
   });
 
-  it("starts the budget over once a fragment actually loads", async () => {
-    // A session lost once an hour is not a session that cannot be served; the only proof a reclaim
-    // worked is a fragment arriving.
+  it("keeps giving up even though every reclaimed session plays a fragment first", async () => {
+    // The budget used to be cleared by the first FRAG_LOADED of any session — and a reclaimed
+    // session essentially always delivers one, because `start_session` does not return until its
+    // first segment exists. So it bounded NEITHER case its own comment named: measured at 40 loss
+    // cycles, the player opened 41 sessions and never showed an error (deep-review round 6). A
+    // fragment is not proof the session can be served; surviving the window is.
     const session = mount();
-    for (let i = 0; i < 4; i++) {
+    const v = () => document.querySelector("video") as Media;
+    for (let i = 0; i < 3; i++) {
       await waitFor(() => expect(hlsInstances).toHaveLength(i + 1));
       act(() => hlsInstances[i]!.emit(Hls.Events.MANIFEST_PARSED));
-      const v = document.querySelector("video") as Media;
-      v._t = 700;
-      act(() => void v.dispatchEvent(new Event("timeupdate")));
+      v()._t = 700;
+      act(() => void v().dispatchEvent(new Event("timeupdate")));
       act(() =>
         hlsInstances[i]!.emit(Hls.Events.FRAG_LOADED, {
           frag: { type: "main", duration: 6, stats: { total: 1000 } },
@@ -191,8 +194,30 @@ describe("an HLS session the server no longer has", () => {
       );
       act(() => hlsInstances[i]!.emit(Hls.Events.ERROR, lost404));
     }
-    expect(screen.queryByText("plex.player.errGeneric")).toBeNull();
-    expect(session).toHaveBeenCalledTimes(5);
+    await screen.findByText("plex.player.errGeneric");
+    expect(session).toHaveBeenCalledTimes(3);
+  });
+
+  it("starts the budget over for a loss long after the last one", async () => {
+    // The other half: a session reaped once an hour is not a session that cannot be served. The
+    // window is what separates the two, so a spent budget must not follow the viewer around.
+    vi.useFakeTimers({ shouldAdvanceTime: true, toFake: ["Date"] });
+    try {
+      const session = mount();
+      const v = () => document.querySelector("video") as Media;
+      for (let i = 0; i < 4; i++) {
+        await waitFor(() => expect(hlsInstances).toHaveLength(i + 1));
+        act(() => hlsInstances[i]!.emit(Hls.Events.MANIFEST_PARSED));
+        v()._t = 700;
+        act(() => void v().dispatchEvent(new Event("timeupdate")));
+        act(() => hlsInstances[i]!.emit(Hls.Events.ERROR, lost404));
+        act(() => void vi.setSystemTime(Date.now() + 10 * 60_000));
+      }
+      expect(screen.queryByText("plex.player.errGeneric")).toBeNull();
+      expect(session).toHaveBeenCalledTimes(5);
+    } finally {
+      vi.useRealTimers();
+    }
   });
 
   it("is a failure, not a restart, when the session never played", async () => {
diff --git a/frontend/src/components/PlexPlayer.session.dom.test.tsx b/frontend/src/components/PlexPlayer.session.dom.test.tsx
index fd37d9c8..f1ac961f 100644
--- a/frontend/src/components/PlexPlayer.session.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.session.dom.test.tsx
@@ -371,14 +371,39 @@ describe("leaving an item that was played through", () => {
     endMedia();
     await screen.findByText("Title B");
     await tick();
-    // The position the viewer actually reached is reported, not suppressed by a finish that the
-    // server never confirmed…
-    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([
-      ["A", 2995, 3000, true],
-    ]);
-    // …and the cached detail is not left claiming watched: only the server is honest now.
+    // The cached detail is not left claiming watched: only the server is honest now.
     const cached = qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"));
     expect(cached?.status).not.toBe("watched");
+    // And the rollback does NOT write the position back. 2995 of 3000 is inside the backend's
+    // finish margin, so that checkpoint would have set watched / position 0 and scrobbled to Plex
+    // — performing, through a second route, the very write that was just refused, while the error
+    // toast said it had failed (round 6). There is no resume point at the end of the media to
+    // restore; the cache drop is the whole of the rollback here.
+    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([]);
+  });
+
+  it("does restore the position when the refused finish came from the credits skip", async () => {
+    // The other caller of the same helper captures a MID-episode position, and there the rollback
+    // is the point: without it the viewer loses the stretch they watched. One helper, two callers,
+    // and only the near-end one must hold back.
+    prefs({ upNext: false, autoSkipCredits: true, autoSkipDelay: 0 });
+    const withCredits = {
+      ...item("A"),
+      markers: [{ type: "credits", start_s: 2000, end_s: 2990 }],
+    } as unknown as PlexItemDetail;
+    const { qc, progress } = mount({
+      details: { A: withCredits, B: item("B") },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    vi.spyOn(api, "plexSetState").mockRejectedValue(new Error("offline"));
+    await playingAt("/media/A", 2010); // inside the credits → auto-skip advances and marks watched
+    await screen.findByText("Title B");
+    await tick();
+    expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([
+      ["A", 2010, 3000, true],
+    ]);
+    expect(qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"))?.status).not.toBe("watched");
   });
 
   it("records a second viewing when the viewer plays on from the finished frame", async () => {
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index 6e815cc8..d566e960 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -75,10 +75,16 @@ import { pushLayer, removeLayer, anyLayerAbove, escapeHandled } from "../lib/lay
 // The rich info overlay (poster/cast/ratings) reuses the same component as the card's info page.
 const PlexInfo = lazy(() => import("./PlexInfo"));
 
-// Consecutive reclaims of a 404'd HLS session before the player stops and says so. Two covers the
-// real case (the session was reaped, once) without letting a server that cannot serve the stream
-// keep the viewer on a spinner (see the ERROR handler).
+// Reclaims of a 404'd HLS session, within `RECLAIM_WINDOW_MS`, before the player stops and says so.
+// Two covers the real case (the session was reaped, once) without letting a server that cannot serve
+// the stream keep the viewer on a spinner (see the ERROR handler).
 const MAX_SESSION_RECLAIMS = 2;
+// A ROLLING window, because "consecutive" could not bound anything: the budget used to be cleared by
+// the first fragment of any session, and a reclaimed session essentially always delivers one —
+// `start_session` does not return until its first segment exists. So both cases the ERROR handler
+// names restarted ffmpeg forever anyway (measured: 40 loss cycles → 41 sessions, never an error).
+// Two losses inside two minutes is a session that keeps being lost; one an hour apart is not.
+const RECLAIM_WINDOW_MS = 120_000;
 
 // The Plex module's rich, full-page player. Plays the LOCAL file: direct-playable files stream raw
 // (native <video>), remux files stream via the seek-restart HLS session (hls.js). The visible
@@ -160,9 +166,10 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   // Where the current session was ASKED to start — set before the request goes out, so the subtitle
   // poll has a position before `sessionK` (the session's answer) and before the first timeupdate.
   const loadStartRef = useRef(0);
-  // How many times in a row this player may reclaim a session the server answered 404 for, before it
-  // stops and says playback failed. Reset by the first fragment that loads (see FRAG_LOADED).
-  const restartsRef = useRef({ n: 0 });
+  // How often this player may reclaim a session the server answered 404 for, before it stops and
+  // says playback failed. `at` is when the window started; the item-start effect zeroes it, so a
+  // budget spent on one episode cannot deny the next one its first legitimate reclaim.
+  const restartsRef = useRef({ n: 0, at: 0 });
   const [seekableEnd, setSeekableEnd] = useState(0); // absolute end of the loaded region
   const { fs, toggleFs } = useFullscreen(wrapRef);
   const [ready, setReady] = useState(false);
@@ -376,9 +383,6 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         // rolling window starts empty rather than carrying the previous session's numbers over.
         fragMeterRef.current.reset();
         hls.on(Hls.Events.FRAG_LOADED, (_e, data) => {
-          // A fragment actually arriving is the only proof a reclaimed session works; the budget is
-          // for a session that keeps being lost, not for one that was lost once an hour.
-          restartsRef.current.n = 0;
           fragMeterRef.current.add({
             type: data.frag.type,
             bytes: data.frag.stats?.total || data.frag.stats?.loaded || 0,
@@ -429,6 +433,11 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
         hls.on(Hls.Events.ERROR, (_e, data) => {
           if (!data.fatal || !current()) return;
           if (parsed && data.type === Hls.ErrorTypes.NETWORK_ERROR && data.response?.code === 404) {
+            const now = Date.now();
+            // A new window: the last loss was long enough ago that this is a fresh incident, not the
+            // same session being lost over and over.
+            if (now - restartsRef.current.at > RECLAIM_WINDOW_MS)
+              restartsRef.current = { n: 0, at: now };
             if (restartsRef.current.n < MAX_SESSION_RECLAIMS) {
               restartsRef.current.n += 1;
               loadSession(playhead(absRef, loadStartRef), !video.paused);
@@ -504,6 +513,9 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
   useEffect(() => {
     if (!detail || detail.id !== id || startedForRef.current === id) return;
     startedForRef.current = id;
+    // A fresh item is a fresh incident: the reclaim budget must not carry over from the previous
+    // one (the player stays mounted across a queue advance — `go()` only changes `id`).
+    restartsRef.current = { n: 0, at: 0 };
     // Restore the per-account audio/subtitle language choice, resolved to THIS item's tracks. Set the
     // audio ref synchronously so the loadSession below picks the right track on the first request.
     const aOrd = audioOrdForLang(detail.audio_streams ?? [], prefs.audioLang);
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index bca36f2d..01ccfda3 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -21,6 +21,13 @@ import { plexLang } from "../i18n";
 import { type PlexPlayerPrefs } from "./plexPlayerPrefs";
 import { PLEX_SCALE, normalizeVolumeIn, stepVolumeIn } from "./playerVolume";
 
+// How close to the end the backend counts as "finished" (`_FINISH_MARGIN_S` in routes/plex/playback):
+// a progress checkpoint at or past `duration - this` marks the item watched and clears the position.
+// Mirrored here because `finish`'s rollback must not accidentally drive that branch. It is a
+// one-way safety margin, not a shared contract — if the two ever diverge, the worst case is a
+// rollback that is skipped or a resume point set a few seconds from the end.
+const FINISH_MARGIN_S = 30;
+
 // A live wall clock for the top bar, re-rendered every 15s (minute resolution is enough for the
 // HH:MM display, and a coarse tick keeps the whole player from re-rendering each second).
 export function useWallClock(): Date {
@@ -186,7 +193,15 @@ export function usePlexProgress(opts: {
       const dur = durationRef.current;
       void confirmed?.catch(() => {
         finished = false;
-        if (pos > 0 && dur > 0) api.plexProgress(id, pos, dur, true).catch(() => {});
+        // Restore the resume point the finish replaced — but ONLY where there is one to restore.
+        // On the play-to-the-end path `pos` IS the end of the media, and the backend reads a
+        // position within `_FINISH_MARGIN_S` of the duration as a finish: it would set watched,
+        // clear the position and scrobble to Plex. So the branch named "take the finish back"
+        // performed, through a second route, exactly the write that had just been refused — while
+        // the caller's error toast was already on screen saying it had failed (round 6). The
+        // credits-skip caller captures a mid-episode position and is unaffected.
+        if (pos > 0 && dur > 0 && pos <= dur - FINISH_MARGIN_S)
+          api.plexProgress(id, pos, dur, true).catch(() => {});
         // `settle` may already have patched the detail to watched / 0 on the way out. Dropping that
         // entry rather than invalidating it: an invalidated query with no observer keeps serving its
         // stale data, and this one is a lie — no data is better, the next open fetches the truth.

From a0114deff194f9053fcf9036bd899fa60eb4f712 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 05:50:31 +0200
Subject: [PATCH 45/52] fix(api,ui): a refused write says why, wherever the
 refusal happens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 5 taught `notifyActionError` to discard a plain-string `detail` in favour
of the caller's translated fallback, because `req` leaves 403/404/429 to the
caller and those routes hand-write English. Three places did not get the
message.

**The demo account lost its explanation.** `require_human` refused with a plain
string, so from that commit on the shared demo account got its caller's generic
"couldn't do that" and no hint that the demo account was the reason — and the
gate is not backed by a UI gate everywhere: the comfort shelf has no `is_demo`
check, so the pin button is live and simply fails. A structured `{code: "demo"}`
and an `errors.demo` string in both locales. The two auth routes that hand-roll
the same check were swept with it.

**`ChatThread` carried a second copy of the contract.** It filtered 404/429
itself and then did `e.detail || t(…)`, the pre-fix order, so the central fix
could not reach it and "That member hasn't set up messaging yet." stayed English
under a Hungarian UI. It goes through the shared helper now, and a contract test
pins the remaining raw-`detail` consumers as an explicit SET — never a count —
so a new copy fails the gate instead of shipping. The five on that list are
inline surfaces (a form field's error line, a setup banner) and are deferred
with the ~60 backend routes whose details they print.

**The Plex "Add to playlist" dialog was still silent.** Same shape as the
collection editor round 5 fixed and the YouTube twin that already had the fix:
no catch, so a playlist deleted on another device answered a structured 404 that
nothing reported — the tick never flipped, the gone row stayed, and the floating
promise became an unhandled rejection.

Also: the `ABORTED` sentinel's VALUE was asserted nowhere. The consumer test
hand-built the error it expected, so replacing `xhr.onabort`'s rejection with a
friendlier message left the lane green — and every upload the user cancels would
then raise a red "the upload failed" toast, which is what the sentinel prevents.
Both producer tests assert through `isAborted` now.

And two backend tests were pinning fewer sites than their own docstrings claimed:
the channel-404 loop said "all five" and issued three requests (explore and
subscribe unexercised, the excuse for subscribe naming a different call site
with a different reason slug), and the recipient/job test named three refusals
and requested two — `share_download`'s `not_found("recipient")` had no test in
the suite at all, nor did the locale keys added beside it. Every site named now
has a request behind it.

6 tests, mutation-checked against 7 mutations: the demo detail at both the gate
and an auth route, a re-hand-rolled ChatThread, the silent Plex dialog, the
abort sentinel, and each unpinned 404 — all red on the test that names them.
---
 backend/app/auth.py                           |  6 +-
 backend/app/routes/auth.py                    |  4 +-
 backend/tests/test_demo_refusal_detail.py     | 47 ++++++++++++++
 backend/tests/test_not_found_detail.py        | 53 +++++++++++++--
 frontend/src/components/ChatThread.tsx        | 15 +++--
 .../PlaylistEditFailures.dom.test.tsx         | 25 +++++++
 frontend/src/components/PlexPlaylistAdd.tsx   | 19 +++++-
 frontend/src/i18n/locales/en/errors.json      |  1 +
 frontend/src/i18n/locales/en/plex.json        |  5 +-
 frontend/src/i18n/locales/hu/errors.json      |  1 +
 frontend/src/i18n/locales/hu/plex.json        |  5 +-
 .../src/lib/actionErrors.contract.test.ts     | 65 +++++++++++++++++++
 frontend/src/lib/actionErrors.test.ts         | 20 ++++++
 frontend/src/lib/api/core.test.ts             | 17 ++++-
 frontend/src/lib/api/core.ts                  |  4 ++
 15 files changed, 266 insertions(+), 21 deletions(-)
 create mode 100644 backend/tests/test_demo_refusal_detail.py
 create mode 100644 frontend/src/lib/actionErrors.contract.test.ts

diff --git a/backend/app/auth.py b/backend/app/auth.py
index 8a6859bb..95d027ec 100644
--- a/backend/app/auth.py
+++ b/backend/app/auth.py
@@ -341,7 +341,11 @@ def require_human(user: User = Depends(current_user)) -> User:
     no token, so has_read_scope/has_write_scope are False); this makes the boundary explicit
     where there's no scope check to lean on."""
     if user.is_demo:
-        raise HTTPException(status_code=403, detail="Not available in the demo account.")
+        # Structured, because `req` leaves 403 to the caller and `notifyActionError` only shows a
+        # STRUCTURED detail — a plain string here reached the demo user as their caller's generic
+        # "couldn't do that", with no hint that the demo account is the reason (round 6). Affordances
+        # this gate sits behind are not all UI-gated on `is_demo` (the comfort shelf is not).
+        raise HTTPException(status_code=403, detail={"code": "demo"})
     return user
 
 
diff --git a/backend/app/routes/auth.py b/backend/app/routes/auth.py
index c76bd49f..b96d4304 100644
--- a/backend/app/routes/auth.py
+++ b/backend/app/routes/auth.py
@@ -1246,7 +1246,7 @@ def logout_others(
     are rejected, then re-stamp THIS cookie so the caller stays signed in. For "I left myself logged
     in somewhere" / a suspected session compromise. The demo account (shared) is excluded."""
     if user.is_demo:
-        raise HTTPException(status_code=403, detail="Not available in the demo account.")
+        raise HTTPException(status_code=403, detail={"code": "demo"})
     # Commit the bump BEFORE re-stamping this cookie, so a failed commit can't strand the current
     # session at a newer epoch than the DB (see set_password).
     bump_session_epoch(user)
@@ -1293,7 +1293,7 @@ def set_password(
     account) needs no current password — the session already proves identity. Changing an
     existing one requires the current password, so a hijacked session can't silently rotate it."""
     if user.is_demo:
-        raise HTTPException(status_code=403, detail="Not available in the demo account.")
+        raise HTTPException(status_code=403, detail={"code": "demo"})
     new_password = body.password or ""
     if len(new_password) < PASSWORD_MIN_LEN:
         raise HTTPException(
diff --git a/backend/tests/test_demo_refusal_detail.py b/backend/tests/test_demo_refusal_detail.py
new file mode 100644
index 00000000..6596c862
--- /dev/null
+++ b/backend/tests/test_demo_refusal_detail.py
@@ -0,0 +1,47 @@
+"""The shared demo account's refusal says WHY, in the reader's language (deep-review round 6).
+
+`require_human` answered `403 "Not available in the demo account."` — a plain string. `req` leaves
+403 to the caller, and round 5 taught `notifyActionError` to discard a plain-string detail in favour
+of the caller's already-translated fallback, so from that commit on the demo user got a generic
+"couldn't do that" and no hint that the demo account was the reason. Not every affordance behind
+this gate is UI-gated on `is_demo` either — the comfort shelf is not, so the pin button is live.
+
+A structured `{code: "demo"}` is what `localizeDetail` can turn into `errors.demo` in both locales.
+Pinned at all three sites: the shared dependency and the two auth routes that hand-roll the same
+check, because an asymmetric fix is the smell this repo bans. Needs the DB.
+"""
+
+from app.models import User
+
+
+def test_every_demo_refusal_carries_the_same_structured_reason(db, make_user, as_user):
+    demo = make_user(email="demo@example.com", is_demo=True)
+    client = as_user(demo)
+    for method, url, body in [
+        # `require_human` itself, through an affordance the UI does NOT gate on is_demo.
+        ("post", "/api/discover/pins", {"kind": "video", "ref": "v1"}),
+        # The two routes that repeat the check inline rather than depending on the gate.
+        ("post", "/auth/logout-others", None),
+        ("post", "/auth/set-password", {"password": "a long enough password"}),
+    ]:
+        r = getattr(client, method)(url, **({"json": body} if body is not None else {}))
+        assert r.status_code == 403, (url, r.text)
+        assert r.json()["detail"] == {"code": "demo"}, url
+
+
+def test_a_real_account_is_not_refused_by_the_gate(db, make_user, as_user):
+    """The other half: the structured detail must not come from having broken the gate open the
+    other way. A non-demo account gets past `require_human` and fails (or succeeds) on its own
+    merits — anything but a 403 demo refusal."""
+    client = as_user(make_user(email="real@example.com"))
+    r = client.post("/auth/logout-others")
+    assert r.status_code == 200, r.text
+    assert not isinstance(r.json().get("detail"), dict)
+
+
+def test_the_gate_reads_the_flag_and_not_the_email(db):
+    """`is_demo` is a column, not a convention about the address — a real account that happens to
+    be called demo@ must not be refused."""
+    from app.auth import require_human
+
+    assert require_human(User(email="demo@example.com", is_demo=False)) is not None
diff --git a/backend/tests/test_not_found_detail.py b/backend/tests/test_not_found_detail.py
index 6f177d98..b7e9645e 100644
--- a/backend/tests/test_not_found_detail.py
+++ b/backend/tests/test_not_found_detail.py
@@ -6,6 +6,9 @@ Hungarian UI toasted it verbatim. The structured-404 fix had gone into one ad-ho
 the shared one, so every other owner check kept the English. Needs the DB.
 """
 
+from app.auth import require_write_scope
+from app.models import DownloadJob, MediaAsset
+
 
 def test_a_gone_view_tag_or_pin_says_what_is_gone(db, make_user, as_user):
     client = as_user(make_user())
@@ -41,18 +44,27 @@ def test_a_gone_channel_video_or_user_says_what_is_gone(db, make_user, as_user):
         assert r.json()["detail"] == {"code": "not_found", "reason": what}, url
 
 
-def test_every_gone_channel_route_says_it_the_same_way(db, make_user, as_user):
+def test_every_gone_channel_route_says_it_the_same_way(db, make_user, as_user, override_dep):
     """The round-4 sweep converted ONE of the five `db.get(Channel, …) is None -> 404 "Unknown
     channel"` sites (block), and shipped the HU/EN string with it — so the Hungarian UI said it in
     Hungarian on the Block button and in English on the four beside it (deep-review round 5). The
-    asymmetric fix is the smell this repo bans, so all five are pinned together."""
+    asymmetric fix is the smell this repo bans, so all five are pinned together.
+
+    Literally all five: round 6 found this loop issuing three requests under a docstring claiming
+    five, with explore silently absent and subscribe excused as "covered by the tags route" — which
+    reaches `_user_subscription`, a different site answering `reason: subscription`. Reverting
+    either of those two to its bare English string left the whole lane green."""
     admin = make_user(role="admin")
     client = as_user(admin)
+    # Subscribe's own gate (the optional YouTube write scope) sits in FRONT of the lookup, so a
+    # plain account 403s before reaching it. The gate is not what is under test here.
+    override_dep(require_write_scope, lambda: admin)
     gone = "UCgone000000000000000000"
-    # Subscribe is behind the write-scope gate, so it is covered by the tags route below instead.
     for method, url in [
         ("get", f"/api/channels/{gone}"),
+        ("post", f"/api/channels/{gone}/explore"),
         ("post", f"/api/channels/{gone}/reset-backfill"),
+        ("post", f"/api/channels/{gone}/subscribe"),
         ("post", f"/api/channels/{gone}/block"),
     ]:
         r = getattr(client, method)(url)
@@ -63,15 +75,44 @@ def test_every_gone_channel_route_says_it_the_same_way(db, make_user, as_user):
 def test_a_gone_subscription_recipient_or_job_says_what_is_gone(db, make_user, as_user):
     """The three bare-English 404s the same sweep left behind, which `notifyActionError` printed
     verbatim into an otherwise Hungarian UI: "Not subscribed to this channel", "No user with that
-    email.", "Unknown job"."""
+    email.", "Unknown job".
+
+    All three, with a request each. Round 6 found this test naming three and issuing two: the
+    recipient site had no test in the whole suite (nor did the `errors.notFound.recipient` keys
+    added beside it), and `run_job_now` rode on its PATCH sibling's coverage."""
     admin = make_user(role="admin")
     client = as_user(admin)
     r = client.post("/api/channels/UCgone000000000000000000/tags", json={"tag_id": 1})
     assert r.status_code == 404, r.text
     assert r.json()["detail"] == {"code": "not_found", "reason": "subscription"}
-    r = client.patch("/api/admin/scheduler/jobs/no_such_job", json={"interval_minutes": 30})
+    for method, url in [
+        ("patch", "/api/admin/scheduler/jobs/no_such_job"),
+        ("post", "/api/admin/scheduler/jobs/no_such_job/run"),
+    ]:
+        kw = {"json": {"interval_minutes": 30}} if method == "patch" else {}
+        r = getattr(client, method)(url, **kw)
+        assert r.status_code == 404, (url, r.text)
+        assert r.json()["detail"] == {"code": "not_found", "reason": "job"}, url
+    # Sharing needs a finished download of one's own to share; the recipient lookup is the next check.
+    asset = MediaAsset(
+        source_kind="url", source_ref="share-404", format_sig="sig", status="ready", ref_count=1
+    )
+    db.add(asset)
+    db.flush()
+    job = DownloadJob(
+        user_id=admin.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref="share-404",
+        status="done",
+        queue_pos=1,
+        profile_snapshot={},
+    )
+    db.add(job)
+    db.commit()
+    r = client.post(f"/api/downloads/{job.id}/share", json={"email": "nobody@example.com"})
     assert r.status_code == 404, r.text
-    assert r.json()["detail"] == {"code": "not_found", "reason": "job"}
+    assert r.json()["detail"] == {"code": "not_found", "reason": "recipient"}
 
 
 def test_a_nul_in_a_request_string_is_a_422_not_a_500(db, make_user, as_user):
diff --git a/frontend/src/components/ChatThread.tsx b/frontend/src/components/ChatThread.tsx
index cfcd63b8..4f9e8f2e 100644
--- a/frontend/src/components/ChatThread.tsx
+++ b/frontend/src/components/ChatThread.tsx
@@ -3,13 +3,13 @@ import { qk } from "../lib/queryKeys";
 import { useTranslation } from "react-i18next";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { Send } from "lucide-react";
-import { api, HttpError, type Message, type MessageUser } from "../lib/api";
+import { api, type Message, type MessageUser } from "../lib/api";
 import { useLiveQuery } from "../lib/useLiveQuery";
 import { useScrollFade } from "../lib/useScrollFade";
 import { Button } from "./ui/Button";
 import { LoadingState, StateMessage } from "./ui/QueryState";
 import { relativeTime } from "../lib/format";
-import { notify } from "../lib/notifications";
+import { notifyActionError } from "../lib/actionErrors";
 import { partnerPub, POLL_MS, refreshPartnerPub, useKeyState } from "../lib/messaging";
 import * as e2ee from "../lib/e2ee";
 import KeyGate from "./KeyGate";
@@ -132,9 +132,14 @@ export default function ChatThread({
       // The draft is kept (only cleared on success) so the user can retry. 400/409/422/500 already
       // raised the global error dialog; 404 (recipient gone) and 429 (rate-limited) are "caller-
       // handled" in api.req (no modal), so surface those here or the send fails silently.
-      if (e instanceof HttpError && (e.status === 404 || e.status === 429)) {
-        notify({ level: "error", message: e.detail || t("messages.sendFailed") });
-      }
+      //
+      // Through the shared helper, which knows both of those rules: it no-ops on anything already
+      // reported, and it prefers the server's reason only when that reason is a STRUCTURED detail.
+      // The hand-written copy that used to live here did `e.detail || …`, so a Hungarian reader got
+      // the route's English sentence — "That member hasn't set up messaging yet." — which is
+      // exactly what round 5 changed `notifyActionError` to stop doing. A second copy of a contract
+      // is how the fix misses a caller (round 6).
+      notifyActionError(e, t("messages.sendFailed"));
     },
   });
 
diff --git a/frontend/src/components/PlaylistEditFailures.dom.test.tsx b/frontend/src/components/PlaylistEditFailures.dom.test.tsx
index 304982b5..625af9a0 100644
--- a/frontend/src/components/PlaylistEditFailures.dom.test.tsx
+++ b/frontend/src/components/PlaylistEditFailures.dom.test.tsx
@@ -27,6 +27,7 @@ vi.mock("../lib/notifications", async (importOriginal) => ({
 
 import PlexPlaylistView from "./PlexPlaylistView";
 import AddToPlaylist from "./AddToPlaylist";
+import PlexPlaylistAdd from "./PlexPlaylistAdd";
 import TagManager from "./TagManager";
 import { api, HttpError, type PlexCard } from "../lib/api";
 
@@ -123,6 +124,30 @@ describe("the add-to-playlist popover", () => {
     await waitFor(() => expect(errors()).toEqual(["gone playlist"]));
     await waitFor(() => expect(lists.mock.calls.length).toBeGreaterThan(1));
   });
+
+  it("says so on the PLEX side too, where the same sweep had missed the dialog", async () => {
+    // Same shape, same 404, same silence — `req` leaves 403/404/429 to the caller, and this one had
+    // no catch: the tick did not flip, nothing was said, the gone row stayed, and the floating
+    // promise became an unhandled rejection. Round 5 fixed the collection editor and the YouTube
+    // twin above; this dialog was left behind (round 6).
+    const lists = vi
+      .spyOn(api, "plexPlaylists")
+      .mockResolvedValue({ playlists: [{ id: 9, title: "Gone", has_item: false }] } as never);
+    vi.spyOn(api, "plexPlaylistAddItem").mockRejectedValue(gone("playlist"));
+    render(
+      <QueryClientProvider client={client()}>
+        <PlexPlaylistAdd
+          target={{ kind: "single", ratingKey: "m1", title: "A Movie" }}
+          onClose={() => {}}
+        />
+      </QueryClientProvider>,
+    );
+    fireEvent.click(await screen.findByText("Gone"));
+    // The server's own localized reason wins over the caller's fallback when the detail is
+    // STRUCTURED — same as the twin above. What is under test is that anything is said at all.
+    await waitFor(() => expect(errors()).toEqual(["gone playlist"]));
+    await waitFor(() => expect(lists.mock.calls.length).toBeGreaterThan(1));
+  });
 });
 
 describe("the tag manager", () => {
diff --git a/frontend/src/components/PlexPlaylistAdd.tsx b/frontend/src/components/PlexPlaylistAdd.tsx
index 76d37f58..bdd63f76 100644
--- a/frontend/src/components/PlexPlaylistAdd.tsx
+++ b/frontend/src/components/PlexPlaylistAdd.tsx
@@ -4,6 +4,7 @@ import { useTranslation } from "react-i18next";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { Check, Minus, Plus } from "lucide-react";
 import { api, type PlexPlaylist } from "../lib/api";
+import { notifyActionError } from "../lib/actionErrors";
 import { useScrollFade } from "../lib/useScrollFade";
 import { Button } from "./ui/Button";
 import Modal from "./ui/Modal";
@@ -54,6 +55,11 @@ export default function PlexPlaylistAdd({
     return isGroup ? (p.group_in ?? 0) : p.has_item ? 1 : 0;
   }
 
+  // A failure is said, and the list refreshed either way. With no catch, a playlist deleted on
+  // another device (a 404 `not_found/playlist` — still offered here, from a cache up to 30 s old)
+  // was an unhandled rejection: `req` leaves 403/404/429 to the caller, so nothing was shown, the
+  // tick never flipped and the gone row stayed. Round 5 swept the collection editor and its own
+  // YouTube twin (`AddToPlaylist`) and missed this one (round 6).
   async function toggle(p: PlexPlaylist) {
     if (busy) return;
     setBusy(true);
@@ -67,8 +73,13 @@ export default function PlexPlaylistAdd({
         else await api.plexPlaylistAddItem(p.id, target.ratingKey);
       }
       setOverride((m) => new Map(m).set(p.id, allIn ? 0 : size));
-      refresh();
+    } catch (e) {
+      notifyActionError(
+        e,
+        t(allIn ? "plex.playlistAdd.removeFailed" : "plex.playlistAdd.addFailed"),
+      );
     } finally {
+      refresh();
       setBusy(false);
     }
   }
@@ -87,8 +98,12 @@ export default function PlexPlaylistAdd({
         setOverride((m) => new Map(m).set(pl.id, 1));
       }
       setNewName("");
-      refresh();
+    } catch (e) {
+      // The create may already have landed when the add fails — `refresh()` in `finally` is what
+      // makes that half-done state visible instead of leaving a playlist the dialog never lists.
+      notifyActionError(e, t("plex.playlistAdd.createFailed"));
     } finally {
+      refresh();
       setBusy(false);
     }
   }
diff --git a/frontend/src/i18n/locales/en/errors.json b/frontend/src/i18n/locales/en/errors.json
index 05c6e9c2..f7420be4 100644
--- a/frontend/src/i18n/locales/en/errors.json
+++ b/frontend/src/i18n/locales/en/errors.json
@@ -1,6 +1,7 @@
 {
   "title": "Couldn't complete that",
   "generic": "The server couldn't carry out that action. Please try again.",
+  "demo": "This isn't available in the demo account.",
   "validation": "Some of the values you entered weren't valid. Please check them and try again.",
   "server": "Server error",
   "syncCooldown": "You've synced a few times just now — give it a few minutes. The YouTube budget is shared with everyone on this instance, and background syncing keeps running either way.",
diff --git a/frontend/src/i18n/locales/en/plex.json b/frontend/src/i18n/locales/en/plex.json
index f4d4c768..a1fc8a67 100644
--- a/frontend/src/i18n/locales/en/plex.json
+++ b/frontend/src/i18n/locales/en/plex.json
@@ -297,7 +297,10 @@
     "create": "Create",
     "none": "No playlists yet. Create one above.",
     "count": "{{count}} items",
-    "groupProgress": "{{in}} / {{size}}"
+    "groupProgress": "{{in}} / {{size}}",
+    "addFailed": "Couldn't add it to the playlist.",
+    "removeFailed": "Couldn't remove it from the playlist.",
+    "createFailed": "Couldn't create the playlist."
   },
   "playlist": {
     "section": "Playlists",
diff --git a/frontend/src/i18n/locales/hu/errors.json b/frontend/src/i18n/locales/hu/errors.json
index 0971ba85..f6e73b46 100644
--- a/frontend/src/i18n/locales/hu/errors.json
+++ b/frontend/src/i18n/locales/hu/errors.json
@@ -1,6 +1,7 @@
 {
   "title": "Nem sikerült",
   "generic": "A szerver nem tudta végrehajtani a műveletet. Próbáld újra.",
+  "demo": "Ez a bemutató fiókban nem érhető el.",
   "validation": "Néhány megadott érték érvénytelen volt. Ellenőrizd, majd próbáld újra.",
   "server": "Szerverhiba",
   "syncCooldown": "Az imént többször is szinkronizáltál — várj pár percet. A YouTube-keret közös az instance összes felhasználójával, a háttérszinkron pedig így is fut tovább.",
diff --git a/frontend/src/i18n/locales/hu/plex.json b/frontend/src/i18n/locales/hu/plex.json
index 61da094c..f3fd3afc 100644
--- a/frontend/src/i18n/locales/hu/plex.json
+++ b/frontend/src/i18n/locales/hu/plex.json
@@ -297,7 +297,10 @@
     "create": "Létrehozás",
     "none": "Még nincs lista. Hozz létre egyet fent.",
     "count": "{{count}} elem",
-    "groupProgress": "{{in}} / {{size}}"
+    "groupProgress": "{{in}} / {{size}}",
+    "addFailed": "Nem sikerült hozzáadni a lejátszási listához.",
+    "removeFailed": "Nem sikerült eltávolítani a lejátszási listáról.",
+    "createFailed": "Nem sikerült létrehozni a lejátszási listát."
   },
   "playlist": {
     "section": "Lejátszási listák",
diff --git a/frontend/src/lib/actionErrors.contract.test.ts b/frontend/src/lib/actionErrors.contract.test.ts
new file mode 100644
index 00000000..f15de4fe
--- /dev/null
+++ b/frontend/src/lib/actionErrors.contract.test.ts
@@ -0,0 +1,65 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+
+// One contract, one implementation — `notifyActionError` (see actionErrors.ts).
+//
+// `req` deliberately leaves 403/404/429 to the caller, and the routes behind those statuses
+// hand-write English. Round 5 taught the shared helper to discard a plain-string `detail` in favour
+// of the caller's already-translated fallback. Round 6 then found `ChatThread` carrying a SECOND,
+// hand-written copy of the same contract (`e.detail || t("messages.sendFailed")`) — so the central
+// fix could not reach it and the English sentence stayed in a Hungarian UI. A fix that lands in one
+// place while a copy of the rule lives in another is this repo's recurring smell; this is the check
+// that names the copies.
+//
+// The assertion pins the expected SET, never a count: a guard that counts is green the moment its
+// glob stops matching (E10 review round 4 learned that the hard way).
+
+// Reads a raw `HttpError.detail` and uses it as the message a user sees. Matches `e.detail ||`,
+// `err.detail ? err.detail :` and `(e instanceof HttpError ? e.detail : undefined) ??`.
+const RAW_DETAIL = /\b[A-Za-z_$][\w$]*\.detail\b(?!\s*(?:=[^=]|\)))/;
+
+// Every place that still prefers the server's raw string over a translated fallback. These are
+// INLINE surfaces — a form field's error line, a setup step's banner — not toasts, and each shows a
+// reason the user is mid-flow on, so converting them is a sweep of its own (with the ~60 backend
+// routes that hand-write those strings). Logged on ROADMAP.md under the bug-hunt deferrals. What
+// must not happen is a NEW one, or a toast path growing one again.
+const KNOWN_RAW_DETAIL_CONSUMERS = [
+  "components/Feed.tsx", // the live-YouTube search error line
+  "components/KeyGate.tsx", // the passphrase field's own refusal
+  "components/SettingsPanel.tsx", // the change-password field
+  "components/SetupWizard.tsx", // the first-run wizard's banner
+  "components/Welcome.tsx", // the sign-in card's refusal panel
+];
+
+// Where the rule itself lives, plus the request layer that produces and localizes the value.
+const IMPLEMENTATION = ["lib/actionErrors.ts", "lib/api/core.ts"];
+
+function consumers(): string[] {
+  const files = import.meta.glob("../**/*.{ts,tsx}", {
+    query: "?raw",
+    import: "default",
+    eager: true,
+  });
+  const hits: string[] = [];
+  for (const [rel, source] of Object.entries(files)) {
+    // Vite resolves the glob against THIS file, so same-directory hits come back as "./x".
+    const path = rel.startsWith("./") ? `lib/${rel.slice(2)}` : rel.replace(/^\.\.\//, "");
+    if (/\.test\.tsx?$|\.d\.ts$/.test(path)) continue;
+    if (IMPLEMENTATION.includes(path)) continue;
+    const lines = String(source)
+      .split("\n")
+      .filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l)); // a comment about the rule is not a copy of it
+    if (lines.some((l) => RAW_DETAIL.test(l))) hits.push(path);
+  }
+  return hits.sort();
+}
+
+describe("the refused-write contract", () => {
+  it("has no copies beyond the ones on the deferral list", () => {
+    // The glob must actually match something, or this whole file is a green no-op.
+    expect(readFileSync(new URL("./actionErrors.ts", import.meta.url), "utf8")).toContain(
+      "detailData",
+    );
+    expect(consumers()).toEqual(KNOWN_RAW_DETAIL_CONSUMERS);
+  });
+});
diff --git a/frontend/src/lib/actionErrors.test.ts b/frontend/src/lib/actionErrors.test.ts
index f46cb78a..1e5f5b22 100644
--- a/frontend/src/lib/actionErrors.test.ts
+++ b/frontend/src/lib/actionErrors.test.ts
@@ -68,6 +68,26 @@ describe("notifyActionError", () => {
     expect(notifyMock).toHaveBeenCalledWith({ level: "error", message: "TRANSLATED" });
   });
 
+  it("tells a demo user that the demo account is the reason", async () => {
+    // `require_human`'s refusal was a plain English string, so round 5's fix — discard a
+    // plain-string detail, show the caller's translated fallback — discarded the only explanation
+    // the demo user got: a generic "couldn't pin it" with no hint why (round 6). The gate answers
+    // a structured code now, and `localizeDetail` has a branch for it in both locales.
+    vi.spyOn(globalThis, "fetch").mockResolvedValue(
+      new Response(JSON.stringify({ detail: { code: "demo" } }), {
+        status: 403,
+        headers: { "content-type": "application/json" },
+      }),
+    );
+    const err = await api.addComfortPin("video", "v1").catch((e: unknown) => e);
+    notifyMock.mockClear();
+    notifyActionError(err, "GENERIC FALLBACK");
+    expect(notifyMock).toHaveBeenCalledWith({
+      level: "error",
+      message: i18n.t("errors.demo"),
+    });
+  });
+
   it("still prefers a STRUCTURED reason, which the request layer has already localized", () => {
     // `req` runs `{code, reason}` through localizeDetail, so `detail` is in the reader's language
     // AND more specific than the caller's generic fallback — quota numbers, which row is gone.
diff --git a/frontend/src/lib/api/core.test.ts b/frontend/src/lib/api/core.test.ts
index dc614ed8..fa038bf6 100644
--- a/frontend/src/lib/api/core.test.ts
+++ b/frontend/src/lib/api/core.test.ts
@@ -22,7 +22,14 @@ vi.mock("../activeAccount", () => ({
   notifyActiveAccountChange: vi.fn(),
 }));
 
-import { req, uploadReq, setUnauthorizedHandler, HttpError, alreadyReported } from "./core";
+import {
+  req,
+  uploadReq,
+  setUnauthorizedHandler,
+  HttpError,
+  alreadyReported,
+  isAborted,
+} from "./core";
 
 // A fake XHR whose lifecycle the test drives: capture the instance, set status/responseText, then
 // invoke onload/onerror/abort by hand.
@@ -74,11 +81,15 @@ describe("uploadReq", () => {
     await expect(p).resolves.toEqual({ id: 7 });
   });
 
+  // Both abort producers are asserted through `isAborted`, not through `{status: 0}`: what the
+  // upload dialog reads is the SENTINEL, and a cancelled upload that stops matching it becomes a
+  // red "the upload failed" toast. Changing either `reject` to a friendlier message left every
+  // test green, because the only consumer test hand-builds the error it expects (round 6).
   it("rejects immediately if the signal is already aborted (never sends)", async () => {
     const ac = new AbortController();
     ac.abort();
     const p = uploadReq("/u", form(), { signal: ac.signal });
-    await expect(p).rejects.toBeInstanceOf(HttpError);
+    await expect(p).rejects.toSatisfy(isAborted);
     expect(FakeXHR.last?.sent).not.toBe(true);
   });
 
@@ -86,7 +97,7 @@ describe("uploadReq", () => {
     const ac = new AbortController();
     const p = uploadReq("/u", form(), { signal: ac.signal });
     ac.abort(); // → our abort listener calls xhr.abort() → onabort → reject
-    await expect(p).rejects.toMatchObject({ status: 0 });
+    await expect(p).rejects.toSatisfy(isAborted);
   });
 
   it("calls the unauthorized handler on 401", async () => {
diff --git a/frontend/src/lib/api/core.ts b/frontend/src/lib/api/core.ts
index a8cce25f..45858f3f 100644
--- a/frontend/src/lib/api/core.ts
+++ b/frontend/src/lib/api/core.ts
@@ -85,6 +85,10 @@ function localizeDetail(d: unknown): string {
   // a raw key, which is what an i18n miss would otherwise put on screen.
   if (o?.code === "login")
     return t(`welcome.auth.blocked.${o.reason}.short`, t("welcome.auth.genericError"));
+  // The shared demo account refusing a personal-state write (`require_human`). Not every affordance
+  // behind that gate is UI-gated on `is_demo` — the comfort shelf is not — so without this the demo
+  // user got their caller's generic "couldn't do that" and no reason at all (round 6).
+  if (o?.code === "demo") return t("errors.demo");
   // The two email-link confirmations. Their failure is one a user meets by simply clicking an old
   // link, so it is the last place that may answer in hardcoded English under a bilingual UI.
   if (o?.code === "verify") return t("welcome.auth.verifyInvalid");

From 3eb0f41962b99213f3cecbe6e12574bfccd128c8 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 05:50:40 +0200
Subject: [PATCH 46/52] fix(plex): a Plex reorder the server accepted is the
 order the cache holds
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The YouTube list got this rule in round 5 — one accepted write, one cache entry
that matches it — and the Plex list got only the rollback half of that fix. Its
success path invalidated `qk.plexPlaylists()`, a disjoint key root, and never
touched `qk.plexPlaylist(id)`: the key `putBack` rolls back to, and the one a
re-entry renders from without refetching.

So after an accepted drag the detail cache still held the pre-reorder order.
Leaving the playlist and coming back inside the 30 s staleTime showed the
reorder undone, and the next drag from there persisted that — silently undoing
an order the server had taken. Measured in jsdom: server 2,1,3, cache 1,2,3, no
refetch.

1 test, mutation-checked.
---
 .../PlexPlaylistReorder.dom.test.tsx          | 90 +++++++++++++++++++
 frontend/src/components/PlexPlaylistView.tsx  | 13 ++-
 2 files changed, 102 insertions(+), 1 deletion(-)
 create mode 100644 frontend/src/components/PlexPlaylistReorder.dom.test.tsx

diff --git a/frontend/src/components/PlexPlaylistReorder.dom.test.tsx b/frontend/src/components/PlexPlaylistReorder.dom.test.tsx
new file mode 100644
index 00000000..b085f2b6
--- /dev/null
+++ b/frontend/src/components/PlexPlaylistReorder.dom.test.tsx
@@ -0,0 +1,90 @@
+// @vitest-environment jsdom
+//
+// One accepted write, one cache entry that matches it — the Plex half.
+//
+// `Playlists.tsx` (the YouTube list) got this rule in round 5: the detail cache is what a rollback
+// reads and what a re-entry inside the 30 s staleTime renders without refetching, so an accepted
+// reorder that is not written there leaves the cache disagreeing with the server. The Plex list got
+// the rollback half of that round's fix and not this half (round 6).
+//
+// Its own file: `@dnd-kit/core` is mocked module-wide so the test can fire `onDragEnd` directly —
+// dnd-kit's pointer sensor does not activate under jsdom (no layout, no pointer capture).
+import { it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, cleanup, screen, act, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({ t: (key: string) => key, i18n: { language: "en" } }),
+  };
+});
+
+const { dragEnd } = vi.hoisted(() => ({ dragEnd: { fire: (_e: unknown) => {} } }));
+vi.mock("@dnd-kit/core", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@dnd-kit/core")>();
+  return {
+    ...actual,
+    DndContext: ({
+      children,
+      onDragEnd,
+    }: {
+      children: React.ReactNode;
+      onDragEnd: (e: unknown) => void;
+    }) => {
+      dragEnd.fire = onDragEnd;
+      return <>{children}</>;
+    },
+  };
+});
+
+import PlexPlaylistView from "./PlexPlaylistView";
+import { api, type PlexCard } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+const movie = (id: string) =>
+  ({ id, type: "movie", title: `Movie ${id}`, year: 2020, thumb: "" }) as unknown as PlexCard;
+
+it("writes the order the server accepted into the detail cache", async () => {
+  vi.spyOn(api, "plexPlaylist").mockResolvedValue({
+    id: 5,
+    title: "Films",
+    items: [movie("1"), movie("2"), movie("3")],
+  });
+  const reorder = vi.spyOn(api, "plexReorderPlaylist").mockResolvedValue(undefined as never);
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  render(
+    <QueryClientProvider client={qc}>
+      <PlexPlaylistView playlistId={5} onBack={() => {}} onPlay={() => {}} />
+    </QueryClientProvider>,
+  );
+  await screen.findByText("Movie 1");
+  act(() => dragEnd.fire({ active: { id: "1" }, over: { id: "2" } }));
+  await waitFor(() => expect(reorder).toHaveBeenCalledWith(5, ["2", "1", "3"]));
+  // The list key was always invalidated; the DETAIL key — the one `putBack` reads and the one a
+  // re-entry renders from — kept the pre-reorder order, so leaving and coming back inside the
+  // staleTime showed the reorder undone, and the next drag persisted that.
+  await waitFor(() =>
+    expect(
+      qc.getQueryData<{ items: PlexCard[] }>(qk.plexPlaylist(5))?.items.map((i) => i.id),
+    ).toEqual(["2", "1", "3"]),
+  );
+});
diff --git a/frontend/src/components/PlexPlaylistView.tsx b/frontend/src/components/PlexPlaylistView.tsx
index 9e3f33f3..a4cc0e58 100644
--- a/frontend/src/components/PlexPlaylistView.tsx
+++ b/frontend/src/components/PlexPlaylistView.tsx
@@ -427,7 +427,18 @@ export default function PlexPlaylistView({
         playlistId,
         next.map((i) => i.id),
       )
-      .then(() => qc.invalidateQueries({ queryKey: qk.plexPlaylists() }))
+      .then(() => {
+        // Write the accepted order into the DETAIL cache, not just the list. That cache is what
+        // `putBack` rolls back to and what a re-entry inside the 30 s staleTime renders without
+        // refetching — so after an accepted reorder it showed the pre-reorder order again, and the
+        // next drag from there persisted it, silently undoing the one the server took. The
+        // YouTube sibling (`Playlists.tsx`) got this in round 5; this half was left behind (round
+        // 6). One accepted write, one cache entry that matches it.
+        qc.setQueryData<{ items: PlexCard[] }>(qk.plexPlaylist(playlistId), (old) =>
+          old ? { ...old, items: next } : old,
+        );
+        qc.invalidateQueries({ queryKey: qk.plexPlaylists() });
+      })
       .catch((e: unknown) => {
         notifyActionError(e, t("plex.playlist.reorderFailed"));
         putBack();

From 71d7646bf15366f170598bf940e3e3b1bb3e2002 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 16:21:37 +0200
Subject: [PATCH 47/52] fix(plex): a name this session cannot write fails at
 once, and the layout has one spelling
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 6 turned `artifact_may_arrive` into a positive rule, but keyed it to the HLS vocabulary in
general rather than to what THIS session produces: the playlist regex accepted master/index/stream_*
for every session and the `seq == 0` branch accepted any variant token unconditionally. The two argv
branches are disjoint — a single-audio session is given `seg_%d.ts` + `index.m3u8` and no `%v` at
all, so `master.m3u8`, `stream_*.m3u8` and every `seg_<variant>_<n>.ts` are names it can never write,
and vice versa — so each of those was read as "an HLS name, so wait and see" and held a threadpool
worker, plus its pooled DB connection, for the full timeout. That is verbatim the round-5 outage the
route's own comment claims it prevents.

Measured through the real route against a live single-audio session, before: master.m3u8 404 after
30.0s, stream_q7z.m3u8 404 after 30.0s, seg_a0_0.ts / seg_zzzz_0.ts / seg_0_0.ts 404 after 20.1s
each. After, on the running localdev API: 404 in 44-316ms for all of them, while index.m3u8,
seg_0.ts and seg_1.ts still answer 200 — nothing is over-refused.

The session now carries the rendition names its ffmpeg was told to write, and `entry` is derived from
them instead of passed. And "one place" now means the argv BUILDS its patterns from the same
functions the parser reads back (`segment_name("%d", "%v")`, `variant_playlist_name("%v")`): the
layout was still spelled out independently in six places, with `_VIDEO_VARIANT` read by no consumer,
which is the drift that caused round 6's HIGH. A test asserts the argv's own patterns are what those
functions produce, and that every name they expand to is one the guard accepts.

The load-bearing MEASURED comment cited ffmpeg 8.1.1 — the Windows host's. The binary that writes
these files is the API container's 7.1.5; re-measured there, the conclusion holds.
---
 backend/app/plex/stream.py                | 115 ++++++++++++++++------
 backend/app/routes/plex/playback.py       |  12 ++-
 backend/tests/test_plex_hls_file_route.py | 107 +++++++++++++++++---
 3 files changed, 189 insertions(+), 45 deletions(-)

diff --git a/backend/app/plex/stream.py b/backend/app/plex/stream.py
index b6b51161..e65d65e8 100644
--- a/backend/app/plex/stream.py
+++ b/backend/app/plex/stream.py
@@ -26,6 +26,7 @@ import shutil
 import subprocess
 import threading
 import time
+from collections.abc import Sequence
 from pathlib import Path
 
 from sqlalchemy.orm import Session as DbSession
@@ -99,7 +100,7 @@ class HlsSession:
         directory: Path,
         proc: subprocess.Popen,
         start_s: float,
-        entry: str,
+        variants: "Sequence[str]",
         transcode: bool = False,
         hw: bool = False,
         tonemap: bool = False,
@@ -126,7 +127,13 @@ class HlsSession:
         # subtitle cue-shift both key off the true content position — no drift. Provisional = X until
         # the first segment is probed.
         self.media_start_s = start_s
-        self.entry = entry  # the playlist filename hls.js should load (master.m3u8 with subs, else index.m3u8)
+        # The rendition names this session's ffmpeg was told to write — () for a single-audio
+        # session. Held on the session because it is what `artifact_may_arrive` needs to tell a name
+        # this session CAN produce from one belonging to the other argv branch (see it).
+        self.variants = tuple(variants)
+        # The playlist filename hls.js should load: the master of a multi-audio session, else the
+        # single index. Derived, not passed, so it cannot disagree with the argv.
+        self.entry = _MASTER_PL if self.variants else _INDEX_PL
         self.last_access = time.time()
 
 
@@ -509,7 +516,8 @@ def _ffmpeg_cmd(
         # switches audio CLIENT-SIDE on the same timeline (no session restart, no drift) — the premium
         # audio-switch path. Produces master.m3u8 + one stream_%v.m3u8 and seg_%v_*.ts per variant,
         # where %v is the video rendition's index ("0") and each audio rendition's `name:` (a0, a1,
-        # …) — see `_SEG_NAME_RE`, which is the one place that layout is written down.
+        # …). Those names are spelled by `segment_name` / `variant_playlist_name` below, which the
+        # guard and the warm-up read back — see them for the measurement behind the ordering.
         args += ["-map", "0:v:0"]
         for i in range(len(audio_langs)):
             args += ["-map", f"{ai}:a:{i}?"]
@@ -523,14 +531,16 @@ def _ffmpeg_cmd(
             if i == 0:
                 entry += ",default:yes"
             var.append(entry)
+        # The name patterns come from the vocabulary functions, with ffmpeg's own placeholders passed
+        # through them — so the producer and the parser cannot spell the layout differently (round 7).
         args += _HLS_TAIL + [
             "-master_pl_name",
-            "master.m3u8",
+            _MASTER_PL,
             "-var_stream_map",
             " ".join(var),
             "-hls_segment_filename",
-            str(out_dir / "seg_%v_%d.ts"),
-            str(out_dir / "stream_%v.m3u8"),
+            str(out_dir / segment_name("%d", "%v")),
+            str(out_dir / variant_playlist_name("%v")),
         ]
     else:
         ao = audio_ord if audio_ord is not None else 0
@@ -538,8 +548,8 @@ def _ffmpeg_cmd(
         args += [*venc, *_aenc_opts(loudnorm)]
         args += _HLS_TAIL + [
             "-hls_segment_filename",
-            str(out_dir / "seg_%d.ts"),
-            str(out_dir / "index.m3u8"),
+            str(out_dir / segment_name("%d")),
+            str(out_dir / _INDEX_PL),
         ]
     return args
 
@@ -627,6 +637,9 @@ def start_session(
     start_s = max(0.0, float(start_s))
     audio_langs = _probe_audio_langs(src) if multi else []
     is_multi = len(audio_langs) > 1  # only worth a master playlist when there really are ≥2 tracks
+    # The rendition names the argv below will produce — one source for the argv, the warm-up's
+    # segment names, the entry playlist and the artifact guard.
+    variants = session_variants(audio_langs if is_multi else None)
     # Loudness normalisation changes the AUDIO THE SEGMENTS CONTAIN, so it belongs in the directory
     # name beside the other parameters that do (offset, audio track, A/V offset): a session left over
     # from before the admin flipped the knob must not be mistaken for one that honours it. Appended to
@@ -636,7 +649,7 @@ def start_session(
     directory = _HLS_ROOT / f"{key}_{int(start_s)}_{tag}_{aoff:+.2f}"
 
     def _seg(i: int) -> Path:
-        return directory / segment_name(i, is_multi)
+        return directory / segment_name(i, _VIDEO_VARIANT if variants else None)
 
     def _spawn(
         hw: bool, tonemap: bool = False, *, replace_only: "HlsSession | None" = None
@@ -691,7 +704,7 @@ def start_session(
                 directory,
                 proc,
                 start_s,
-                "master.m3u8" if is_multi else "index.m3u8",
+                variants,
                 transcode=transcode,
                 hw=hw,
                 tonemap=tonemap,
@@ -763,27 +776,64 @@ def current_session(key: str) -> HlsSession | None:
         return s
 
 
-# The names ffmpeg writes into a session directory, in ONE place. Getting this wrong is invisible —
-# every path that reads a name falls back to "wait and see" — so it is a constant plus a matching
-# parser, not three comments that can drift (they did: deep-review round 6 found the regex, `_seg`
-# and the comment above `_ffmpeg_cmd` all disagreeing).
+# The names ffmpeg writes into a session directory, in ONE place — and "one place" means the argv
+# BUILDS its patterns from these same functions (`segment_name("%d", "%v")`), not that a comment
+# says so. Getting this wrong is invisible in both directions: a name we failed to anticipate used
+# to fall back to "wait and see" (round 6's HIGH), and now that the rule is positive it falls back
+# to a 404 instead — so the producer and the parser have to be literally the same spelling.
 #
-# MEASURED (ffmpeg 8.1.1, this repo's own argv): `-hls_segment_filename seg_%v_%d.ts` substitutes
-# `%v` with the VARIANT and `%d` with the SEQUENCE — variant FIRST. A dual-audio session writes
-# seg_0_0.ts… (video, the unnamed variant) plus seg_a0_0.ts… / seg_a1_0.ts… (the `name:aN` audio
-# renditions), and the playlists beside them are master.m3u8 + stream_0/a0/a1.m3u8. Single-audio
-# uses `seg_%d.ts` + index.m3u8, with no variant field at all.
+# MEASURED (ffmpeg 7.1.5 in the API container — the binary that actually writes these files — and
+# re-checked on 8.1.1): `-hls_segment_filename seg_%v_%d.ts` substitutes `%v` with the VARIANT and
+# `%d` with the SEQUENCE — variant FIRST. A dual-audio session writes seg_0_0.ts… (video, the
+# unnamed variant) plus seg_a0_0.ts… / seg_a1_0.ts… (the `name:aN` audio renditions), and the
+# playlists beside them are master.m3u8 + stream_0/a0/a1.m3u8. Single-audio uses `seg_%d.ts` +
+# index.m3u8, with no variant field at all.
+#
+# The two argv branches are DISJOINT vocabularies, which is why the guard below is keyed to the
+# SESSION and not to HLS in general: a single-audio session can never write `master.m3u8`,
+# `stream_*.m3u8` or any `seg_<variant>_<n>.ts`, and a multi-audio one can never write `index.m3u8`
+# or `seg_<n>.ts`. Accepting the union meant a hopeless name of the other shape was waited out for
+# the full playlist/segment timeout — the threadpool parking this guard exists to end (round 7).
+_MASTER_PL = "master.m3u8"
+_INDEX_PL = "index.m3u8"
 _SEG_NAME_RE = re.compile(r"^seg_(?:([0-9a-z]{1,4})_)?(\d{1,9})\.ts$")
-_PLAYLIST_NAME_RE = re.compile(r"^(?:master|index|stream_[0-9a-z]{1,4})\.m3u8$")
 
 
-def segment_name(seq: int, is_multi: bool) -> str:
-    """The file ffmpeg writes for the `seq`-th VIDEO segment of a session."""
-    return f"seg_{_VIDEO_VARIANT}_{seq}.ts" if is_multi else f"seg_{seq}.ts"
+def session_variants(audio_langs: "Sequence[str | None] | None") -> tuple[str, ...]:
+    """The `-var_stream_map` rendition names a session will write, or () for a single-audio one.
+
+    The video rendition is left unnamed in the map, so ffmpeg falls back to its index
+    (`_VIDEO_VARIANT`); each audio rendition is named `aN` in track order."""
+    if not audio_langs:
+        return ()
+    return (_VIDEO_VARIANT, *(f"a{i}" for i in range(len(audio_langs))))
 
 
-def artifact_may_arrive(directory: Path, filename: str) -> bool:
-    """Whether waiting for `filename` can possibly end in a file.
+def segment_name(seq: "int | str", variant: "str | None" = None) -> str:
+    """The file ffmpeg writes for the `seq`-th segment of `variant`.
+
+    `variant=None` is a single-audio session, whose argv carries no `%v` field at all. `seq` and
+    `variant` are typed loosely because `_ffmpeg_cmd` builds its own `-hls_segment_filename` pattern
+    through this function, passing ffmpeg's `"%d"` / `"%v"` placeholders — that is what keeps the
+    producer and the parser from drifting, rather than a comment asking the next editor not to."""
+    return f"seg_{variant}_{seq}.ts" if variant else f"seg_{seq}.ts"
+
+
+def variant_playlist_name(variant: str) -> str:
+    """The sub-playlist ffmpeg writes for one rendition of a multi-audio session."""
+    return f"stream_{variant}.m3u8"
+
+
+def playlist_names(variants: "Sequence[str]") -> frozenset[str]:
+    """Every playlist name this session's argv can write — the master plus one per rendition, or
+    just `index.m3u8` for a single-audio session."""
+    if not variants:
+        return frozenset({_INDEX_PL})
+    return frozenset({_MASTER_PL, *(variant_playlist_name(v) for v in variants)})
+
+
+def artifact_may_arrive(s: "HlsSession", filename: str) -> bool:
+    """Whether waiting for `filename` can possibly end in a file OF THIS SESSION.
 
     Positive rule, not a blocklist: a session produces segments and playlists and NOTHING else, so
     any other name is refused at once. ffmpeg also produces segments strictly in order, so a segment
@@ -791,23 +841,32 @@ def artifact_may_arrive(directory: Path, filename: str) -> bool:
     and no amount of waiting will conjure it. Playlists are the one thing that must still be waited
     for: they are rewritten continuously and have no ordering to read.
 
+    Keyed to the SESSION's own vocabulary, not to HLS's: the two argv branches are disjoint, so a
+    name belonging to the other shape is as hopeless here as a random string. Reading those as "an
+    HLS name, so wait and see" left the whole class reachable — measured through the real route
+    against a live single-audio session, `master.m3u8` and `stream_q7z.m3u8` were 404s after 30.0 s
+    and `seg_a0_0.ts` / `seg_zzzz_0.ts` after 20.1 s each (deep-review round 7).
+
     Saying no at once matters because the route that waits is a SYNC one: it holds a thread off the
     ~40-slot pool, and a pooled DB connection with it, for the whole timeout. An ordinary seek past
     the produced region was enough to park one for 20 s, and forty concurrent requests for a name
     that will never exist parked the whole API (deep-review round 5). Round 5's guard read only
     single-audio segment names, so both halves of that were still fully reachable: every multi-audio
     name fell through, and so did any `.m3u8`/`.vtt` name at all."""
-    if _PLAYLIST_NAME_RE.match(filename):
+    if filename in playlist_names(s.variants):
         return True
     m = _SEG_NAME_RE.match(filename)
     if m is None:
         return False
     variant, seq = m.group(1), int(m.group(2))
+    # The variant field must be one THIS session writes: present and known for a multi-audio
+    # session, absent for a single-audio one.
+    if variant not in (s.variants or (None,)):
+        return False
     if seq == 0:
         return True
-    prev = f"seg_{variant}_{seq - 1}.ts" if variant else f"seg_{seq - 1}.ts"
     try:
-        return (directory / prev).exists()
+        return (s.dir / segment_name(seq - 1, variant)).exists()
     except OSError:
         return False
 
diff --git a/backend/app/routes/plex/playback.py b/backend/app/routes/plex/playback.py
index 42105e09..d08b81ca 100644
--- a/backend/app/routes/plex/playback.py
+++ b/backend/app/routes/plex/playback.py
@@ -673,12 +673,14 @@ def stream_hls_file(
     if s is None or s.id != session_id:
         raise HTTPException(status_code=404, detail="No active playback session")
     path = s.dir / filename
-    # Only a name this session can actually produce is worth waiting for: the playlists, and a
-    # segment whose predecessor is already on disk (ffmpeg writes them in order, so if it is not
-    # there this one is not next). Answering now instead of waiting it out is what keeps a seek past
-    # the produced region — or a deliberate flood of hopeless names — from parking threadpool
+    # Only a name THIS session can actually produce is worth waiting for: its own playlists, and a
+    # segment of one of its own renditions whose predecessor is already on disk (ffmpeg writes them
+    # in order, so if it is not there this one is not next). The session is passed, not just its
+    # directory, because the single- and multi-audio argv branches spell their names differently and
+    # neither can produce the other's. Answering now instead of waiting it out is what keeps a seek
+    # past the produced region — or a deliberate flood of hopeless names — from parking threadpool
     # workers and their DB connections (see `artifact_may_arrive`).
-    if not plex_stream.artifact_may_arrive(s.dir, filename):
+    if not plex_stream.artifact_may_arrive(s, filename):
         raise HTTPException(status_code=404, detail="Not available yet")
     timeout = 30 if ext == ".m3u8" else 20
     # `proc` so a session whose ffmpeg has already exited answers at once instead of polling out the
diff --git a/backend/tests/test_plex_hls_file_route.py b/backend/tests/test_plex_hls_file_route.py
index 448b2bfc..81fb645c 100644
--- a/backend/tests/test_plex_hls_file_route.py
+++ b/backend/tests/test_plex_hls_file_route.py
@@ -39,11 +39,16 @@ class _Proc:
 
 
 class _Session:
-    def __init__(self, session_id: str, directory, running: bool = False):
+    def __init__(self, session_id: str, directory, running: bool = False, audio_langs=None):
         self.id = session_id
         self.dir = directory
         self.proc = _Proc(running)
         self.last_access = time.time()
+        # The real session derives both of these from the argv it spawned; the guard reads
+        # `variants` to tell a name this session can produce from one only the OTHER argv branch
+        # writes, so a stand-in without it would test a shape that cannot exist.
+        self.variants = plex_stream.session_variants(audio_langs)
+        self.entry = "master.m3u8" if self.variants else "index.m3u8"
 
 
 @pytest.fixture
@@ -145,7 +150,7 @@ def test_a_multi_audio_segment_beyond_the_region_fails_at_once_too(
     d.mkdir()
     (d / "seg_0_0.ts").write_bytes(b"x")
     (d / "seg_a0_0.ts").write_bytes(b"x")
-    sessions["m1"] = _Session("sid-a", d, running=True)
+    sessions["m1"] = _Session("sid-a", d, running=True, audio_langs=["hu", "en"])
     started = time.monotonic()
     r = client.get(f"/api/plex/stream/m1/hls/sid-a/{name}")
     elapsed = time.monotonic() - started
@@ -161,7 +166,7 @@ def test_a_multi_audio_segment_whose_predecessor_exists_is_served(client, tmp_pa
     d.mkdir()
     (d / "seg_a0_0.ts").write_bytes(b"x")
     (d / "seg_a0_1.ts").write_bytes(b"audio")
-    sessions["m1"] = _Session("sid-a", d, running=True)
+    sessions["m1"] = _Session("sid-a", d, running=True, audio_langs=["hu", "en"])
     r = client.get("/api/plex/stream/m1/hls/sid-a/seg_a0_1.ts")
     assert r.status_code == 200, r.text
     assert r.content == b"audio"
@@ -227,13 +232,91 @@ def test_a_dead_producer_is_not_waited_out(client, tmp_path, sessions):
     assert elapsed < 2.0, f"waited {elapsed:.1f}s on a producer that had already exited"
 
 
-@pytest.mark.parametrize("is_multi", [False, True])
-def test_the_name_ffmpeg_is_asked_for_is_a_name_the_guard_understands(tmp_path, is_multi):
-    """One vocabulary, enforced. `segment_name` is what the warm-up and the PTS probe wait for, and
-    `artifact_may_arrive` is what the route parses — they were three separate statements of the
-    layout and two of them were wrong. Pin them to each other instead."""
-    name = plex_stream.segment_name(3, is_multi)
-    prev = plex_stream.segment_name(2, is_multi)
-    assert not plex_stream.artifact_may_arrive(tmp_path, name)
+@pytest.mark.parametrize("audio_langs", [None, ["hu", "en"]])
+def test_the_name_ffmpeg_is_asked_for_is_a_name_the_guard_understands(tmp_path, audio_langs):
+    """One vocabulary, enforced. `segment_name` is what the warm-up and the PTS probe wait for, what
+    the argv's own `-hls_segment_filename` pattern is built from, and what `artifact_may_arrive`
+    parses back — they were three separate statements of the layout and two of them were wrong. Pin
+    them to each other instead."""
+    sess = _Session("sid", tmp_path, audio_langs=audio_langs)
+    variant = sess.variants[0] if sess.variants else None
+    name = plex_stream.segment_name(3, variant)
+    prev = plex_stream.segment_name(2, variant)
+    assert not plex_stream.artifact_may_arrive(sess, name)
     (tmp_path / prev).write_bytes(b"x")
-    assert plex_stream.artifact_may_arrive(tmp_path, name)
+    assert plex_stream.artifact_may_arrive(sess, name)
+
+
+def test_the_argv_asks_for_exactly_the_names_the_guard_accepts(tmp_path):
+    """The producer and the parser, pinned to each other through the argv itself.
+
+    Round 6's HIGH was a guard that read `seg_%v_%d.ts` sequence-first, so it was inert on every
+    multi-audio item, and a warm-up that waited 8 s for a name ffmpeg never writes. The fix was to
+    give the layout one spelling — but a comment saying so is what had just failed, so assert that
+    the `-hls_segment_filename` pattern in the real argv is literally what `segment_name` produces,
+    and that every playlist the argv names is one `playlist_names` accepts."""
+    for audio_langs in (None, ["hu", "en", "de"]):
+        args = plex_stream._ffmpeg_cmd(
+            tmp_path / "in.mkv", 0.0, tmp_path, 0, 0.0, audio_langs, loudnorm=False
+        )
+        variants = plex_stream.session_variants(audio_langs)
+        sess = _Session("sid", tmp_path, audio_langs=audio_langs)
+        # The two patterns in the argv are the vocabulary's own spelling, `%d`/`%v` and all.
+        seg_pattern = args[args.index("-hls_segment_filename") + 1]
+        pl_pattern = args[-1].rsplit("/", 1)[-1].rsplit("\\", 1)[-1]
+        if variants:
+            assert seg_pattern.endswith(plex_stream.segment_name("%d", "%v")), seg_pattern
+            assert pl_pattern == plex_stream.variant_playlist_name("%v"), pl_pattern
+            assert args[args.index("-master_pl_name") + 1] == plex_stream._MASTER_PL
+        else:
+            assert seg_pattern.endswith(plex_stream.segment_name("%d")), seg_pattern
+            assert pl_pattern == plex_stream._INDEX_PL, pl_pattern
+            assert "-master_pl_name" not in args
+
+        # And every name those patterns can actually expand to is one the guard lets through — the
+        # entry playlist hls.js is handed included, since a session whose own manifest is refused
+        # cannot start at all.
+        for v in variants or (None,):
+            assert plex_stream.artifact_may_arrive(sess, plex_stream.segment_name(0, v))
+            if v is not None:
+                assert plex_stream.artifact_may_arrive(sess, plex_stream.variant_playlist_name(v))
+        assert plex_stream.artifact_may_arrive(sess, sess.entry)
+
+
+def test_a_name_only_the_other_argv_branch_writes_is_refused_at_once(tmp_path, client, sessions):
+    """The guard is keyed to THIS session's vocabulary, not to HLS in general.
+
+    The two argv branches are disjoint: a single-audio session is given `seg_%d.ts` + `index.m3u8`
+    and no `%v` at all, so `master.m3u8`, `stream_*.m3u8` and every `seg_<variant>_<n>.ts` are names
+    it can never write — and vice versa. Accepting the union read them as "an HLS name, so wait and
+    see", and each one then held a threadpool worker and its pooled DB connection for the full
+    timeout: measured through this route against a live single-audio session, `master.m3u8` took
+    30.0 s and `seg_a0_0.ts` 20.1 s to answer 404 (deep-review round 7)."""
+    single = tmp_path / "m1_0_0_+0.00"
+    single.mkdir()
+    sessions["m1"] = _Session("sid-a", single, running=True)
+    multi = tmp_path / "m2_0_multi_+0.00"
+    multi.mkdir()
+    sessions["m2"] = _Session("sid-b", multi, running=True, audio_langs=["hu", "en"])
+
+    # Each of these belongs to the other shape (or to no shape at all) and must be refused without
+    # a wait — the assertion is the ELAPSED time as much as the status.
+    for key, sid, names in (
+        ("m1", "sid-a", ["master.m3u8", "stream_0.m3u8", "seg_0_0.ts", "seg_zzzz_0.ts"]),
+        ("m2", "sid-b", ["index.m3u8", "seg_0.ts", "seg_a9_0.ts", "stream_zz.m3u8"]),
+    ):
+        for name in names:
+            started = time.monotonic()
+            r = client.get(f"/api/plex/stream/{key}/hls/{sid}/{name}")
+            elapsed = time.monotonic() - started
+            assert r.status_code == 404, f"{name}: {r.text}"
+            assert elapsed < 2.0, (
+                f"{name}: waited {elapsed:.1f}s for a name this session cannot write"
+            )
+
+    # And the control: the names each session CAN write are still waited for, not refused.
+    assert plex_stream.artifact_may_arrive(sessions["m1"], "index.m3u8")
+    assert plex_stream.artifact_may_arrive(sessions["m1"], "seg_0.ts")
+    assert plex_stream.artifact_may_arrive(sessions["m2"], "master.m3u8")
+    assert plex_stream.artifact_may_arrive(sessions["m2"], "stream_a1.m3u8")
+    assert plex_stream.artifact_may_arrive(sessions["m2"], "seg_a1_0.ts")

From 8036251589c6d5dcdbb3937e88978737e379532a Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 16:21:51 +0200
Subject: [PATCH 48/52] fix(plex): the reclaim window rolls, and a refused
 finish is not performed through a third route
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two ways round 6's own fixes did not bound what their comments said they bounded.

The reclaim budget's window anchor was written only where the window RESET, so it marked the window's
start rather than the last loss — a tumbling window, not the rolling one the constant is named for.
Any loss cadence slower than half the window satisfied the reset on every second loss, so the budget
never reached its bound: measured over 200 loss cycles, 61/70/90/119s apart all gave 200 reclaims and
never an error, while 5s and 30s apart correctly gave two and then the honest answer. The failing
band is exactly the case the ERROR handler names — a transcode that falls behind realtime — and both
committed tests spaced their losses 0s and 10min apart, i.e. outside it. The anchor now moves with
every loss.

And `finish`'s refusal handler lowered the play-through latch, which is the only gate on the 10s
interval, the page-hide beacon and `settle`. All three post `absRef`, which on the play-to-the-end
path IS the end of the media, and the backend reads a position within `_FINISH_MARGIN_S` of the
duration as a finish — so within ten seconds of the toast saying the mark had failed, the item was
marked watched, its position cleared and a scrobble sent to Plex. Round 6 closed the explicit
rollback write and left the other three open; the test it added set `upNext: false`, which tears the
effect down before any of them can fire. The refusal now takes back the CLAIM rather than the latch:
a second flag stops `settle` re-asserting watched, and playing again clears both.

`FINISH_MARGIN_S` duplicated the backend's constant in a second language with nothing relating them,
and its comment had the asymmetry backwards — if the BACKEND's margin grows, this guard starts
admitting a rollback the backend reads as a finish, i.e. re-opens the defect above. Pinned by a
contract test that reads the Python, and the comment corrected.
---
 .../components/PlexPlayer.hls.dom.test.tsx    | 28 +++++++++++
 .../PlexPlayer.session.dom.test.tsx           | 38 +++++++++++++++
 frontend/src/components/PlexPlayer.tsx        | 12 +++--
 .../src/lib/plexFinishMargin.contract.test.ts | 39 ++++++++++++++++
 frontend/src/lib/plexPlayerHooks.ts           | 46 ++++++++++++++-----
 5 files changed, 149 insertions(+), 14 deletions(-)
 create mode 100644 frontend/src/lib/plexFinishMargin.contract.test.ts

diff --git a/frontend/src/components/PlexPlayer.hls.dom.test.tsx b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
index cc78a1fd..1e83fb9e 100644
--- a/frontend/src/components/PlexPlayer.hls.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.hls.dom.test.tsx
@@ -220,6 +220,34 @@ describe("an HLS session the server no longer has", () => {
     }
   });
 
+  it("gives up on a session lost over and over on a SLOW cadence too", async () => {
+    // The window's anchor used to be written only where the window RESET, so it marked the start of
+    // the window instead of the last loss — a tumbling window, not the rolling one the constant is
+    // named for. Any cadence slower than half the window then cleared the budget on every second
+    // loss and the bound never bit: a transcode falling ~70s behind realtime — the case the ERROR
+    // handler itself names — reclaimed forever (measured: 200 losses 70s apart → 200 reclaims,
+    // never an error). The two cases above space their losses 0s and 10min apart, i.e. both sit
+    // outside the 60–120s band where the defect lived (deep-review round 7).
+    vi.useFakeTimers({ shouldAdvanceTime: true, toFake: ["Date"] });
+    try {
+      const session = mount();
+      const v = () => document.querySelector("video") as Media;
+      for (let i = 0; i < 6 && !screen.queryByText("plex.player.errGeneric"); i++) {
+        await waitFor(() => expect(hlsInstances).toHaveLength(i + 1));
+        act(() => hlsInstances[i]!.emit(Hls.Events.MANIFEST_PARSED));
+        v()._t = 700;
+        act(() => void v().dispatchEvent(new Event("timeupdate")));
+        act(() => hlsInstances[i]!.emit(Hls.Events.ERROR, lost404));
+        act(() => void vi.setSystemTime(Date.now() + 70_000));
+      }
+      await screen.findByText("plex.player.errGeneric");
+      // Two reclaims, each within two minutes of the loss before it — then the honest answer.
+      expect(session).toHaveBeenCalledTimes(3);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
   it("is a failure, not a restart, when the session never played", async () => {
     // Otherwise a session that 404s from the start would restart itself in a loop.
     const session = mount();
diff --git a/frontend/src/components/PlexPlayer.session.dom.test.tsx b/frontend/src/components/PlexPlayer.session.dom.test.tsx
index f1ac961f..5593d358 100644
--- a/frontend/src/components/PlexPlayer.session.dom.test.tsx
+++ b/frontend/src/components/PlexPlayer.session.dom.test.tsx
@@ -382,6 +382,44 @@ describe("leaving an item that was played through", () => {
     expect(progress.mock.calls.filter(([id, , , final]) => id === "A" && final)).toEqual([]);
   });
 
+  it("performs the refused mark through no OTHER route while it stays on the finished item", async () => {
+    // Round 6 guarded the explicit rollback write, but the same catch lowered the play-through
+    // latch — and that latch is the only gate on the 10s interval, the page-hide beacon and
+    // `settle`. All three post `absRef`, which on this path IS the end of the media, and the
+    // backend reads a position within `_FINISH_MARGIN_S` of the duration as a finish: within ten
+    // seconds of the toast saying the mark had failed, the item was watched, its position cleared
+    // and a scrobble sent to Plex (deep-review round 7). `upNext` is ON here — the default — so the
+    // player STAYS on the finished item and those routes are live; the round-6 test above turns it
+    // off, which tears the effect down before any of them can fire.
+    prefs({ upNext: true });
+    const beacon = vi.spyOn(api, "plexProgressBeacon").mockImplementation(() => {});
+    const { qc, progress, unmount } = mount({
+      details: { A: item("A"), B: item("B") },
+      sessions: { A: () => Promise.resolve(direct("A")), B: () => new Promise(() => {}) },
+      queue: ["A", "B"],
+    });
+    vi.spyOn(api, "plexSetState").mockRejectedValue(new Error("offline"));
+    await playingAt("/media/A", 2995);
+    endMedia(); // the up-next card is up, the item is finished, and the mark comes back refused
+    await tick();
+    progress.mockClear();
+
+    // The viewer closes the tab while the failed-mark toast is still up.
+    act(() => void window.dispatchEvent(new Event("pagehide")));
+    expect(beacon).not.toHaveBeenCalled();
+
+    // The refusal dropped the cached detail — and the open player's own observer refetches it, so
+    // by the time the viewer leaves there is an entry again. `settle` must not re-assert watched
+    // onto it: only the server is honest about this item now.
+    act(() => void qc.setQueryData(qk.plexItem("A", "en"), item("A")));
+
+    // And leaving the player: `settle` must neither post the end position nor re-assert watched.
+    unmount();
+    await tick();
+    expect(progress.mock.calls.filter(([id]) => id === "A")).toEqual([]);
+    expect(qc.getQueryData<PlexItemDetail>(qk.plexItem("A", "en"))?.status).not.toBe("watched");
+  });
+
   it("does restore the position when the refused finish came from the credits skip", async () => {
     // The other caller of the same helper captures a MID-episode position, and there the rollback
     // is the point: without it the viewer loses the stretch they watched. One helper, two callers,
diff --git a/frontend/src/components/PlexPlayer.tsx b/frontend/src/components/PlexPlayer.tsx
index d566e960..0b3ed07a 100644
--- a/frontend/src/components/PlexPlayer.tsx
+++ b/frontend/src/components/PlexPlayer.tsx
@@ -435,9 +435,15 @@ export default function PlexPlayer({ itemId, onClose, queue }: Props) {
           if (parsed && data.type === Hls.ErrorTypes.NETWORK_ERROR && data.response?.code === 404) {
             const now = Date.now();
             // A new window: the last loss was long enough ago that this is a fresh incident, not the
-            // same session being lost over and over.
-            if (now - restartsRef.current.at > RECLAIM_WINDOW_MS)
-              restartsRef.current = { n: 0, at: now };
+            // same session being lost over and over. The anchor moves with EVERY loss, because with
+            // it left at the window's start the window tumbled instead of rolling: any loss period
+            // longer than half the window satisfied the reset on every second loss, so the budget
+            // never reached its bound and the reclaim loop it exists to end ran forever (measured:
+            // 200 losses 70s apart → 200 reclaims, never an error; 5s apart → 2 and an error, which
+            // is why the committed test, spacing its cases 0s and 10min apart, could not see it —
+            // deep-review round 7).
+            if (now - restartsRef.current.at > RECLAIM_WINDOW_MS) restartsRef.current.n = 0;
+            restartsRef.current.at = now;
             if (restartsRef.current.n < MAX_SESSION_RECLAIMS) {
               restartsRef.current.n += 1;
               loadSession(playhead(absRef, loadStartRef), !video.paused);
diff --git a/frontend/src/lib/plexFinishMargin.contract.test.ts b/frontend/src/lib/plexFinishMargin.contract.test.ts
new file mode 100644
index 00000000..c773e626
--- /dev/null
+++ b/frontend/src/lib/plexFinishMargin.contract.test.ts
@@ -0,0 +1,39 @@
+import { readFileSync } from "node:fs";
+import { expect, it } from "vitest";
+
+// One invariant, two languages, no shared wire format — so a test is the only thing that can hold
+// them together.
+//
+// The backend finishes an item when a progress checkpoint lands within `_FINISH_MARGIN_S` of the
+// duration: watched, position cleared, scrobbled to Plex. The player's refused-finish rollback must
+// therefore never post a position inside that window, or the branch named "take the finish back"
+// performs, through the backend, the very write that was just refused (rounds 6 and 7 both landed
+// on this). The frontend mirrors the number so it knows where the window starts.
+//
+// Both were 30 and exactly complementary, but nothing related them, so a backend-only change would
+// have re-opened the defect silently — a rule stated in a comment and not enforced in code, the one
+// thing this repo's house rules single out. The direction matters: the frontend's margin must be at
+// LEAST the backend's. Larger is merely conservative (a rollback skipped where it could have run);
+// smaller is the bug.
+//
+// Both values are read from source rather than imported: `plexPlayerHooks` pulls in the i18n module
+// (and with it `localStorage`), and booting half the app to read one integer would make this test
+// about the module graph instead of about the two numbers.
+function constantIn(path: string, pattern: RegExp): number {
+  const source = readFileSync(new URL(path, import.meta.url), "utf8");
+  const m = pattern.exec(source);
+  // If this fails the constant was renamed or moved — find it and re-point this test, because the
+  // invariant it guards did not go away.
+  expect(m, `${pattern} not found in ${path}`).not.toBeNull();
+  return Number(m![1]);
+}
+
+it("never lets the player's finish margin fall below the backend's", () => {
+  const backend = constantIn(
+    "../../../backend/app/routes/plex/playback.py",
+    /^_FINISH_MARGIN_S\s*=\s*(\d+)/m,
+  );
+  const frontend = constantIn("./plexPlayerHooks.ts", /^const FINISH_MARGIN_S\s*=\s*(\d+)/m);
+  expect(backend).toBeGreaterThan(0);
+  expect(frontend).toBeGreaterThanOrEqual(backend);
+});
diff --git a/frontend/src/lib/plexPlayerHooks.ts b/frontend/src/lib/plexPlayerHooks.ts
index 01ccfda3..90020698 100644
--- a/frontend/src/lib/plexPlayerHooks.ts
+++ b/frontend/src/lib/plexPlayerHooks.ts
@@ -23,9 +23,16 @@ import { PLEX_SCALE, normalizeVolumeIn, stepVolumeIn } from "./playerVolume";
 
 // How close to the end the backend counts as "finished" (`_FINISH_MARGIN_S` in routes/plex/playback):
 // a progress checkpoint at or past `duration - this` marks the item watched and clears the position.
-// Mirrored here because `finish`'s rollback must not accidentally drive that branch. It is a
-// one-way safety margin, not a shared contract — if the two ever diverge, the worst case is a
-// rollback that is skipped or a resume point set a few seconds from the end.
+// Mirrored here because `finish`'s rollback must not accidentally drive that branch.
+//
+// Drift is NOT symmetric, which an earlier version of this comment had backwards. If THIS value
+// grows, the rollback is skipped where it need not be — a lost resume point, annoying. If the
+// BACKEND's grows (its own comment invites that tuning by contrasting it with the feed's 10 s),
+// this guard starts admitting a rollback the backend reads as a finish, which marks the item
+// watched, clears the position and scrobbles to Plex — re-performing the very write that was just
+// refused, i.e. exactly the defect this constant was introduced to close. So the invariant is
+// one-directional and it is PINNED, not described: `plexFinishMargin.contract.test.ts` reads the
+// Python and fails if this value ever drops below it (round 7).
 const FINISH_MARGIN_S = 30;
 
 // A live wall clock for the top bar, re-rendered every 15s (minute resolution is enough for the
@@ -111,6 +118,16 @@ export function usePlexProgress(opts: {
   const finishRef = useRef<(confirmed?: Promise<unknown>) => void>(() => {});
   useEffect(() => {
     let finished = false;
+    // Raised when the caller's watched write came back REFUSED. The play-through latch itself stays
+    // up, because lowering it re-armed three other routes to the same write: the 10s interval, the
+    // page-hide beacon and `settle` all post `absRef`, which on this path IS the end of the media,
+    // and the backend reads a position within `_FINISH_MARGIN_S` of the duration as a finish. So the
+    // branch named "take the finish back" marked the item watched, cleared the position and
+    // scrobbled to Plex within ten seconds — the refused write performed through a third route,
+    // under an error toast saying it had failed. Round 6 closed only the explicit rollback write;
+    // this closes the other three (deep-review round 7). What the refusal does take back is the
+    // CLAIM: the cache must not say watched, and `settle` must not re-assert it on the way out.
+    let finishRefused = false;
     // `final` = a settled checkpoint (pause / page-hide / leaving the player) vs. the periodic tick.
     // Only final checkpoints get mirrored to a linked Plex account (backend-side debounce), so Plex
     // sees the resume position when the user actually stops — not a timeline call every 10 seconds.
@@ -157,6 +174,7 @@ export function usePlexProgress(opts: {
     window.addEventListener("pagehide", onHide);
     const onPlayAgain = () => {
       finished = false;
+      finishRefused = false;
     };
     video?.addEventListener("play", onPlayAgain);
     // Back (unmount) persists the position server-side via flush(), but reopening the same item in
@@ -170,9 +188,14 @@ export function usePlexProgress(opts: {
       // Match the language-keyed detail query (E5 S6) so the optimistic resume patch lands.
       const key = qk.plexItem(id, plexLang());
       if (finished) {
-        qc.setQueryData(key, (old) =>
-          old ? { ...old, status: "watched", position_seconds: 0 } : old,
-        );
+        // A refused finish claims nothing: the server has the item unwatched at the position the
+        // rollback restored, and the catch below has already dropped this entry, so the next open
+        // fetches the truth. Re-patching "watched / 0" here would put back the very lie the
+        // refusal handler removed.
+        if (!finishRefused)
+          qc.setQueryData(key, (old) =>
+            old ? { ...old, status: "watched", position_seconds: 0 } : old,
+          );
         return;
       }
       flush(true);
@@ -185,14 +208,15 @@ export function usePlexProgress(opts: {
     finishRef.current = (confirmed?: Promise<unknown>) => {
       finished = true;
       // The latch has to go up BEFORE the media pauses, so it cannot wait for the server. If the
-      // watched write is then refused, the latch is taken back: the cached detail said watched /
-      // position 0 while the server still had the item unwatched at the last checkpoint, and the
-      // once-per-id start guard meant the corrected detail arriving later was never used — the
-      // episode reopened at 0:00 with a Watched badge the server disagreed with (round 5).
+      // watched write is then refused, what is taken back is the CLAIM, not the latch (see
+      // `finishRefused`): the cached detail said watched / position 0 while the server still had
+      // the item unwatched at the last checkpoint, and the once-per-id start guard meant the
+      // corrected detail arriving later was never used — the episode reopened at 0:00 with a
+      // Watched badge the server disagreed with (round 5).
       const pos = Math.floor(absRef.current);
       const dur = durationRef.current;
       void confirmed?.catch(() => {
-        finished = false;
+        finishRefused = true;
         // Restore the resume point the finish replaced — but ONLY where there is one to restore.
         // On the play-to-the-end path `pos` IS the end of the media, and the backend reads a
         // position within `_FINISH_MARGIN_S` of the duration as a finish: it would set watched,

From c7a377396b2fe8b0e862534652185e63c51c1483 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 16:22:06 +0200
Subject: [PATCH 49/52] fix(ui): a closing dialog leaves the focus to the
 dialog standing above it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 6 widened dialog focus ownership to count focus inside ANY `aria-modal` subtree as ours, so a
dialog and the dialog stacked on it closing together would still hand the focus back. That clause has
no way to tell a layer closing WITH us from one that stays open, so a dialog closing on its own — an
in-flight mutation's `onSuccess`, not a click, since a scrim covers it — under a modal raised above it
pulled the focus onto its own pre-open trigger, behind that scrim, where Enter still activated it.
Three verifiers confirmed the mechanism and two corrected the severity down: it self-heals on the
next Tab, which is why this is a containment violation rather than a broken end state.

`lib/layerStack` cannot refine it. Measured against the real hook: at the instant the lower dialog's
focus cleanup runs, the both-closing case and the sibling-stays-open case give identical readings —
`anyLayerAbove` true, the upper layer topmost — because passive cleanups run parent-first and
`useDialogChrome` is declared before the effect that calls `removeLayer`. Gating on the stack turns
round 6's own test red. What separates them is the DOM: React detaches a deleted subtree before
passive cleanups, so a layer closing with us is already disconnected while one that stays open is
not. Both tests are green, and each was mutation-checked against the other.

Verified in Chrome on localdev: opening the cheat sheet from a sidebar button and closing it restores
that button; with the command palette stacked over the cheat sheet, closing the top one leaves the
focus neither on the background trigger nor on <body>, and closing both returns it to the trigger.

Welcome's Lightbox got the trap and the restore in round 6 but not the layer membership the other
shells have, so its Escape and Tab fired from a raw window listener whatever was on top — the shape
the wizard's comment records being bitten by, unreachable today only by a mount ordering nothing
enforces. It joins the stack. Its comment also read as though the four-shell sweep were finished:
`PlayerModal` is still an `aria-modal` surface with no name, no trap and no restore, which is on
ROADMAP.md now rather than implied to be done.
---
 frontend/src/components/Welcome.tsx           | 43 +++++++++++++++----
 frontend/src/components/ui/Modal.dom.test.tsx | 37 ++++++++++++++++
 frontend/src/components/ui/dialogFocus.ts     | 22 +++++++++-
 .../welcomeMode.render.dom.test.tsx           | 25 +++++++++++
 4 files changed, 118 insertions(+), 9 deletions(-)

diff --git a/frontend/src/components/Welcome.tsx b/frontend/src/components/Welcome.tsx
index 68362b41..70d57391 100644
--- a/frontend/src/components/Welcome.tsx
+++ b/frontend/src/components/Welcome.tsx
@@ -30,6 +30,7 @@ import { setLanguage, type LangCode } from "../i18n";
 import LanguageSwitcher from "./LanguageSwitcher";
 import { Button } from "./ui/Button";
 import { trapTab, useDialogChrome } from "./ui/dialogFocus";
+import { isTopmost, pushLayer, removeLayer } from "../lib/layerStack";
 import { inputCls } from "./ui/form";
 import { entryHash, entrySearch } from "../lib/entryUrl";
 import type { VerifyEntry } from "../lib/useVerifyEntry";
@@ -267,22 +268,48 @@ function Preview({
 // (aspect ratio preserved via object-contain). Closes on backdrop click, the ✕, or Escape.
 function Lightbox({ src, label, onClose }: { src: string; label: string; onClose: () => void }) {
   const { t } = useTranslation();
-  // The fourth `aria-modal` shell in the app, and the one the round-5 extraction did not sweep in:
-  // it declared itself a modal dialog while leaving focus on the thumbnail behind an 80%-black
-  // scrim, announcing nothing, and letting Tab walk the landing page underneath — the ✕ reachable
-  // only after tabbing past every remaining gallery shot (deep-review round 6). The contract comes
-  // from the same place `ui/Modal` and the wizard get theirs; the body-scroll lock moved with it.
+  // An `aria-modal` shell that round 5's focus extraction did not sweep in: it declared itself a
+  // modal dialog while leaving focus on the thumbnail behind an 80%-black scrim, announcing nothing,
+  // and letting Tab walk the landing page underneath — the ✕ reachable only after tabbing past every
+  // remaining gallery shot (deep-review round 6). The contract comes from the same place `ui/Modal`
+  // and the wizard get theirs; the body-scroll lock moved with it, and round 7 added the layer
+  // membership below.
+  //
+  // It is the THIRD of four to get the contract, not the last: `PlayerModal` is also
+  // `role="dialog" aria-modal="true"` and still hand-rolls its own scroll lock with no accessible
+  // name, no Tab trap and no focus restore. Saying "the fourth shell" here read as though the sweep
+  // were finished, which is the false-completeness that let a demo refusal sit unconverted for a
+  // whole round. It is on ROADMAP.md instead (round 7).
   const panelRef = useRef<HTMLDivElement>(null);
   useDialogChrome(panelRef);
+  // Keep a stable handler across renders so the stack id is assigned once per mount (as in ui/Modal).
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
   useEffect(() => {
+    // Round 6 gave this shell the trap and the restore but not the LAYER MEMBERSHIP the other three
+    // have, so its Escape and Tab fired from a raw window listener whatever was on top of it. That
+    // is the shape the wizard's own comment records being bitten by — "one Esc closed the error AND
+    // ended onboarding" — and it is unreachable today only because `App` returns `<Welcome/>` before
+    // it mounts `ErrorDialog` and the Toaster, i.e. by an ordering nothing enforces. Joining the
+    // stack costs two lines and removes the trap-fights-trap failure mode from the next layer the
+    // landing page grows (deep-review round 7).
+    const id = pushLayer();
     const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") onClose();
+      if (!isTopmost(id)) return;
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        onCloseRef.current();
+        return;
+      }
       const panel = panelRef.current;
       if (e.key === "Tab" && panel) trapTab(e, panel, panel);
     };
     window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [onClose]);
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      removeLayer(id);
+    };
+  }, []);
   return (
     <div
       ref={panelRef}
diff --git a/frontend/src/components/ui/Modal.dom.test.tsx b/frontend/src/components/ui/Modal.dom.test.tsx
index 07e1816c..853c2891 100644
--- a/frontend/src/components/ui/Modal.dom.test.tsx
+++ b/frontend/src/components/ui/Modal.dom.test.tsx
@@ -254,6 +254,43 @@ describe("Modal focus trap (offsetParent stubbed 'visible')", () => {
     document.body.removeChild(trigger);
   });
 
+  it("leaves the focus alone when a dialog above it is still standing", () => {
+    // The other side of the clause above. Counting focus in ANY `aria-modal` subtree as ours cannot
+    // tell a layer closing WITH us from one that stays open, and the layer stack cannot either: at
+    // the moment this cleanup runs the child's `removeLayer` has not fired, so both cases read "a
+    // layer is above me" (measured). So a dialog that closes on its own — an in-flight mutation's
+    // `onSuccess`, not a click, since a scrim covers it — under a modal raised above it yanked the
+    // focus out of that standing dialog onto its own trigger, behind the scrim, where Enter still
+    // activated it (deep-review round 7). Sibling dialogs, not nested: that is the arrangement
+    // `ConfirmProvider` and the app-wide `ErrorDialog` actually use.
+    const trigger = document.createElement("button");
+    document.body.appendChild(trigger);
+    trigger.focus();
+    function Siblings() {
+      const [lower, setLower] = useState(true);
+      return (
+        <>
+          {lower && (
+            <Modal title="lower" onClose={() => {}}>
+              <button onClick={() => setLower(false)}>close lower</button>
+            </Modal>
+          )}
+          <Modal title="upper" onClose={() => {}}>
+            <button>upper-body</button>
+          </Modal>
+        </>
+      );
+    }
+    render(<Siblings />);
+    const upper = screen.getByText("upper-body");
+    upper.focus();
+    // The lower dialog closes by itself while the upper one holds the focus.
+    act(() => void screen.getByText("close lower").click());
+    expect(screen.queryByText("close lower")).toBeNull(); // it really did unmount
+    expect(document.activeElement).toBe(upper);
+    document.body.removeChild(trigger);
+  });
+
   it("leaves the focus alone when the user moved it out of the dialog themselves", () => {
     // The other half of the same rule, and the branch nothing drove: taking focus back from where
     // the user deliberately put it is the rudest thing a closing dialog can do.
diff --git a/frontend/src/components/ui/dialogFocus.ts b/frontend/src/components/ui/dialogFocus.ts
index 00d444ab..321ef0be 100644
--- a/frontend/src/components/ui/dialogFocus.ts
+++ b/frontend/src/components/ui/dialogFocus.ts
@@ -118,7 +118,27 @@ export function useDialogChrome(
       // Restore focus to the trigger, if it's still in the document and focusable — and only if the
       // dialog still held the focus. Once the user has moved it elsewhere, taking it back is the
       // rudest thing a closing dialog can do.
-      if (heldRef.current && restoreTo && restoreTo.isConnected) restoreTo.focus();
+      //
+      // Not, though, when a dialog stacked above us is STILL STANDING. `heldRef` counts focus in any
+      // `aria-modal` subtree as ours (see above), which cannot tell a layer closing WITH us from one
+      // that stays open — and the layer stack cannot tell them apart either: at this instant the
+      // child's `removeLayer` has not run, because passive cleanups are parent-first and this hook
+      // is declared before that effect, so BOTH cases read "a layer is above me" (measured). What
+      // does separate them is the DOM: React detaches a deleted subtree before passive cleanups, so
+      // a layer closing with us is already disconnected while one that stays open is not. Without
+      // this, a dialog closing on its own (an in-flight mutation's `onSuccess`) under a modal raised
+      // above it pulled the focus out of that standing dialog onto our own trigger, behind its
+      // scrim — where Enter still activated it (deep-review round 7).
+      const owner = ownerRef?.current ?? scopeRef.current;
+      const active = document.activeElement;
+      const above = active instanceof Element ? active.closest('[aria-modal="true"]') : null;
+      const standingAbove =
+        above !== null &&
+        above.isConnected &&
+        !above.contains(owner as Node | null) &&
+        !(owner?.contains(above) ?? false);
+      if (heldRef.current && !standingAbove && restoreTo && restoreTo.isConnected)
+        restoreTo.focus();
     };
   }, [restoreTo, scopeRef, ownerRef]);
 }
diff --git a/frontend/src/components/welcomeMode.render.dom.test.tsx b/frontend/src/components/welcomeMode.render.dom.test.tsx
index 1f2cced3..13172a1c 100644
--- a/frontend/src/components/welcomeMode.render.dom.test.tsx
+++ b/frontend/src/components/welcomeMode.render.dom.test.tsx
@@ -28,6 +28,7 @@ vi.mock("../lib/api", async (importOriginal) => {
 });
 
 import Welcome from "./Welcome";
+import { pushLayer, removeLayer } from "../lib/layerStack";
 import type { VerifyEntry } from "../lib/useVerifyEntry";
 
 // App confirms the emailed token and hands the outcome down; these tests are about the card's
@@ -178,4 +179,28 @@ describe("the screenshot lightbox", () => {
     fireEvent.keyDown(window, { key: "Escape" });
     await waitFor(() => expect(document.activeElement).toBe(shot));
   });
+
+  it("defers its Escape and its Tab to a layer opened above it", async () => {
+    // Round 6 gave this shell the trap and the restore but not the LAYER MEMBERSHIP the other
+    // three have, so both fired from a raw window listener no matter what was on top. That is the
+    // shape the wizard's own comment records being bitten by ("one Esc closed the error AND ended
+    // onboarding"), and it was unreachable here only because `App` renders `<Welcome/>` before it
+    // mounts `ErrorDialog` and the Toaster — an ordering nothing enforces (round 7).
+    const { panel } = await openIt();
+    const above = pushLayer(); // whatever the landing page grows next
+    try {
+      fireEvent.keyDown(window, { key: "Escape" });
+      // Still open: the layer above owns that Escape.
+      expect(screen.queryByRole("dialog")).toBe(panel);
+      // And it must not fight the layer above for the Tab either — same reasoning as the test
+      // above, so assert the keydown was NOT cancelled rather than where the focus went.
+      screen.getByLabelText("common.close").focus();
+      expect(fireEvent.keyDown(window, { key: "Tab", cancelable: true })).toBe(true);
+    } finally {
+      removeLayer(above);
+    }
+    // With the layer above gone it is topmost again and closes normally.
+    fireEvent.keyDown(window, { key: "Escape" });
+    await waitFor(() => expect(screen.queryByRole("dialog")).toBeNull());
+  });
 });

From 63bf1bca78d79b9c7c6c93731d66a5923e4070ec Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 16:22:27 +0200
Subject: [PATCH 50/52] fix(plex): an accepted reorder refetches the detail it
 just wrote
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`commit`'s success handler writes the dragged list into the detail cache — round 6's fix, so a
re-entry inside the 30s staleTime renders the accepted order without a request — but then invalidated
only the LIST key, while the YouTube sibling it cites invalidates both. `next` is the membership of
the render that started the drag, and `reorder_playlist` only touches the rating_keys it is handed,
so it never ratifies that list: anything that landed meanwhile was clobbered by the write with
nothing scheduled to correct it. `commit` sets no busy flag either, so a removal really can complete
while a reorder is in flight, and with staleTime 30s and refetchOnWindowFocus off the phantom row
stayed on screen for as long as the view was mounted — and the next drag persisted an order built
from it.

Round 6's test had to be re-pointed, because it was written in a world with no refetch: its mock
answered the pre-reorder order forever, which a server that just accepted the write cannot do. It now
holds the refetch open instead, so it still pins what round 6 actually fixed — the cache is right
WITHOUT waiting for a request — and would fail if the write were deleted. Both halves are
mutation-checked against each other.
---
 .../PlexPlaylistReorder.dom.test.tsx          | 52 ++++++++++++++++---
 frontend/src/components/PlexPlaylistView.tsx  |  7 +++
 2 files changed, 53 insertions(+), 6 deletions(-)

diff --git a/frontend/src/components/PlexPlaylistReorder.dom.test.tsx b/frontend/src/components/PlexPlaylistReorder.dom.test.tsx
index b085f2b6..768e5744 100644
--- a/frontend/src/components/PlexPlaylistReorder.dom.test.tsx
+++ b/frontend/src/components/PlexPlaylistReorder.dom.test.tsx
@@ -63,12 +63,17 @@ afterEach(() => {
 const movie = (id: string) =>
   ({ id, type: "movie", title: `Movie ${id}`, year: 2020, thumb: "" }) as unknown as PlexCard;
 
-it("writes the order the server accepted into the detail cache", async () => {
-  vi.spyOn(api, "plexPlaylist").mockResolvedValue({
-    id: 5,
-    title: "Films",
-    items: [movie("1"), movie("2"), movie("3")],
-  });
+it("writes the order the server accepted into the detail cache, without waiting for a refetch", async () => {
+  // The refetch that same handler schedules (round 7) must not be what makes the cache right: the
+  // point of the write is that a re-entry inside the 30 s staleTime renders the accepted order
+  // immediately, with no request at all. So the refetch is HELD OPEN here — if this assertion
+  // needed it to land, deleting the write would still pass and round 6's fix would be unguarded.
+  let calls = 0;
+  vi.spyOn(api, "plexPlaylist").mockImplementation(() =>
+    ++calls === 1
+      ? Promise.resolve({ id: 5, title: "Films", items: [movie("1"), movie("2"), movie("3")] })
+      : new Promise(() => {}),
+  );
   const reorder = vi.spyOn(api, "plexReorderPlaylist").mockResolvedValue(undefined as never);
   const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
   render(
@@ -88,3 +93,38 @@ it("writes the order the server accepted into the detail cache", async () => {
     ).toEqual(["2", "1", "3"]),
   );
 });
+
+it("refetches the detail too, so a membership change that landed meanwhile is not clobbered", async () => {
+  // `next` is the membership of the render that started the drag, and `reorder_playlist` only
+  // touches the rating_keys it is handed — it never ratifies that list. So writing `next` into the
+  // detail cache silently drops anything that landed in between (a row removed from another
+  // surface, an item added elsewhere), and with only the LIST key invalidated nothing corrected it:
+  // staleTime is 30 s and refetchOnWindowFocus is off, so the phantom row stayed on screen for as
+  // long as the view was mounted and the next drag persisted an order built from it. The YouTube
+  // sibling invalidates the detail key right after writing it; this half did not (round 7).
+  let calls = 0;
+  vi.spyOn(api, "plexPlaylist").mockImplementation(() =>
+    Promise.resolve(
+      ++calls === 1
+        ? { id: 5, title: "Films", items: [movie("1"), movie("2"), movie("3")] }
+        : { id: 5, title: "Films", items: [movie("2"), movie("1")] }, // "3" is gone server-side
+    ),
+  );
+  const reorder = vi.spyOn(api, "plexReorderPlaylist").mockResolvedValue(undefined as never);
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  render(
+    <QueryClientProvider client={qc}>
+      <PlexPlaylistView playlistId={5} onBack={() => {}} onPlay={() => {}} />
+    </QueryClientProvider>,
+  );
+  await screen.findByText("Movie 3");
+  act(() => dragEnd.fire({ active: { id: "1" }, over: { id: "2" } }));
+  await waitFor(() => expect(reorder).toHaveBeenCalledWith(5, ["2", "1", "3"]));
+  // The refetch the accepted write schedules brings the real membership back.
+  await waitFor(() => expect(screen.queryByText("Movie 3")).toBeNull());
+  await waitFor(() =>
+    expect(
+      qc.getQueryData<{ items: PlexCard[] }>(qk.plexPlaylist(5))?.items.map((i) => i.id),
+    ).toEqual(["2", "1"]),
+  );
+});
diff --git a/frontend/src/components/PlexPlaylistView.tsx b/frontend/src/components/PlexPlaylistView.tsx
index a4cc0e58..6b3890e3 100644
--- a/frontend/src/components/PlexPlaylistView.tsx
+++ b/frontend/src/components/PlexPlaylistView.tsx
@@ -437,6 +437,13 @@ export default function PlexPlaylistView({
         qc.setQueryData<{ items: PlexCard[] }>(qk.plexPlaylist(playlistId), (old) =>
           old ? { ...old, items: next } : old,
         );
+        qc.invalidateQueries({ queryKey: qk.plexPlaylist(playlistId) });
+        // …and then REFETCH it, exactly as the sibling does. `next` is this render's membership, and
+        // the server only reorders the keys it was given — so anything that landed meanwhile (a row
+        // removed from another surface, an item added elsewhere) is clobbered by that write. With
+        // only the list key invalidated nothing corrected it: staleTime is 30 s and
+        // refetchOnWindowFocus is off, so the wrong membership stayed on screen for as long as the
+        // view was mounted and the next drag persisted an order built from it (round 7).
         qc.invalidateQueries({ queryKey: qk.plexPlaylists() });
       })
       .catch((e: unknown) => {

From 8c51062e5b26b67732e22d38f6765fe7efd0b650 Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 16:22:27 +0200
Subject: [PATCH 51/52] fix(api,ui): the demo refusal says why at every site,
 and the contract guard cannot fail open
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Round 6 converted three of four `is_demo` 403s to a structured detail and wrote a docstring saying it
had converted all the sites there are. The account-delete route in `routes/me.py` still answered a
hand-written English sentence, which `notifyActionError` discards in favour of the caller's
translated fallback — so the demo user gets no hint that the demo account is the reason. It is
UI-gated today, so the string is unreachable; what was reachable was the false completeness claim,
which is precisely what stops the next reader from looking. The site is converted, and the list is
now DERIVED from the source: a new test walks `app/` for every `is_demo`-guarded 403, asserts each
raises a structured detail, and fails when the count moves — so this file cannot fall behind the code
the way it just did.

The same round's frontend contract guard was failing open. Its pattern required a bare identifier
before `.detail` and excluded `.detail` used as a last call argument, so `setErr(e.detail)`,
`(e as HttpError).detail`, `String(e.detail)` and four more idiomatic forms were invisible — and
because the file set is compared with `toEqual`, a file the pattern cannot see is simply never listed
and the gate stays green over a fresh copy of the contract. Widened to cover cast receivers, optional
chains and call-argument reads; the pinned set is unchanged, so the narrowing had removed no false
positive. A destructured `detail` stays out of reach (a pattern loose enough for it fires on
react-query's own `const { data: detail }`), and that hole is written into the test rather than
papered over with two innocent files.

Its anti-vacuity guard also did not guard anything: the comment says the glob must have matched
something, but the assertion under it read a sibling file by its own URL, which resolves whether or
not the glob enumerated anything. That only mattered while the pinned list was non-empty — the moment
the deferral sweep lands and it becomes [], the whole file would pass over a glob matching zero
files. The scan size is asserted now.
---
 backend/app/routes/me.py                      |  7 ++-
 backend/tests/test_demo_refusal_detail.py     | 51 +++++++++++++++--
 .../src/lib/actionErrors.contract.test.ts     | 56 +++++++++++++++++--
 3 files changed, 103 insertions(+), 11 deletions(-)

diff --git a/backend/app/routes/me.py b/backend/app/routes/me.py
index 6de8d72d..ec625c5f 100644
--- a/backend/app/routes/me.py
+++ b/backend/app/routes/me.py
@@ -159,8 +159,13 @@ def delete_my_account(
     which all cascade on the users row. Quota-audit events are kept but anonymised (FK SET NULL).
     The shared demo account can't be deleted, and the last remaining admin can't delete itself
     (that would lock everyone out of the admin surfaces)."""
+    # Structured, like the other three demo refusals: `req` leaves 403 to the caller and
+    # `notifyActionError` discards a plain-string detail in favour of the caller's translated
+    # fallback, so a hand-written English sentence here reaches a Hungarian UI as a generic
+    # "couldn't do that" — or, on this affordance, as nothing at all. `reason` distinguishes it
+    # from the other sites' bare `{code: "demo"}` so the UI can say what specifically is refused.
     if user.is_demo:
-        raise HTTPException(status_code=403, detail="The shared demo account can't be deleted.")
+        raise HTTPException(status_code=403, detail={"code": "demo", "reason": "delete_account"})
     if user.role == "admin" and count_admins(db) <= 1:
         raise HTTPException(
             status_code=400,
diff --git a/backend/tests/test_demo_refusal_detail.py b/backend/tests/test_demo_refusal_detail.py
index 6596c862..f629f9cf 100644
--- a/backend/tests/test_demo_refusal_detail.py
+++ b/backend/tests/test_demo_refusal_detail.py
@@ -7,10 +7,19 @@ of the caller's already-translated fallback, so from that commit on the demo use
 this gate is UI-gated on `is_demo` either — the comfort shelf is not, so the pin button is live.
 
 A structured `{code: "demo"}` is what `localizeDetail` can turn into `errors.demo` in both locales.
-Pinned at all three sites: the shared dependency and the two auth routes that hand-roll the same
-check, because an asymmetric fix is the smell this repo bans. Needs the DB.
+Pinned at all FOUR sites: the shared dependency, the two auth routes that hand-roll the same check,
+and the account-delete route in `routes/me.py` — which round 6 missed while its docstring claimed
+all the sites were covered, so the next reader had no reason to look (round 7). An asymmetric fix is
+the smell this repo bans, and a docstring asserting symmetry it does not have is worse than none.
+
+The list is derived from the source, not typed out: `test_every_is_demo_refusal_is_on_the_list`
+below fails when a fifth `is_demo` 403 appears anywhere in `app/`, so this file cannot fall behind
+the code the way round 6's did. Needs the DB.
 """
 
+import re
+from pathlib import Path
+
 from app.models import User
 
 
@@ -20,13 +29,47 @@ def test_every_demo_refusal_carries_the_same_structured_reason(db, make_user, as
     for method, url, body in [
         # `require_human` itself, through an affordance the UI does NOT gate on is_demo.
         ("post", "/api/discover/pins", {"kind": "video", "ref": "v1"}),
-        # The two routes that repeat the check inline rather than depending on the gate.
+        # The three routes that repeat the check inline rather than depending on the gate.
         ("post", "/auth/logout-others", None),
         ("post", "/auth/set-password", {"password": "a long enough password"}),
+        ("delete", "/api/me/account", None),
     ]:
         r = getattr(client, method)(url, **({"json": body} if body is not None else {}))
         assert r.status_code == 403, (url, r.text)
-        assert r.json()["detail"] == {"code": "demo"}, url
+        detail = r.json()["detail"]
+        # Every one of them is a dict whose `code` the frontend can localize; the delete route adds
+        # a `reason` so its refusal can be worded specifically.
+        assert isinstance(detail, dict), (url, detail)
+        assert detail["code"] == "demo", (url, detail)
+
+
+def test_every_is_demo_refusal_is_on_the_list():
+    """A fifth site must not be able to appear unnoticed.
+
+    Round 6 converted three of four `is_demo` 403s and wrote a docstring saying it had converted
+    them all; the fourth kept answering a bare English string for another round because nothing
+    counted them. So count them here: every `is_demo`-guarded 403 in `app/` has to raise a
+    structured detail, and the number of them has to match what this file exercises."""
+    app_dir = Path(__file__).resolve().parents[1] / "app"
+    sites = []
+    for path in sorted(app_dir.rglob("*.py")):
+        lines = path.read_text(encoding="utf-8").splitlines()
+        for i, line in enumerate(lines):
+            # `if user.is_demo:` / `if u.is_demo:` — the hand-rolled gate, not the ORM filters
+            # (`User.is_demo.is_(False)`) and not the column definition.
+            if not re.search(r"^\s*if\s+\w+\.is_demo\s*:", line):
+                continue
+            block = "\n".join(lines[i : i + 6])
+            if "403" not in block:
+                continue
+            sites.append(f"{path.relative_to(app_dir)}:{i + 1}")
+            assert 'detail={"code": "demo"' in block, (
+                f"{path.relative_to(app_dir)}:{i + 1} refuses the demo account with an "
+                f"unstructured detail — the frontend cannot localize it:\n{block}"
+            )
+    # auth.py's shared gate + routes/auth.py's two + routes/me.py's delete. A new one is welcome,
+    # but it has to be added to the loop above in the same commit.
+    assert len(sites) == 4, sites
 
 
 def test_a_real_account_is_not_refused_by_the_gate(db, make_user, as_user):
diff --git a/frontend/src/lib/actionErrors.contract.test.ts b/frontend/src/lib/actionErrors.contract.test.ts
index f15de4fe..9b11f047 100644
--- a/frontend/src/lib/actionErrors.contract.test.ts
+++ b/frontend/src/lib/actionErrors.contract.test.ts
@@ -15,8 +15,25 @@ import { describe, expect, it } from "vitest";
 // glob stops matching (E10 review round 4 learned that the hard way).
 
 // Reads a raw `HttpError.detail` and uses it as the message a user sees. Matches `e.detail ||`,
-// `err.detail ? err.detail :` and `(e instanceof HttpError ? e.detail : undefined) ??`.
-const RAW_DETAIL = /\b[A-Za-z_$][\w$]*\.detail\b(?!\s*(?:=[^=]|\)))/;
+// `err.detail ? err.detail :`, `(e instanceof HttpError ? e.detail : undefined) ??`, a cast
+// receiver (`(e as HttpError).detail`), an optional chain (`e?.detail`) and a `.detail` passed
+// straight as a call argument (`setErr(e.detail)`).
+//
+// The receiver alternation and the absence of a `)` lookahead are both load-bearing. The first
+// version required a bare identifier before `.detail` and excluded `.detail)` — so `setErr(e.detail)`,
+// `String(e.detail)` and `(e as HttpError).detail` were all invisible, and because the file SET is
+// compared with `toEqual` a file the pattern cannot see is simply never listed: the guard stayed
+// green over a fresh copy of the contract written in any of those shapes (round 7). The `)`
+// exclusion bought nothing — the only `.detail)` in the frontend is inside `lib/api/core.ts`, which
+// `IMPLEMENTATION` skips wholesale — and re-scanning with the wider pattern returns the same five
+// files, so it removes no false positive.
+const RAW_DETAIL = /(?:\)|[A-Za-z_$][\w$]*)\s*\??\.detail\b(?!\s*=[^=])/;
+// KNOWN LIMIT: a `detail` pulled out by destructuring (`const { detail } = err`) is out of reach
+// of a line-level scan — by then there is no receiver left to match, and a pattern loose enough
+// to catch it fires on every unrelated `detail` field too (measured: `const { data: detail } =
+// useQuery(...)` in VideoInfoCard and an options destructure in plexPlayerHooks, neither of which
+// touches an HttpError). Naming the hole beats pinning two innocent files into the list below as
+// though they were copies of the contract.
 
 // Every place that still prefers the server's raw string over a translated fallback. These are
 // INLINE surfaces — a form field's error line, a setup step's banner — not toasts, and each shows a
@@ -34,7 +51,7 @@ const KNOWN_RAW_DETAIL_CONSUMERS = [
 // Where the rule itself lives, plus the request layer that produces and localizes the value.
 const IMPLEMENTATION = ["lib/actionErrors.ts", "lib/api/core.ts"];
 
-function consumers(): string[] {
+function consumers(): { hits: string[]; scanned: number } {
   const files = import.meta.glob("../**/*.{ts,tsx}", {
     query: "?raw",
     import: "default",
@@ -51,15 +68,42 @@ function consumers(): string[] {
       .filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l)); // a comment about the rule is not a copy of it
     if (lines.some((l) => RAW_DETAIL.test(l))) hits.push(path);
   }
-  return hits.sort();
+  return { hits: hits.sort(), scanned: Object.keys(files).length };
 }
 
 describe("the refused-write contract", () => {
   it("has no copies beyond the ones on the deferral list", () => {
-    // The glob must actually match something, or this whole file is a green no-op.
+    const { hits, scanned } = consumers();
+    // The GLOB must have matched something, or this whole file is a green no-op — and the old
+    // version of this guard did not check that: it read `actionErrors.ts` by its own URL, which
+    // resolves whether or not `import.meta.glob` enumerated a single file. That only mattered
+    // because the pinned set was non-empty; the moment the deferral sweep below lands and the list
+    // becomes `[]`, `expect([]).toEqual([])` would pass over a glob that matched nothing (round 7).
+    expect(scanned).toBeGreaterThan(100);
     expect(readFileSync(new URL("./actionErrors.ts", import.meta.url), "utf8")).toContain(
       "detailData",
     );
-    expect(consumers()).toEqual(KNOWN_RAW_DETAIL_CONSUMERS);
+    expect(hits).toEqual(KNOWN_RAW_DETAIL_CONSUMERS);
+  });
+
+  it("sees a raw detail written in any of the shapes this codebase uses", () => {
+    // The pattern is the whole guard, so pin the pattern itself: each of these is a real form
+    // found in this frontend or in its sibling PRs, and every one of the first five was invisible
+    // to the original regex.
+    for (const line of [
+      "  setErr(e.detail);",
+      "  reportError(err.detail);",
+      "  notify({ message: (e as HttpError).detail });",
+      "  toast(String(e.detail));",
+      "  notify({ message: (err as HttpError).detail ?? fallback });",
+      '  setError(e.detail ?? t("x"));',
+      '  const msg = err.detail || t("x");',
+      "  setErr(state.err?.detail);",
+    ])
+      expect(RAW_DETAIL.test(line), line).toBe(true);
+    // And it must not fire on the places that PRODUCE or localize the value, which is why
+    // `IMPLEMENTATION` exists rather than a cleverer pattern: an assignment is not a read.
+    for (const line of ["  detail = await r.json();", "  this.detail = detail;"])
+      expect(RAW_DETAIL.test(line), line).toBe(false);
   });
 });

From 415a6c16f99a55ce05111b56358a90cd759e215a Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sat, 12 Sep 2026 16:43:54 +0200
Subject: [PATCH 52/52] =?UTF-8?q?release:=200.84.0=20=E2=80=94=20the=20own?=
 =?UTF-8?q?er's=20sixteen-item=20bug=20hunt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sixteen items written from real use: eleven fixed, one measured and closed without a code change
(the micro-stutter is a 23.976 fps film on a 120.0148 Hz display, reproduced identically outside
Siftlode), two parked for a reproducible case, one scoped out to its own sprint. Two of the eleven
were destroying user state — a YouTube video that rewound itself on reopen, and a "clear resume
point" that told Plex nothing about an in-progress item.

Then seven deep-review rounds over the fixes and over each other's fixes: 32 → 24 → 43 → 31 → 22 →
26 → 18 raised. Minor, not patch: item 14 added an admin knob, item 10 a sort control, and items
2/4/5/7 are features.
---
 CHANGELOG.md                     | 34 ++++++++++++++++++++++++++++++++
 VERSION                          |  2 +-
 frontend/src/lib/releaseNotes.ts | 33 +++++++++++++++++++++++++++++++
 3 files changed, 68 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bca46e62..5a533e01 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,40 @@ edit the release notes and re-run the generator.
 
 Upgrading, pinning a version and rolling back: [docs/self-hosting.md](docs/self-hosting.md#upgrading).
 
+## 0.84.0 — 2026-09-12
+
+A bug-fix release, from a list you wrote while using Siftlode. Two of these were destroying your own data: a YouTube video rewound itself when you reopened it, and clearing a resume point on a half-watched Plex item told Plex nothing. Subtitles now appear in seconds instead of minutes, the Plex player's bitrate is a real measurement rather than a guess, and a channel you turn full history on for fills in front of you instead of looking frozen.
+
+### Features
+
+- Subtitles arrive in seconds. Picking an embedded subtitle track used to take about two and a half minutes on a large film, and switching from Hungarian to English cost the same again — because the cost was never the conversion, it was reading the whole file. It now reads a window around where you are, shows that first, and finishes the rest behind it; every text track rides the SAME read, so switching tracks is instant. On a 17 GB film: 154 s before, 8 s for the window now. Nothing blocks while it works, there is a “Preparing subtitles” pill instead of a frozen player, and a track that can never be shown finally says so.
+- The Plex player's info panel tells you the truth. Bitrate is measured from the bytes actually arriving, not copied off the manifest — and it shows a dash until there is something to measure rather than a confident wrong number. It also lists the audio and the subtitle track you are on, which it never did.
+- A new admin switch: loudness normalisation for Plex playback (Configuration → Plex). Off by default, because it makes a film markedly louder and narrows its dynamic range — that is a taste call, not a fix. On a 5.1 film it moved the measured loudness from −35.2 to −17.2 LUFS, and it does not touch A/V sync.
+- Collections can be sorted. The collection page had no sort control at all and always ordered by release year — it now carries the same Sort control as the library grid, with the same options, and your choice survives a reload without re-sorting the library behind it. A collection opened from a shared link also shows its real name instead of a raw id.
+- Remove a video from a playlist without leaving the player, and the player steps to whatever followed instead of closing. Above the move-to submenu there is now a one-click “move to the list you last moved to”.
+- Live YouTube search results can be sorted — by views, date or length, over the results already on screen, so sorting rearranges what you are looking at instead of running a different search.
+- The channel name in the player is a real link again: middle-click and Ctrl-click open it in a new tab, the way the YouTube icon beside it always did, while a plain click still takes the in-app route.
+
+### Fixes
+
+- A YouTube video no longer rewinds when you reopen it. Closing at 13:50 and coming back put you at 12:31 — the checkpoint reached the server but not the page's own cache, so the stale position won. It now goes forward: 811 → 816 → 825 s across reopens.
+- “Clear resume point” works on a half-watched Plex item. The push to Plex was skipped for exactly the case you would use it on, so Plex kept the old offset and handed it straight back on the next import. Verified against the real server, including a full 44,885-item re-import.
+- Turning full history on for a channel fills the page in front of you. The grid and the item count stayed frozen for the best part of a minute while the header counted up, because the request that starts the backfill returns before anything is stored. Measured: the count now moves 54 → 139 within about twelve seconds, no reload.
+- Starting or seeking a Plex film is about eight seconds faster. Every session start and every seek waited out a dead eight-second timer for a file the transcoder never writes — on a film with more than one audio track, which is most of them. A multi-audio session now starts in 0.9 s cold and 0.7 s on a seek.
+- A Plex session the server no longer has now recovers or says so, instead of spinning forever. A stream that kept being lost could restart itself indefinitely behind a spinner that never became an error.
+- A Plex stream request for something that cannot exist answers immediately rather than holding the server for 20–30 seconds. Enough of those at once could stall the whole app.
+- The Plex player no longer counts one viewing twice, and a failed “watched” mark no longer half-happens: it used to leave the item looking watched in the app while the server disagreed, or quietly mark it watched anyway a few seconds after telling you it had failed.
+- Dragging a Plex playlist into a new order sticks. Leaving and coming straight back showed the old order, and the next drag saved that.
+- A refused action says WHY, in the language you are reading. Several places showed a generic “couldn't do that” — or nothing at all — where the server had explained itself, including the Plex “Add to playlist” dialog, the collection editor and the upload dialog. The demo account gets its reason back too.
+- Dialogs behave for the keyboard. Opening one puts the cursor where you would expect (the jump-to box opens on its search field, not its close button), closing one hands the focus back to what you opened it from, and a dialog that closes underneath another one no longer steals the focus out of the one still on screen.
+- The regular micro-stutter in the Plex player is NOT Siftlode's, and this release does not pretend to fix it. Measured per frame: the player delivers every source frame with nothing dropped; the hold comes from a 23.976 fps film on a 120.0148 Hz display, and it reproduces identically outside Siftlode. Setting the display to 119.88 Hz removes it for every application, not just this one.
+
+### Internal
+
+- The round started from sixteen items written from real use, not from an audit. Eleven were fixed, one was measured and closed without a code change (the display cadence above), two are parked for a reproducible case, and one — playlist multi-select and bulk actions — was scoped out to its own sprint. The measurements are the point: item 8's “35 s” turned out to be one file's number, and the real law is bytes-ffmpeg-must-read divided by ~140 MB/s, which is why the fix is a window rather than a faster conversion.
+- Seven deep-review rounds followed, each reviewing the previous round's own fix commits: 32 → 24 → 43 → 31 → 22 → 26 → 18 raised. Round 7 was run TARGETED rather than full — four reviewers on the six surfaces round 6 had changed, and adversarial verification spent only where a wrong fix could re-break the previous round's — which is seven agents instead of about thirty-six for two HIGH findings. Every regression test added in a fix round was mutation-checked: reverted, run, and confirmed red for the defect it is named after. Thirteen of round 7's mutations were, and two were instructive — one guard no test could drive, and one round-6 test whose mock modelled a server that accepts a write and then serves the pre-write state.
+- What the eight-lane gate structurally cannot catch, and what this round taught about it: every real defect of the last three rounds was a wrong belief about an external system, not broken logic. ffmpeg substitutes the VARIANT before the sequence in its segment filenames, so a guard written the other way round was inert on every multi-audio file and a warm-up waited eight seconds for a name that is never written. A reclaim budget's window was anchored at the first failure rather than the last, so any failure cadence between one and two minutes reset it forever — invisible to two tests that spaced their cases at zero and ten minutes. jsdom performs no default Tab, so a focus test can be green with no focus trap installed at all. The conclusion carried forward is to measure the boundary when writing the code, not when reviewing it: one ffmpeg run costs pennies, a review round costs a session.
+
 ## 0.83.0 — 2026-09-09
 
 Siftlode now opens on a page that answers one question: what should I watch right now. You say how much time you have — ten minutes, half an hour, a whole evening — and it gives you one suggestion, from YouTube or from Plex, with a button that picks up where you left off. Under it sits a shelf of the things you always come back to, which you fill yourself.
diff --git a/VERSION b/VERSION
index 83dcd12c..09c49413 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.83.0
+0.84.0
diff --git a/frontend/src/lib/releaseNotes.ts b/frontend/src/lib/releaseNotes.ts
index d424e8d9..cd3303e9 100644
--- a/frontend/src/lib/releaseNotes.ts
+++ b/frontend/src/lib/releaseNotes.ts
@@ -14,6 +14,39 @@ export interface ReleaseEntry {
 }
 
 export const RELEASE_NOTES: ReleaseEntry[] = [
+  {
+    version: "0.84.0",
+    date: "2026-09-12",
+    summary:
+      "A bug-fix release, from a list you wrote while using Siftlode. Two of these were destroying your own data: a YouTube video rewound itself when you reopened it, and clearing a resume point on a half-watched Plex item told Plex nothing. Subtitles now appear in seconds instead of minutes, the Plex player's bitrate is a real measurement rather than a guess, and a channel you turn full history on for fills in front of you instead of looking frozen.",
+    features: [
+      "Subtitles arrive in seconds. Picking an embedded subtitle track used to take about two and a half minutes on a large film, and switching from Hungarian to English cost the same again \u2014 because the cost was never the conversion, it was reading the whole file. It now reads a window around where you are, shows that first, and finishes the rest behind it; every text track rides the SAME read, so switching tracks is instant. On a 17 GB film: 154 s before, 8 s for the window now. Nothing blocks while it works, there is a \u201cPreparing subtitles\u201d pill instead of a frozen player, and a track that can never be shown finally says so.",
+      "The Plex player's info panel tells you the truth. Bitrate is measured from the bytes actually arriving, not copied off the manifest \u2014 and it shows a dash until there is something to measure rather than a confident wrong number. It also lists the audio and the subtitle track you are on, which it never did.",
+      "A new admin switch: loudness normalisation for Plex playback (Configuration \u2192 Plex). Off by default, because it makes a film markedly louder and narrows its dynamic range \u2014 that is a taste call, not a fix. On a 5.1 film it moved the measured loudness from \u221235.2 to \u221217.2 LUFS, and it does not touch A/V sync.",
+      "Collections can be sorted. The collection page had no sort control at all and always ordered by release year \u2014 it now carries the same Sort control as the library grid, with the same options, and your choice survives a reload without re-sorting the library behind it. A collection opened from a shared link also shows its real name instead of a raw id.",
+      "Remove a video from a playlist without leaving the player, and the player steps to whatever followed instead of closing. Above the move-to submenu there is now a one-click \u201cmove to the list you last moved to\u201d.",
+      "Live YouTube search results can be sorted \u2014 by views, date or length, over the results already on screen, so sorting rearranges what you are looking at instead of running a different search.",
+      "The channel name in the player is a real link again: middle-click and Ctrl-click open it in a new tab, the way the YouTube icon beside it always did, while a plain click still takes the in-app route.",
+    ],
+    fixes: [
+      "A YouTube video no longer rewinds when you reopen it. Closing at 13:50 and coming back put you at 12:31 \u2014 the checkpoint reached the server but not the page's own cache, so the stale position won. It now goes forward: 811 \u2192 816 \u2192 825 s across reopens.",
+      "\u201cClear resume point\u201d works on a half-watched Plex item. The push to Plex was skipped for exactly the case you would use it on, so Plex kept the old offset and handed it straight back on the next import. Verified against the real server, including a full 44,885-item re-import.",
+      "Turning full history on for a channel fills the page in front of you. The grid and the item count stayed frozen for the best part of a minute while the header counted up, because the request that starts the backfill returns before anything is stored. Measured: the count now moves 54 \u2192 139 within about twelve seconds, no reload.",
+      "Starting or seeking a Plex film is about eight seconds faster. Every session start and every seek waited out a dead eight-second timer for a file the transcoder never writes \u2014 on a film with more than one audio track, which is most of them. A multi-audio session now starts in 0.9 s cold and 0.7 s on a seek.",
+      "A Plex session the server no longer has now recovers or says so, instead of spinning forever. A stream that kept being lost could restart itself indefinitely behind a spinner that never became an error.",
+      "A Plex stream request for something that cannot exist answers immediately rather than holding the server for 20\u201330 seconds. Enough of those at once could stall the whole app.",
+      "The Plex player no longer counts one viewing twice, and a failed \u201cwatched\u201d mark no longer half-happens: it used to leave the item looking watched in the app while the server disagreed, or quietly mark it watched anyway a few seconds after telling you it had failed.",
+      "Dragging a Plex playlist into a new order sticks. Leaving and coming straight back showed the old order, and the next drag saved that.",
+      "A refused action says WHY, in the language you are reading. Several places showed a generic \u201ccouldn't do that\u201d \u2014 or nothing at all \u2014 where the server had explained itself, including the Plex \u201cAdd to playlist\u201d dialog, the collection editor and the upload dialog. The demo account gets its reason back too.",
+      "Dialogs behave for the keyboard. Opening one puts the cursor where you would expect (the jump-to box opens on its search field, not its close button), closing one hands the focus back to what you opened it from, and a dialog that closes underneath another one no longer steals the focus out of the one still on screen.",
+      "The regular micro-stutter in the Plex player is NOT Siftlode's, and this release does not pretend to fix it. Measured per frame: the player delivers every source frame with nothing dropped; the hold comes from a 23.976 fps film on a 120.0148 Hz display, and it reproduces identically outside Siftlode. Setting the display to 119.88 Hz removes it for every application, not just this one.",
+    ],
+    chores: [
+      "The round started from sixteen items written from real use, not from an audit. Eleven were fixed, one was measured and closed without a code change (the display cadence above), two are parked for a reproducible case, and one \u2014 playlist multi-select and bulk actions \u2014 was scoped out to its own sprint. The measurements are the point: item 8's \u201c35 s\u201d turned out to be one file's number, and the real law is bytes-ffmpeg-must-read divided by ~140 MB/s, which is why the fix is a window rather than a faster conversion.",
+      "Seven deep-review rounds followed, each reviewing the previous round's own fix commits: 32 \u2192 24 \u2192 43 \u2192 31 \u2192 22 \u2192 26 \u2192 18 raised. Round 7 was run TARGETED rather than full \u2014 four reviewers on the six surfaces round 6 had changed, and adversarial verification spent only where a wrong fix could re-break the previous round's \u2014 which is seven agents instead of about thirty-six for two HIGH findings. Every regression test added in a fix round was mutation-checked: reverted, run, and confirmed red for the defect it is named after. Thirteen of round 7's mutations were, and two were instructive \u2014 one guard no test could drive, and one round-6 test whose mock modelled a server that accepts a write and then serves the pre-write state.",
+      "What the eight-lane gate structurally cannot catch, and what this round taught about it: every real defect of the last three rounds was a wrong belief about an external system, not broken logic. ffmpeg substitutes the VARIANT before the sequence in its segment filenames, so a guard written the other way round was inert on every multi-audio file and a warm-up waited eight seconds for a name that is never written. A reclaim budget's window was anchored at the first failure rather than the last, so any failure cadence between one and two minutes reset it forever \u2014 invisible to two tests that spaced their cases at zero and ten minutes. jsdom performs no default Tab, so a focus test can be green with no focus trap installed at all. The conclusion carried forward is to measure the boundary when writing the code, not when reviewing it: one ffmpeg run costs pennies, a review round costs a session.",
+    ],
+  },
   {
     version: "0.83.0",
     date: "2026-09-09",