release: 0.84.0 (bug/hunt-2026-09)

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

@@ -7,6 +7,89 @@ 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.
+
+### Features
+
+- A new Home page, and it is where Siftlode starts. It asks how much time you have — 10 minutes, 30 minutes, an evening, or it does not matter — and answers with ONE suggestion rather than a wall of thumbnails. The question is on top, the answer directly under it. If you would rather land on the feed as before, Settings → Appearance → Startup turns it off.
+- The time you have picks the source, not just the length. Ten minutes gets you a short video; an evening is allowed to offer a film. It matches on the time you have LEFT in something, so a series episode you are four minutes from finishing counts as a four-minute answer.
+- The suggestion is one of three things, and it says which: something you left half-finished, something off your comfort shelf, or a surprise. Continue takes you back to the second you stopped. Something else rerolls it — there is no separate surprise-me page, the reroll is it.
+- A comfort shelf you fill yourself, for the media you put on without thinking. It takes a whole channel, a whole show, a film, a single video or a playlist — because comfort viewing is put on TheVR, not play this one episode. One click resolves it: a show gives you the next unwatched episode, a channel its newest unwatched video. The shelf can be reordered into the order you want.
+- Pin from wherever you are: the same ⋯ menu — or a right-click — on a feed video, a channel row, a playlist, a Plex poster or a Plex row now carries a Comfort shelf entry. Feed video cards answer a right-click for the first time.
+- Continue watching, on both sides at once. The rail merges what you left half-watched on YouTube with what you left half-watched on Plex, most recently touched first — the YouTube half of that did not exist before.
+- Shift+W jumps to Home from anywhere, including out of a player, and it is in the keyboard sheet. The jump-to box (Ctrl+K) gained a Surprise me row, and typing what should I watch finds Home itself.
+
+### Internal
+
+- E24, four sprints. S1 built a discover read-model as its own backend package — the unified card shape maps the EXISTING Plex and feed serializers rather than adding a base serializer, the rails reuse the feed query layer and the Plex rollup, and the tiered hero rule is one shared function that returns the tier it chose, so the UI prints an honest kicker instead of guessing. The shelf is a typed comfort_pins table with a one-of check constraint and a real foreign key per kind, not a polymorphic string reference: a deleted Plex item must not leave a dead pin on the shelf. S2 built the page on the existing carousel and the two existing card components rather than a third. S3 wired pinning through the context-menu input path E10 shipped, which absorbed that epic's parked video-card item. S4 added the ways in.
+- The closing review ran four rounds, 46 → 23 → 19 → 15 → 14, each round reviewing the previous round's own fix diff, with three adversarial verifiers per finding in rounds one to three. Four of round one's findings died at 2-of-3 and are recorded so they are not raised again. What the eight-lane gate could not have caught: the resume rail built its own query and dropped the per-user channel blocklist, so a video from a channel you had just banned could become the landing page's suggestion; the shelf numbered a new pin by row COUNT while nothing renumbers, so after any non-tail unpin a pin landed mid-shelf and could collide; the Home tile and the show page disagreed about which episode comes next, one taking the first in-progress episode and the other the last; and Shift+W was dead whenever anything was open, because the page change unmounted the player and its cleanup reclaimed the history entry the navigation had just pushed. Rounds three and four stopped finding defects in the epic and started finding them in the review's own fix commits — a test named after a branch it never reached, comments claiming more than the code does — which is the signal to stop.
+- Two process notes worth keeping. A commit in this epic fixed a bug that does not exist: its message and two comments claimed a sort key raises when two rows both lack a timestamp, which tuple comparison never reaches — three verifiers executed it independently, and the rationale is now corrected in place rather than quietly deleted. And three of the regression tests written during the fix rounds could not go red for the defect they named until they were rewritten, which is why every test added in a fix round on this epic was mutation-checked.
+
+## 0.82.0 — 2026-09-06
+
+Siftlode gets a keyboard. There is one place that lists every shortcut, a jump-to box that takes you anywhere by name, and a right-click menu on playlist rows — plus the whole app now holds together at a tablet's width and stops thinning itself out on a very wide screen.
+
+### Features
+
+- Press h anywhere and Siftlode tells you what you can press. One sheet for the whole app, and it only lists keys that actually do something where you are standing — the player's keys inside the player, undo where there is something to undo. It is h rather than the usual ?, because on a Hungarian keyboard ? is a two-key chord and h is already the key you use in the Plex player.
+- Ctrl+K (⌘K on a Mac) opens a jump-to box: start typing and it finds your modules, channels, playlists and saved views by name, plus a few actions like switching theme. It ignores accents and word order, so "penzugy" finds "Pénzügy" and "pod thevr" finds "TheVR Podcast".
+- Playlist rows answer a right-click. The same menu the ⋯ button opens — right-click anywhere on the row, long-press on a tablet, or Shift+F10 from the keyboard. Rail rows can be renamed in place and deleted from it, and a video can be moved straight to another list through a submenu.
+- Moving a video between lists is now one request instead of two. It used to add it there and then remove it here, which left the video in both lists whenever the second step failed; and if the move cannot be done, it now says so instead of the row quietly sliding back.
+- The app is built for 1024×768 as its floor — a tablet in landscape — and every page is measured against it rather than eyeballed. That caught a bug no screenshot could show: a hidden element used to measure filter chips was dragging the whole page 249px sideways on the channel manager, pulling the header off-screen with it.
+- A very wide screen now gets bigger cards instead of more of them. At 3440px the feed used to lay out eleven narrow columns and keep the cards at their minimum size; it now spends the extra width on the cards, which is what a screen you watch from across the room wants. Nothing changes at 1024, 1920 or a normal 2560.
+- Switching audio or subtitle track in the Plex player finally tells you where you landed. The keys already worked — what was missing was the answer, so you had to open the tracks menu to see which one you had picked.
+
+### Fixes
+
+- Ctrl+A in the Plex player selects text again instead of cycling the audio track. Six separate keyboard handlers had drifted apart; the one in the player matched the letter without checking whether Ctrl was held.
+- Typing into a dropdown or an editable area no longer triggers app shortcuts. Some surfaces checked for a text box and a text area but not for either of those.
+- The keyboard sheet no longer promises keys that do nothing where you are. Backspace does not claim to go back one level while the player is up, because there it does not.
+- Choosing a destination from the jump-to box lands you there. A command that navigates used to be undone by the box closing a fraction of a second later.
+- A button that is switched off no longer lights up under the pointer as though it could be clicked.
+- Two buttons in Messages announced themselves to a screen reader as just "button"; both are the only way out of the view they sit in.
+- In Hungarian, the built-in list is called "Megnézem később" everywhere, including in the message explaining that it cannot be renamed — which used to call it "Watch later".
+
+### Internal
+
+- E10, four sprints. S1 finished a half-done component adoption: the app's shared button primitive gained the variants the call sites proved were missing, ~60 hand-rolled buttons moved onto it, and the 1024×768 size contract (minimum touch target, the type scale bound to the text-size slider) moved into the primitives instead of living in ~160 call sites. The platform components moved into `components/ui/` and the boundary that makes it a layer — no feature components, no domain API slices — is enforced by eslint. S2 added a right-click/long-press/Shift+F10 input path onto the menu the app already had, rather than a second menu, plus an atomic move endpoint. S3 collapsed six drifting keydown listeners into one table whose handler map makes a table/implementation mismatch a type error, and built the cheat sheet and palette on it. S4 swept the viewport contract by measuring rather than looking.
+- The closing review ran three rounds, 32 → 15 → 11, each one reviewing the previous round's own fix diff. Round 1's 77 raw findings deduplicated to 64 and 32 survived three-refuter adversarial verification; six died at 2-of-3 and are recorded so they are not raised again. Rounds 2 and 3 each found that the previous round's fixes had introduced regressions, and both reverted rather than attempting a third variant — an aria-disabled menu row that the popover library skips exactly as it skips a disabled one (a comment one file away already said so), and a focus-restore that broke two other surfaces. The eslint rule meant to enforce the new layer boundary turned out to match almost nothing: its patterns were written in plain string literals, where the escape for a literal dot collapses into a wildcard, so the two commonest violations passed a green gate. It now has its own test. One bug was settled by measuring in a real browser after three rounds produced three contradictory explanations of React's commit ordering, and the jsdom harness built to decide it was deleted for reproducing nothing. Residuals are on the roadmap rather than closed: a disabled menu row's explanation still reaches nobody, Escape from an inline rename strands focus, and the overlay history bookkeeping counts buried entries rather than marking them.
+
 ## 0.81.0 — 2026-09-05
 
 If you run your own Siftlode, this one is mostly for you: there is now a way back from a bad upgrade, backup scripts that actually restore, and a way to let someone in on an instance that cannot send mail. If you just use Siftlode, the visible part is that a download can no longer quietly blow past your storage limit, and that the box refuses addresses on the server's own network.

CLAUDE.md

@@ -26,8 +26,8 @@ The local gate is **ruff (`check` + `format --check`) + typecheck (3 tsc project
   keep commits logical and Conventional-Commit-styled.
 - **No AI attribution in commits.** No `Co-Authored-By` trailer, no "generated by" lines. (This file
   being AI-written is the intended, visible exception; commits are not.)
-- **Release: user-owned in timing, agent-run in execution.** The user decides *when* to ship; on their
-  go-ahead *you* run `siftlode release` from the feature branch (merge to `main` → publish → deploy →
+- **Release: user-owned in timing, agent-run in execution.** The user decides _when_ to ship; on their
+  go-ahead _you_ run `siftlode release` from the feature branch (merge to `main` → publish → deploy →
   verify `/api/version`). Never self-ship — bring work to a green, committed state and stop for the
   go-ahead first, then run it yourself.
 - **Public repo.** Keep ops/topology/secrets out — those live in a separate private repo. Nothing here
@@ -41,7 +41,7 @@ how it gets built. Concretely:
 - **Plan before you build.** For anything non-trivial, present a short plan (sprint-level for larger
   work) and get a go-ahead before writing code.
 - **Offer choices, mark the optimal — and explain the trade-off.** When several solutions are viable,
-  list them and mark the recommended one. This is the *one* place to spend extra words: give the *why*
+  list them and mark the recommended one. This is the _one_ place to spend extra words: give the _why_
   behind each option and the weight of the decision. These decision points are where the product owner
   engages with the build and learns from it, so make them understandable — a reasoned menu, not a bare one.
 - **Mockups for design/UX decisions.** For any visual or interaction choice, show mockup options to
@@ -59,31 +59,38 @@ how it gets built. Concretely:
 `downloads/`, `youtube/` (shared by routes + scheduler + worker) → flat core (`auth`, `quota`,
 `sysconfig`, `state`, `audit`, `notifications`, `userscope`, `realtime`, `ratelimit`, `progress`,
 `security`) → `models/db/config`. **Dependency direction is one-way: core never imports routes.**
-Frontend: `main.tsx` provider tree → `App.tsx` shell → `moduleRegistry` route-chunks → components; data
-via react-query (`qk` factory), per-account `localStorage`, and server prefs; API through `lib/api/*`
-slices over `core.req<T>`.
+Frontend: `main.tsx` provider tree → `App.tsx` shell → `moduleRegistry` route-chunks → module
+components → the **platform layer `components/ui/`** (domain-free primitives: the popover engine and
+its menus, `Modal`/`Overlay`, `Button`/`form`, `DataTable`/`VirtualGrid`, `QueryState`, …). That
+boundary is one-way and **lint-enforced**, not just described: a platform component may not import a
+feature component or a domain API slice (`no-restricted-imports` in `eslint.config.js`, with its own
+test). A new generic component goes in `ui/`; see [`frontend/src/components/ui/README.md`](frontend/src/components/ui/README.md).
+Data via react-query (`qk` factory), per-account `localStorage`, and server prefs; API through
+`lib/api/*` slices over `core.req<T>`.
 
 **Not wanted** (reviewed and rejected as over-engineering for this size): microservices, event bus,
 CQRS, a repository/DI framework, a router library, a generic CRUD-router factory or base serializer.
 
 ## Canonical patterns — when you have a choice, pick THIS
 
-| Area | Use | Not |
-|---|---|---|
-| ORM | SQLAlchemy 2.0 `select()` | `db.query(...)` |
-| Request body | a Pydantic model | `payload: dict` |
-| Ownership check | `owned_or_404` / `get_or_404` | ad-hoc `_own_playlist`/`_owned`/`_own_job` |
-| Admin gate import | `app.auth` | the `app.routes.admin` re-export |
-| Upstream failure status | `422` with JSON detail | `502` (reserve 502 for raw byte-proxies) |
-| User-facing error | structured `detail` (`{code, reason}`) | a bare English string under a bilingual UI |
-| Mutation response | `{"ok": true, …}` (`{"deleted": id}`) | ad-hoc `{"unsubscribed"}`/`{"cleared": n}`/echo |
-| Transaction commit | the handler/job-wrapper commits; helpers `flush` | helpers that commit (only `quota` owns its session) |
-| Admin knob storage | `sysconfig` (values) | env / `app_state` / `scheduler_settings` scatter |
-| Job status word | the `downloads/status.py` StrEnum | loose `"canceled"`/`"cancelled"` literals |
-| Current time | inline `datetime.now(timezone.utc)` | new `now_utc`/`_now` helpers |
-| FE per-account state | `usePref` | raw `readAccount`/`writeAccount` or bespoke hooks |
-| FE control | the chip/segmented primitives (`Select` only for >6 options) | a native `<select>` |
-| FE loading/empty/error | `QueryState` / `StateMessage` | ad-hoc conditionals |
+| Area                    | Use                                                          | Not                                                    |
+| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------ |
+| ORM                     | SQLAlchemy 2.0 `select()`                                    | `db.query(...)`                                        |
+| Request body            | a Pydantic model                                             | `payload: dict`                                        |
+| Ownership check         | `owned_or_404` / `get_or_404`                                | ad-hoc `_own_playlist`/`_owned`/`_own_job`             |
+| Admin gate import       | `app.auth`                                                   | the `app.routes.admin` re-export                       |
+| Upstream failure status | `422` with JSON detail                                       | `502` (reserve 502 for raw byte-proxies)               |
+| User-facing error       | structured `detail` (`{code, reason}`)                       | a bare English string under a bilingual UI             |
+| Mutation response       | `{"ok": true, …}` (`{"deleted": id}`)                        | ad-hoc `{"unsubscribed"}`/`{"cleared": n}`/echo        |
+| Transaction commit      | the handler/job-wrapper commits; helpers `flush`             | helpers that commit (only `quota` owns its session)    |
+| Admin knob storage      | `sysconfig` (values)                                         | env / `app_state` / `scheduler_settings` scatter       |
+| Job status word         | the `downloads/status.py` StrEnum                            | loose `"canceled"`/`"cancelled"` literals              |
+| Current time            | inline `datetime.now(timezone.utc)`                          | new `now_utc`/`_now` helpers                           |
+| FE per-account state    | `usePref`                                                    | raw `readAccount`/`writeAccount` or bespoke hooks      |
+| FE action button        | `ui/Button` — pick a `SIZES` rung                            | a hand-rolled `<button className="px-3 py-2 …">`       |
+| FE keyboard shortcut    | a row in `lib/keymap.ts` + `dispatch()`                      | a private `keydown` listener with its own key literals |
+| FE control              | the chip/segmented primitives (`Select` only for >6 options) | a native `<select>`                                    |
+| FE loading/empty/error  | `QueryState` / `StateMessage`                                | ad-hoc conditionals                                    |
 
 ## House rules that bite (learned from real bugs)
 
@@ -100,6 +107,6 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 
 ---
 
-*Run-it-locally and the full gate commands live in [`docs/development.md`](docs/development.md); backend
+_Run-it-locally and the full gate commands live in [`docs/development.md`](docs/development.md); backend
 code conventions in [`backend/app/README.md`](backend/app/README.md). This file stays the source of
-truth for the canonical-patterns table and the gate/workflow/collaboration rules above.*
+truth for the canonical-patterns table and the gate/workflow/collaboration rules above._

VERSION

@@ -1 +1 @@
-0.81.0
+0.84.0

backend/alembic/versions/0083_comfort_pins.py

@@ -0,0 +1,78 @@
+"""comfort_pins — the shelf you fall back to when you cannot decide
+
+Revision ID: 0083_comfort_pins
+Revises: 0082_invite_lang
+Create Date: 2026-09-06
+
+E24's one new table. The shelf holds five different things — a video, a YouTube channel, a Plex show,
+a Plex movie, a playlist — because comfort media is usually "put on X", a series or a channel, and
+almost never one particular video.
+
+Three shapes were possible and two are wrong here:
+
+- a boolean on `video_states` / `plex_states` cannot ORDER a shelf, and has nowhere to put a channel
+  or a show (neither has a per-user state row at all);
+- a polymorphic `(kind, ref)` string pair orders and holds anything, but drops the foreign key — and a
+  Plex item removed from the library, or a channel the user unsubscribes and prunes, would then leave
+  a dead tile on the one surface whose entire job is to be reliable when nothing else is.
+
+So: one nullable CASCADE-ing FK per kind, plus `num_nonnulls(...) = 1`. The union invariant lives in
+the schema rather than in a comment at every insert site, which is the same rule that the
+`cancelled`/`canceled` bug taught this codebase.
+
+NULLs are DISTINCT in a Postgres unique index, so the five per-kind `(user_id, <ref>)` uniques each
+stop a double-pin without colliding with the other four kinds' NULL rows.
+
+No backfill: an empty shelf is the honest state for every existing account. The surface renders its
+own empty state and invites the first pin.
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0083_comfort_pins"
+down_revision: str | None = "0082_invite_lang"
+branch_labels: str | None = None
+depends_on: str | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "comfort_pins",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column(
+            "user_id",
+            sa.Integer(),
+            sa.ForeignKey("users.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("video_id", sa.String(length=16), sa.ForeignKey("videos.id", ondelete="CASCADE")),
+        sa.Column(
+            "channel_id", sa.String(length=32), sa.ForeignKey("channels.id", ondelete="CASCADE")
+        ),
+        sa.Column("plex_item_id", sa.Integer(), sa.ForeignKey("plex_items.id", ondelete="CASCADE")),
+        sa.Column("plex_show_id", sa.Integer(), sa.ForeignKey("plex_shows.id", ondelete="CASCADE")),
+        sa.Column("playlist_id", sa.Integer(), sa.ForeignKey("playlists.id", ondelete="CASCADE")),
+        sa.Column("position", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.CheckConstraint(
+            "num_nonnulls(video_id, channel_id, plex_item_id, plex_show_id, playlist_id) = 1",
+            name="ck_comfort_pin_one_ref",
+        ),
+        sa.UniqueConstraint("user_id", "video_id", name="uq_comfort_pin_video"),
+        sa.UniqueConstraint("user_id", "channel_id", name="uq_comfort_pin_channel"),
+        sa.UniqueConstraint("user_id", "plex_item_id", name="uq_comfort_pin_plex_item"),
+        sa.UniqueConstraint("user_id", "plex_show_id", name="uq_comfort_pin_plex_show"),
+        sa.UniqueConstraint("user_id", "playlist_id", name="uq_comfort_pin_playlist"),
+    )
+    op.create_index("ix_comfort_pins_user_id", "comfort_pins", ["user_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_comfort_pins_user_id", table_name="comfort_pins")
+    op.drop_table("comfort_pins")

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
 
 

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

backend/app/discover/__init__.py

@@ -0,0 +1,10 @@
+"""E24 — the read-model behind the Home surface ("Mit nézzek most?").
+
+The anti-paralysis answer layer: one hero suggestion, a cross-source resume rail, and the user's own
+comfort shelf, all served from our own Postgres with no upstream call at serve time (the same rule
+the Plex Discover surface follows).
+
+Layering, mirroring `app/plex/`: `budget` (the time bands) and `cards` (the unified row shape) are
+pure; `queries` holds the SQL; `rails`, `pins` and `hero` compose. Nothing here imports from
+`app.routes` — `routes/discover.py` is a thin HTTP shell over these.
+"""

backend/app/discover/budget.py

@@ -0,0 +1,62 @@
+"""The time budget — E24's replacement for "what mood are you in?".
+
+`random-gondolatok` 15/D asked for a mood questionnaire before the recommendations. The same file's
+later BA-interview note (#23) says the mood half is not what makes this work: the friction is
+deciding at all. A mood→genre mapping would also be invented data — we store no mood signal and never
+will — whereas "how much time do you have" is a question the library can actually answer, from a
+column we already have.
+
+So the surface asks about TIME, and the answer is deterministic: four bands, no model, no latency.
+The band also picks the source for free — ten minutes is a YouTube video, an evening is a movie —
+which is exactly the cross-source behaviour the Home surface exists to provide.
+
+The bands overlap on purpose. "I have 30 minutes" should not be answered with a two-minute Short just
+because it fits; a lower bound is as much a part of the promise as the upper one.
+"""
+
+from typing import Literal
+
+Budget = Literal["short", "medium", "long", "any"]
+
+DEFAULT_BUDGET: Budget = "any"
+
+# budget -> (min_seconds, max_seconds); None = unbounded on that side.
+BANDS: dict[str, tuple[int | None, int | None]] = {
+    "short": (None, 12 * 60),  # "10 perc" — a bit of slack over the round number the chip shows
+    "medium": (8 * 60, 40 * 60),  # "30 perc"
+    "long": (40 * 60, None),  # "Egy este"
+    "any": (None, None),  # "Mindegy"
+}
+
+
+def band(budget: str) -> tuple[int | None, int | None]:
+    """The (min, max) seconds for a budget. Unknown budgets fall back to the unbounded band rather
+    than raising: the route validates the vocabulary with a Literal, so anything reaching here with a
+    bad value is our own bug, and an unfiltered shelf is a better failure than a 500 on the landing
+    page."""
+    return BANDS.get(budget, BANDS["any"])
+
+
+def remaining_seconds(duration_seconds: int | None, position_seconds: int) -> int | None:
+    """What is actually LEFT to watch. The question is "how much time do you have", so a 90-minute
+    film with 8 minutes to go belongs in the ten-minute band, not the evening one. Unknown duration
+    stays unknown — see `fits`."""
+    if duration_seconds is None:
+        return None
+    return max(0, duration_seconds - max(0, position_seconds))
+
+
+def fits(seconds: int | None, budget: str) -> bool:
+    """Does a runtime fit the budget?
+
+    An unknown duration fits only the unbounded band. We cannot promise an item finishes inside ten
+    minutes when we do not know how long it is, and quietly including it would make the one control
+    on this page dishonest — the failure mode the house rules call an un-honest state."""
+    lo, hi = band(budget)
+    if seconds is None:
+        return lo is None and hi is None
+    if lo is not None and seconds < lo:
+        return False
+    if hi is not None and seconds > hi:
+        return False
+    return True

backend/app/discover/cards.py

@@ -0,0 +1,141 @@
+"""The unified discover card: one row shape the Home surface can render without knowing which
+module it came from.
+
+This is deliberately a THIN mapping, not a new serializer layer. The per-source projections already
+exist and are already the shapes the frontend's `VideoCard` and `PlexPosterCard` consume —
+`feedquery.serialize` for YouTube, `plex.cards.movie_card`/`show_card`/`leaf_card` for Plex — so each
+unified card carries the native payload under `video` / `plex` alongside the handful of fields the
+rail chrome itself needs (title, thumbnail, progress, runtime). The Home page therefore renders with
+the existing card components rather than a third one, and a field added to a feed row or a Plex card
+still gets added in exactly one place. CLAUDE.md's "not wanted" list names a base serializer for
+precisely this reason.
+
+`aspect` is the one genuinely new field. A rail has to know whether a tile is a 16:9 still or a 2:3
+poster, and that is a property of the ARTWORK, not of the module: a Plex episode ships a landscape
+still exactly like a YouTube video does, while a movie and a show ship posters. Emitting it lets the
+rail layer stay domain-free instead of branching on `source`.
+
+`subtitle` only ever carries DATA — a channel name, a show title, a year. Nothing here composes an
+English phrase: this repo is HU+EN with zero key drift, and a sentence assembled in the backend is a
+string no translation file can reach. Anything that needs wording (season counts, "N videó") is left
+to the client, which has both the native payload and the translations.
+"""
+
+from app.discover.budget import remaining_seconds
+from app.models import Channel, Playlist
+
+# Plex artwork is a poster for the things you browse and a landscape still for the things you play.
+_POSTER_KINDS = ("movie", "show")
+
+
+def _base(
+    *,
+    source: str,  # "youtube" | "plex"
+    kind: str,  # "video" | "movie" | "show" | "episode" | "channel" | "playlist"
+    id: str,
+    title: str | None,
+    aspect: str,  # "wide" (16:9) | "poster" (2:3)
+    subtitle: str | None = None,
+    thumb: str | None = None,
+    duration_seconds: int | None = None,
+    position_seconds: int = 0,
+    status: str = "new",
+) -> dict:
+    return {
+        "source": source,
+        "kind": kind,
+        "id": id,
+        "title": title or "",
+        "subtitle": subtitle,
+        "thumb": thumb,
+        "aspect": aspect,
+        "duration_seconds": duration_seconds,
+        "position_seconds": position_seconds,
+        "remaining_seconds": remaining_seconds(duration_seconds, position_seconds),
+        "status": status,
+        # Native payloads — at most one is ever set. The client opens the player from these.
+        "video": None,
+        "plex": None,
+    }
+
+
+def key(card: dict) -> str:
+    """The identity of a card ACROSS sources — `<source>:<id>`. A Plex rating_key and a YouTube video
+    id could in principle collide as bare strings, and the reroll's exclusion list has to be able to
+    say "not that one" about either."""
+    return f"{card['source']}:{card['id']}"
+
+
+def from_video(row: dict) -> dict:
+    """`row` is a `feedquery.serialize` dict — the same object the feed grid renders."""
+    card = _base(
+        source="youtube",
+        kind="video",
+        id=row["id"],
+        title=row["title"],
+        aspect="wide",
+        subtitle=row.get("channel_title"),
+        thumb=row.get("thumbnail_url"),
+        duration_seconds=row.get("duration_seconds"),
+        position_seconds=row.get("position_seconds") or 0,
+        status=row.get("status") or "new",
+    )
+    card["video"] = row
+    return card
+
+
+def from_plex(row: dict) -> dict:
+    """`row` is a `plex.cards` dict (movie / show / leaf). Its own `type` is the kind."""
+    kind = row.get("type") or "movie"
+    if kind == "episode":
+        subtitle = row.get("show_title")
+    elif kind == "show":
+        subtitle = None  # season count lives in the native payload; the client words it
+    else:
+        subtitle = str(row["year"]) if row.get("year") else None
+
+    card = _base(
+        source="plex",
+        kind=kind,
+        id=row["id"],
+        title=row.get("title"),
+        aspect="poster" if kind in _POSTER_KINDS else "wide",
+        subtitle=subtitle,
+        thumb=row.get("thumb"),
+        duration_seconds=row.get("duration_seconds"),
+        position_seconds=row.get("position_seconds") or 0,
+        status=row.get("status") or "new",
+    )
+    card["plex"] = row
+    return card
+
+
+def from_channel(ch: Channel, unwatched: int) -> dict:
+    """A pinned channel. It is not itself playable — the shelf resolves it to its newest unwatched
+    video on click (see `pins._shelf_card`) — so the tile advertises what is waiting there instead of a
+    runtime it does not have."""
+    card = _base(
+        source="youtube",
+        kind="channel",
+        id=ch.id,
+        title=ch.title,
+        aspect="wide",
+        thumb=ch.thumbnail_url,
+    )
+    card["unwatched_count"] = unwatched
+    return card
+
+
+def from_playlist(pl: Playlist, item_count: int, thumb: str | None) -> dict:
+    """A pinned playlist. `thumb` is its first item's thumbnail — a shelf of blank tiles would defeat
+    the point of a surface you are supposed to be able to scan at a glance."""
+    card = _base(
+        source="youtube",
+        kind="playlist",
+        id=str(pl.id),
+        title=pl.name,
+        aspect="wide",
+        thumb=thumb,
+    )
+    card["item_count"] = item_count
+    return card

backend/app/discover/hero.py

@@ -0,0 +1,104 @@
+"""The hero: the single suggestion the Home surface leads with.
+
+One rule, in one function, because the page's entire promise is that it answers rather than offers.
+Three tiers, tried in order:
+
+1. **resume** — something already started whose REMAINING time fits the budget. Almost always the
+   right answer: it is the thing the user themselves chose most recently, and finishing it costs no
+   decision at all.
+2. **comfort** — a pinned shelf entry that fits. The user's own declared fallback, which beats
+   anything we could infer.
+3. **surprise** — a seeded draw from what is unseen and fits.
+
+That order is the PAGE's answer. "Mást kérek" rotates it (`start`), so each press offers a different
+KIND of answer rather than the next row of the same list — the user's call, 2026-09-06, after the
+button was measured cycling nine resume cards and never once reaching the shelf.
+
+The tier travels with the card so the client can label it honestly ("Ott hagytad abba" vs "A
+polcodról" vs "Meglepetés") instead of guessing from the shape of the payload — a kicker that says
+"where you left off" over a film the user has never opened is exactly the kind of quiet lie the house
+rules call a dishonest state.
+
+Budgets are matched against REMAINING time throughout (`budget.remaining_seconds`, which equals the
+runtime for anything not yet started): with eight minutes left, a 90-minute film is a ten-minute
+answer.
+"""
+
+from sqlalchemy.orm import Session
+
+from app.discover import cards, pins, rails
+from app.discover.budget import fits
+from app.models import User
+
+HERO_TIERS = ("resume", "comfort", "surprise")
+
+# How deep the surprise tier draws before giving up. Deliberately deeper than one, so an excluded
+# pick moves the tier along instead of emptying it (the shuffle is seeded — the same seed always
+# hands back the same order, so without the headroom "already shown" would mean "nothing left").
+SURPRISE_DRAW = 12
+
+
+def pick(
+    db: Session,
+    user: User,
+    budget: str,
+    seed: int,
+    *,
+    resume: list[dict] | None = None,
+    shelf: list[dict] | None = None,
+    exclude: set[str] | None = None,
+    start: int = 0,
+) -> dict | None:
+    """`{"tier": ..., "card": ...}`, or None when nothing at all fits.
+
+    `resume` and `shelf` may be passed pre-computed so the consolidated `/api/discover` response does
+    not build the same two rails twice; the reroll endpoint passes neither and pays only for what it
+    reaches.
+
+    `exclude` is what makes "Mást kérek" mean something. A new seed alone only re-draws the SURPRISE
+    tier: the resume tier deterministically returns the most recently progressed thing that fits, so
+    pressing reroll on a user who has something half-finished handed back the identical card and the
+    button looked dead (measured in the browser, 2026-09-06). Skipping the cards already shown makes
+    every press produce a different answer, at every tier.
+
+    `start` ROTATES which tier is tried first — 0 keeps the priority order (the page's own first
+    answer), 1 leads with comfort, 2 with surprise. Exclusion alone was not enough: the resume rail
+    holds up to 20 rows, so the button walked down it and never reached the shelf or a surprise at
+    all (measured, 2026-09-06: twelve presses returned nine cards, every one of them `resume`). The
+    fallthrough is kept, so a press does not come back empty just because the tier it led with has
+    nothing to offer."""
+    skip = exclude or set()
+
+    def _resume() -> dict | None:
+        for card in rails.continue_watching(db, user) if resume is None else resume:
+            playable = rails.playable(db, user.id, card)
+            # Excluded on the card the USER saw (the show), not only on what it resolves to, so a
+            # rerolled-past show does not come straight back as its own next episode.
+            if cards.key(card) in skip or (playable is not None and cards.key(playable) in skip):
+                continue
+            if playable is not None and fits(playable["remaining_seconds"], budget):
+                return playable
+        return None
+
+    def _comfort() -> dict | None:
+        for card in pins.playables(pins.shelf(db, user) if shelf is None else shelf):
+            if cards.key(card) not in skip and fits(card["remaining_seconds"], budget):
+                return card
+        return None
+
+    def _surprise() -> dict | None:
+        # A wider draw than the one card we need: the shuffle is seeded, so without the headroom an
+        # excluded pick would leave the tier empty rather than move past it.
+        for card in rails.surprise(db, user, budget, seed, limit=SURPRISE_DRAW):
+            if cards.key(card) not in skip:
+                return card
+        return None
+
+    tiers = {"resume": _resume, "comfort": _comfort, "surprise": _surprise}
+    offset = start % len(HERO_TIERS)
+    for tier in HERO_TIERS[offset:] + HERO_TIERS[:offset]:
+        card = tiers[tier]()
+        if card is not None:
+            return {"tier": tier, "card": card}
+
+    return None

backend/app/discover/pins.py

@@ -0,0 +1,173 @@
+"""The comfort shelf: pin a thing you can always fall back to, and have it be one click from playing.
+
+Five kinds are pinnable — a video, a YouTube channel, a Plex show, a Plex movie, a playlist — because
+comfort media is almost always "put on X", a series or a channel, and only sometimes one particular
+video. `models.ComfortPin` carries that union as five nullable FKs under a `num_nonnulls(...) = 1`
+check; this module is where the union is spoken about in one vocabulary, so no call site invents a
+second one.
+
+Every shelf card carries a resolved `next`: the thing that actually plays when you click the tile —
+a show's in-progress-or-next episode, a channel's newest unwatched video, a playlist's first
+unwatched item. It costs a query per non-leaf pin, which is affordable precisely because this shelf is
+short and hand-curated, and it buys the property the whole surface exists for: one click, no
+intermediate page, no second decision.
+
+Domain module, so nothing here raises HTTP. `resolve_ref` returns None for "no such thing, or not
+yours" and the route turns that into its 404 — core never imports routes.
+"""
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.discover import cards, queries
+from app.models import Channel, ComfortPin, PlexItem, PlexShow, Playlist, User, Video
+from app.plex import rollup
+from app.plex.cards import leaf_card, show_card
+from app.plex.lookups import by_rating_key
+
+# kind -> the ComfortPin column that holds it. The client's vocabulary and the schema's, in one place.
+PIN_COLUMNS: dict[str, str] = {
+    "video": "video_id",
+    "channel": "channel_id",
+    "plex_item": "plex_item_id",
+    "plex_show": "plex_show_id",
+    "playlist": "playlist_id",
+}
+PIN_KINDS = tuple(PIN_COLUMNS)
+
+
+def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, object] | None:
+    """Translate the client's (kind, ref) into the (column, value) the row stores, or None.
+
+    The client speaks the ids the rest of the API speaks: a video id, a channel id, a Plex
+    `rating_key`, a playlist id. Plex's internal integer keys never leave the backend, so the
+    translation belongs here rather than in five call sites.
+
+    The COLUMN half of every answer comes from `PIN_COLUMNS`; only the LOOKUP differs per kind
+    (a direct `db.get`, a rating-key translation, an int parse plus an ownership check). Before the
+    E24 review the branches spelled the column names out again and `PIN_COLUMNS` had no readers at
+    all — a constant that called itself the one vocabulary while nothing spoke it."""
+    col = PIN_COLUMNS.get(kind)
+    if col is None:
+        return None
+    if kind == "video":
+        return (col, ref) if db.get(Video, ref) is not None else None
+    if kind == "channel":
+        return (col, ref) if db.get(Channel, ref) is not None else None
+    if kind == "plex_item":
+        it = by_rating_key(db, PlexItem, ref)
+        return (col, it.id) if it is not None else None
+    if kind == "plex_show":
+        sh = by_rating_key(db, PlexShow, ref)
+        return (col, sh.id) if sh is not None else None
+    try:
+        pid = int(ref)
+    except ValueError:
+        return None
+    pl = db.get(Playlist, pid)
+    # A playlist is per-user, unlike the other four (which are shared catalog rows whose PRIVACY
+    # lives in the state tables). Someone else's list must read as "no such thing", not as a 403 —
+    # the same reason `owned_or_404` 404s rather than 403s.
+    return (col, pl.id) if pl is not None and pl.user_id == user.id else None
+
+
+def list_pins(db: Session, user: User) -> list[ComfortPin]:
+    return list(
+        db.execute(
+            select(ComfortPin)
+            .where(ComfortPin.user_id == user.id)
+            .order_by(ComfortPin.position.asc(), ComfortPin.id.asc())
+        )
+        .scalars()
+        .all()
+    )
+
+
+def next_position(db: Session, user: User) -> int:
+    """New pins land at the end of the shelf.
+
+    `max(position) + 1`, not the row count. Positions are never renumbered on removal — `remove_pin`
+    deletes the row, and every FK cascade silently removes a pin when the thing it points at goes
+    away — so past the first hole a count under-counts and would drop the new pin into the MIDDLE of
+    the shelf, or onto a position another pin already holds (nothing in the schema forbids that).
+    Same idiom as `routes/playlists._next_playlist_position`."""
+    return (
+        db.scalar(
+            select(func.coalesce(func.max(ComfortPin.position), -1)).where(
+                ComfortPin.user_id == user.id
+            )
+        )
+        + 1
+    )
+
+
+def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
+    """One pin as a unified card with its resolved `next`. None when the pinned row has gone (the FK
+    cascade removes the pin itself, so this is only the window between a delete and a refetch)."""
+    card: dict | None = None
+    nxt: dict | None = None
+
+    if pin.video_id is not None:
+        row = queries.yt_video_row(db, user, pin.video_id)
+        if row is None:
+            return None
+        card = cards.from_video(row)
+        nxt = dict(card)  # a video plays itself
+
+    elif pin.channel_id is not None:
+        ch = db.get(Channel, pin.channel_id)
+        if ch is None:
+            return None
+        card = cards.from_channel(ch, queries.channel_unwatched_count(db, user, ch.id))
+        row = queries.channel_next_video(db, user, ch.id)
+        nxt = cards.from_video(row) if row else None
+
+    elif pin.plex_item_id is not None:
+        it = db.get(PlexItem, pin.plex_item_id)
+        if it is None:
+            return None
+        st = rollup.item_state_map(db, user.id, [it.id]).get(it.id)
+        card = cards.from_plex(leaf_card(it, st))
+        nxt = dict(card)  # a movie or a single episode plays itself
+
+    elif pin.plex_show_id is not None:
+        sh = db.get(PlexShow, pin.plex_show_id)
+        if sh is None:
+            return None
+        status = rollup.state_map(db, user.id, [sh.id]).get(sh.id, "new")
+        card = cards.from_plex(show_card(sh, status))
+        ep = queries.next_episode(db, user.id, sh.id)
+        nxt = cards.from_plex(ep) if ep else None
+
+    elif pin.playlist_id is not None:
+        pl = db.get(Playlist, pin.playlist_id)
+        if pl is None:
+            return None
+        count, row = queries.playlist_summary(db, user, pl.id)
+        card = cards.from_playlist(pl, count, row.get("thumbnail_url") if row else None)
+        nxt = cards.from_video(row) if row else None
+
+    if card is None:
+        return None
+    # A COPY, never the card itself: a self-playing pin (a video, a movie) would otherwise make
+    # `card["next"] is card`, which serializes as a circular reference and 500s the whole shelf. The
+    # copy is taken before `pin_id`/`next` are attached, so `next` stays a plain playable card.
+    card["pin_id"] = pin.id
+    card["next"] = nxt
+    return card
+
+
+def shelf(db: Session, user: User) -> list[dict]:
+    """The whole shelf, in the user's own order."""
+    out = []
+    for pin in list_pins(db, user):
+        card = _shelf_card(db, user, pin)
+        if card is not None:
+            out.append(card)
+    return out
+
+
+def playables(shelf_cards: list[dict]) -> list[dict]:
+    """The `next` of every shelf entry that has one — what the hero may draw from. A pinned channel
+    with nothing unwatched left, or an empty playlist, simply is not an answer right now."""
+    return [c["next"] for c in shelf_cards if c.get("next")]

backend/app/discover/queries.py

@@ -0,0 +1,348 @@
+"""The row fetchers behind the Home surface — one place where "what is startable right now" is
+expressed as SQL, for both sources.
+
+Two rules shape this module:
+
+**Reuse the query layer, not the route.** The YouTube half calls `feedquery.filtered_query` /
+`sort_keys`, so the Home surface inherits the feed's own definitions of subscribed, blocked,
+explore-visible and in-progress for free, and cannot drift from them. The Plex half calls
+`plex.rollup` and the `plex.cards` serializers rather than `routes/plex/discover.py`: that route
+narrows EVERY rail by the Plex sidebar's `LibraryFilters`, which is right for a surface that HAS a
+sidebar and wrong for a landing page that does not.
+
+**One seed drives both halves.** The feed orders a shuffle by `md5(id || seed)` so a keyset cursor
+stays valid across pages; the Plex surprise rail uses `ORDER BY random()`, which is fine for a single
+un-paged draw but cannot be reproduced. A cross-source reroll needs both halves to move together —
+otherwise "Mást kérek" re-draws the Plex picks while the YouTube ones stand still — so the Plex side
+here takes the feed's seeded-md5 idiom instead of `random()`.
+"""
+
+from sqlalchemy import and_, func, or_, select
+from sqlalchemy.orm import Session, aliased
+
+from app.discover.budget import band
+from app.feedquery import (
+    feed_columns,
+    filtered_query,
+    not_blocked_cond,
+    order_by,
+    serialize,
+    sort_keys,
+)
+from app.models import (
+    Channel,
+    PlaylistItem,
+    PlexItem,
+    PlexShow,
+    PlexState,
+    User,
+    Video,
+    VideoState,
+)
+from app.plex import rollup
+from app.plex.cards import leaf_card, movie_card, show_card
+from app.plex.query import apply_show_state_filter, content_libs
+
+# How many rows a single rail may carry. Matches `routes/plex/discover.py`'s RAIL_LIMIT on purpose —
+# the two surfaces should feel like the same app, and a rail is a rail.
+RAIL_LIMIT = 20
+
+# The feed parameters a Home rail runs with. Spelled out rather than borrowed from the route's
+# `_feed_params` defaults, because those are an HTTP contract that may change for the feed's own
+# reasons; the landing page's scope should not move with them silently.
+_FEED_BASE: dict = {
+    "tags": [],
+    "tag_modes": {},
+    "untagged": False,
+    "channel_ids": [],
+    "q": None,
+    "min_duration": None,
+    "max_duration": None,
+    "max_age_days": None,
+    "published_after": None,
+    "published_before": None,
+    "show_normal": True,
+    "include_shorts": False,
+    "include_live": False,
+    "show": "unwatched",
+    "scope": "my",
+    "library_source": "organic",
+}
+
+
+def _seeded(col, seed: int):
+    """The feed's deterministic shuffle expression, reused for Plex so one seed moves both halves."""
+    return func.md5(func.concat(col, str(seed)))
+
+
+# ── YouTube ───────────────────────────────────────────────────────────────────────────────────────
+
+
+def yt_in_progress(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[tuple[object, dict]]:
+    """Started-but-not-finished videos, most recently progressed first, as (progressed_at, row).
+
+    The predicate is `feedquery`'s `show="in_progress"` verbatim (a stored resume position, status not
+    watched/hidden) — but the query is built here rather than through `filtered_query` because this
+    rail wants an ordering by `progress_updated_at`, and that column lives on the state alias the feed
+    query keeps private. Driving from `video_states` is also the faster plan: it is a per-user table of
+    a few hundred rows, against a catalog of many thousands.
+
+    Building it here means the feed's OTHER predicates have to be chosen deliberately rather than
+    inherited. `not_blocked_cond` is shared, because "never show me this channel" outranks "you
+    started it" — blocking leaves the state row untouched, so without this the video the user just
+    banned heads the resume rail. The feed's SCOPE clauses (subscribed / via_explore accessibility)
+    are deliberately NOT applied, for the reason `yt_video_row` gives: something you have already
+    started must stay resumable even after you unsubscribe or an exploration expires."""
+    st = aliased(VideoState)
+    q = (
+        select(*feed_columns(user, st), st.progress_updated_at.label("progressed_at"))
+        .join(Channel, Channel.id == Video.channel_id)
+        .join(st, and_(st.video_id == Video.id, st.user_id == user.id))
+        .where(
+            st.position_seconds > 0,
+            st.status.notin_(("watched", "hidden")),
+            Video.unavailable_since.is_(None),
+            not_blocked_cond(user),
+        )
+        .order_by(st.progress_updated_at.desc().nullslast())
+        .limit(limit)
+    )
+    return [(r.progressed_at, serialize(r)) for r in db.execute(q).all()]
+
+
+def yt_surprise(db: Session, user: User, budget: str, seed: int, limit: int) -> list[dict]:
+    """Unwatched videos from the user's own feed scope, in seeded-shuffle order, inside the budget.
+
+    Shorts are opened up only for the shortest band: "I have ten minutes" is the one answer a Short is
+    actually a good response to, and the feed's own default keeps them out otherwise."""
+    lo, hi = band(budget)
+    params = dict(_FEED_BASE, min_duration=lo, max_duration=hi, include_shorts=budget == "short")
+    query, rank_expr = filtered_query(db, user, **params)
+    keys = sort_keys("shuffle", seed, rank_expr)
+    # Over-fetch, then drop anything already started. The feed's `unwatched` scope keeps watched and
+    # hidden out but deliberately keeps in-progress rows in (they belong in the feed). Here they must
+    # go: the resume tier has already had its chance at them, and it may have passed precisely because
+    # the REMAINING time did not fit the budget — offering the same item back as a surprise, whose
+    # runtime does fit, would label a half-finished thing "Meglepetés" and contradict the question.
+    rows = db.execute(query.order_by(*order_by(keys)).limit(limit * 4)).all()
+    out = [serialize(r) for r in rows]
+    return [r for r in out if not r["position_seconds"]][:limit]
+
+
+def channel_next_video(db: Session, user: User, channel_id: str) -> dict | None:
+    """The newest unwatched video of a pinned channel — what "put on that channel" resolves to."""
+    # `library_source="all"`: a pinned channel means the whole channel, including videos that only
+    # ever arrived through a search. The feed's "organic" default is a feed-scoping choice, not a
+    # statement about what belongs to a channel.
+    params = dict(_FEED_BASE, channel_ids=[channel_id], scope="all", library_source="all")
+    query, rank_expr = filtered_query(db, user, **params)
+    keys = sort_keys("newest", 0, rank_expr)
+    row = db.execute(query.order_by(*order_by(keys)).limit(1)).first()
+    return serialize(row) if row is not None else None
+
+
+def yt_video_row(db: Session, user: User, video_id: str) -> dict | None:
+    """One video as a feed row, with this user's watch state.
+
+    Built directly rather than through `filtered_query` on purpose: a PINNED video must keep working
+    even when it falls outside the feed's scope — the user unsubscribed from the channel, or blocked
+    it, or the video only ever arrived through a search. The shelf is the surface you fall back to;
+    it silently losing an entry because a filter moved is exactly the failure it must not have."""
+    st = aliased(VideoState)
+    row = db.execute(
+        select(*feed_columns(user, st))
+        .join(Channel, Channel.id == Video.channel_id)
+        .outerjoin(st, and_(st.video_id == Video.id, st.user_id == user.id))
+        .where(Video.id == video_id)
+    ).first()
+    return serialize(row) if row is not None else None
+
+
+def channel_unwatched_count(db: Session, user: User, channel_id: str) -> int:
+    """How many unwatched videos a pinned channel is holding — the tile's only honest promise, since a
+    channel has no runtime of its own."""
+    params = dict(_FEED_BASE, channel_ids=[channel_id], scope="all", library_source="all")
+    query, _ = filtered_query(db, user, **params)
+    return int(db.execute(select(func.count()).select_from(query.subquery())).scalar() or 0)
+
+
+def playlist_summary(db: Session, user: User, playlist_id: int) -> tuple[int, dict | None]:
+    """(item count, the row to play next) for a pinned playlist — its first not-yet-watched item, or
+    its first item once the whole list is watched. The same row doubles as the tile's artwork, so a
+    shelf of playlists is scannable instead of a row of blank boxes."""
+    st = aliased(VideoState)
+    rows = db.execute(
+        select(*feed_columns(user, st), PlaylistItem.position)
+        .join(PlaylistItem, PlaylistItem.video_id == Video.id)
+        .join(Channel, Channel.id == Video.channel_id)
+        .outerjoin(st, and_(st.video_id == Video.id, st.user_id == user.id))
+        .where(PlaylistItem.playlist_id == playlist_id)
+        .order_by(PlaylistItem.position.asc())
+    ).all()
+    if not rows:
+        return 0, None
+    nxt = next((r for r in rows if (r.status or "new") not in ("watched", "hidden")), rows[0])
+    return len(rows), serialize(nxt)
+
+
+# ── Plex ──────────────────────────────────────────────────────────────────────────────────────────
+
+
+def _unseen_movie_conds(uid: int):
+    """A movie the user has neither finished nor hidden. A LEFT-JOIN-IS-NULL would also drop rows that
+    merely carry a resume position, which are exactly the ones Continue watching wants back."""
+    seen = (
+        select(1)
+        .select_from(PlexState)
+        .where(
+            PlexState.item_id == PlexItem.id,
+            PlexState.user_id == uid,
+            or_(
+                PlexState.status.in_(("watched", "hidden")),
+                # Started counts as "not a surprise" too — see the note in `yt_surprise`.
+                PlexState.position_seconds > 0,
+            ),
+        )
+        .exists()
+    )
+    return ~seen
+
+
+def plex_in_progress(db: Session, uid: int, limit: int = RAIL_LIMIT) -> list[tuple[object, dict]]:
+    """In-progress movies + partially-watched shows as (progressed_at, card).
+
+    Mirrors `routes/plex/discover.py::_continue_watching` — same `PlexState` predicate for movies (a
+    NULL status still counts as started, so `notin_` alone would drop it), and the same shared
+    `rollup.agg_subquery` + `apply_show_state_filter` for shows, so the two rails cannot disagree on
+    what "in progress" means. What it does NOT inherit is that route's `LibraryFilters` narrowing:
+    this surface has no Plex sidebar to read a filter from."""
+    movie_libs, show_libs = content_libs(db)
+    out: list[tuple[object, dict]] = []
+
+    if movie_libs:
+        mq = (
+            select(PlexItem, PlexState)
+            .join(PlexState, and_(PlexState.item_id == PlexItem.id, PlexState.user_id == uid))
+            .where(
+                PlexItem.kind == "movie",
+                PlexItem.library_id.in_(movie_libs),
+                PlexState.position_seconds > 0,
+                or_(
+                    PlexState.status.is_(None),
+                    PlexState.status.notin_(("watched", "hidden")),
+                ),
+            )
+            .order_by(PlexState.progress_updated_at.desc().nullslast())
+            .limit(limit)
+        )
+        for it, st in db.execute(mq).all():
+            out.append((st.progress_updated_at, movie_card(it, st)))
+
+    if show_libs:
+        prog = rollup.agg_subquery(db, uid, include_resumed=True).subquery()
+        sq = apply_show_state_filter(
+            select(PlexShow, prog.c.resumed_at).join(prog, prog.c.show_id == PlexShow.id),
+            prog.c.total,
+            prog.c.watched,
+            prog.c.inprog,
+            "in_progress",
+        ).where(PlexShow.library_id.in_(show_libs))
+        for sh, resumed_at in db.execute(
+            sq.order_by(prog.c.resumed_at.desc().nullslast()).limit(limit)
+        ).all():
+            out.append((resumed_at, show_card(sh, "in_progress")))
+
+    return out
+
+
+def plex_surprise(db: Session, uid: int, budget: str, seed: int, limit: int) -> list[dict]:
+    """Unseen playable movies inside the budget, in seeded-shuffle order.
+
+    Movies only. A show is not a thing you can start playing, and resolving every candidate show to
+    its next episode just to draw three cards would be a query per row for a rail whose whole value is
+    that it answers instantly — shows reach this surface through Continue watching and the comfort
+    shelf, which is where "put the next episode on" actually belongs.
+
+    No `playable` filter, matching the Plex surprise rail: `PlexItem.playable` is a playback CLASS
+    ("direct" / "remux" / "transcode"), not a yes/no, and NULL there means "not probed yet" rather than
+    "will not play". Excluding un-probed items would quietly hide a fresh library from the one surface
+    that is supposed to have an answer. The class travels on the card, so the client still shows it."""
+    movie_libs, _ = content_libs(db)
+    if not movie_libs:
+        return []
+    lo, hi = band(budget)
+    q = (
+        select(PlexItem)
+        .where(
+            PlexItem.kind == "movie",
+            PlexItem.library_id.in_(movie_libs),
+            _unseen_movie_conds(uid),
+        )
+        .order_by(_seeded(PlexItem.rating_key, seed))
+        .limit(limit)
+    )
+    if lo is not None:
+        q = q.where(PlexItem.duration_s >= lo)
+    if hi is not None:
+        q = q.where(PlexItem.duration_s <= hi)
+    items = db.execute(q).scalars().all()
+    states = rollup.item_state_map(db, uid, [it.id for it in items])
+    return [movie_card(it, states.get(it.id)) for it in items]
+
+
+# Watch states that take an episode out of the running for "what would play next".
+_DONE = ("watched", "hidden")
+
+
+def next_episode(db: Session, uid: int, show_id: int) -> dict | None:
+    """What "put that show on" means: the episode in progress, else the first unwatched one, else the
+    first — over the same `(season, episode)` broadcast ordering `detail.py::_episode_nav` uses.
+
+    Three ordered `LIMIT 1` probes rather than one scan picked apart in Python. The Python version
+    loaded EVERY episode of the show to choose one of them — 236 rows for Friends, 227 for JAG — which
+    the comfort shelf could just about afford (a handful of hand-picked pins) and the resume rail
+    could not, since it resolves a show per rail row on the landing page.
+
+    Returned as a `leaf_card` so it carries the show title the episode row itself does not."""
+    asc = (
+        PlexItem.season_number.asc().nullsfirst(),
+        PlexItem.episode_number.asc().nullsfirst(),
+    )
+    base = (
+        select(PlexItem, PlexState)
+        .outerjoin(PlexState, and_(PlexState.item_id == PlexItem.id, PlexState.user_id == uid))
+        .where(PlexItem.show_id == show_id, PlexItem.kind == "episode")
+        .limit(1)
+    )
+    # In progress — the LAST one in broadcast order, which is `plex.rollup.rollup`'s `inprog[-1]`,
+    # i.e. what the show page's own Resume button plays. Two episodes of one show are in progress at
+    # once more often than it sounds (`watch_sync._reconcile_inprogress_movies` documents that a
+    # scrub to the end leaves a stale `status='new', position>0` row until the daily reconcile), and
+    # taking opposite ends of that set is how one show came to have two different "continue" answers:
+    # the Home tile ranked it by its LATEST touch and then offered the EARLIEST started episode.
+    # `position_seconds > 0` already requires the state row to exist, so no null guard.
+    pick = db.execute(
+        base.where(PlexState.position_seconds > 0, PlexState.status.notin_(_DONE)).order_by(
+            PlexItem.season_number.desc().nullslast(),
+            PlexItem.episode_number.desc().nullslast(),
+        )
+    ).first()
+    # Unwatched — INCLUDING an episode with no state row at all, which is the common case and the one
+    # a bare `status NOT IN (...)` silently drops (NULL is not false, it is unknown, so the row fails
+    # the filter).
+    pick = (
+        pick
+        or db.execute(
+            base.where(or_(PlexState.id.is_(None), PlexState.status.notin_(_DONE))).order_by(*asc)
+        ).first()
+    )
+    # Fully watched show: start it again from the top.
+    pick = pick or db.execute(base.order_by(*asc)).first()
+    if pick is None:
+        return None
+
+    ep, st = pick
+    show = db.get(PlexShow, show_id)
+    return leaf_card(
+        ep, st, show_title=show.title if show else None, show_rk=show.rating_key if show else None
+    )

backend/app/discover/rails.py

@@ -0,0 +1,97 @@
+"""The Home surface's rails: cross-source lists, assembled from `queries.py` and emitted as unified
+cards.
+
+The whole point of this module is that a rail is ONE list, not a YouTube list beside a Plex list. Two
+side-by-side rails would just move the choice the user could not make ("which half do I look at?") one
+level up, which is the opposite of what this epic is for.
+"""
+
+from sqlalchemy.orm import Session
+
+from app import sysconfig
+from app.discover import cards, queries
+from app.discover.queries import RAIL_LIMIT
+from app.models import PlexShow, User
+from app.plex.lookups import by_rating_key
+from app.plex.rollup import NO_TS
+
+
+def plex_available(db: Session) -> bool:
+    """Plex is a deployment-level toggle, not a per-user one (see `routes/me.py`). With it off, the
+    Home rails are YouTube-only and say nothing about Plex."""
+    return sysconfig.get_bool(db, "plex_enabled")
+
+
+def playable(db: Session, uid: int, card: dict) -> dict | None:
+    """The thing that would actually START from this card — itself for anything with a runtime, and
+    for a Plex SHOW the episode that is next (in progress, else the first unwatched, else the first).
+
+    ONE function, because three surfaces need the same answer and a second implementation is how the
+    shelf and the rail came to disagree in the first place: the hero calls it to decide what it is
+    offering, `continue_watching` calls it to fill each show tile's `next`, and the comfort shelf
+    resolves the same way in `pins`. None when the show has no episodes mirrored yet.
+
+    A card that already carries a resolved `next` (a rail row) is taken at its word rather than
+    re-queried — the hero reads the rail it was handed."""
+    if not (card.get("source") == "plex" and card.get("kind") == "show"):
+        return card
+    if "next" in card:
+        return card["next"]
+    sh = by_rating_key(db, PlexShow, card["id"])
+    if sh is None:
+        return None
+    ep = queries.next_episode(db, uid, sh.id)
+    return cards.from_plex(ep) if ep else None
+
+
+def continue_watching(db: Session, user: User, limit: int = RAIL_LIMIT) -> list[dict]:
+    """One resume rail across both sources, most recently progressed first.
+
+    A Plex SHOW enters as a show CARD — that is what the Plex rail shows, and it is the artwork the
+    user recognises — but it carries `next`: the episode that would actually start. Without it a
+    click on a half-watched series landed on the show page with six seasons to choose between, which
+    is the decision this whole surface exists to remove (the comfort shelf and the hero already
+    resolved; only this rail did not). The client plays `next ?? card`, so the tile stays a poster and
+    the click stays one click."""
+    rows: list[tuple[object, dict]] = [
+        (ts, cards.from_video(r)) for ts, r in queries.yt_in_progress(db, user, limit)
+    ]
+    if plex_available(db):
+        rows += [(ts, cards.from_plex(c)) for ts, c in queries.plex_in_progress(db, user.id, limit)]
+    rows.sort(key=lambda r: r[0] or NO_TS, reverse=True)
+    out = [card for _, card in rows[:limit]]
+    # Resolve AFTER the slice: only the rows that survive it are worth a query.
+    for card in out:
+        if card["kind"] == "show":
+            card["next"] = playable(db, user.id, card)
+    return out
+
+
+def surprise(db: Session, user: User, budget: str, seed: int, limit: int = 3) -> list[dict]:
+    """The hero's draw pool: unseen things that fit the budget, from both sources under ONE seed.
+
+    Interleaved rather than concatenated — the same alternation `routes/plex/discover.py` uses for its
+    movie/show split — so a short pool never comes back all-YouTube or all-Plex just because one side
+    happened to be queried first.
+
+    WHICH source leads is decided by the seed, not by a hardcoded order. The hero draws a pool of ONE,
+    so a fixed order would mean the Plex library could never answer "egy este" while a single YouTube
+    video also fit — the reroll would look broken and the cross-source promise would quietly be a
+    YouTube promise. Parity on the same seed that orders the rows keeps it deterministic: the same
+    seed always gives the same answer, and pressing "Mást kérek" moves both halves together."""
+    halves = [
+        (cards.from_video, queries.yt_surprise(db, user, budget, seed, limit)),
+        (
+            cards.from_plex,
+            queries.plex_surprise(db, user.id, budget, seed, limit) if plex_available(db) else [],
+        ),
+    ]
+    if seed % 2:
+        halves.reverse()
+
+    out: list[dict] = []
+    for i in range(max(len(rows) for _, rows in halves)):
+        for to_card, rows in halves:
+            if i < len(rows):
+                out.append(to_card(rows[i]))
+    return out[:limit]

backend/app/feedquery.py

@@ -117,6 +117,19 @@ def tags_by_category(db: Session, tag_ids: list[int]) -> dict[str, list[int]]:
     return out
 
 
+def not_blocked_cond(user: User):
+    """Per-user channel blocklist: never show this user videos from a channel they blocked
+    (applies to feed, Library, explore, the channel page and the Home resume rail alike).
+
+    A shared expression rather than a clause each surface writes for itself. Blocking does not touch
+    `video_states`, so a half-watched video from a newly blocked channel survives with its resume
+    position — and the one query that copied only PART of this predicate set is exactly how that
+    video came back as the landing page's suggestion after the user had said "never again"."""
+    return Video.channel_id.notin_(
+        select(BlockedChannel.channel_id).where(BlockedChannel.user_id == user.id)
+    )
+
+
 def filtered_query(
     db: Session,
     user: User,
@@ -207,13 +220,7 @@ def filtered_query(
         )
     )
 
-    # Per-user channel blocklist: never show this user videos from a channel they blocked
-    # (applies to feed, Library, explore, and the channel page alike).
-    query = query.where(
-        Video.channel_id.notin_(
-            select(BlockedChannel.channel_id).where(BlockedChannel.user_id == user.id)
-        )
-    )
+    query = query.where(not_blocked_cond(user))
 
     # Source filter. In the shared Library ("all" scope) it uses the GLOBAL via_search flag
     # (search-discovered by anyone). In "my" scope it's the user's OWN provenance:

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
@@ -21,18 +24,21 @@ 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
 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,
     auth as auth_routes,
     channels,
     config as config_routes,
+    discover as discover_routes,
     downloads,
     feed,
     health,
@@ -76,6 +82,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
@@ -85,10 +92,36 @@ 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.
+
+    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_idle)
+        except Exception:
+            log.exception("HLS session reap failed")
 
 
 async def _sweep_hls_orphans() -> None:
@@ -107,6 +140,34 @@ 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.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,
@@ -187,6 +248,7 @@ app.include_router(auth_routes.router)
 app.include_router(sync.router)
 app.include_router(tags.router)
 app.include_router(feed.router)
+app.include_router(discover_routes.router)
 app.include_router(search_routes.router)
 app.include_router(me.router)
 app.include_router(notifications.router)

backend/app/models.py

@@ -3,6 +3,7 @@ from datetime import date, datetime
 from sqlalchemy import (
     BigInteger,
     Boolean,
+    CheckConstraint,
     Computed,
     Date,
     DateTime,
@@ -23,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."""
@@ -422,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
     )
@@ -1406,3 +1413,52 @@ class PlexPlaylistItem(Base):
         ForeignKey("plex_items.id", ondelete="CASCADE"), index=True
     )
     position: Mapped[int] = mapped_column(Integer, default=0, server_default="0", nullable=False)
+
+
+class ComfortPin(Base, TimestampMixin):
+    """One entry on a user's comfort shelf — the anti-paralysis fallback: "just put on X" (E24).
+
+    Deliberately NOT a boolean on `VideoState`/`PlexState`, and NOT a polymorphic `(kind, ref)` string
+    pair. A flag cannot ORDER a shelf and cannot hold a channel or a show — and comfort media is
+    usually "put on X", a series or a channel, not one particular video. A string ref would order and
+    hold anything, but it would also lose the foreign key: a Plex item dropped from the library, or an
+    unsubscribed channel, would leave a dead tile on the one surface whose whole job is to be
+    reliable. So instead: one nullable CASCADE-ing FK per pinnable kind, and a check constraint that
+    exactly one of them is set.
+
+    That constraint is the house rule applied to a five-way union — the invariant lives in the schema,
+    not in a comment every insert site has to remember. `kind`/`ref` below derive FROM the columns, so
+    there is no second vocabulary to keep in sync.
+
+    NULLs are DISTINCT in a Postgres unique index, so the five per-kind unique constraints each stop a
+    double-pin of the same thing without colliding across kinds."""
+
+    __tablename__ = "comfort_pins"
+    __table_args__ = (
+        CheckConstraint(
+            "num_nonnulls(video_id, channel_id, plex_item_id, plex_show_id, playlist_id) = 1",
+            name="ck_comfort_pin_one_ref",
+        ),
+        UniqueConstraint("user_id", "video_id", name="uq_comfort_pin_video"),
+        UniqueConstraint("user_id", "channel_id", name="uq_comfort_pin_channel"),
+        UniqueConstraint("user_id", "plex_item_id", name="uq_comfort_pin_plex_item"),
+        UniqueConstraint("user_id", "plex_show_id", name="uq_comfort_pin_plex_show"),
+        UniqueConstraint("user_id", "playlist_id", name="uq_comfort_pin_playlist"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    user_id: Mapped[int] = mapped_column(ForeignKey("users.id", ondelete="CASCADE"), index=True)
+
+    video_id: Mapped[str | None] = mapped_column(ForeignKey("videos.id", ondelete="CASCADE"))
+    channel_id: Mapped[str | None] = mapped_column(ForeignKey("channels.id", ondelete="CASCADE"))
+    plex_item_id: Mapped[int | None] = mapped_column(
+        ForeignKey("plex_items.id", ondelete="CASCADE")
+    )
+    plex_show_id: Mapped[int | None] = mapped_column(
+        ForeignKey("plex_shows.id", ondelete="CASCADE")
+    )
+    playlist_id: Mapped[int | None] = mapped_column(ForeignKey("playlists.id", ondelete="CASCADE"))
+
+    # 0-based shelf order. The shelf is short and hand-curated, so a dense integer the reorder
+    # endpoint rewrites wholesale beats a fractional index nobody would ever exercise here.
+    position: Mapped[int] = mapped_column(Integer, default=0, server_default="0", nullable=False)

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}"

backend/app/plex/lookups.py

@@ -11,5 +11,11 @@ _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 — 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()

backend/app/plex/query.py

@@ -8,11 +8,28 @@ from datetime import datetime, timedelta, timezone
 
 from sqlalchemy import and_, case, func, or_, select, type_coerce
 from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Session
 
-from app.models import PlexItem
+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
@@ -342,3 +359,26 @@ def apply_show_state_filter(query, tot, wat, inp, show: str):
     if show == "unwatched":
         return query.where(wat == 0, inp == 0)
     return query
+
+
+def content_libs(db: Session) -> tuple[list[int], list[int]]:
+    """The BROWSABLE content libraries, partitioned into (movie_lib_ids, show_lib_ids) — the single
+    source of the browse scope. Excludes HU overlay libraries (`overlay_of` set): those are never
+    browsed on their own, they only lend their Hungarian metadata to the EN twin's rows (E5 S5).
+
+    Lives here, in the query layer, rather than in `routes/plex/_shared.py` where it started: E24's
+    Home surface needs the same scope, and a domain package importing from `routes/` would invert the
+    one-way dependency CLAUDE.md draws. It never touched request state, so nothing was lost by the
+    move."""
+    libs = (
+        db.execute(
+            select(PlexLibrary).where(
+                PlexLibrary.enabled.is_(True), PlexLibrary.overlay_of.is_(None)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    movie_lib_ids = [lb.id for lb in libs if lb.kind == "movie"]
+    show_lib_ids = [lb.id for lb in libs if lb.kind == "show"]
+    return movie_lib_ids, show_lib_ids

backend/app/plex/rollup.py

@@ -3,11 +3,25 @@
 Drives the show/season grid badges and the Resume / Play-from-start / mark-all buttons.
 """
 
+from datetime import datetime, timezone
+
 from sqlalchemy import and_, case, func, or_, select
 from sqlalchemy.orm import Session, aliased
 
 from app.models import PlexItem, PlexState
 
+# Sort sentinel for a rail row whose timestamp is missing, so `key=lambda r: r[0] or NO_TS` reads the
+# same at every rail that merges two type-homogeneous lists in Python.
+#
+# It is NOT a crash fix, whatever the E24 commit that introduced it says. The `(ts is not None, ts)`
+# key it replaced cannot raise: tuple comparison finds the first UNEQUAL element via `==`, so two
+# `(False, None)` keys compare equal and `None < None` is never reached — verified by execution
+# during the E24 epic-end review, over every permutation of null/non-null rows. What the sentinel
+# buys is one idiom instead of two, and a key that says "missing sorts last" outright rather than
+# encoding it in a boolean flag. A BARE `r[0]` would genuinely raise, which is the mutation the
+# rails' tests do guard against.
+NO_TS = datetime.min.replace(tzinfo=timezone.utc)
+
 
 def show_status(total: int, watched: int, inprog: int) -> str:
     """Roll a show's episodes up into a single watch state: fully watched, partially started, or new."""

backend/app/plex/stream.py

@@ -21,10 +21,12 @@ 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
 import time
+from collections.abc import Sequence
 from pathlib import Path
 
 from sqlalchemy.orm import Session as DbSession
@@ -55,6 +57,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
@@ -94,11 +100,19 @@ class HlsSession:
         directory: Path,
         proc: subprocess.Popen,
         start_s: float,
-        entry: str,
+        variants: "Sequence[str]",
         transcode: bool = False,
         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
@@ -113,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()
 
 
@@ -271,6 +291,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 +490,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
@@ -469,11 +514,15 @@ 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,
+        # …). 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}?"]
-        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}"
@@ -482,23 +531,25 @@ 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
         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"),
-            str(out_dir / "index.m3u8"),
+            str(out_dir / segment_name("%d")),
+            str(out_dir / _INDEX_PL),
         ]
     return args
 
@@ -579,16 +630,26 @@ 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)
+    # 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
+    # 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:
-        # 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, _VIDEO_VARIANT if variants else None)
 
     def _spawn(
         hw: bool, tonemap: bool = False, *, replace_only: "HlsSession | None" = None
@@ -632,6 +693,7 @@ def start_session(
                     preset=preset,
                     crf=crf,
                     max_height=max_height,
+                    loudnorm=loudnorm,
                 ),
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
@@ -642,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,
@@ -714,6 +776,101 @@ def current_session(key: str) -> HlsSession | None:
         return s
 
 
+# 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 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$")
+
+
+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 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
+    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.
+
+    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 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
+    try:
+        return (s.dir / segment_name(seq - 1, variant)).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
@@ -785,14 +942,47 @@ 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 said they still want for `_SESSION_IDLE_S` — or, once their ffmpeg
+    has finished, for `finished_idle_s`.
+
+    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. 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: 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()
     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 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()

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 = {
@@ -31,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]
@@ -39,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}"
 
 
@@ -109,7 +150,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"
@@ -125,11 +166,686 @@ 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:
+        return False
+
+
+# --- 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 _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:
+    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, ValueError):  # ValueError: a NUL in the key — `stat` refuses the path outright
+        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 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 ""):
+            canon = _canonical_cue(block.strip())
+            if canon is None:
+                continue  # header / NOTE / STYLE — the merged file gets its own single header
+            start, key, text = canon
+            if key in seen:
+                continue
+            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) -> 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
+    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)
+        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 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
+            # 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)):
+            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 ----------------------------------------------------------------------
+
+# 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
+# …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.
+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
+# 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()
+# 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`), 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):
+    """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,
+}
+# 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:
+    """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:
+    """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 — 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)
+    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())
+
+
+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 _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:
+        _sweep_memos()
+        _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.
+
+    ``ready`` = fully extracted · ``partial`` = usable, covers ``at``, still growing · ``preparing``
+    = 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": 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 {
+            "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": "unavailable", "code": "extract_failed", "gen": gen}
+    if not code:
+        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]:
+    """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, 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. A 1 s status poll (or a second viewer) joins a job already
+    queued or running instead of starting another ffmpeg.
+
+    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]] = []
+    with _LOCK:
+        if _STOPPING:
+            return
+        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()
+                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 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 = _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:
+    """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 _exists(_vtt_path(key)):
+        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:
+    key = cache_key(rating_key, sub_ord)
+    try:
+        if _STOPPING or _already_done(key, window_start, at):
+            return
+        _extract_and_publish(rating_key, sub_ord, window_start)
+    except SubtitleUnavailable as e:
+        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(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)
+        _pass_failed(rating_key, [key], window_start)
+    finally:
+        with _LOCK:
+            _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:
+            _sweep_memos()
+            _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]]:
+    """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"):
+            # 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)
+            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")
+        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
+    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)
+        landed = publish(
+            key,
+            shift_vtt(vtt, -start),  # zero-based window clock → absolute cue times
+            (start, covered_end),
+            clean and length is None,
+        )
+        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))
+
+
+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
+) -> 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 {}, True
+    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}"]
+                # 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 — 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()
+        timed_out = False
+        try:
+            try:
+                _, err = proc.communicate(timeout=EXTRACT_TIMEOUT_S)
+            except subprocess.TimeoutExpired:
+                # 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)
+        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")
+    clean = proc.returncode == 0 and not timed_out
+    if not clean:
+        log.warning(
+            "ffmpeg subtitle pass %s: %s",
+            "timed out" if timed_out else f"exited {proc.returncode}",
+            (err or b"")[:200],
+        )
+    return got, clean

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

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,

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(

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, 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
@@ -663,8 +655,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.
@@ -706,7 +697,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,

backend/app/routes/discover.py

@@ -0,0 +1,197 @@
+"""E24 · the Home surface's HTTP shell.
+
+Thin by construction: every decision — what counts as in progress, what fits a time budget, which
+tier the hero comes from — lives in `app/discover/`, so the scheduler, a future CLI or a test can ask
+the same questions without a request. This file validates, gates and serializes.
+
+The consolidated `GET /api/discover` mirrors the Plex Discover route's one-payload shape (E5 S4): a
+landing page that fires four requests to answer one question would spend its whole budget on the
+thing it exists to remove.
+"""
+
+from typing import Literal
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app.auth import current_user, require_human
+from app.db import get_db
+from app.discover import hero as hero_mod
+from app.discover import pins, rails
+from app.discover.budget import Budget, DEFAULT_BUDGET
+from app.models import ComfortPin, User
+from app.routes._common import owned_or_404
+
+router = APIRouter(prefix="/api/discover", tags=["discover"])
+
+
+class PinIn(BaseModel):
+    # From `pins.PIN_KINDS`, not a second hand-written list: the vocabulary, the schema columns and
+    # this request contract have to move together, and re-typing them here is how they would not.
+    kind: Literal[*pins.PIN_KINDS]
+    # The id the rest of the API speaks for that kind: a video id, a channel id, a Plex rating_key,
+    # or a playlist id. `pins.resolve_ref` does the translation to the row's internal key.
+    ref: str
+
+
+class ReorderIn(BaseModel):
+    ids: list[int]
+
+
+@router.get("")
+def get_discover(
+    budget: Budget = DEFAULT_BUDGET,
+    seed: int = 0,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Everything the Home page renders, in one pass.
+
+    `resume` and `shelf` are built once and handed to the hero, so the two rails the hero draws from
+    are not queried twice for a single page load."""
+    resume = rails.continue_watching(db, user)
+    shelf = pins.shelf(db, user)
+    return {
+        "budget": budget,
+        "hero": hero_mod.pick(db, user, budget, seed, resume=resume, shelf=shelf),
+        "continue_watching": resume,
+        "comfort": shelf,
+    }
+
+
+# How many already-shown cards a reroll may carry, matched to the client's own rolling window
+# (`SEEN_WINDOW` in `Home.tsx`). A cheap sanity clamp, and deliberately no more than that: `exclude`
+# never reaches SQL — `hero.pick` uses it only as set membership over an already-bounded candidate
+# pool (the resume rail's `RAIL_LIMIT` rows, the shelf, `SURPRISE_DRAW` surprise draws) — so there is
+# no scan for a crafted URL to unbound, and the set is built in full before this slice anyway. The
+# comment that claimed otherwise was corrected in round 2; the request line's own length is what
+# actually bounds a hostile `exclude`.
+MAX_EXCLUDE = 32
+
+
+@router.get("/pick")
+def get_pick(
+    budget: Budget = DEFAULT_BUDGET,
+    seed: int = 0,
+    exclude: str = "",
+    start: int = 0,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The "Mást kérek" reroll: a hero on its own, for a new seed and/or a new budget.
+
+    One seed drives BOTH sources (see `discover/queries.py`) — otherwise a reroll would re-draw the
+    Plex half while the YouTube half stood still, and the button would look broken half the time.
+
+    `exclude` is a comma-separated list of `<source>:<id>` keys the user has already been shown. It
+    is what makes the button honest: a seed alone only moves the surprise tier, so a user with
+    something half-finished got the same card back every press.
+
+    `start` is the press count: it rotates which tier answers first, so consecutive presses offer a
+    different KIND of answer instead of walking down the resume rail. Taken modulo the tier count in
+    `hero.pick`, so any integer is valid and no value can 422 a button."""
+    skip = {p for p in exclude.split(",") if p}
+    return {
+        "budget": budget,
+        "hero": hero_mod.pick(
+            db, user, budget, seed, exclude=set(list(skip)[:MAX_EXCLUDE]), start=start
+        ),
+    }
+
+
+@router.get("/pins")
+def list_pins(
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The shelf on its own — for the shelf editor, which needs it without the rest of the page."""
+    return {"items": pins.shelf(db, user)}
+
+
+@router.post("/pins")
+def add_pin(
+    body: PinIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Pin something to the comfort shelf.
+
+    `require_human`, like every other personal-state write: the shared demo account must not be able
+    to curate a communal shelf. Re-pinning something already on the shelf is a no-op that returns the
+    existing pin rather than a 409 — the gesture is "make sure this is on my shelf", and the unique
+    constraint is the mechanism, not the message."""
+    resolved = pins.resolve_ref(db, user, body.kind, body.ref)
+    if resolved is None:
+        raise HTTPException(status_code=404, detail="Unknown item")
+    column, value = resolved
+
+    existing = db.execute(
+        select(ComfortPin).where(
+            ComfortPin.user_id == user.id,
+            getattr(ComfortPin, column) == value,
+        )
+    ).scalar_one_or_none()
+    if existing is not None:
+        return {"ok": True, "id": existing.id, "created": False}
+
+    pin = ComfortPin(user_id=user.id, position=pins.next_position(db, user), **{column: value})
+    db.add(pin)
+    try:
+        db.commit()
+    except IntegrityError:
+        # A concurrent pin of the same thing from a second tab. The unique constraint did its job;
+        # the user's intent ("be on my shelf") is satisfied either way, so report the winner rather
+        # than a 500 the user can do nothing with.
+        db.rollback()
+        winner = db.execute(
+            select(ComfortPin).where(
+                ComfortPin.user_id == user.id,
+                getattr(ComfortPin, column) == value,
+            )
+        ).scalar_one_or_none()
+        if winner is None:
+            # Not the unique constraint, then: the only other way in is the target row being pruned
+            # between `resolve_ref` confirming it and this INSERT (a Plex sync dropping a removed
+            # item), which trips the FK. Semantically that is the same "no such thing" the pre-check
+            # returns above — re-raising handed the user a 500 they could do nothing with.
+            raise HTTPException(status_code=404, detail="Unknown item")
+        return {"ok": True, "id": winner.id, "created": False}
+    return {"ok": True, "id": pin.id, "created": True}
+
+
+@router.delete("/pins/{pin_id}")
+def remove_pin(
+    pin_id: int,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    pin = owned_or_404(db, ComfortPin, pin_id, user, what="pin")
+    db.delete(pin)
+    db.commit()
+    return {"deleted": pin_id}
+
+
+@router.post("/pins/reorder")
+def reorder_pins(
+    body: ReorderIn,
+    user: User = Depends(require_human),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Rewrite the shelf order from a full list of pin ids.
+
+    Whole-list rather than a move-one delta: the shelf is short, and a full rewrite cannot leave two
+    tiles claiming the same slot the way an interrupted sequence of single moves can. Ids that are not
+    this user's are ignored rather than 404'd — a stale tab replaying an order that includes a pin
+    deleted meanwhile should reorder what still exists, not fail wholesale."""
+    owned = {p.id for p in pins.list_pins(db, user)}
+    for position, pin_id in enumerate(i for i in body.ids if i in owned):
+        db.execute(
+            update(ComfortPin)
+            .where(ComfortPin.id == pin_id, ComfortPin.user_id == user.id)
+            .values(position=position)
+        )
+    db.commit()
+    return {"ok": True}

backend/app/routes/downloads.py

@@ -38,6 +38,7 @@ from app.models import (
     MediaAsset,
     User,
 )
+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
@@ -801,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(
@@ -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:

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, Field
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
@@ -22,12 +22,14 @@ from app.feedquery import (
     sort_keys,
 )
 from app.models import (
+    POSITION_MAX_S,
     ChannelTag,
     Tag,
     User,
     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
@@ -234,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)
 
@@ -303,11 +304,16 @@ 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.
-    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")
@@ -326,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

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,

backend/app/routes/playlists.py

@@ -3,6 +3,8 @@ CRUD (create / rename / delete, add / remove / reorder items) plus YouTube two-w
 mirror the user's own YouTube playlists in (`/sync-youtube`) and push/revert local edits back
 out (`/{id}/push-plan`, `/{id}/revert-youtube`), behind the optional write scope."""
 
+from datetime import datetime, timezone
+
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
 from sqlalchemy import func, select, and_
@@ -21,6 +23,7 @@ from app.sync.playlists import (
     sync_user_playlists,
 )
 from app.ratelimit import RateLimiter
+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"])
@@ -46,10 +49,23 @@ 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")
-    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:
+    """Bump the playlist's `updated_at` for an edit that only writes `playlist_items`.
+
+    `UpdatedAtMixin`'s `onupdate` fires on an UPDATE of the PLAYLIST row, and add / remove /
+    reorder / move write the item rows instead — so without this the rail's "recently changed"
+    sort would only ever see renames. The assignment is what makes the column mean "last time
+    this list changed", which is what the rail promises the reader."""
+    pl.updated_at = datetime.now(timezone.utc)
 
 
 def _next_playlist_position(db: Session, user_id: int) -> int:
@@ -91,6 +107,7 @@ def _add_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) ->
     )
     if mark_dirty:
         recompute_dirty(db, pl)
+    _touch(pl)
     db.commit()
     return True
 
@@ -108,6 +125,7 @@ def _remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool)
     db.delete(item)
     if mark_dirty:
         recompute_dirty(db, pl)
+    _touch(pl)
     db.commit()
     return True
 
@@ -129,6 +147,9 @@ def _summary(
         "item_count": count,
         "total_duration_seconds": total_duration,
         "cover_thumbnail": cover,
+        # When this list last CHANGED (rename, add/remove/move/reorder) — the rail's
+        # "recently changed first" sort reads it. See _touch for why it isn't automatic.
+        "updated_at": pl.updated_at,
     }
     if has_video is not None:
         out["has_video"] = has_video
@@ -239,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()
@@ -271,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 HTTPException(status_code=404, detail="Unknown 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}
@@ -300,10 +320,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)
@@ -320,18 +337,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:
@@ -339,9 +354,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
 
 
@@ -359,7 +372,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
@@ -389,14 +402,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}")
@@ -441,7 +451,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)
@@ -476,18 +486,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}
@@ -502,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 HTTPException(status_code=404, detail="Unknown 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}
 
@@ -520,6 +529,65 @@ def remove_item(
     return {"playlist_id": pl.id, "video_id": video_id}
 
 
+class MoveItemIn(BaseModel):
+    target_playlist_id: int
+
+
+@router.post("/{playlist_id}/items/{video_id}/move")
+def move_item(
+    playlist_id: int,
+    video_id: str,
+    body: MoveItemIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Move one video from a playlist into another of the caller's playlists, atomically.
+
+    ONE transaction on purpose. The obvious client-side shape — add to the target, then remove
+    from the source — leaves the video in BOTH lists whenever the second call fails, which is
+    exactly the kind of half-applied state this codebase treats as a bug rather than an edge
+    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)
+    # 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"}
+        )
+    item = db.scalar(
+        select(PlaylistItem).where(
+            PlaylistItem.playlist_id == src.id, PlaylistItem.video_id == video_id
+        )
+    )
+    if item is None:
+        # A concurrent edit (another tab, or a YouTube re-pull) already took it out.
+        raise HTTPException(
+            status_code=404, detail={"code": "playlist_move", "reason": "not_in_playlist"}
+        )
+    already = db.scalar(
+        select(PlaylistItem).where(
+            PlaylistItem.playlist_id == dst.id, PlaylistItem.video_id == video_id
+        )
+    )
+    if already is not None:
+        db.delete(item)  # the uq_playlist_video constraint would reject a second row anyway
+    else:
+        # Re-parent the existing row rather than delete+insert: `added_at` ("when I saved this")
+        # survives the move, and there is no window where the video belongs to neither list.
+        item.playlist_id = dst.id
+        item.position = _next_item_position(db, dst.id)
+    # Both sides changed, so both get the dirty recompute and the timestamp — the asymmetric
+    # version of this (touching only the source) is the recurring smell CLAUDE.md warns about.
+    recompute_dirty(db, src)
+    recompute_dirty(db, dst)
+    _touch(src)
+    _touch(dst)
+    db.commit()
+    return {"ok": True, "from_playlist_id": src.id, "to_playlist_id": dst.id, "video_id": video_id}
+
+
 class ReorderItemsIn(BaseModel):
     video_ids: list[str] = []
 
@@ -555,5 +623,6 @@ def reorder_items(
         it.position = pos
         pos += 1
     recompute_dirty(db, pl)
+    _touch(pl)
     db.commit()
     return {"playlist_id": pl.id, "count": pos}

backend/app/routes/plex/_shared.py

@@ -3,13 +3,9 @@
 import logging
 
 from fastapi import HTTPException
-from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app.models import (
-    PlexItem,
-    PlexLibrary,
-)
+from app.models import PlexItem
 from app.plex.lookups import by_rating_key
 
 log = logging.getLogger("siftlode.plex")
@@ -25,21 +21,3 @@ def item_or_404(db: Session, rating_key: str) -> PlexItem:
 def _norm_lang(lang: str | None) -> str:
     """The overlay has an EN base + an optional HU twin; anything other than `hu` serves EN."""
     return "hu" if lang == "hu" else "en"
-
-
-def _content_libs(db: Session) -> tuple[list[int], list[int]]:
-    """The BROWSABLE content libraries, partitioned into (movie_lib_ids, show_lib_ids) — the single
-    source of the browse scope. Excludes HU overlay libraries (`overlay_of` set): those are never
-    browsed on their own, they only lend their Hungarian metadata to the EN twin's rows (E5 S5)."""
-    libs = (
-        db.execute(
-            select(PlexLibrary).where(
-                PlexLibrary.enabled.is_(True), PlexLibrary.overlay_of.is_(None)
-            )
-        )
-        .scalars()
-        .all()
-    )
-    movie_lib_ids = [lb.id for lb in libs if lb.kind == "movie"]
-    show_lib_ids = [lb.id for lb in libs if lb.kind == "show"]
-    return movie_lib_ids, show_lib_ids

backend/app/routes/plex/browse.py

@@ -34,6 +34,7 @@ from app.plex.query import (
     apply_meta_filters,
     apply_movie_state_filter,
     apply_show_state_filter,
+    content_libs,
     field_recheck,
     genres_col,
     meta_filter_conds,
@@ -47,12 +48,28 @@ from app.plex.query import (
     vector_col,
     vector_match,
 )
-from app.routes.plex._shared import _content_libs, _norm_lang
+from app.routes.plex._shared import _norm_lang
 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
@@ -109,7 +126,7 @@ def unified_library(
     offset = max(0, offset)
     lang = _norm_lang(lang)
     p = f.as_dict()
-    movie_lib_ids, show_lib_ids = _content_libs(db)
+    movie_lib_ids, show_lib_ids = content_libs(db)
     want_movies = scope in ("movie", "both") and bool(movie_lib_ids)
     want_shows = scope in ("show", "both") and bool(show_lib_ids)
 
@@ -220,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()
@@ -328,7 +338,7 @@ def facets(
         "duration_min": None,
         "duration_max": None,
     }
-    all_movie_ids, all_show_ids = _content_libs(db)
+    all_movie_ids, all_show_ids = content_libs(db)
     movie_ids = all_movie_ids if scope in ("movie", "both") else []
     show_ids = all_show_ids if scope in ("show", "both") else []
     if not movie_ids and not show_ids:

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
@@ -19,8 +24,7 @@ from app.plex import sync as plex_sync
 from app.plex.cards import movie_card, show_card
 from app.plex.client import PlexClient, PlexError, PlexNotConfigured
 from app.plex.lookups import by_rating_key
-from app.plex.query import like_escape, runtime_by_key, top_art_keys
-from app.routes.plex._shared import _content_libs
+from app.plex.query import content_libs, like_escape, runtime_by_key, top_art_keys
 
 # The most-restrictive → least ordering used to pick a collection's effective content rating from its
 # members (Plex shows one cert on the collection; we don't store it, so derive it).
@@ -84,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)))
@@ -114,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(
@@ -128,7 +146,7 @@ def collections(
     # members (a collection lives in one library, so exactly one side has art) — a show collection would
     # otherwise render blank; the collection's own poster is the next fallback, then the colour hash.
     # Runtime is movie-only (shows have no single duration).
-    movie_ids, show_ids = _content_libs(db)
+    movie_ids, show_ids = content_libs(db)
     keys = [c.rating_key for c in rows]
     art_m = top_art_keys(db, PlexItem, movie_ids, PlexItem.collection_keys, keys, per=2)
     art_s = top_art_keys(db, PlexShow, show_ids, PlexShow.collection_keys, keys, per=2)
@@ -150,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")
@@ -180,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),
@@ -230,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:

backend/app/routes/plex/discover.py

@@ -27,12 +27,13 @@ from app.plex.query import (
     LibraryFilters,
     apply_meta_filters,
     apply_show_state_filter,
+    content_libs,
     genres_col,
     meta_filter_conds,
     top_art_keys,
 )
 from app.plex.tmdb import resolve_recs
-from app.routes.plex._shared import _content_libs, _norm_lang
+from app.routes.plex._shared import _norm_lang
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 
@@ -43,7 +44,7 @@ SURPRISE_PER_KIND = 3  # Surprise-me: at most this many movies + this many shows
 
 def _scope_libs(db: Session, scope: str) -> tuple[list[int], list[int]]:
     """The movie/show library ids visible for this scope (empty list = out of scope)."""
-    movie_ids, show_ids = _content_libs(db)
+    movie_ids, show_ids = content_libs(db)
     return (
         movie_ids if scope in ("movie", "both") else [],
         show_ids if scope in ("show", "both") else [],
@@ -112,10 +113,11 @@ def _recently_added(
         else []
     )
     # Merge the two type-homogeneous lists by added_at, then serialize each side in one batch so the
-    # per-card state lookups stay batched (no N+1). The `(is not None, value)` key sorts a missing
-    # timestamp last under reverse.
+    # per-card state lookups stay batched (no N+1). Same `or NO_TS` key as the two rails below — the
+    # E24 review found this one still on the older `(is not None, value)` form, i.e. one rule in two
+    # spellings, with the two comments explaining it differently.
     tagged = [(m.added_at, "movie", m) for m in movies] + [(s.added_at, "show", s) for s in shows]
-    tagged.sort(key=lambda t: (t[0] is not None, t[0]), reverse=True)
+    tagged.sort(key=lambda t: t[0] or rollup.NO_TS, reverse=True)
     top = tagged[:RAIL_LIMIT]
     # Key the serialized cards back by rating_key (globally unique in Plex — a movie and a show never
     # share one), so the merge doesn't depend on object identity staying alive.
@@ -170,7 +172,7 @@ def _recently_watched(
         )
         for ep, st, sh_title, sh_rk in db.execute(eq).all():
             rows.append((st.watched_at, leaf_card(ep, st, show_title=sh_title, show_rk=sh_rk)))
-    rows.sort(key=lambda r: (r[0] is not None, r[0]), reverse=True)
+    rows.sort(key=lambda r: r[0] or rollup.NO_TS, reverse=True)
     return [card for _, card in rows[:RAIL_LIMIT]]
 
 
@@ -234,7 +236,7 @@ def _continue_watching(
         for sh, resumed_at in srows:
             rows.append((resumed_at, show_card(sh, "in_progress")))
 
-    rows.sort(key=lambda r: (r[0] is not None, r[0]), reverse=True)
+    rows.sort(key=lambda r: r[0] or rollup.NO_TS, reverse=True)
     return [card for _, card in rows[:RAIL_LIMIT]]
 
 

backend/app/routes/plex/people.py

@@ -19,8 +19,7 @@ from app.models import (
 from app.plex import rollup
 from app.plex import tmdb as plex_tmdb
 from app.plex.cards import movie_card, show_card
-from app.plex.query import split_csv
-from app.routes.plex._shared import _content_libs
+from app.plex.query import content_libs, split_csv
 
 router = APIRouter(prefix="/api/plex", tags=["plex"])
 log = logging.getLogger("siftlode.plex")
@@ -71,7 +70,7 @@ def people_cards(
     wanted = split_csv(names)[:16]
     if not wanted:
         return {"people": []}
-    movie_lib_ids, show_lib_ids = _content_libs(db)
+    movie_lib_ids, show_lib_ids = content_libs(db)
     want_movies = scope in ("movie", "both") and bool(movie_lib_ids)
     want_shows = scope in ("show", "both") and bool(show_lib_ids)
     photos = {
@@ -185,7 +184,7 @@ def person_detail(
         and _should_schedule_enrich(person.id)
     ):
         background_tasks.add_task(_enrich_person_bg, person.id)
-    movie_lib_ids, show_lib_ids = _content_libs(db)
+    movie_lib_ids, show_lib_ids = content_libs(db)
 
     movies: list[dict] = []
     if movie_lib_ids:

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
 
@@ -12,17 +10,20 @@ from fastapi import (
     BackgroundTasks,
     Depends,
     HTTPException,
+    Path,
+    Query,
     Request,
     Response,
 )
 from fastapi.responses import FileResponse
-from pydantic import BaseModel
+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,
@@ -89,62 +90,70 @@ 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.
+#
+# 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 = _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.
+    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
+    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."""
+    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 = _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).
+    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
     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."""
-    _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")
+    AND embedded text subs (extracted from the local file). Image subs (PGS/VobSub) → 415. Disk-cached.
+
+    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).
+    hit, code = subtitles.cached_track(rating_key, sub_ord)
+    if hit is None and code:
+        raise HTTPException(
+            status_code=subtitles.UNAVAILABLE_STATUS.get(code, 422),
+            detail={"code": "subtitle", "reason": code},
+        )
+    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
@@ -287,10 +296,15 @@ 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
-    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
 
 
@@ -309,6 +323,14 @@ 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)
+    # 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)
     final = body.final
@@ -406,10 +428,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:
@@ -524,9 +556,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),
@@ -536,7 +569,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
@@ -560,7 +592,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,
@@ -592,45 +626,82 @@ 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/{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:
+    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:
-        # 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):
+    # 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, 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
+    # 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")
+    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"},
     )

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:

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):

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}

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):

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 ---

backend/tests/test_demo_refusal_detail.py

@@ -0,0 +1,90 @@
+"""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 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
+
+
+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 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)
+        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):
+    """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

backend/tests/test_discover.py

@@ -0,0 +1,942 @@
+"""E24 S1 — the Home surface's read-model.
+
+Covers the four things that can silently rot here: the time-budget bands (pure), the cross-source
+resume rail's merge order, the hero's tier ladder, and the comfort shelf (its schema-level one-of
+invariant, its cascade, and the resolved `next` that makes one click enough).
+
+DB lane (`db` fixture) except for the budget block — skipped without Postgres.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from sqlalchemy import delete, func, select, text
+from sqlalchemy.exc import IntegrityError
+
+from app.discover import hero, pins, queries, rails
+from app.discover.budget import BANDS, fits, remaining_seconds
+from app.plex import rollup
+from app.plex.cards import leaf_card
+from app.models import (
+    BlockedChannel,
+    Channel,
+    ComfortPin,
+    PlexItem,
+    PlexLibrary,
+    PlexShow,
+    PlexState,
+    Playlist,
+    PlaylistItem,
+    Subscription,
+    User,
+    Video,
+    VideoState,
+)
+
+NOW = datetime(2026, 6, 1, tzinfo=timezone.utc)
+
+
+# ── budget (pure) ─────────────────────────────────────────────────────────────────────────────────
+
+
+def test_bands_cover_every_runtime_and_overlap_deliberately():
+    """Every runtime has a home in `any`, and the bands overlap so "30 perc" is not answered with a
+    two-minute Short just because it fits under the cap."""
+    assert fits(3, "any") and fits(10_000, "any")
+    assert fits(2 * 60, "short") and not fits(2 * 60, "medium")  # a Short is not a 30-minute answer
+    assert fits(30 * 60, "medium") and not fits(30 * 60, "short")
+    assert fits(110 * 60, "long") and not fits(110 * 60, "medium")
+
+
+def test_unknown_duration_only_fits_the_unbounded_band():
+    """We cannot promise an unknown-length item finishes inside ten minutes, so it is not offered as
+    an answer to a bounded question — the one control on the page has to mean what it says."""
+    for budget in BANDS:
+        assert fits(None, budget) is (budget == "any")
+
+
+def test_budget_is_matched_against_what_is_LEFT():
+    """A 90-minute film with 8 minutes to go is a ten-minute answer."""
+    assert remaining_seconds(90 * 60, 82 * 60) == 8 * 60
+    assert fits(remaining_seconds(90 * 60, 82 * 60), "short")
+    assert not fits(remaining_seconds(90 * 60, 0), "short")
+    assert remaining_seconds(None, 30) is None
+    assert remaining_seconds(600, 900) == 0  # a position past the end never goes negative
+
+
+# ── fixtures ──────────────────────────────────────────────────────────────────────────────────────
+
+
+def _seed_yt(db) -> tuple[User, Channel]:
+    """A subscribed channel with three videos of distinct lengths, so a budget can pick between them."""
+    user = User(email="discover-e24@example.com")
+    ch = Channel(id="UCe24", title="Comfort Channel", handle="@comfort")
+    db.add_all([user, ch])
+    db.flush()
+    db.add(Subscription(user_id=user.id, channel_id=ch.id))
+    db.add_all(
+        [
+            Video(
+                id="vshort",
+                channel_id=ch.id,
+                title="Ten minute video",
+                duration_seconds=9 * 60,
+                published_at=NOW - timedelta(days=1),
+            ),
+            Video(
+                id="vmed",
+                channel_id=ch.id,
+                title="Half hour video",
+                duration_seconds=30 * 60,
+                published_at=NOW - timedelta(days=2),
+            ),
+            Video(
+                id="vlong",
+                channel_id=ch.id,
+                title="Feature length video",
+                duration_seconds=95 * 60,
+                published_at=NOW - timedelta(days=3),
+            ),
+        ]
+    )
+    db.commit()
+    return user, ch
+
+
+def _seed_plex(db, user: User) -> tuple[PlexItem, PlexShow, PlexItem]:
+    lib_m = PlexLibrary(plex_key="90", title="Movies", kind="movie", enabled=True)
+    lib_s = PlexLibrary(plex_key="91", title="Shows", kind="show", enabled=True)
+    db.add_all([lib_m, lib_s])
+    db.flush()
+    movie = PlexItem(
+        rating_key="pm1",
+        library_id=lib_m.id,
+        kind="movie",
+        title="A Movie",
+        duration_s=100 * 60,
+        playable="direct",
+    )
+    show = PlexShow(rating_key="ps1", library_id=lib_s.id, title="A Show", child_count=1)
+    db.add_all([movie, show])
+    db.flush()
+    ep1 = PlexItem(
+        rating_key="ps1e1",
+        library_id=lib_s.id,
+        kind="episode",
+        title="Ep 1",
+        show_id=show.id,
+        season_number=1,
+        episode_number=1,
+        duration_s=45 * 60,
+    )
+    ep2 = PlexItem(
+        rating_key="ps1e2",
+        library_id=lib_s.id,
+        kind="episode",
+        title="Ep 2",
+        show_id=show.id,
+        season_number=1,
+        episode_number=2,
+        duration_s=45 * 60,
+    )
+    db.add_all([ep1, ep2])
+    db.commit()
+    return movie, show, ep1
+
+
+def _enable_plex(db):
+    from app import sysconfig
+
+    sysconfig.set_value(db, "plex_enabled", True)
+    db.commit()
+
+
+# ── continue watching ─────────────────────────────────────────────────────────────────────────────
+
+
+def test_continue_watching_merges_both_sources_by_recency(db):
+    """One rail, not two lists side by side — and ordered by when the user last touched each thing,
+    across sources. Two side-by-side rails would just move the decision up a level."""
+    user, _ = _seed_yt(db)
+    movie, _, _ = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add_all(
+        [
+            VideoState(
+                user_id=user.id,
+                video_id="vmed",
+                status="new",
+                position_seconds=300,
+                progress_updated_at=NOW - timedelta(hours=5),
+            ),
+            PlexState(
+                user_id=user.id,
+                item_id=movie.id,
+                status="new",
+                position_seconds=600,
+                progress_updated_at=NOW - timedelta(hours=1),
+            ),
+        ]
+    )
+    db.commit()
+
+    got = rails.continue_watching(db, user)
+    assert [(c["source"], c["id"]) for c in got] == [("plex", "pm1"), ("youtube", "vmed")]
+    assert got[0]["remaining_seconds"] == 100 * 60 - 600
+
+
+def test_continue_watching_is_youtube_only_when_plex_is_off(db):
+    """Plex is a deployment toggle; with it off the surface says nothing about Plex at all."""
+    user, _ = _seed_yt(db)
+    movie, _, _ = _seed_plex(db, user)
+    db.add_all(
+        [
+            VideoState(
+                user_id=user.id,
+                video_id="vmed",
+                status="new",
+                position_seconds=300,
+                progress_updated_at=NOW,
+            ),
+            PlexState(
+                user_id=user.id,
+                item_id=movie.id,
+                status="new",
+                position_seconds=600,
+                progress_updated_at=NOW,
+            ),
+        ]
+    )
+    db.commit()
+    assert {c["source"] for c in rails.continue_watching(db, user)} == {"youtube"}
+
+
+def test_the_resume_rail_obeys_the_channel_blocklist(db):
+    """Blocking a channel does not touch `video_states`, so a half-watched video from it survives
+    with its resume position — and this rail builds its own SELECT instead of going through
+    `filtered_query`. "Never show me this channel" has to outrank "you started it", or the landing
+    page answers "what should I watch" with the thing the user has just banned."""
+    user, ch = _seed_yt(db)
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vmed",
+            status="new",
+            position_seconds=300,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    assert [c["id"] for c in rails.continue_watching(db, user)] == ["vmed"]
+
+    db.add(BlockedChannel(user_id=user.id, channel_id=ch.id))
+    db.commit()
+    assert rails.continue_watching(db, user) == []
+    # And so the hero, whose resume tier draws from that rail, has nothing to offer either.
+    assert hero.pick(db, user, "any", 0) is None
+
+
+def test_a_null_timestamp_sorts_last(db):
+    """A missing progress timestamp sorts last rather than 500ing the landing page.
+
+    Narrower than it was written to be, and the epic-end review corrected it: the previous key,
+    `(ts is not None, ts)`, does NOT raise on two nulls — tuple comparison finds the first UNEQUAL
+    element via `==`, so `None < None` is never reached, and this test passes under that key too.
+    What it does discriminate is the naive `key=lambda r: r[0]`, which really does raise. See
+    `plex.rollup.NO_TS` for the corrected rationale."""
+    user, _ = _seed_yt(db)
+    db.add_all(
+        [
+            VideoState(
+                user_id=user.id, video_id="vmed", status="new", position_seconds=1
+            ),  # no progress_updated_at
+            VideoState(
+                user_id=user.id, video_id="vlong", status="new", position_seconds=1
+            ),  # nor here
+            VideoState(
+                user_id=user.id,
+                video_id="vshort",
+                status="new",
+                position_seconds=1,
+                progress_updated_at=NOW,
+            ),
+        ]
+    )
+    db.commit()
+    got = rails.continue_watching(db, user)
+    assert got[0]["id"] == "vshort"
+    assert len(got) == 3
+
+
+# ── hero ──────────────────────────────────────────────────────────────────────────────────────────
+
+
+def test_hero_prefers_resume_and_labels_the_tier(db):
+    user, _ = _seed_yt(db)
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vmed",
+            status="new",
+            position_seconds=300,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    got = hero.pick(db, user, "any", seed=1)
+    assert got["tier"] == "resume"
+    assert got["card"]["id"] == "vmed"
+
+
+def test_hero_skips_a_resume_that_does_not_fit_the_budget(db):
+    """ "I have ten minutes" must not be answered with the 80 minutes left on a film, even though
+    that film is the most recent thing the user touched."""
+    user, _ = _seed_yt(db)
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vlong",
+            status="new",
+            position_seconds=60,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    got = hero.pick(db, user, "short", seed=1)
+    assert got["tier"] == "surprise"
+    assert got["card"]["duration_seconds"] <= BANDS["short"][1]
+
+
+def test_hero_falls_back_to_the_shelf_before_guessing(db):
+    """The user's own declared fallback beats anything we could infer."""
+    user, ch = _seed_yt(db)
+    db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
+    db.commit()
+    got = hero.pick(db, user, "medium", seed=1)
+    assert got["tier"] == "comfort"
+    assert got["card"]["id"] == "vmed"
+
+
+def test_hero_resolves_a_show_to_the_episode_that_would_play(db):
+    """A show has no Play button. The hero of a partially-watched show is its next episode."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add(
+        PlexState(
+            user_id=user.id,
+            item_id=ep1.id,
+            status="watched",
+            watched_at=NOW,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    got = hero.pick(db, user, "any", seed=1)
+    assert got["tier"] == "resume"
+    assert got["card"]["kind"] == "episode"
+    assert got["card"]["id"] == "ps1e2"  # ep1 is finished → ep2 is what plays
+
+
+def test_hero_is_none_when_nothing_fits(db):
+    """An empty answer is an honest answer: the page renders its own empty state rather than being
+    handed a card that does not answer what was asked. Here the whole library is under 40 minutes,
+    so "egy este" has nothing to offer."""
+    user, ch = _seed_yt(db)
+    db.execute(text("DELETE FROM videos WHERE id = 'vlong'"))
+    db.commit()
+    assert hero.pick(db, user, "long", seed=1) is None
+
+
+def test_surprise_is_reproducible_for_a_seed(db):
+    """The reroll button depends on this: one seed drives both sources, so the same seed must give
+    the same answer and a different seed must be free to give another."""
+    user, _ = _seed_yt(db)
+    a = rails.surprise(db, user, "any", seed=7, limit=3)
+    b = rails.surprise(db, user, "any", seed=7, limit=3)
+    assert [c["id"] for c in a] == [c["id"] for c in b]
+    seeds = {tuple(c["id"] for c in rails.surprise(db, user, "any", s, 3)) for s in range(12)}
+    assert len(seeds) > 1  # the seed actually reaches the ordering
+
+
+def test_surprise_never_offers_something_already_started(db):
+    """The resume tier may have skipped an item because its REMAINING time did not fit; handing the
+    same item back as "Meglepetés" — where the full runtime does fit — would contradict the question
+    the user just answered."""
+    user, _ = _seed_yt(db)
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vlong",
+            status="new",
+            position_seconds=90 * 60,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    assert "vlong" not in {c["id"] for c in rails.surprise(db, user, "long", seed=3, limit=5)}
+
+
+def test_the_seed_decides_which_source_leads(db):
+    """With a pool of one, a fixed source order would mean the Plex library could never answer "egy
+    este" whenever a YouTube video also fit — the cross-source promise would quietly be a YouTube
+    promise."""
+    user, _ = _seed_yt(db)
+    _seed_plex(db, user)
+    _enable_plex(db)
+    leaders = {rails.surprise(db, user, "any", s, limit=1)[0]["source"] for s in range(6)}
+    assert leaders == {"youtube", "plex"}
+
+
+def test_the_reroll_must_be_able_to_move_past_the_resume_tier(db):
+    """A new seed alone only re-draws the SURPRISE tier — the resume tier deterministically returns
+    the most recently progressed thing that fits, so without an exclusion the reroll handed the same
+    card straight back and the button looked dead (found in the browser, 2026-09-06)."""
+    user, _ = _seed_yt(db)
+    db.add_all(
+        [
+            VideoState(
+                user_id=user.id,
+                video_id="vmed",
+                status="new",
+                position_seconds=300,
+                progress_updated_at=NOW,
+            ),
+            VideoState(
+                user_id=user.id,
+                video_id="vshort",
+                status="new",
+                position_seconds=60,
+                progress_updated_at=NOW - timedelta(hours=1),
+            ),
+        ]
+    )
+    db.commit()
+
+    first = hero.pick(db, user, "any", seed=1)
+    assert first["card"]["id"] == "vmed"
+    # Same seed, same everything — only the exclusion differs.
+    second = hero.pick(db, user, "any", seed=1, exclude={"youtube:vmed"})
+    assert second["card"]["id"] == "vshort"
+
+
+def test_the_reroll_rotates_which_tier_answers(db):
+    """Measured 2026-09-06: exclusion alone left the button walking down the resume rail (20 rows)
+    and cycling nine cards, every one of them `resume` — the shelf and the surprise tier were
+    unreachable by pressing it. `start` is the press count, so consecutive presses offer a different
+    KIND of answer."""
+    user, _ = _seed_yt(db)
+    # One of each: something half-finished, something pinned, and a third video for the draw.
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vmed",
+            status="new",
+            position_seconds=300,
+            progress_updated_at=NOW,
+        )
+    )
+    db.add(ComfortPin(user_id=user.id, video_id="vlong", position=0))
+    db.commit()
+    tiers = [hero.pick(db, user, "any", seed=1, start=n)["tier"] for n in range(4)]
+    assert tiers == ["resume", "comfort", "surprise", "resume"]
+
+
+def test_the_rotation_still_falls_through_an_empty_tier(db):
+    """A press must not come back empty just because the tier it happened to lead with has nothing.
+    Here there is no shelf at all, so the comfort-led press has to answer from somewhere else."""
+    user, _ = _seed_yt(db)
+    assert db.execute(select(func.count()).select_from(ComfortPin)).scalar_one() == 0
+    got = hero.pick(db, user, "any", seed=1, start=1)
+    assert got is not None and got["tier"] != "comfort"
+
+
+def test_excluding_a_show_also_excludes_the_episode_it_resolves_to(db):
+    """The user rerolled past the SHOW they were shown; handing back its next episode under a
+    different title would be the same suggestion wearing a hat."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add(
+        PlexState(
+            user_id=user.id,
+            item_id=ep1.id,
+            status="new",
+            position_seconds=120,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+
+    shown = hero.pick(db, user, "any", seed=1)
+    assert shown["card"]["id"] == "ps1e1"  # the show resolved to its in-progress episode
+    # Excluding what the USER saw — the show — must move the tier on, not return the episode again.
+    after = hero.pick(db, user, "any", seed=1, exclude={"plex:ps1"})
+    assert after is None or after["card"]["id"] != "ps1e1"
+
+
+# ── comfort shelf ─────────────────────────────────────────────────────────────────────────────────
+
+
+def test_a_pin_must_reference_exactly_one_thing(db):
+    """The union invariant lives in the schema, not in a comment at every insert site."""
+    user, ch = _seed_yt(db)
+    for kwargs in ({}, {"video_id": "vmed", "channel_id": ch.id}):
+        db.add(ComfortPin(user_id=user.id, position=0, **kwargs))
+        with pytest.raises(IntegrityError):
+            db.flush()
+        db.rollback()
+
+
+def test_the_same_thing_cannot_be_pinned_twice(db):
+    """The per-kind unique constraints are what make the route's concurrent-tab path safe (it catches
+    `IntegrityError` precisely because of them) — and the migration drift check filters constraint
+    diffs out as noise, so nothing else would notice them going missing. The route's own dedupe
+    returns early without ever reaching the DB, so only this test exercises them."""
+    user, _ = _seed_yt(db)
+    db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
+    db.commit()
+    db.add(ComfortPin(user_id=user.id, video_id="vmed", position=1))
+    with pytest.raises(IntegrityError):
+        db.flush()
+    db.rollback()
+
+
+def test_deleting_the_pinned_row_removes_the_pin(db):
+    """A film dropped from the library must not leave a dead tile on the one surface whose whole job
+    is to be reliable — which is why the shelf holds foreign keys, not strings."""
+    user, _ = _seed_yt(db)
+    db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
+    db.commit()
+    db.execute(text("DELETE FROM videos WHERE id = 'vmed'"))
+    db.commit()
+    assert db.execute(select(func.count()).select_from(ComfortPin)).scalar() == 0
+
+
+def test_shelf_resolves_a_channel_to_its_newest_unwatched_video(db):
+    """ "Put that channel on" has to be one click, so the tile carries what would play."""
+    user, ch = _seed_yt(db)
+    db.add(ComfortPin(user_id=user.id, channel_id=ch.id, position=0))
+    db.commit()
+    (card,) = pins.shelf(db, user)
+    assert card["kind"] == "channel"
+    assert card["unwatched_count"] == 3
+    assert card["next"]["id"] == "vshort"  # newest
+
+
+def test_shelf_resolves_a_playlist_to_its_first_unwatched_item(db):
+    user, _ = _seed_yt(db)
+    pl = Playlist(user_id=user.id, name="Elalvós")
+    db.add(pl)
+    db.flush()
+    db.add_all(
+        [
+            PlaylistItem(playlist_id=pl.id, video_id="vshort", position=0),
+            PlaylistItem(playlist_id=pl.id, video_id="vmed", position=1),
+        ]
+    )
+    db.add(VideoState(user_id=user.id, video_id="vshort", status="watched", watched_at=NOW))
+    db.add(ComfortPin(user_id=user.id, playlist_id=pl.id, position=0))
+    db.commit()
+    (card,) = pins.shelf(db, user)
+    assert card["kind"] == "playlist"
+    assert card["item_count"] == 2
+    assert card["next"]["id"] == "vmed"
+
+
+def test_a_pinned_video_survives_leaving_the_feed_scope(db):
+    """The shelf is the fallback surface. An entry silently vanishing because the user unsubscribed
+    from the channel is exactly the failure it must not have."""
+    user, ch = _seed_yt(db)
+    db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
+    db.commit()
+    db.execute(delete(Subscription))
+    db.commit()
+    (card,) = pins.shelf(db, user)
+    assert card["id"] == "vmed"
+    assert card["next"]["id"] == "vmed"
+
+
+def test_the_plex_surprise_obeys_the_time_budget(db):
+    """The one control on the page has to mean what it says: a 100-minute film is not an answer to
+    "10 perc". The YouTube half of this rule has had its own test since S1; the Plex half's duration
+    bounds could be deleted with the whole suite still green, because every test that reached
+    `plex_surprise` passed budget="any"."""
+    user, _ = _seed_yt(db)
+    _seed_plex(db, user)
+    _enable_plex(db)
+    drawn = lambda budget: {  # noqa: E731
+        (c["source"], c["id"]) for s in range(6) for c in rails.surprise(db, user, budget, s, 5)
+    }
+    assert ("plex", "pm1") not in drawn("short")
+    # …and it IS offered where it fits, so this cannot pass by the rail being empty.
+    assert ("plex", "pm1") in drawn("long")
+
+
+def test_the_plex_surprise_never_offers_something_already_started(db):
+    """A half-watched film is not a surprise, and the resume tier has already had its chance at it.
+    The mirror of `test_surprise_never_offers_something_already_started` for the other source — the
+    asymmetric half of one principle, which the house rules say to fix everywhere."""
+    user, _ = _seed_yt(db)
+    movie, _, _ = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add(
+        PlexState(
+            user_id=user.id,
+            item_id=movie.id,
+            status="new",
+            position_seconds=600,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    drawn = {
+        (c["source"], c["id"]) for s in range(6) for c in rails.surprise(db, user, "long", s, 5)
+    }
+    assert ("plex", "pm1") not in drawn
+
+
+def test_a_new_pin_lands_at_the_end_even_after_a_hole(db):
+    """Positions are never renumbered on removal — `remove_pin` deletes the row, and every FK cascade
+    silently removes a pin when its target disappears — so the append position has to come from
+    `max(position)`, not from the row count. With a count, the first hole drops the next pin into the
+    MIDDLE of the shelf and the second makes two pins claim one slot."""
+    user, ch = _seed_yt(db)
+    db.add_all(
+        [
+            ComfortPin(user_id=user.id, video_id="vshort", position=0),
+            ComfortPin(user_id=user.id, video_id="vmed", position=1),
+            ComfortPin(user_id=user.id, video_id="vlong", position=2),
+        ]
+    )
+    db.commit()
+    db.execute(delete(ComfortPin).where(ComfortPin.video_id.in_(("vshort", "vmed"))))
+    db.commit()
+
+    db.add(ComfortPin(user_id=user.id, channel_id=ch.id, position=pins.next_position(db, user)))
+    db.commit()
+    assert [c["kind"] for c in pins.shelf(db, user)] == ["video", "channel"]
+    positions = (
+        db.execute(select(ComfortPin.position).order_by(ComfortPin.position)).scalars().all()
+    )
+    assert len(set(positions)) == len(positions)  # and no two tiles claim the same slot
+
+
+def test_a_self_playing_pin_does_not_reference_itself(db):
+    """`next` must be a distinct dict even when the pin plays itself. Aliasing the card into its own
+    `next` is a cycle, and the serializer turns the whole shelf into a 500 over it."""
+    user, _ = _seed_yt(db)
+    db.add(ComfortPin(user_id=user.id, video_id="vmed", position=0))
+    db.commit()
+    (card,) = pins.shelf(db, user)
+    assert card["next"] is not card
+    assert "next" not in card["next"]
+
+
+def test_the_resume_rail_says_what_would_actually_play(db):
+    """A show tile that only opens the show page moves the decision instead of removing it — the
+    click lands on six seasons to choose between, which is the paralysis this whole surface exists
+    for. The shelf and the hero already resolved; this rail did not (reported 2026-09-06). The tile
+    stays the show (its artwork is what the user recognises); `next` is what starts."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add(
+        PlexState(
+            user_id=user.id,
+            item_id=ep1.id,
+            status="watched",
+            watched_at=NOW,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    rail = rails.continue_watching(db, user)
+    tile = next(c for c in rail if c["kind"] == "show")
+    assert tile["id"] == "ps1"  # still the show
+    assert tile["next"]["kind"] == "episode"
+    assert tile["next"]["id"] == "ps1e2"  # ep1 is finished → ep2 is what plays
+
+
+def test_only_a_show_row_pays_for_a_resolution(db):
+    """`next` is the answer to "a show has no Play button". Attaching it to a movie or a video would
+    both cost a query for nothing and re-open the self-reference cycle the shelf already hit.
+
+    The states are what make this test exist: without them every rail query inner-joins its way to
+    zero rows, the loop body never runs, and the assertion is vacuous — which is exactly how the
+    epic-end review found it."""
+    user, _ = _seed_yt(db)
+    movie, _, ep1 = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add_all(
+        [
+            VideoState(
+                user_id=user.id,
+                video_id="vmed",
+                status="new",
+                position_seconds=300,
+                progress_updated_at=NOW,
+            ),
+            PlexState(
+                user_id=user.id,
+                item_id=movie.id,
+                status="new",
+                position_seconds=600,
+                progress_updated_at=NOW,
+            ),
+            PlexState(
+                user_id=user.id,
+                item_id=ep1.id,
+                status="new",
+                position_seconds=120,
+                progress_updated_at=NOW,
+            ),
+        ]
+    )
+    db.commit()
+
+    rail = rails.continue_watching(db, user)
+    # A video, a movie and a show — one row of each kind that can appear here, so the assertion below
+    # actually exercises both sides of the equality.
+    assert {c["kind"] for c in rail} == {"video", "movie", "show"}
+    for card in rail:
+        assert ("next" in card) == (card["kind"] == "show"), card["id"]
+
+
+def test_next_episode_takes_an_episode_with_no_state_row_at_all(db):
+    """The NULL trap in the SQL rewrite: `status NOT IN ('watched','hidden')` is UNKNOWN — not true —
+    for an episode the user has never touched, so a bare filter drops exactly the common case and the
+    rail would offer episode 1 of a show already half-watched."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    db.add(PlexState(user_id=user.id, item_id=ep1.id, status="watched", watched_at=NOW))
+    db.commit()  # ep2 has NO PlexState row
+    assert queries.next_episode(db, user.id, show.id)["id"] == "ps1e2"
+
+
+def test_a_finished_show_starts_again_from_the_top(db):
+    """Nothing unwatched left is not "nothing to play" — it is "watch it again"."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    ep2 = db.execute(select(PlexItem).where(PlexItem.rating_key == "ps1e2")).scalar_one()
+    db.add_all(
+        [
+            PlexState(user_id=user.id, item_id=ep1.id, status="watched", watched_at=NOW),
+            PlexState(user_id=user.id, item_id=ep2.id, status="watched", watched_at=NOW),
+        ]
+    )
+    db.commit()
+    assert queries.next_episode(db, user.id, show.id)["id"] == "ps1e1"
+
+
+def test_next_episode_agrees_with_the_show_page_when_two_are_in_progress(db):
+    """One show, one answer. `plex.rollup.rollup` — which drives the show page's Resume button —
+    takes the LAST in-progress episode in broadcast order; taking the FIRST here gave the same show
+    two different "continue" answers, with the rail ranking it by its most recent touch and then
+    offering the episode abandoned weeks earlier. Two in-progress episodes are not exotic: a scrub to
+    the end leaves a stale `status='new', position>0` row until the daily reconcile."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    ep2 = db.execute(select(PlexItem).where(PlexItem.rating_key == "ps1e2")).scalar_one()
+    db.add_all(
+        [
+            PlexState(
+                user_id=user.id,
+                item_id=ep1.id,
+                status="new",
+                position_seconds=300,
+                progress_updated_at=NOW - timedelta(days=9),
+            ),
+            PlexState(
+                user_id=user.id,
+                item_id=ep2.id,
+                status="new",
+                position_seconds=600,
+                progress_updated_at=NOW,
+            ),
+        ]
+    )
+    db.commit()
+
+    got = queries.next_episode(db, user.id, show.id)
+    assert got["id"] == "ps1e2"
+    # Asserted against the other implementation rather than against a literal, so the two cannot
+    # drift apart again without this failing.
+    ordered = [
+        leaf_card(ep, db.execute(select(PlexState).where(PlexState.item_id == ep.id)).scalar_one())
+        for ep in (ep1, ep2)
+    ]
+    assert rollup.rollup(ordered)["resume"]["id"] == got["id"]
+
+
+def test_next_episode_prefers_the_one_in_progress(db):
+    """In progress beats "next unwatched": resuming is cheaper than starting."""
+    user, _ = _seed_yt(db)
+    _, show, ep1 = _seed_plex(db, user)
+    ep2 = db.execute(select(PlexItem).where(PlexItem.rating_key == "ps1e2")).scalar_one()
+    db.add_all(
+        [
+            PlexState(user_id=user.id, item_id=ep1.id, status="watched", watched_at=NOW),
+            PlexState(user_id=user.id, item_id=ep2.id, status="new", position_seconds=120),
+        ]
+    )
+    db.commit()
+    assert queries.next_episode(db, user.id, show.id)["id"] == "ps1e2"
+
+
+# ── HTTP surface ──────────────────────────────────────────────────────────────────────────────────
+
+
+def test_discover_endpoint_answers_in_one_pass(db, as_user):
+    user, _ = _seed_yt(db)
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vmed",
+            status="new",
+            position_seconds=300,
+            progress_updated_at=NOW,
+        )
+    )
+    db.commit()
+    r = as_user(user).get("/api/discover?budget=medium")
+    assert r.status_code == 200
+    body = r.json()
+    assert body["budget"] == "medium"
+    assert body["hero"]["tier"] == "resume"
+    assert [c["id"] for c in body["continue_watching"]] == ["vmed"]
+    assert body["comfort"] == []
+
+
+def test_an_unknown_budget_is_refused_rather_than_silently_widened(db, as_user):
+    user, _ = _seed_yt(db)
+    assert as_user(user).get("/api/discover?budget=whenever").status_code == 422
+
+
+def test_pinning_twice_is_the_same_shelf(db, as_user):
+    """The gesture is "make sure this is on my shelf", so a re-pin is a no-op, not a 409."""
+    user, _ = _seed_yt(db)
+    c = as_user(user)
+    first = c.post("/api/discover/pins", json={"kind": "video", "ref": "vmed"}).json()
+    second = c.post("/api/discover/pins", json={"kind": "video", "ref": "vmed"}).json()
+    assert first["created"] is True and second["created"] is False
+    assert first["id"] == second["id"]
+    assert len(c.get("/api/discover/pins").json()["items"]) == 1
+
+
+def test_pinning_a_plex_show_resolves_to_the_episode_that_would_play(db, as_user):
+    """Two of the five pinnable kinds are Plex, and the rating_key → internal-id translation is
+    theirs alone — a wrong column or a wrong model in either arm pins the wrong row, or 404s every
+    Plex pin. Neither arm had a test before the epic-end review."""
+    user, _ = _seed_yt(db)
+    _, _, ep1 = _seed_plex(db, user)
+    _enable_plex(db)
+    db.add(PlexState(user_id=user.id, item_id=ep1.id, status="watched", watched_at=NOW))
+    db.commit()
+    c = as_user(user)
+    assert c.post("/api/discover/pins", json={"kind": "plex_show", "ref": "ps1"}).status_code == 200
+    (tile,) = c.get("/api/discover/pins").json()["items"]
+    assert (tile["kind"], tile["id"]) == ("show", "ps1")
+    assert tile["next"]["id"] == "ps1e2"  # ep1 is finished
+
+
+def test_pinning_a_plex_movie_plays_itself_without_a_cycle(db, as_user):
+    """The self-reference that once 500'd the whole shelf, on the other leaf kind: `next` has to be a
+    distinct dict, not the tile aliased into itself. Covered for a video since S1, never for a movie."""
+    user, _ = _seed_yt(db)
+    _seed_plex(db, user)
+    _enable_plex(db)
+    c = as_user(user)
+    assert c.post("/api/discover/pins", json={"kind": "plex_item", "ref": "pm1"}).status_code == 200
+    (tile,) = c.get("/api/discover/pins").json()["items"]
+    assert tile["id"] == "pm1" and tile["next"]["id"] == "pm1"
+
+
+def test_the_reroll_endpoint_parses_its_whole_exclusion_list_and_its_press_count(db, as_user):
+    """The reroll's behaviour is covered at the domain level; the ROUTE's query-string translation —
+    the comma split and the `start` passthrough — was not covered at all, so a change there could
+    hand back the same card on every press with the suite green. Excluding all three candidates is
+    what proves the whole list parsed: a delimiter change leaves one unsplit string in the set, and a
+    hero comes back.
+
+    NOT the `MAX_EXCLUDE` clamp, which this sends three keys against a cap of 32 and cannot see. The
+    docstring used to claim it did (round 2). The clamp is deliberately left unpinned: it guards
+    nothing the route would otherwise do — see the constant's own comment — and a test that sent 33
+    keys could only assert that the request still answers, which the comma split already proves."""
+    user, _ = _seed_yt(db)
+    db.add(
+        VideoState(
+            user_id=user.id,
+            video_id="vmed",
+            status="new",
+            position_seconds=300,
+            progress_updated_at=NOW,
+        )
+    )
+    db.add(ComfortPin(user_id=user.id, video_id="vlong", position=0))
+    db.commit()
+    c = as_user(user)
+
+    # `start` rotates which tier answers first: 0 leads with resume, 1 with the shelf.
+    assert c.get("/api/discover/pick?seed=1&start=0").json()["hero"]["tier"] == "resume"
+    assert c.get("/api/discover/pick?seed=1&start=1").json()["hero"]["tier"] == "comfort"
+
+    skip = ",".join(f"youtube:{v}" for v in ("vshort", "vmed", "vlong"))
+    assert c.get(f"/api/discover/pick?seed=2&exclude={skip}").json()["hero"] is None
+    assert c.get("/api/discover/pick?budget=whenever").status_code == 422
+
+
+def test_pinning_something_that_does_not_exist_is_a_404(db, as_user):
+    user, _ = _seed_yt(db)
+    r = as_user(user).post("/api/discover/pins", json={"kind": "video", "ref": "nope"})
+    assert r.status_code == 404
+
+
+def test_a_pin_whose_target_vanishes_mid_request_is_a_404_not_a_500(db, as_user, monkeypatch):
+    """`add_pin`'s `except IntegrityError` arm was reached by no test at all, so the 500→404
+    narrowing could be reverted with the whole suite green (round 2). The 404 above comes from the
+    `resolve_ref` PRE-CHECK, a different branch that returns before the INSERT.
+
+    The race the arm exists for — a Plex sync dropping the row between `resolve_ref` confirming it
+    and the INSERT — needs two transactions, but the BRANCH does not: a `resolve_ref` pointing at an
+    id no row carries lets the pre-check pass and trips the same FK on commit, with the re-query
+    finding no winner. The sentinel has to FIT `comfort_pins.video_id` (varchar(16)) — a longer one
+    raises `DataError` on the way in, which this arm does not catch and never meant to. Its sibling arm (a concurrent duplicate, where the re-query DOES find a winner
+    and answers 200) genuinely needs a second connection and stays uncovered."""
+    user, _ = _seed_yt(db)
+    monkeypatch.setattr(pins, "resolve_ref", lambda *a, **k: ("video_id", "gone-mid-req"))
+    r = as_user(user).post("/api/discover/pins", json={"kind": "video", "ref": "vshort"})
+    assert r.status_code == 404
+
+
+def test_another_users_playlist_is_not_pinnable(db, as_user):
+    """404, not 403 — a 403 would confirm the id exists to a stranger."""
+    user, _ = _seed_yt(db)
+    other = User(email="other-e24@example.com")
+    db.add(other)
+    db.flush()
+    pl = Playlist(user_id=other.id, name="Theirs")
+    db.add(pl)
+    db.commit()
+    r = as_user(user).post("/api/discover/pins", json={"kind": "playlist", "ref": str(pl.id)})
+    assert r.status_code == 404
+
+
+def test_reorder_ignores_ids_that_are_not_yours(db, as_user):
+    """A stale tab replaying an order that includes a since-deleted pin should reorder what still
+    exists rather than fail wholesale."""
+    user, ch = _seed_yt(db)
+    c = as_user(user)
+    a = c.post("/api/discover/pins", json={"kind": "video", "ref": "vmed"}).json()["id"]
+    b = c.post("/api/discover/pins", json={"kind": "channel", "ref": ch.id}).json()["id"]
+    assert c.post("/api/discover/pins/reorder", json={"ids": [b, 9999, a]}).status_code == 200
+    assert [p["pin_id"] for p in c.get("/api/discover/pins").json()["items"]] == [b, a]
+
+
+def test_deleting_a_pin_reports_what_went(db, as_user):
+    user, _ = _seed_yt(db)
+    c = as_user(user)
+    pin_id = c.post("/api/discover/pins", json={"kind": "video", "ref": "vmed"}).json()["id"]
+    r = c.delete(f"/api/discover/pins/{pin_id}")
+    assert r.status_code == 200 and r.json() == {"deleted": pin_id}
+    assert c.get("/api/discover/pins").json()["items"] == []

backend/tests/test_hls_reaper.py

@@ -0,0 +1,204 @@
+"""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
+(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" 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
+
+
+class _Configured:
+    def __enter__(self):
+        return None
+
+    def __exit__(self, *exc):
+        return False
+
+
+def test_the_periodic_pass_is_the_one_that_runs_and_it_uses_the_short_rule(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)
+    # `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):
+            await asyncio.sleep(0.2)
+
+    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_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(
+    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_idle() == 2
+    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

backend/tests/test_not_found_detail.py

@@ -0,0 +1,148 @@
+"""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.
+"""
+
+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())
+    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
+
+
+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_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.
+
+    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"
+    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)
+        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".
+
+    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"}
+    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": "recipient"}
+
+
+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
+
+
+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

backend/tests/test_playlist_move.py

@@ -0,0 +1,244 @@
+"""E10 S2 — the one-step "move this video to another list" endpoint, and the `updated_at` touch
+the rail's "recently changed" sort reads.
+
+Two properties are load-bearing and neither is visible from the happy path alone:
+
+1. **The move is one transaction.** The client-side shape it replaces (add to the target, then
+   remove from the source) leaves the video in BOTH lists when the second call fails. So the
+   tests assert the *pair* of lists after every call, never just the destination.
+2. **`updated_at` tracks item edits.** `UpdatedAtMixin.onupdate` only fires on an UPDATE of the
+   playlist row, and add/remove/reorder/move write `playlist_items` — so the timestamp is bumped
+   explicitly, and a regression there would silently degrade the sort to "renames only".
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from app.models import Channel, Playlist, PlaylistItem, Video
+
+
+def _seed_videos(db, ids):
+    db.add(Channel(id="UCtest", title="Test"))
+    now = datetime.now(timezone.utc)
+    for v in ids:
+        db.add(Video(id=v, channel_id="UCtest", published_at=now))
+    db.commit()
+
+
+def _playlist(db, user, name, video_ids, **kw):
+    pl = Playlist(user_id=user.id, name=name, **kw)
+    db.add(pl)
+    db.flush()
+    for i, vid in enumerate(video_ids):
+        db.add(PlaylistItem(playlist_id=pl.id, video_id=vid, position=i))
+    db.commit()
+    return pl
+
+
+def _ids(db, pl_id):
+    return [
+        it.video_id
+        for it in db.execute(
+            PlaylistItem.__table__.select()
+            .where(PlaylistItem.playlist_id == pl_id)
+            .order_by(PlaylistItem.position)
+        ).all()
+    ]
+
+
+def _move(client, src, video_id, dst):
+    return client.post(
+        f"/api/playlists/{src}/items/{video_id}/move", json={"target_playlist_id": dst}
+    )
+
+
+def test_move_leaves_the_video_in_exactly_one_list(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["v1", "v2"])
+    src = _playlist(db, user, "Source", ["v1", "v2"])
+    dst = _playlist(db, user, "Target", [])
+
+    r = _move(as_user(user), src.id, "v1", dst.id)
+    assert r.status_code == 200
+    assert r.json() == {
+        "ok": True,
+        "from_playlist_id": src.id,
+        "to_playlist_id": dst.id,
+        "video_id": "v1",
+    }
+    db.expire_all()
+    assert _ids(db, src.id) == ["v2"]
+    assert _ids(db, dst.id) == ["v1"]
+
+
+def test_move_appends_to_the_end_of_the_target(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["v1", "v2", "v3"])
+    src = _playlist(db, user, "Source", ["v3"])
+    dst = _playlist(db, user, "Target", ["v1", "v2"])
+
+    assert _move(as_user(user), src.id, "v3", dst.id).status_code == 200
+    db.expire_all()
+    assert _ids(db, dst.id) == ["v1", "v2", "v3"]
+
+
+def test_move_into_a_list_that_already_has_it_is_a_removal_not_a_duplicate(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["v1"])
+    src = _playlist(db, user, "Source", ["v1"])
+    dst = _playlist(db, user, "Target", ["v1"])
+
+    assert _move(as_user(user), src.id, "v1", dst.id).status_code == 200
+    db.expire_all()
+    assert _ids(db, src.id) == []
+    assert _ids(db, dst.id) == ["v1"]  # exactly one row, not two
+
+
+def test_move_to_the_same_list_is_refused(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["v1"])
+    src = _playlist(db, user, "Source", ["v1"])
+
+    r = _move(as_user(user), src.id, "v1", src.id)
+    assert r.status_code == 400
+    assert r.json()["detail"] == {"code": "playlist_move", "reason": "same_playlist"}
+    db.expire_all()
+    assert _ids(db, src.id) == ["v1"]
+
+
+def test_move_of_a_video_that_left_the_source_reports_it(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["v1"])
+    src = _playlist(db, user, "Source", [])
+    dst = _playlist(db, user, "Target", [])
+
+    r = _move(as_user(user), src.id, "v1", dst.id)
+    assert r.status_code == 404
+    assert r.json()["detail"] == {"code": "playlist_move", "reason": "not_in_playlist"}
+
+
+def test_move_into_someone_elses_list_404s_and_changes_nothing(db, make_user, as_user):
+    user, other = make_user(), make_user()
+    _seed_videos(db, ["v1"])
+    src = _playlist(db, user, "Mine", ["v1"])
+    theirs = _playlist(db, other, "Theirs", [])
+
+    assert _move(as_user(user), src.id, "v1", theirs.id).status_code == 404
+    db.expire_all()
+    assert _ids(db, src.id) == ["v1"]
+    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": "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."""
+    user = make_user()
+    _seed_videos(db, ["v1"])
+    src = _playlist(db, user, "Src", ["v1"], yt_playlist_id="PLsrc", synced_video_ids='["v1"]')
+    dst = _playlist(db, user, "Dst", [], yt_playlist_id="PLdst", synced_video_ids="[]")
+    # Baseline: both are in sync with YouTube before the move.
+    src.dirty = False
+    dst.dirty = False
+    db.commit()
+
+    assert _move(as_user(user), src.id, "v1", dst.id).status_code == 200
+    db.expire_all()
+    assert db.get(Playlist, src.id).dirty is True
+    assert db.get(Playlist, dst.id).dirty is True
+
+
+def test_item_edits_bump_updated_at(db, make_user, as_user):
+    """The rail's "recently changed first" sort reads this. Adding, moving and reordering all
+    write `playlist_items` only, so nothing here is covered by the ORM's `onupdate`."""
+    user = make_user()
+    _seed_videos(db, ["v1", "v2"])
+    src = _playlist(db, user, "Source", ["v1", "v2"])
+    dst = _playlist(db, user, "Target", [])
+    old = datetime.now(timezone.utc) - timedelta(days=3)
+    src.updated_at = old
+    dst.updated_at = old
+    db.commit()
+    client = as_user(user)
+
+    assert client.post(f"/api/playlists/{dst.id}/items", json={"video_id": "v1"}).status_code == 200
+    db.expire_all()
+    assert db.get(Playlist, dst.id).updated_at > old
+
+    dst.updated_at = old
+    db.commit()
+    assert (
+        client.put(f"/api/playlists/{src.id}/order", json={"video_ids": ["v2", "v1"]}).status_code
+        == 200
+    )
+    db.expire_all()
+    assert db.get(Playlist, src.id).updated_at > old
+
+    src.updated_at = old
+    dst.updated_at = old
+    db.commit()
+    assert _move(client, src.id, "v2", dst.id).status_code == 200
+    db.expire_all()
+    # BOTH sides of a move are "recently changed" — the target is where the reader will look.
+    assert db.get(Playlist, src.id).updated_at > old
+    assert db.get(Playlist, dst.id).updated_at > old
+
+
+def test_the_list_endpoint_publishes_updated_at(db, make_user, as_user):
+    user = make_user()
+    _playlist(db, user, "Solo", [])
+    rows = as_user(user).get("/api/playlists").json()
+    assert len(rows) == 1
+    assert rows[0]["updated_at"]  # the rail cannot sort by a field the API never sends

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) == []

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"] == []

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()
 

backend/tests/test_plex_hls_file_route.py

@@ -0,0 +1,322 @@
+"""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).
+
+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
+
+import pytest
+from fastapi.testclient import TestClient
+
+import app.state as state
+from app.auth import current_user
+from app.main import app
+from app.models import User
+from app.plex import stream as plex_stream
+
+
+class _Proc:
+    def __init__(self, running: bool = False):
+        self.running = running
+
+    def poll(self):
+        return None if self.running else 0
+
+    def terminate(self):
+        pass
+
+    def wait(self, timeout=None):
+        return 0
+
+
+class _Session:
+    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
+def sessions(monkeypatch):
+    live: dict = {}
+    monkeypatch.setattr(plex_stream, "_sessions", live)
+    return live
+
+
+@pytest.fixture
+def client(monkeypatch):
+    monkeypatch.setattr(state, "_configured_cache", True)
+    user = User(email="hls@example.com")
+    app.dependency_overrides[current_user] = lambda: user
+    try:
+        yield TestClient(app)
+    finally:
+        app.dependency_overrides.pop(current_user, None)
+
+
+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)
+    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(
+    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."""
+    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)
+    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(
+    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,
+    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),
+    )
+    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(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
+    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()
+    (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)
+    started = time.monotonic()
+    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, audio_langs=["hu", "en"])
+    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, 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"
+
+
+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("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(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")

backend/tests/test_plex_overlay.py

@@ -12,7 +12,7 @@ import app.plex.sync as syncmod
 from app import sysconfig
 from app.models import PlexItem, PlexLibrary
 from app.plex.sync import _apply_item, _canonical_guid, _sync_overlay
-from app.routes.plex._shared import _content_libs
+from app.plex.query import content_libs
 
 
 class _StubPlex:
@@ -155,7 +155,7 @@ def test_sync_designates_overlay_and_writes_hu(db, monkeypatch):
     assert m.title_hu == "Öldöklés"
     assert m.genres_hu == ["Akció"]
     # The HU section is not browsable and mirrored no rows of its own.
-    movie_ids, _ = _content_libs(db)
+    movie_ids, _ = content_libs(db)
     assert en.id in movie_ids and hu.id not in movie_ids
     assert db.scalar(select(func.count(PlexItem.id)).where(PlexItem.library_id == hu.id)) == 0
     assert stats["overlaid"] == 1
@@ -240,7 +240,7 @@ def test_content_libs_excludes_overlay_libraries(db):
     db.add(overlay)
     db.commit()
 
-    movie_ids, show_ids = _content_libs(db)
+    movie_ids, show_ids = content_libs(db)
     assert en_lib.id in movie_ids
     assert overlay.id not in movie_ids  # the HU overlay is never browsable
     assert show_ids == [en_shows.id]

backend/tests/test_plex_person.py

@@ -1,6 +1,6 @@
 """DB-backed regression (E5 S4): GET /api/plex/person/{name} returns a cast/crew member's
 filmography — movies + shows in the ENABLED libraries whose cast OR directors include the name,
-each carrying the caller's watch-state, plus the cached headshot. Also covers `_content_libs`
+each carrying the caller's watch-state, plus the cached headshot. Also covers `content_libs`
 scoping (disabled libraries excluded) and the kind filter (episodes are not movies).
 
 Uses the DB lane (`db` fixture) — skipped when no Postgres is reachable.
@@ -20,7 +20,7 @@ from app.models import (
     PlexState,
     User,
 )
-from app.routes.plex._shared import _content_libs
+from app.plex.query import content_libs
 
 NAME = "Robert De Niro"
 
@@ -151,5 +151,5 @@ def test_content_libs_partitions_only_enabled(db):
         ]
     )
     db.commit()
-    movie_ids, show_ids = _content_libs(db)
+    movie_ids, show_ids = content_libs(db)
     assert len(movie_ids) == 1 and len(show_ids) == 1  # the disabled movie lib is excluded

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)

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)

backend/tests/test_plex_subtitle_auth.py

@@ -0,0 +1,45 @@
+"""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, "_WIN_POOL", pool)
+    monkeypatch.setattr(subtitles, "_FULL_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"

backend/tests/test_progress_bounds.py

@@ -0,0 +1,63 @@
+"""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
+
+
+@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

frontend/eslint.config.js

@@ -67,5 +67,47 @@ export default tseslint.config(
       ],
     },
   },
+  {
+    // E10 S1: `components/ui/` is the PLATFORM layer, and the rule that makes it a layer rather than
+    // a folder is enforced here, not in prose (see components/ui/README.md). A platform component is
+    // domain-free: it may import sibling primitives and generic `lib/` helpers, never a feature
+    // component (`../Feed`) and never a domain API slice. Without this rule the boundary erodes on
+    // the first "just this once" import and the directory silently becomes another components/.
+    files: ["src/components/ui/**/*.{ts,tsx}"],
+    rules: {
+      "no-restricted-imports": [
+        "error",
+        {
+          // NOTE the String.raw: these are REGEX sources, and in a plain "..." literal `\.` is an
+          // unknown escape that collapses to a bare `.` — the any-char wildcard. The first cut of
+          // this rule shipped that way and matched far less than it read like (E10 review round 1).
+          patterns: [
+            {
+              // `../X` (exactly one level up = a feature component). A `regex` rather than a glob:
+              // eslint matches `patterns` gitignore-style, where `../*` also swallows `../../lib/x`.
+              regex: String.raw`^\.\./(?!\.\./)`,
+              message:
+                "components/ui/ is domain-free: a platform component may not import a feature component. Invert the dependency (take a prop/render-prop) or keep the component outside ui/.",
+            },
+            {
+              // The same file by its OTHER spelling. `../../components/Feed` resolves exactly where
+              // `../Feed` does, so the rule above is only half the boundary; `ui/` is carved out
+              // because a sibling primitive is the one thing this path may legitimately name.
+              regex: String.raw`^\.\./\.\./components/(?!ui/)`,
+              message:
+                "components/ui/ is domain-free: a platform component may not import a feature component. Invert the dependency (take a prop/render-prop) or keep the component outside ui/.",
+            },
+            {
+              // `(/|$)` so the BARREL counts too: `../../lib/api` is the spelling every feature
+              // component uses, and a `/`-anchored pattern let exactly that one through.
+              regex: String.raw`^\.\./\.\./lib/api(/|$)`,
+              message:
+                "components/ui/ is domain-free: a platform component may not call a domain API slice. Take the data as props.",
+            },
+          ],
+        },
+      ],
+    },
+  },
   prettier,
 );

frontend/src/App.keymap.contract.test.ts

@@ -0,0 +1,33 @@
+// The global Shift+W wiring, pinned at its call site.
+//
+// What this is: a source contract, the same idiom as uiBoundary.contract.test.ts — a structural rule
+// asserted directly rather than left to prose. What it is NOT: a behaviour test. The behaviour lives
+// in history.dom.test.ts and history.burial.dom.test.ts, which drive `navigateOverOverlays` against
+// real overlay entries; the end-to-end gesture (Shift+W over an open player, then Back) is a browser
+// check, because jsdom reproduces history ordering only as bookkeeping.
+//
+// It exists because the composition line itself was unpinned: App.tsx is the one module no test
+// renders (main.tsx lazy-imports it and nothing else does), globalKeymap.dom.test.tsx drives the
+// hook with its OWN handler, and history.dom.test.ts drives the helper with its own navigate — so
+// dropping `navigateOverOverlays` from App left all 818 tests green while the user-visible bug came
+// straight back (round 2, verified by running that revert).
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const APP = readFileSync(fileURLToPath(new URL("./App.tsx", import.meta.url)), "utf8");
+
+describe("App · global keymap wiring", () => {
+  it("routes the global home shortcut through navigateOverOverlays", () => {
+    const call = /useGlobalKeymap\(([\s\S]*?)\);/.exec(APP)?.[1];
+    // A rename or a move is a legitimate change — but then this test is the thing that has to be
+    // updated deliberately, which is the whole point of pinning it.
+    expect(
+      call,
+      "App.tsx no longer calls useGlobalKeymap in a shape this test can read",
+    ).toBeTypeOf("string");
+    expect(call).toContain("navigateOverOverlays");
+    expect(call).toContain('setPage("home")');
+  });
+});

frontend/src/App.tsx

@@ -29,12 +29,16 @@ import Welcome from "./components/Welcome";
 import SetupWizard from "./components/SetupWizard";
 import Header from "./components/Header";
 import NavSidebar from "./components/NavSidebar";
-import BackToTop from "./components/BackToTop";
-import PageShell from "./components/PageShell";
+import BackToTop from "./components/ui/BackToTop";
+import PageShell from "./components/ui/PageShell";
 import GlassTuner from "./components/GlassTuner";
 import ChatDock from "./components/ChatDock";
-import Toaster from "./components/Toaster";
-import { StateMessage } from "./components/QueryState";
+import Toaster from "./components/ui/Toaster";
+import KeyboardHelp from "./components/ui/KeyboardHelp";
+import AppCommandPalette from "./components/AppCommandPalette";
+import { useGlobalKeymap } from "./lib/keymap";
+import { navigateOverOverlays } from "./lib/history";
+import { StateMessage } from "./components/ui/QueryState";
 import ErrorDialog from "./components/ErrorDialog";
 import VersionBanner from "./components/VersionBanner";
 import DemoBanner from "./components/DemoBanner";
@@ -134,6 +138,18 @@ export default function App() {
     refetchInterval: (query) => (query.state.data ? 60_000 : false),
   });
 
+  // The `global` key scope: `h` opens the cheat sheet, Mod+K the jump-to palette, Shift+W jumps to
+  // Home ("mit nézzek?"). Bound only once signed in, because that is where the overlays are mounted
+  // (bottom of this tree) and where the modules exist at all — see useGlobalKeymap on why binding it
+  // above the signed-out branch is worse than not binding it.
+  // Through `navigateOverOverlays`, because a global key can fire while an overlay is open and does
+  // not know it: the page change unmounts the player (it lives inside the module), whose reconcile
+  // then reclaimed the entry this push had just made — Shift+W over a playing video closed the
+  // player and snapped straight back to the feed. `setPage`'s boolean is load-bearing here, not
+  // decoration: pressed while ALREADY on Home (the default landing page) it navigates nowhere, and
+  // burying the open player's entry under a push that never happened orphaned it — see `buryUnder`.
+  useGlobalKeymap(!!meQuery.data, () => navigateOverOverlays(() => setPage("home")));
+
   // Pin this tab to whatever account it first loaded as. Without this, a tab that never picked
   // an account (it was riding the session's default) would silently swap identity when ANOTHER
   // tab changes the default — e.g. that other tab adds/switches an account. Once pinned, this
@@ -263,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"));
           },
         },
       });
@@ -412,6 +429,11 @@ export default function App() {
             (collapsed or expanded) without tracking its width. */}
         <Toaster />
       </div>
+      {/* The two app-wide overlays: the keyboard cheat sheet (`h`) and the jump-to palette (Mod+K).
+          Mounted once, outside the page area, so every surface answers "what can I press here" and
+          "take me to X" the same way. Their keys are bound by useGlobalKeymap above. */}
+      <KeyboardHelp />
+      <AppCommandPalette />
       {meQuery.data && !meQuery.data.is_demo && <ChatDock meId={meQuery.data.id} />}
       <Suspense fallback={null}>
         {aboutOpen && (

frontend/src/components/About.tsx

@@ -4,7 +4,8 @@ import { useTranslation } from "react-i18next";
 import { Info, Sparkles } from "lucide-react";
 import { api } from "../lib/api";
 import { FRONTEND_VERSION, FRONTEND_SHA, FRONTEND_BUILD_DATE } from "../lib/version";
-import Modal from "./Modal";
+import { Button } from "./ui/Button";
+import Modal from "./ui/Modal";
 
 function fmtDate(d?: string | null): string {
   if (!d) return "—";
@@ -70,12 +71,9 @@ export default function About({
         ))}
       </div>
 
-      <button
-        onClick={onOpenReleaseNotes}
-        className="mt-4 w-full inline-flex items-center justify-center gap-2 px-4 py-2 rounded-xl font-semibold btn-primary transition"
-      >
+      <Button variant="primary" size="lg" className="mt-4 w-full" onClick={onOpenReleaseNotes}>
         <Sparkles className="w-4 h-4" /> {t("about.whatsNew")}
-      </button>
+      </Button>
     </Modal>
   );
 }

frontend/src/components/AboutCell.tsx

@@ -3,7 +3,7 @@ import { useQuery } from "@tanstack/react-query";
 import { qk } from "../lib/queryKeys";
 import { api } from "../lib/api";
 import ChannelAboutContent from "./ChannelAbout";
-import { PopoverSurface, useAnchoredPopover } from "./AnchoredPopover";
+import { PopoverSurface, useAnchoredPopover } from "./ui/AnchoredPopover";
 
 /**
  * A channel-description cell: one truncated line in the table, revealing the FULL channel "About"

frontend/src/components/AccountPanel.tsx

@@ -2,8 +2,8 @@ import { useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { Check, Clock, Copy, Globe, KeyRound, Mail, Send, ShieldAlert } from "lucide-react";
-import Modal from "./Modal";
-import { LoadingState, StateMessage } from "./QueryState";
+import Modal from "./ui/Modal";
+import { LoadingState, StateMessage } from "./ui/QueryState";
 import { api } from "../lib/api";
 import { qk } from "../lib/queryKeys";
 import { notify } from "../lib/notifications";

frontend/src/components/ActionMenu.tsx

@@ -1,78 +0,0 @@
-import { useState, type ReactNode } from "react";
-import { MoreHorizontal } from "lucide-react";
-import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./AnchoredPopover";
-
-// A reusable "⋯ more actions" overflow menu: a compact trigger that opens a list of one-shot actions.
-// Built on the R8 AnchoredPopover platform (arrows/typeahead/Escape/anchor-flip), same as ViewSwitcher
-// and LanguageSwitcher. Use it to keep occasional actions out of a crowded toolbar. The items are
-// fire-and-close (`onSelect`); a `disabled` item (e.g. a mutation already in flight) is inert.
-
-export interface ActionMenuItem {
-  id: string;
-  label: string;
-  icon?: ReactNode; // an element (so a caller can swap in a spinning icon while pending)
-  onSelect: () => void;
-  disabled?: boolean;
-  title?: string; // optional native tooltip (carries a longer hint the label alone can't)
-}
-
-export default function ActionMenu({
-  items,
-  ariaLabel,
-  className,
-  trigger,
-}: {
-  items: readonly ActionMenuItem[];
-  /** Accessible name for the trigger (e.g. "Catalog actions"). */
-  ariaLabel: string;
-  /** Trigger className override; omit for the default glass ⋯ icon button. */
-  className?: string;
-  /** Custom trigger content; omit for the default ⋯ icon. */
-  trigger?: ReactNode;
-}) {
-  const [open, setOpen] = useState(false);
-  // A disabled item (a mutation already in flight) is skipped by roving keyboard nav automatically:
-  // PopoverItem renders it as a native `disabled` button, which useListNavigation reads and never
-  // focuses. No explicit disabledIndices needed. See ActionMenu.dom.test.tsx for the guard.
-  const pop = useAnchoredPopover({ open, onOpenChange: setOpen, placement: "bottom-end" });
-  return (
-    <>
-      <button
-        type="button"
-        ref={pop.refs.setReference}
-        {...pop.getReferenceProps()}
-        aria-label={ariaLabel}
-        title={ariaLabel}
-        className={
-          className ??
-          "glass-card glass-hover flex items-center justify-center rounded-xl p-2 text-sm transition"
-        }
-      >
-        {trigger ?? <MoreHorizontal className="h-5 w-5" aria-hidden="true" />}
-      </button>
-      <PopoverSurface
-        popover={pop}
-        ariaLabel={ariaLabel}
-        className="glass-menu min-w-52 rounded-xl p-1.5 animate-[popIn_0.16s_ease]"
-      >
-        {items.map((it) => (
-          <PopoverItem
-            key={it.id}
-            role="menuitem"
-            disabled={it.disabled}
-            label={it.label}
-            title={it.title}
-            onSelect={() => {
-              it.onSelect();
-              setOpen(false);
-            }}
-            className="flex w-full items-center gap-2.5 rounded-lg px-2 py-1.5 text-left text-sm outline-hidden transition disabled:opacity-50"
-          >
-            {it.icon && <span className="shrink-0 text-muted">{it.icon}</span>}
-            <span className="flex-1 truncate">{it.label}</span>
-          </PopoverItem>
-        ))}
-      </PopoverSurface>
-    </>
-  );
-}

frontend/src/components/ActiveFilterChips.tsx

@@ -3,8 +3,8 @@ import { useTranslation } from "react-i18next";
 import { Filter, X } from "lucide-react";
 import type { ActiveFilter } from "../lib/useActiveFilters";
 import { decideChipLayout } from "../lib/chipOverflow";
-import { useChipOverflowFit } from "../lib/useChipOverflowFit";
-import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./AnchoredPopover";
+import { chipLaneClass, useChipOverflowFit } from "../lib/useChipOverflowFit";
+import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./ui/AnchoredPopover";
 
 // The applied-filter row above the feed: every narrowing currently in force, each removable on its
 // own. It exists because the filter panel now sits collapsed as a tab — without this you'd have to
@@ -172,7 +172,7 @@ export default function ActiveFilterChips({
     <div
       ref={laneRef}
       data-testid="active-filter-chips"
-      className={`relative flex min-w-0 items-center gap-1.5 ${className ?? ""}`}
+      className={`${chipLaneClass} flex min-w-0 items-center gap-1.5 ${className ?? ""}`}
       aria-label={t("feed.chips.label")}
     >
       {/* Hidden mirror of the full set, used only to measure natural widths. Kept out of the a11y tree

frontend/src/components/AddToPlaylist.tsx

@@ -4,9 +4,10 @@ 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 "./AnchoredPopover";
+import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./ui/AnchoredPopover";
 
 // A small anchored menu for toggling a video's membership in the user's playlists, with inline
 // "new playlist" creation. Same shape as the channel tag editor (R8 S1's pilot): radio-style
@@ -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);
     }
   }

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([]);
+  });
+});

frontend/src/components/AdminUsers.tsx

@@ -26,17 +26,19 @@ import {
 import { notify } from "../lib/notifications";
 import { invalidateUserAccess, isEmailOff } from "../lib/adminUsers";
 import { ADMIN_USERS_TAB_KEY } from "../lib/adminUsersTab";
-import Tooltip from "./Tooltip";
-import InlineNotice from "./InlineNotice";
+import { Button } from "./ui/Button";
+import Tooltip from "./ui/Tooltip";
+import InlineNotice from "./ui/InlineNotice";
 import { Section } from "./ui/form";
-import SegmentedToggle from "./SegmentedToggle";
+import SegmentedToggle from "./ui/SegmentedToggle";
 import { LANGUAGES, type LangCode } from "../i18n";
-import { LoadingState, StateMessage } from "./QueryState";
+import { LoadingState, StateMessage } from "./ui/QueryState";
 import AccountPanel from "./AccountPanel";
 import { useConfirm } from "./ConfirmProvider";
-import Tabs, { usePersistedTab } from "./Tabs";
-import { PageToolbar } from "./PageShell";
+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
@@ -119,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),
@@ -128,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({
@@ -145,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),
@@ -155,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) => {
@@ -244,14 +257,16 @@ function UsersRoles({ me }: { me: Me }) {
                           : t("users.roles.makeAdmin")
                   }
                 >
-                  <button
+                  <Button
+                    variant="glass"
+                    size="xs"
+                    className="shrink-0"
                     onClick={() => onToggle(u)}
                     disabled={u.is_demo || self || pendingIds.has(u.id)}
-                    className="shrink-0 glass-card glass-hover inline-flex items-center gap-1 px-2.5 py-1.5 rounded-lg text-xs disabled:opacity-40 transition"
+                    icon={<Shield className="w-3.5 h-3.5" />}
                   >
-                    <Shield className="w-3.5 h-3.5" />
                     {u.role === "admin" ? t("users.roles.makeUser") : t("users.roles.makeAdmin")}
-                  </button>
+                  </Button>
                 </Tooltip>
                 <Tooltip
                   hint={
@@ -264,36 +279,36 @@ function UsersRoles({ me }: { me: Me }) {
                           : t("users.suspend.action")
                   }
                 >
-                  <button
+                  <Button
+                    variant={u.is_suspended ? "outline-warn" : "outline"}
+                    size="icon-sm"
+                    className="shrink-0"
                     onClick={() => onSuspend(u)}
                     disabled={u.is_demo || self || pendingIds.has(u.id)}
                     aria-label={
                       u.is_suspended ? t("users.suspend.undoAction") : t("users.suspend.action")
                     }
-                    className={`shrink-0 p-1.5 rounded-lg border disabled:opacity-40 transition ${
-                      u.is_suspended
-                        ? "border-warn/40 text-warn hover:bg-warn/10"
-                        : "border-border text-muted hover:text-warn"
-                    }`}
-                  >
-                    {u.is_suspended ? (
-                      <RotateCcw className="w-4 h-4" />
-                    ) : (
-                      <Ban className="w-4 h-4" />
-                    )}
-                  </button>
+                    icon={
+                      u.is_suspended ? (
+                        <RotateCcw className="w-4 h-4" />
+                      ) : (
+                        <Ban className="w-4 h-4" />
+                      )
+                    }
+                  />
                 </Tooltip>
                 <Tooltip
                   hint={u.is_demo || self ? t("users.delete.locked") : t("users.delete.action")}
                 >
-                  <button
+                  <Button
+                    variant="outline-danger"
+                    size="icon-sm"
+                    className="shrink-0"
                     onClick={() => onDelete(u)}
                     disabled={u.is_demo || self || pendingIds.has(u.id)}
                     aria-label={t("users.delete.action")}
-                    className="shrink-0 p-1.5 rounded-lg border border-border text-muted hover:text-danger disabled:opacity-40 transition"
-                  >
-                    <Trash2 className="w-4 h-4" />
-                  </button>
+                    icon={<Trash2 className="w-4 h-4" />}
+                  />
                 </Tooltip>
               </div>
             );
@@ -435,25 +450,28 @@ function PendingAccessRowView({
       </div>
       {!row.email_verified && (
         <Tooltip hint={t("users.pendingAccess.resendHint")}>
-          <button
+          <Button
+            variant="outline"
+            size="icon-sm"
+            className="shrink-0"
             onClick={onResend}
             disabled={busy}
-            className="shrink-0 p-1.5 rounded-lg border border-border text-muted hover:text-fg disabled:opacity-50 transition"
             aria-label={t("users.pendingAccess.resend")}
-          >
-            <Send className="w-4 h-4" />
-          </button>
+            icon={<Send className="w-4 h-4" />}
+          />
         </Tooltip>
       )}
       {row.can_activate && (
         <Tooltip hint={t("users.pendingAccess.activateHint")}>
-          <button
+          <Button
+            variant="outline-accent"
+            size="xs"
+            className="shrink-0"
             onClick={onActivate}
             disabled={busy}
-            className="shrink-0 px-2.5 py-1.5 rounded-lg border border-accent/40 text-accent text-xs font-medium hover:bg-accent/10 disabled:opacity-50 transition"
           >
             {t("users.pendingAccess.activate")}
-          </button>
+          </Button>
         </Tooltip>
       )}
     </div>
@@ -512,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),
@@ -520,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({
@@ -624,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 ?? [];
@@ -673,12 +691,14 @@ function AdminInvites() {
           placeholder={t("settings.invites.addPlaceholder")}
           className="flex-1 min-w-0 bg-surface border border-border rounded-xl px-3 py-2 text-sm focus:outline-hidden focus:ring-2 focus:ring-accent/40"
         />
-        <button
+        <Button
           type="submit"
-          className="shrink-0 glass-card glass-hover flex items-center gap-1.5 px-3 py-2 rounded-xl text-sm transition"
+          variant="glass"
+          className="shrink-0"
+          icon={<UserPlus className="w-4 h-4" />}
         >
-          <UserPlus className="w-4 h-4" /> {t("settings.invites.add")}
-        </button>
+          {t("settings.invites.add")}
+        </Button>
       </form>
 
       {decided.length > 0 && (
@@ -772,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),
@@ -780,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({
@@ -798,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 ?? [];
@@ -820,14 +840,15 @@ function AdminDemo() {
                 )}
               </div>
               <Tooltip hint={t("settings.demo.removeHint")}>
-                <button
+                <Button
+                  variant="outline-danger"
+                  size="icon-sm"
+                  className="shrink-0"
                   onClick={() => onRemove(r)}
                   disabled={remove.isPending}
-                  className="shrink-0 p-1.5 rounded-lg border border-border text-muted hover:text-danger disabled:opacity-50 transition"
                   aria-label={t("settings.demo.remove")}
-                >
-                  <Trash2 className="w-4 h-4" />
-                </button>
+                  icon={<Trash2 className="w-4 h-4" />}
+                />
               </Tooltip>
             </div>
           ))}
@@ -848,12 +869,9 @@ function AdminDemo() {
           placeholder={t("settings.demo.addPlaceholder")}
           className="flex-1 min-w-0 bg-surface border border-border rounded-xl px-3 py-2 text-sm focus:outline-hidden focus:ring-2 focus:ring-accent/40"
         />
-        <button
-          type="submit"
-          className="shrink-0 glass-card glass-hover flex items-center gap-1.5 px-3 py-2 rounded-xl text-sm transition"
-        >
+        <Button variant="glass" size="md" className="shrink-0" type="submit">
           <UserPlus className="w-4 h-4" /> {t("settings.demo.add")}
-        </button>
+        </Button>
       </form>
 
       <div className="mt-4 pt-3 border-t border-border">
@@ -909,24 +927,26 @@ function InviteRow({
         )}
       </div>
       <Tooltip hint={t("settings.invites.approveHint")}>
-        <button
+        <Button
+          variant="outline-accent"
+          size="icon-sm"
+          className="shrink-0"
           onClick={onApprove}
           disabled={busy}
-          className="shrink-0 p-1.5 rounded-lg border border-accent/40 text-accent hover:bg-accent/10 disabled:opacity-50 transition"
           aria-label={t("settings.invites.approve")}
-        >
-          <Check className="w-4 h-4" />
-        </button>
+          icon={<Check className="w-4 h-4" />}
+        />
       </Tooltip>
       <Tooltip hint={t("settings.invites.denyHint")}>
-        <button
+        <Button
+          variant="outline-danger"
+          size="icon-sm"
+          className="shrink-0"
           onClick={onDeny}
           disabled={busy}
-          className="shrink-0 p-1.5 rounded-lg border border-border text-muted hover:text-danger disabled:opacity-50 transition"
           aria-label={t("settings.invites.deny")}
-        >
-          <X className="w-4 h-4" />
-        </button>
+          icon={<X className="w-4 h-4" />}
+        />
       </Tooltip>
       {/* Deny records a decision and keeps the row; delete forgets the address. Once an account
           exists for it the row is that account's approval gate, so it is managed from Users & roles
@@ -946,14 +966,15 @@ function InviteRow({
         </button>
       ) : (
         <Tooltip hint={t("settings.invites.deleteHint")}>
-          <button
+          <Button
+            variant="outline-danger"
+            size="icon-sm"
+            className="shrink-0"
             onClick={onDelete}
             disabled={busy}
-            className="shrink-0 p-1.5 rounded-lg border border-border text-muted hover:text-danger disabled:opacity-50 transition"
             aria-label={t("settings.invites.deleteLabel", { email: inv.email })}
-          >
-            <Trash2 className="w-4 h-4" />
-          </button>
+            icon={<Trash2 className="w-4 h-4" />}
+          />
         </Tooltip>
       )}
     </div>

frontend/src/components/AppCommandPalette.tsx

@@ -0,0 +1,174 @@
+import { useMemo } from "react";
+import { useTranslation } from "react-i18next";
+import { useQuery } from "@tanstack/react-query";
+import { Keyboard, ListVideo, Palette, Sparkles, Tv } from "lucide-react";
+import CommandPalette, { type CommandGroup } from "./ui/CommandPalette";
+import { api } from "../lib/api";
+import { qk } from "../lib/queryKeys";
+import { useMe } from "../lib/useMe";
+import { moduleDef, moduleOrder } from "../lib/modules";
+import { SCHEMES, type Scheme } from "../lib/theme";
+import { closePalette, toggleKeyboardHelp, usePaletteOpen } from "../lib/keymap";
+import { requestSurprise } from "../lib/homeIntent";
+import { useNavigationActions } from "./NavigationProvider";
+import { usePlaylistsActions } from "./PlaylistsProvider";
+import { usePrefs } from "./PrefsProvider";
+import { useSavedViews } from "./SavedViewsProvider";
+
+// What Ctrl/Cmd+K can reach. The generic list/filter/keyboard shell is `ui/CommandPalette`; this is
+// the domain half — the layer boundary says a primitive may not import `lib/api` or a module.
+//
+// Scope decided with the product owner (2026-09-05): navigation + app-wide ACTIONS. The actions here
+// are the reversible, local ones — the shortcuts sheet and the theme. Deliberately NOT here: "Sync
+// from YouTube". It is a long-running job against a quota, it wants the progress and error surface
+// the Channels page already gives it, and one mistyped Enter is a worse failure than the walk it
+// would have saved.
+//
+// Saved views come from whichever module owns the current SavedViewsProvider source (feed on the
+// feed, Plex on Plex), i.e. exactly the views that are applicable where you stand.
+export default function AppCommandPalette() {
+  const { t } = useTranslation();
+  const open = usePaletteOpen();
+  const me = useMe();
+  const { setPage, openChannel } = useNavigationActions();
+  const { setSelectedId } = usePlaylistsActions();
+  const { theme, setTheme } = usePrefs();
+  const savedViews = useSavedViews();
+
+  // Only fetch the lists while the palette is actually open — it is a rarely-opened surface and
+  // these are otherwise the feed's and the playlist rail's own queries, shared through the cache.
+  const channelsQ = useQuery({
+    queryKey: qk.channels(),
+    queryFn: () => api.channels(),
+    enabled: open,
+  });
+  const playlistsQ = useQuery({
+    queryKey: qk.playlists(),
+    queryFn: () => api.playlists(),
+    enabled: open,
+  });
+
+  const groups = useMemo<CommandGroup[]>(() => {
+    const out: CommandGroup[] = [];
+
+    // Modules, in nav-rail order and gated by the account — the registry decides, not this file.
+    if (me) {
+      const pages = [...moduleOrder(me), "settings" as const];
+      out.push({
+        id: "modules",
+        label: t("palette.groups.modules"),
+        items: pages.map((page) => {
+          const def = moduleDef(page);
+          const Icon = def.icon;
+          return {
+            id: `page:${page}`,
+            label: t(def.labelKey),
+            icon: <Icon className="w-4 h-4" />,
+            // The longer tab title is a second name for the same place ("Channel manager" for
+            // "Channels"), so match on it even though the row shows the short one.
+            keywords: def.titleKey ? t(def.titleKey) : "",
+            run: () => setPage(page),
+          };
+        }),
+      });
+    }
+
+    const channels = channelsQ.data ?? [];
+    if (channels.length > 0) {
+      out.push({
+        id: "channels",
+        label: t("palette.groups.channels"),
+        items: channels
+          .filter((c) => !c.hidden)
+          .map((c) => ({
+            id: `channel:${c.id}`,
+            label: c.title ?? c.id,
+            hint: c.handle ?? undefined,
+            icon: <Tv className="w-4 h-4" />,
+            keywords: c.handle ?? "",
+            run: () => openChannel(c.id, c.title ?? undefined),
+          })),
+      });
+    }
+
+    const playlists = playlistsQ.data ?? [];
+    if (playlists.length > 0) {
+      out.push({
+        id: "playlists",
+        label: t("palette.groups.playlists"),
+        items: playlists.map((p) => ({
+          id: `playlist:${p.id}`,
+          label: p.name,
+          hint: t("palette.videoCount", { count: p.item_count }),
+          icon: <ListVideo className="w-4 h-4" />,
+          run: () => {
+            setSelectedId(p.id);
+            setPage("playlists");
+          },
+        })),
+      });
+    }
+
+    if (savedViews.views.length > 0) {
+      out.push({
+        id: "views",
+        label: t("palette.groups.views"),
+        items: savedViews.views.map((v) => ({
+          id: `view:${v.id}`,
+          label: v.name,
+          run: () => savedViews.apply(v),
+        })),
+      });
+    }
+
+    out.push({
+      id: "actions",
+      label: t("palette.groups.actions"),
+      items: [
+        // "Meglepetés" — Home's reroll, reachable from anywhere (E24). There is deliberately no
+        // second "Mit nézzek?" row beside it: the Home module row above ALREADY matches that phrase,
+        // because the palette searches a module's descriptive `titleKey` too and Home's is literally
+        // "Mit nézzek most?". A row that navigates where an existing row already navigates would be
+        // duplication in the one list whose whole job is to be scanned quickly.
+        {
+          id: "action:surprise",
+          label: t("palette.actions.surprise"),
+          icon: <Sparkles className="w-4 h-4" />,
+          keywords: t("home.title"),
+          run: () => {
+            setPage("home");
+            requestSurprise();
+          },
+        },
+        {
+          id: "action:shortcuts",
+          label: t("keys.title"),
+          icon: <Keyboard className="w-4 h-4" />,
+          run: toggleKeyboardHelp,
+        },
+        ...SCHEMES.map((s) => ({
+          id: `action:theme:${s.id}`,
+          label: t("palette.theme", { name: s.name }),
+          icon: <Palette className="w-4 h-4" />,
+          keywords: s.id,
+          run: () => setTheme({ ...theme, scheme: s.id as Scheme }),
+        })),
+      ],
+    });
+
+    return out;
+  }, [
+    t,
+    me,
+    channelsQ.data,
+    playlistsQ.data,
+    savedViews,
+    theme,
+    setTheme,
+    setPage,
+    openChannel,
+    setSelectedId,
+  ]);
+
+  return <CommandPalette open={open} onClose={closePalette} groups={groups} />;
+}

frontend/src/components/AuditLog.tsx

@@ -6,11 +6,13 @@ import { Trash2 } from "lucide-react";
 import { api } from "../lib/api";
 import { notify } from "../lib/notifications";
 import { LS } from "../lib/storage";
+import { Button } from "./ui/Button";
 import { Section } from "./ui/form";
 import { useConfirm } from "./ConfirmProvider";
-import DataTable from "./DataTable";
-import { LoadingState, StateMessage } from "./QueryState";
+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
@@ -35,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 (
@@ -72,14 +74,15 @@ export default function AuditLog() {
               persistKey={LS.auditTable}
               controlsPosition="top"
               controlsLeading={
-                <button
+                <Button
+                  variant="outline-danger"
+                  size="xs"
                   onClick={onClear}
                   disabled={clear.isPending}
-                  className="inline-flex items-center gap-1.5 text-xs px-2.5 py-1.5 rounded-lg border border-border text-muted hover:text-danger disabled:opacity-50 transition"
+                  icon={<Trash2 className="w-3.5 h-3.5" />}
                 >
-                  <Trash2 className="w-3.5 h-3.5" />
                   {t("audit.clear")}
-                </button>
+                </Button>
               }
               emptyText={t("audit.empty")}
             />

frontend/src/components/ChannelDiscovery.tsx

@@ -12,15 +12,15 @@ import { useCardPager } from "../lib/useCardPager";
 import { subsColumn } from "./channelColumns";
 import { notify } from "../lib/notifications";
 import { notifyYouTubeActionError } from "../lib/youtubeErrors";
-import Tooltip from "./Tooltip";
+import Tooltip from "./ui/Tooltip";
 import ChannelLink from "./ChannelLink";
 import AboutCell from "./AboutCell";
-import DataTable, { type Column } from "./DataTable";
+import DataTable, { type Column } from "./ui/DataTable";
 import ChannelLayoutGrid from "./ChannelLayoutGrid";
-import { LoadingState, StateMessage } from "./QueryState";
-import ColumnSortControl from "./ColumnSortControl";
-import Pager from "./Pager";
-import { PageToolbar } from "./PageShell";
+import { LoadingState, StateMessage } from "./ui/QueryState";
+import ColumnSortControl from "./ui/ColumnSortControl";
+import Pager from "./ui/Pager";
+import { PageToolbar } from "./ui/PageShell";
 import { useConfirm } from "./ConfirmProvider";
 import { useChannelLayout } from "./ChannelsProvider";
 

frontend/src/components/ChannelLayoutGrid.tsx

@@ -1,7 +1,7 @@
 import { Fragment } from "react";
 import { useTranslation } from "react-i18next";
-import { type Column } from "./DataTable";
-import VirtualGrid from "./VirtualGrid";
+import { type Column } from "./ui/DataTable";
+import VirtualGrid from "./ui/VirtualGrid";
 import { CHANNEL_LAYOUT_SPEC } from "../lib/channelLayout";
 
 // The channel manager's `cards` layout (E4 S3), built by reusing the SAME `Column<T>` render closures
@@ -24,6 +24,9 @@ interface ChannelLayoutGridProps<T> {
   /** Column key rendered as the action cluster, pinned to the card's bottom edge. */
   actionsKey?: string;
   rowClassName?: (row: T) => string;
+  /** Extra DOM props per card — same escape hatch, same single consumer, as `DataTable.rowProps`, so
+   *  a channel answers the right-click in the card layout exactly as it does in the table. */
+  rowProps?: (row: T) => Record<string, unknown>;
   emptyText?: string;
 }
 
@@ -35,6 +38,7 @@ export default function ChannelLayoutGrid<T>({
   aboutKey,
   actionsKey,
   rowClassName,
+  rowProps,
   emptyText,
 }: ChannelLayoutGridProps<T>) {
   const { t } = useTranslation();
@@ -50,6 +54,7 @@ export default function ChannelLayoutGrid<T>({
 
   const renderCard = (row: T) => (
     <div
+      {...rowProps?.(row)}
       className={`glass-card rounded-xl p-3 h-full flex flex-col gap-2 ${rowClassName?.(row) ?? ""}`}
     >
       <div className="flex items-start justify-between gap-2">
@@ -84,7 +89,7 @@ export default function ChannelLayoutGrid<T>({
       items={rows}
       getKey={rowKey}
       minCol={spec.minCol}
-      maxCol={null}
+      colMaxWidth={null}
       rowEst={spec.rowEst}
       renderItem={renderCard}
     />

frontend/src/components/ChannelLink.tsx

@@ -1,7 +1,7 @@
 import { useTranslation } from "react-i18next";
 import { ExternalLink } from "lucide-react";
-import Avatar from "./Avatar";
-import Tooltip from "./Tooltip";
+import Avatar from "./ui/Avatar";
+import Tooltip from "./ui/Tooltip";
 import { channelYouTubeUrl } from "../lib/format";
 
 // Avatar + channel name + "open on YouTube" link, shared by the Channel manager and the

frontend/src/components/ChannelNameLink.dom.test.tsx

@@ -0,0 +1,109 @@
+// @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";
+
+vi.mock("react-i18next", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-i18next")>()),
+  useTranslation: () => ({ t: (key: string) => key }),
+}));
+
+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 }],
+    // 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.
+    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");
+  });
+
+  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();
+  });
+});

frontend/src/components/ChannelNameLink.tsx

@@ -0,0 +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). 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).
+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;
+  /** 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();
+      }}
+    >
+      {/* 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;

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));
+  });
+});

frontend/src/components/ChannelPage.tsx

@@ -2,10 +2,10 @@ 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 "./PriorityStepper";
+import { PriorityStepper } from "./ui/PriorityStepper";
 import { useChannelPriority } from "../lib/useChannelPriority";
 import {
   ArrowLeft,
@@ -20,11 +20,11 @@ import {
   RefreshCw,
   SlidersHorizontal,
 } from "lucide-react";
-import Avatar from "./Avatar";
-import Tabs from "./Tabs";
+import Avatar from "./ui/Avatar";
+import Tabs from "./ui/Tabs";
 import Feed from "./Feed";
 import ChannelAboutContent from "./ChannelAbout";
-import { PageToolbar, PageToolbarSlot } from "./PageShell";
+import { PageToolbar, PageToolbarSlot } from "./ui/PageShell";
 import { useFeedFilters } from "./FeedFiltersProvider";
 import { useConfirm } from "./ConfirmProvider";
 import { notify } from "../lib/notifications";
@@ -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);
@@ -416,14 +420,14 @@ export default function ChannelPage({
                 <ExternalLink className="w-4 h-4" />
               </a>
               {ch?.subscribed && (
-                <button
+                <Button
+                  variant="outline"
+                  size="icon"
                   onClick={onShowInFeed}
                   title={t("channel.showInFeed")}
                   aria-label={t("channel.showInFeed")}
-                  className="inline-flex items-center justify-center w-9 h-9 rounded-lg text-muted hover:text-accent border border-border hover:border-accent transition"
-                >
-                  <SlidersHorizontal className="w-4 h-4" />
-                </button>
+                  icon={<SlidersHorizontal className="w-4 h-4" />}
+                />
               )}
               {ch?.subscribed && !me.is_demo && (
                 <div className="inline-flex items-center gap-1.5 h-9 px-2.5 rounded-lg border border-border">

frontend/src/components/ChannelPicker.tsx

@@ -2,7 +2,7 @@ import { useTranslation } from "react-i18next";
 import { useQuery } from "@tanstack/react-query";
 import { qk } from "../lib/queryKeys";
 import { api, type FeedFilters } from "../lib/api";
-import Combobox, { type ComboboxOption } from "./Combobox";
+import Combobox, { type ComboboxOption } from "./ui/Combobox";
 
 // Pick channels to narrow the feed to — several OR together, so every other filter then applies
 // across all of them. Until this existed the filter was settable only via a shared "?channel=" link:

frontend/src/components/ChannelStatsPopover.tsx

@@ -12,7 +12,7 @@ import {
 import { useTranslation } from "react-i18next";
 import { type MyStatus } from "../lib/api";
 import { formatEta } from "../lib/format";
-import { PopoverSurface, useAnchoredPopover } from "./AnchoredPopover";
+import { PopoverSurface, useAnchoredPopover } from "./ui/AnchoredPopover";
 
 // The channel-manager catalog stats, collapsed from a crowded inline row into a compact "Stats" chip
 // that reveals the numbers on hover (reuses the AnchoredPopover hover mode). One row per stat, each

frontend/src/components/ChannelTags.tsx

@@ -2,10 +2,10 @@ import { useEffect, useRef, useState } from "react";
 import { Check, Plus, Sparkles, X } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { type Tag } from "../lib/api";
-import { useAnchoredPopover, PopoverSurface, PopoverItem } from "./AnchoredPopover";
+import { useAnchoredPopover, PopoverSurface, PopoverItem } from "./ui/AnchoredPopover";
 import { useScrollFade } from "../lib/useScrollFade";
 import { fitChipsWithPill } from "../lib/chipOverflow";
-import { useChipOverflowFit } from "../lib/useChipOverflowFit";
+import { chipLaneClass, useChipOverflowFit } from "../lib/useChipOverflowFit";
 
 // The channel tag surface, shared by the channel manager (table + cards) and the channel detail
 // page. Built on the R8 popover platform. Two design goals it fixes over the old inline TagsCell:
@@ -129,7 +129,7 @@ function SuggestedChipsLane({
   }, [hidden, overflowOpen]);
 
   return (
-    <div className="relative flex items-center gap-1 min-w-0 flex-1">
+    <div className={`${chipLaneClass} flex items-center gap-1 min-w-0 flex-1`}>
       {/* Hidden measurer — real ghost chips at natural width so the fit hook reads their right edges. */}
       <div
         aria-hidden
@@ -374,7 +374,7 @@ export function ChannelTagsControl({
     // collapses the rest into "+N". (max-w-full lets a narrower card shrink it.) Unbounded, the row
     // takes its container's width, so a wide header shows the tags inline instead of collapsing them.
     <div
-      className={`relative flex items-center gap-1 min-w-0 ${bounded ? "w-48 max-w-full" : "w-full"}`}
+      className={`${chipLaneClass} flex items-center gap-1 min-w-0 ${bounded ? "w-48 max-w-full" : "w-full"}`}
     >
       {/* The add trigger LEADS the row — a stable left anchor that never moves as chips are added
           (they grow to its right), so its editor popover can't drift. Compact icon in the width-

frontend/src/components/Channels.tsx

@@ -6,30 +6,35 @@ 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";
 import { notify } from "../lib/notifications";
-import Tooltip from "./Tooltip";
-import DataTable from "./DataTable";
-import Tabs, { type TabDef } from "./Tabs";
+import { Button } from "./ui/Button";
+import Tooltip from "./ui/Tooltip";
+import DataTable from "./ui/DataTable";
+import Tabs, { type TabDef } from "./ui/Tabs";
 import ChannelLayoutGrid from "./ChannelLayoutGrid";
-import { LoadingState, StateMessage } from "./QueryState";
+import { ComfortPinMenu } from "./ComfortPinMenu";
+import { pinChannel } from "./comfortPin";
+import { useContextMenu } from "./ui/useContextMenu";
+import { LoadingState, StateMessage } from "./ui/QueryState";
 import { useChannelTagActions } from "../lib/useChannelTagActions";
 import { useTagSuggestions } from "./useTagSuggestions";
 import { useChannelPriority } from "../lib/useChannelPriority";
 import ViewSwitcher, { type ViewOption } from "./ViewSwitcher";
-import ColumnSortControl from "./ColumnSortControl";
-import FilterChipGroup from "./FilterChipGroup";
+import ColumnSortControl from "./ui/ColumnSortControl";
+import FilterChipGroup from "./ui/FilterChipGroup";
 import TagFilterChips, { type FilterChip } from "./TagFilterChips";
-import ActionMenu, { type ActionMenuItem } from "./ActionMenu";
+import ActionMenu, { type ActionMenuItem } from "./ui/ActionMenu";
 import ChannelStatsPopover from "./ChannelStatsPopover";
-import Pager from "./Pager";
+import Pager from "./ui/Pager";
 import { CHANNEL_LAYOUTS, type ChannelLayout } from "../lib/channelLayout";
 import { sortRows } from "../lib/columnSort";
-import { filterRows } from "./tableHeader";
+import { filterRows } from "./ui/tableHeader";
 import { useCardPager } from "../lib/useCardPager";
-import { PageToolbar } from "./PageShell";
+import { PageToolbar } from "./ui/PageShell";
 import ChannelDiscovery from "./ChannelDiscovery";
 import TagManager from "./TagManager";
 import { useConfirm } from "./ConfirmProvider";
@@ -178,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
@@ -411,6 +416,11 @@ export default function Channels() {
     />
   );
   const hasLayout = view === "subscribed" || view === "discovery";
+  // The comfort-shelf pin on a channel row (E24 S3). ONE menu for the list, shared by the table and
+  // the card layout — they are two paints of the same rows, so a right-click must mean the same
+  // thing in both. Only mounted under the SUBSCRIBED branch below: a discovery result is not a
+  // `Channel` row yet, so pinning one could only 404.
+  const pinMenu = useContextMenu<ManagedChannel>();
   // In cards there are no column headers to sort by, so a dropdown drives the SAME shared sort state
   // the table header uses (table ↔ cards stay in sync). Table mode keeps the header clicks.
   const sortControl = (
@@ -489,13 +499,15 @@ export default function Channels() {
               {/* The "TAGS" label IS the tags-editor trigger (pencil), replacing the separate
                   "Manage tags" button; the tooltip explains what tags are + that it's clickable. */}
               <Tooltip hint={t("channels.tags.yourTagsHint")}>
-                <button
+                <Button
+                  variant="outline"
+                  size="xs"
+                  className="shrink-0 uppercase tracking-wide"
                   onClick={() => setTagManagerOpen(true)}
-                  className="shrink-0 inline-flex items-center gap-1.5 rounded-lg border border-border px-2 py-1 text-xs uppercase tracking-wide text-muted transition hover:border-accent hover:text-accent"
+                  icon={<Pencil className="h-3 w-3" />}
                 >
-                  <Pencil className="h-3 w-3" />
                   {t("channels.tags.label")}
-                </button>
+                </Button>
               </Tooltip>
               <TagFilterChips chips={tagFilterChips} className="flex-1" />
               {tagFilter.length > 0 && (
@@ -518,12 +530,9 @@ export default function Channels() {
                     </span>
                   </Tooltip>
                   {highConfidence.length > 0 && (
-                    <button
-                      onClick={acceptAllHighConfidence}
-                      className="text-xs px-2 py-1 rounded-lg border border-border text-muted hover:border-accent hover:text-accent transition"
-                    >
+                    <Button variant="outline" size="xs" onClick={acceptAllHighConfidence}>
                       {t("channels.tags.acceptAllHigh", { count: highConfidence.length })}
-                    </button>
+                    </Button>
                   )}
                 </div>
               )}
@@ -613,6 +622,7 @@ export default function Channels() {
               onFiltersChange={setFilters}
               fixedLayout
               emptyText={t("channels.empty")}
+              rowProps={pinMenu.triggerProps}
             />
           ) : (
             <ChannelLayoutGrid
@@ -623,8 +633,14 @@ export default function Channels() {
               aboutKey="about"
               actionsKey="actions"
               emptyText={t("channels.empty")}
+              rowProps={pinMenu.triggerProps}
             />
           )}
+          <ComfortPinMenu
+            menu={pinMenu}
+            target={(c) => pinChannel(c.id)}
+            title={(c) => c.title ?? t("channels.row.thisChannel")}
+          />
         </div>
       )}
     </>

frontend/src/components/ChannelsProvider.tsx

@@ -22,8 +22,8 @@ import {
   hasChannelsParams,
   type ChannelsUrlState,
 } from "../lib/channelsUrlState";
-import { usePersistedTab } from "./Tabs";
-import type { FilterMap } from "./tableHeader";
+import { usePersistedTab } from "./ui/Tabs";
+import type { FilterMap } from "./ui/tableHeader";
 import { useNavigation, useNavigationActions } from "./NavigationProvider";
 import type { ChannelsView } from "./Channels";
 

frontend/src/components/ChatDock.tsx

@@ -13,9 +13,9 @@ import {
 } from "../lib/chatDock";
 import { onMessage, onUnread } from "../lib/messagesSocket";
 import * as e2ee from "../lib/e2ee";
-import Avatar from "./Avatar";
+import Avatar from "./ui/Avatar";
 import ChatThread from "./ChatThread";
-import Overlay from "./Overlay";
+import Overlay from "./ui/Overlay";
 
 // The Messenger-style floating chat dock: open conversations live here, bottom-right, across
 // page navigation (state persisted per user). Always mounted (for human users) so it also owns

frontend/src/components/ChatThread.tsx

@@ -3,12 +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 { LoadingState, StateMessage } from "./QueryState";
+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";
@@ -131,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"));
     },
   });
 
@@ -213,15 +219,16 @@ export default function ChatThread({
             placeholder={t("messages.writePlaceholder")}
             className="flex-1 resize-none max-h-28 bg-surface border border-border rounded-xl px-3 py-2 text-sm focus:outline-hidden focus:ring-2 focus:ring-accent/40"
           />
-          <button
+          <Button
+            variant="primary"
+            size="icon"
+            className="shrink-0"
             onClick={submit}
             disabled={!draft.trim() || send.isPending}
-            className="shrink-0 p-2.5 rounded-xl btn-primary transition disabled:opacity-40"
             aria-label={t("messages.send")}
             title={t("messages.send")}
-          >
-            <Send className="w-4 h-4" />
-          </button>
+            icon={<Send className="w-4 h-4" />}
+          />
         </div>
       )}
     </>

frontend/src/components/ComfortPinMenu.tsx

@@ -0,0 +1,50 @@
+import { useTranslation } from "react-i18next";
+
+import { type PlexCard, type Video } from "../lib/api";
+import { pinPlex, pinVideo, useComfortPin, type PinTarget } from "./comfortPin";
+import { ContextMenu } from "./ui/ContextMenu";
+import { type ContextMenuController } from "./ui/useContextMenu";
+
+// The menu SURFACE for the comfort-shelf pin (E24 S3). Split from `comfortPin.tsx` for the same
+// reason `ContextMenu.tsx` is split from `useContextMenu.ts`: a file that exports components and
+// nothing else keeps react-refresh working for every surface that imports it.
+
+/**
+ * The whole right-click menu for a surface whose only context action is the pin — the card grids and
+ * rails. Render ONE per list, outside the rows (see `ui/ContextMenu`), and spread
+ * `menu.triggerProps` on each row.
+ *
+ * `target` maps the row the user right-clicked to its pin; `title` names it in the confirmation
+ * toast. Both come from the call site because only it knows what its rows are.
+ */
+export function ComfortPinMenu<T>({
+  menu,
+  target,
+  title,
+}: {
+  menu: ContextMenuController<T>;
+  target: (row: T) => PinTarget | null;
+  title: (row: T) => string;
+}) {
+  const { t } = useTranslation();
+  const pin = useComfortPin(menu.open);
+  const row = menu.target;
+  return (
+    <ContextMenu
+      menu={menu}
+      ariaLabel={t("home.pin.menu")}
+      items={row ? pin.item(target(row), title(row)) : []}
+    />
+  );
+}
+
+/** The Plex poster grids and rails — five of them, all pinning the same way. One component so the
+ *  show-vs-item decision and the toast's name are written once rather than five times. */
+export function PlexPinMenu({ menu }: { menu: ContextMenuController<PlexCard> }) {
+  return <ComfortPinMenu menu={menu} target={pinPlex} title={(c) => c.title} />;
+}
+
+/** The YouTube video lists (the feed grid, the Home rails). */
+export function VideoPinMenu({ menu }: { menu: ContextMenuController<Video> }) {
+  return <ComfortPinMenu menu={menu} target={(v) => pinVideo(v.id)} title={(v) => v.title ?? ""} />;
+}

frontend/src/components/ConfigPanel.tsx

@@ -5,15 +5,16 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { Plug, RotateCcw, Send } from "lucide-react";
 import { api, type ConfigItem, type PlexTestResult } from "../lib/api";
 import { notify } from "../lib/notifications";
-import Tooltip from "./Tooltip";
-import InlineNotice from "./InlineNotice";
+import Tooltip from "./ui/Tooltip";
+import InlineNotice from "./ui/InlineNotice";
 import { useMe } from "../lib/useMe";
-import Tabs, { usePersistedTab } from "./Tabs";
-import { LoadingState, StateMessage } from "./QueryState";
-import { PageToolbar } from "./PageShell";
+import Tabs, { usePersistedTab } from "./ui/Tabs";
+import { LoadingState, StateMessage } from "./ui/QueryState";
+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"] ?? "")

frontend/src/components/ConfirmProvider.tsx

@@ -1,6 +1,6 @@
 import { createContext, useCallback, useContext, useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import Modal from "./Modal";
+import Modal from "./ui/Modal";
 import { Button } from "./ui/Button";
 
 // App-styled, promise-based replacement for window.confirm. Wrap the tree in

frontend/src/components/DateFilterSelect.tsx

@@ -1,7 +1,7 @@
 import { useLayoutEffect, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { CalendarDays, Check, ChevronDown } from "lucide-react";
-import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./AnchoredPopover";
+import { PopoverItem, PopoverSurface, useAnchoredPopover } from "./ui/AnchoredPopover";
 import { type FeedFilters } from "../lib/api";
 import { deriveDateKey, selectDateChip, type DatePreset } from "../lib/dateFilter";
 

frontend/src/components/DemoBanner.tsx

@@ -1,6 +1,6 @@
 import { useTranslation } from "react-i18next";
 import { AlertTriangle } from "lucide-react";
-import Banner from "./Banner";
+import Banner from "./ui/Banner";
 
 // Permanent, non-dismissible bar shown to the shared demo account so it's always clear the
 // state is communal. (Replaces the old login-time toast, which re-popped on every reload.)

frontend/src/components/DownloadCenter.tsx

@@ -19,9 +19,9 @@ import {
   Trash2,
   UploadCloud,
 } from "lucide-react";
-import Tabs from "./Tabs";
-import { PageToolbar } from "./PageShell";
-import { LoadingState, StateMessage } from "./QueryState";
+import Tabs from "./ui/Tabs";
+import { PageToolbar } from "./ui/PageShell";
+import { LoadingState, StateMessage } from "./ui/QueryState";
 // Lazy: these dialogs/editors open on demand, so they stay out of the Downloads page chunk until
 // used (the video editor in particular is heavy — filmstrip + scrubber).
 const DownloadDialog = lazy(() => import("./DownloadDialog"));

frontend/src/components/DownloadDialog.tsx

@@ -2,7 +2,7 @@ import { lazy, Suspense, useState } from "react";
 import { qk } from "../lib/queryKeys";
 import { useTranslation } from "react-i18next";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
-import Modal from "./Modal";
+import Modal from "./ui/Modal";
 import { Button } from "./ui/Button";
 import { api } from "../lib/api";
 import { invalidateDownloads } from "../lib/downloads";

frontend/src/components/ErrorDialog.tsx

@@ -1,7 +1,7 @@
 import { useSyncExternalStore } from "react";
 import { useTranslation } from "react-i18next";
 import { dismissError, getError, subscribeError } from "../lib/errorDialog";
-import Modal from "./Modal";
+import Modal from "./ui/Modal";
 import { Button } from "./ui/Button";
 
 // Renders the current app error (if any) as a modal the user must acknowledge.

frontend/src/components/Feed.tsx

@@ -27,23 +27,26 @@ 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,
   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";
 import SelectedViewChip from "./SelectedViewChip";
-import { LoadingState, StateMessage } from "./QueryState";
-import { PageToolbar } from "./PageShell";
+import { Button } from "./ui/Button";
+import { LoadingState, StateMessage } from "./ui/QueryState";
+import { PageToolbar } from "./ui/PageShell";
 import { useWizard } from "./WizardProvider";
-import SortControl from "./SortControl";
-import FilterSelect from "./FilterSelect";
-import ItemCount from "./ItemCount";
+import SortControl from "./ui/SortControl";
+import FilterSelect from "./ui/FilterSelect";
+import ItemCount from "./ui/ItemCount";
 import ViewSwitcher from "./ViewSwitcher";
 import VirtualFeed from "./VirtualFeed";
 // Lazy: the in-app YouTube player (IFrame API) loads only when a video is first opened.
@@ -152,6 +155,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 —
@@ -377,7 +387,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
@@ -429,6 +443,16 @@ 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={feedSortOptions(YT_SORT_KEYS, (k) => t("feed.sortKey." + k))}
+              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">
@@ -530,20 +554,18 @@ export default function Feed({
             {isDemo ? t("feed.demoEmptyBody") : t("feed.emptyBody")}
           </p>
           {isDemo ? (
-            <button
+            <Button
+              variant="primary"
+              size="lg"
               onClick={() => setFilters({ ...filters, scope: "all" })}
-              className="inline-flex items-center justify-center gap-2 px-5 py-2.5 rounded-xl font-semibold btn-primary transition"
             >
               {t("feed.browseLibrary")}
-            </button>
+            </Button>
           ) : (
             <>
-              <button
-                onClick={onOpenWizard}
-                className="inline-flex items-center justify-center gap-2 px-5 py-2.5 rounded-xl font-semibold btn-primary transition"
-              >
+              <Button variant="primary" size="lg" onClick={onOpenWizard}>
                 {t("feed.setUp")}
-              </button>
+              </Button>
               <button
                 onClick={() => setFilters({ ...filters, scope: "all" })}
                 className="block mx-auto mt-3 text-sm text-muted hover:text-accent transition"
@@ -559,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

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"]));
+  });
+});

frontend/src/components/FeedScopeToggle.tsx

@@ -1,6 +1,6 @@
 import { useTranslation } from "react-i18next";
 import { Library, User } from "lucide-react";
-import SegmentedToggle from "./SegmentedToggle";
+import SegmentedToggle from "./ui/SegmentedToggle";
 import { useFeedFilters, useFeedFiltersActions } from "./FeedFiltersProvider";
 
 // The feed's Mine/Library scope, relocated from the filter sidebar to sit just right of the header

frontend/src/components/FilterRail.tsx

@@ -1,8 +1,8 @@
 import { useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
 import { defaultLayout, type PanelId, type PanelLayout } from "../lib/panelLayout";
-import SidePanel from "./SidePanel";
-import PanelGroups, { type PanelItem } from "./PanelGroups";
+import SidePanel from "./ui/SidePanel";
+import PanelGroups, { type PanelItem } from "./ui/PanelGroups";
 
 // The shared filter-rail shell, extracted from the three rails that all render the same SidePanel
 // chrome around a PanelGroups body: the feed Sidebar, the PlexSidebar, and the PlaylistsRail. It owns

frontend/src/components/GlassTuner.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useMemo, useState } from "react";
-import Overlay from "./Overlay";
+import Overlay from "./ui/Overlay";
 import { copyText } from "../lib/clipboard";
 import { usePrefs } from "./PrefsProvider";
 

frontend/src/components/Home.dom.test.tsx

@@ -0,0 +1,676 @@
+// @vitest-environment jsdom
+//
+// E24 S2: the Home surface. Covers the four behaviours the browser round actually caught, each of
+// which is invisible to tsc and to a render-only check:
+//   • the hero's kicker comes from the SERVER's tier, never from the card's shape;
+//   • the hero is not printed twice (once as the hero, once as the first resume tile);
+//   • a budget change asks for the new budget and keeps the old answer on screen meanwhile;
+//   • the reroll sends the already-shown card as an exclusion — without it the resume tier hands the
+//     identical card straight back and the button looks dead.
+// i18n is key-passthrough; the api is mocked so queries resolve synchronously. The rails live inside
+// a Carousel (useHScroll → ResizeObserver), stubbed for jsdom.
+import { StrictMode } from "react";
+import { describe, it, expect, afterEach, beforeAll, beforeEach, vi } from "vitest";
+import { act, render, screen, fireEvent, cleanup, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+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;
+});
+
+vi.mock("react-i18next", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("react-i18next")>();
+  return {
+    ...actual,
+    useTranslation: () => ({
+      t: (key: string, opts?: Record<string, unknown>) =>
+        opts?.time ? `${key}:${opts.time}` : key,
+      i18n: { language: "en" },
+    }),
+  };
+});
+
+const discover = vi.fn();
+const discoverPick = vi.fn();
+vi.mock("../lib/api", () => ({
+  api: {
+    discover: (...a: unknown[]) => discover(...a),
+    discoverPick: (...a: unknown[]) => discoverPick(...a),
+    setState: () => Promise.resolve(),
+    watchLaterAdd: () => Promise.resolve(),
+    watchLaterRemove: () => Promise.resolve(),
+  },
+  DISCOVER_BUDGETS: ["short", "medium", "long", "any"],
+  discoverCardKey: (c: { source: string; id: string }) => `${c.source}:${c.id}`,
+}));
+
+// The page hands Plex playback off to the Plex module. The provider itself is not under test, but
+// WHAT is handed over is: the jump target decides both what plays and where Back goes.
+const setPage = vi.fn();
+const setJumpTo = vi.fn();
+vi.mock("./NavigationProvider", () => ({
+  useNavigationActions: () => ({ setPage: (p: string) => setPage(p) }),
+}));
+vi.mock("./PlexProvider", () => ({
+  usePlexActions: () => ({ setJumpTo: (t: unknown) => setJumpTo(t) }),
+}));
+
+import Home from "./Home";
+import { requestSurprise, takeSurprise } from "../lib/homeIntent";
+
+function ytCard(id: string, title: string, extra: Record<string, unknown> = {}) {
+  return {
+    source: "youtube",
+    kind: "video",
+    id,
+    title,
+    subtitle: "A channel",
+    thumb: null,
+    aspect: "wide",
+    duration_seconds: 600,
+    position_seconds: 120,
+    remaining_seconds: 480,
+    status: "new",
+    plex: null,
+    video: {
+      id,
+      title,
+      channel_id: "UC1",
+      channel_title: "A channel",
+      channel_thumbnail: null,
+      channel_url: "https://youtube.com/channel/UC1",
+      published_at: "2026-01-01T00:00:00Z",
+      thumbnail_url: null,
+      duration_seconds: 600,
+      view_count: 10,
+      is_short: false,
+      live_status: "none",
+      status: "new",
+      position_seconds: 120,
+      saved: false,
+      watch_url: `https://www.youtube.com/watch?v=${id}`,
+    },
+    ...extra,
+  };
+}
+
+/** A Plex SHOW row of the resume rail, carrying the episode that would actually start — what the
+ *  backend now attaches (`rails.continue_watching`). */
+const showCard = () => ({
+  source: "plex",
+  kind: "show",
+  id: "show-1",
+  title: "A Show",
+  subtitle: null,
+  thumb: null,
+  aspect: "poster",
+  duration_seconds: null,
+  position_seconds: 0,
+  remaining_seconds: null,
+  status: "in_progress",
+  video: null,
+  plex: { id: "show-1", type: "show", title: "A Show", thumb: "" },
+  next: {
+    source: "plex",
+    kind: "episode",
+    id: "ep-7",
+    title: "Ep 7",
+    subtitle: "A Show",
+    thumb: null,
+    aspect: "wide",
+    duration_seconds: 1500,
+    position_seconds: 0,
+    remaining_seconds: 1500,
+    status: "new",
+    video: null,
+    plex: { id: "ep-7", type: "episode", title: "Ep 7", thumb: "" },
+  },
+});
+
+const payload = (heroId: string, tier = "resume") => ({
+  budget: "any",
+  hero: { tier, card: ytCard(heroId, `Hero ${heroId}`) },
+  continue_watching: [ytCard(heroId, `Hero ${heroId}`), ytCard("v2", "Second thing")],
+  comfort: [],
+});
+
+function mount() {
+  return mountWithClient().result;
+}
+
+/** Same mount, handing back the QueryClient — the tests that need to drive an invalidation (i.e. a
+ *  background refetch, the only way to reach the has-data-and-errored state) cannot reach it
+ *  otherwise. */
+function mountWithClient() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const result = render(
+    <QueryClientProvider client={qc}>
+      <Home />
+    </QueryClientProvider>,
+  );
+  return { qc, result };
+}
+
+beforeEach(() => {
+  discover.mockReset();
+  discoverPick.mockReset();
+  setPage.mockReset();
+  setJumpTo.mockReset();
+  discover.mockResolvedValue(payload("v1"));
+  // Module-level state: a token left behind by one test would reroll the next one's first render.
+  takeSurprise();
+});
+afterEach(cleanup);
+
+describe("Home", () => {
+  it("labels the hero from the server's tier, not from the card", async () => {
+    // The same card shape is served under a `surprise` tier: a client that inferred "where you left
+    // off" from the resume position would get this wrong, which is the dishonest state we forbid.
+    discover.mockResolvedValue(payload("v1", "surprise"));
+    mount();
+    expect(await screen.findByText("home.hero.surprise")).toBeTruthy();
+    expect(screen.queryByText(/home\.hero\.resume/)).toBeNull();
+  });
+
+  it("interpolates the remaining time into the resume kicker", async () => {
+    mount();
+    // 480s left → 8:00, passed through the key-passthrough t() as `<key>:<time>`.
+    expect(await screen.findByText("home.hero.resumeLeft:8:00")).toBeTruthy();
+  });
+
+  it("renders an error, never the empty state, when the payload cannot be loaded", async () => {
+    // The one thing this surface must not do: report a backend outage as "nothing to suggest yet"
+    // over a library full of things to suggest.
+    discover.mockRejectedValue(new Error("boom"));
+    mount();
+    expect(await screen.findByText("home.error")).toBeTruthy();
+    expect(screen.queryByText("home.hero.emptyAny")).toBeNull();
+  });
+
+  it("keeps the page on screen when a BACKGROUND refetch fails", async () => {
+    // react-query flips `status` to error on a failed refetch while keeping the cached payload, and
+    // every mutation here invalidates `qk.discover()` — so an unguarded `isError` blanked a fully
+    // populated landing page over one blip.
+    const { qc } = mountWithClient();
+    await screen.findByText("Hero v1");
+    discover.mockRejectedValue(new Error("blip"));
+    await act(async () => {
+      await qc.invalidateQueries({ queryKey: qk.discover() });
+    });
+    // The refetch must actually have been attempted, or this asserts nothing at all.
+    await waitFor(() => expect(discover).toHaveBeenCalledTimes(2));
+    expect(screen.queryByText("home.error")).toBeNull();
+    expect(screen.getByText("Hero v1")).toBeTruthy();
+  });
+
+  it("does not print the hero again as the first resume tile", async () => {
+    mount();
+    await screen.findByText("home.hero.resumeLeft:8:00");
+    // "Hero v1" is the hero's own heading; the rail below must not repeat it.
+    expect(screen.getAllByText("Hero v1")).toHaveLength(1);
+    expect(screen.getByText("Second thing")).toBeTruthy();
+  });
+
+  it("does not print a Plex series twice when the hero is the episode it resolves to", async () => {
+    // The commonest Plex resume case, and the one a single-key match misses: the rail row is the
+    // SHOW while the hero is the episode that show resolves to, so their `source:id` keys differ.
+    // Renamed on `plex` too, not only on the unified card: the rail tile is a `PlexPosterCard`, which
+    // takes its heading from the NATIVE payload — renaming just the outer title made this vacuous.
+    const s = showCard();
+    const show = { ...s, title: "The Series Tile", plex: { ...s.plex, title: "The Series Tile" } };
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "resume", card: show.next },
+      continue_watching: [show, ytCard("v2", "Second thing")],
+      comfort: [],
+    });
+    mount();
+    await screen.findByText("Second thing");
+    expect(screen.queryByText("The Series Tile")).toBeNull();
+  });
+
+  it("hides the resume rail rather than contradicting the hero that emptied it", async () => {
+    // One in-progress item: it becomes the hero, the dedupe filter takes it out of the rail, and the
+    // rail then announced "nothing half-finished right now" under a hero captioned "where you left
+    // off". The shelf's own empty state is untouched — it still has something to teach.
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "resume", card: ytCard("v1", "Hero v1") },
+      continue_watching: [ytCard("v1", "Hero v1")],
+      comfort: [],
+    });
+    mount();
+    await screen.findByText("Hero v1");
+    expect(screen.queryByText("home.continue.empty")).toBeNull();
+    expect(screen.getByText("home.comfort.empty")).toBeTruthy();
+  });
+
+  it("holds the hero it last found when a reroll fails", async () => {
+    // A failed pick has no data of its own (every press is a new key, and `keepPreviousData` is
+    // pending-only), so the hero used to rewind to the card the page LOADED with — several presses
+    // back — while `core.req`'s own dialog explained the failure.
+    // No resume rail: "Hero v1" then appears exactly where the hero is, so its reappearance is
+    // unambiguous evidence of a rewind rather than a rail tile that stopped being deduplicated.
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "resume", card: ytCard("v1", "Hero v1") },
+      continue_watching: [],
+      comfort: [],
+    });
+    discoverPick.mockResolvedValueOnce({
+      budget: "any",
+      hero: { tier: "surprise", card: ytCard("v9", "Rerolled") },
+    });
+    mount();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await screen.findByText("Rerolled");
+
+    // Rejected on OUR schedule: asserting straight after the call goes out catches the query still
+    // pending, where `keepPreviousData` is legitimately holding the old hero — which is not the
+    // state under test and made this pass with or without the fix.
+    let failPick!: (e: Error) => void;
+    discoverPick.mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failPick = reject;
+      }),
+    );
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(2));
+    await act(async () => {
+      failPick(new Error("boom"));
+      await new Promise((r) => setTimeout(r, 0));
+    });
+    expect(screen.getByText("Rerolled")).toBeTruthy();
+    expect(screen.queryByText("Hero v1")).toBeNull();
+  });
+
+  it("never answers a new budget with the previous budget's pick", async () => {
+    // Both halves of the hold outlive the question they answered: the chip row resets seed/seen/press,
+    // but it cannot reset an answer that already RESOLVED, and `keepPreviousData` chains straight
+    // through the disabled seed-0 query the chip click leaves behind. So the first reroll under a new
+    // budget offered the old budget's card — while it loaded, and permanently once it failed, since
+    // `retry: false` makes a failed pick terminal. Under a chip that promises ten minutes, that makes
+    // the page's one control meaningless (round 2).
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "resume", card: ytCard("v1", "Hero v1") },
+      continue_watching: [],
+      comfort: [],
+    });
+    discoverPick.mockResolvedValueOnce({
+      budget: "any",
+      hero: { tier: "surprise", card: ytCard("v9", "Long film") },
+    });
+    mount();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await screen.findByText("Long film");
+
+    // A different question — whose own answer is already loaded.
+    discover.mockResolvedValue({
+      budget: "short",
+      hero: { tier: "resume", card: ytCard("v2", "Short thing") },
+      continue_watching: [],
+      comfort: [],
+    });
+    fireEvent.click(screen.getByText("home.budget.short"));
+    await screen.findByText("Short thing");
+
+    // Rejected on OUR schedule, as the sibling test above does, so the assertion cannot land while
+    // the query is still pending — that is a different state.
+    let failPick!: (e: Error) => void;
+    discoverPick.mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failPick = reject;
+      }),
+    );
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(2));
+    // In flight: the placeholder must not reach across the budget change.
+    expect(screen.queryByText("Long film")).toBeNull();
+
+    await act(async () => {
+      failPick(new Error("boom"));
+      await new Promise((r) => setTimeout(r, 0));
+    });
+    // Failed: this budget's own hero, never the film picked for "any".
+    expect(screen.getByText("Short thing")).toBeTruthy();
+    expect(screen.queryByText("Long film")).toBeNull();
+  });
+
+  it("a mutation's invalidation reaches the rerolled hero too", async () => {
+    // The reroll has its own query key so pressing the button does not refetch the rails — but under
+    // the SAME root, or the prefix every mutation invalidates misses it and a rerolled hero outlives
+    // the page: play it, finish it, and it was still the answer, with a zeroed progress bar.
+    discoverPick.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "surprise", card: ytCard("v9", "Rerolled") },
+    });
+    const { qc } = mountWithClient();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await screen.findByText("Rerolled");
+    expect(discoverPick).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      await qc.invalidateQueries({ queryKey: qk.discover() });
+    });
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(2));
+  });
+
+  it("an unrelated mutation does not put the reroll button into a spinner", async () => {
+    // The other edge of the test above. Because the pick key sits under the `["discover"]` prefix,
+    // every mark-watched, bookmark, pin and shelf move on this page refetches it in the BACKGROUND —
+    // so binding the button's `loading` to raw `isFetching` made it spin and, since `ui/Button` turns
+    // `loading` into `disabled`, swallow clicks after actions the user never associated with a
+    // reroll (round 2). A press is outstanding only while THIS key has no answer of its own.
+    const rerollBtn = () =>
+      screen.getByText("home.hero.reroll").closest("button") as HTMLButtonElement;
+    let resolvePick!: (v: unknown) => void;
+    discoverPick.mockReturnValueOnce(
+      new Promise((resolve) => {
+        resolvePick = resolve;
+      }),
+    );
+    const { qc } = mountWithClient();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(1));
+
+    // The positive control, and it is the half most easily broken while fixing the other: this is the
+    // FIRST press, so there is no previous pick for the placeholder to hold, and a predicate resting
+    // on `isPlaceholderData` alone would drop the spinner from exactly the press that needs it.
+    expect(rerollBtn().disabled).toBe(true);
+    expect(rerollBtn().getAttribute("aria-busy")).toBe("true");
+
+    await act(async () => {
+      resolvePick({ budget: "any", hero: { tier: "surprise", card: ytCard("v9", "Rerolled") } });
+      await new Promise((r) => setTimeout(r, 0));
+    });
+    await screen.findByText("Rerolled");
+
+    // Never settles, so the assertion lands squarely inside the refetch window rather than after it —
+    // and therefore the invalidation must NOT be awaited: its promise resolves only once every
+    // refetch it started has, which this one never will.
+    discoverPick.mockReturnValue(new Promise(() => {}));
+    act(() => {
+      void qc.invalidateQueries({ queryKey: qk.discover() });
+    });
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(2));
+
+    expect(rerollBtn().disabled).toBe(false);
+    expect(rerollBtn().getAttribute("aria-busy")).toBeNull();
+  });
+
+  it("a press that FAILED does not leave the button hostage to the next mutation", async () => {
+    // Round 3's correction to the case above. A key whose request failed never gets data of its own
+    // (`retry: false` makes it terminal), so a predicate reading `data === undefined` stayed true
+    // forever and every later background refetch re-disabled the button — the same defect, one
+    // branch over. `isFetched` remembers that the key settled, an error counting as settled.
+    const rerollBtn = () =>
+      screen.getByText("home.hero.reroll").closest("button") as HTMLButtonElement;
+    let failPick!: (e: Error) => void;
+    discoverPick.mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failPick = reject;
+      }),
+    );
+    const { qc } = mountWithClient();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(1));
+    // `waitFor`, not a fixed tick: react-query hands the rejection to the observer through
+    // `notifyManager`'s own `setTimeout(0)`, registered AFTER any timer this test schedules, so
+    // "await one macrotask then assert" races it. Round 4 measured that race as an intermittent red.
+    failPick(new Error("boom"));
+    await waitFor(() => expect(rerollBtn().disabled).toBe(false)); // the failure releases the button
+
+    // Now an unrelated action refetches that errored key in the background.
+    discoverPick.mockReturnValue(new Promise(() => {}));
+    act(() => {
+      void qc.invalidateQueries({ queryKey: qk.discover() });
+    });
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(2));
+    expect(rerollBtn().disabled).toBe(false);
+    expect(rerollBtn().getAttribute("aria-busy")).toBeNull();
+  });
+
+  it("keeps the honest empty answer when a press fails after an empty one", async () => {
+    // The tagged slot is authoritative for its own budget, including when what it holds is "no hero
+    // at all". Under a `??` chain that read as "nothing remembered" and fell through to the loaded
+    // payload, so a failed press resurrected the card the page had already excluded as seen and just
+    // said it had nothing beyond (round 3).
+    discover.mockResolvedValue({
+      budget: "short",
+      hero: { tier: "resume", card: ytCard("v1", "Hero v1") },
+      continue_watching: [],
+      comfort: [],
+    });
+    mount();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.budget.short")); // the empty-state branch needs a band
+    await waitFor(() => expect(discover).toHaveBeenLastCalledWith("short", 0));
+
+    // A press that RESOLVES with nothing left: the honest empty state.
+    discoverPick.mockResolvedValueOnce({ budget: "short", hero: null });
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await screen.findByText("home.hero.emptyBudget");
+    expect(screen.queryByText("Hero v1")).toBeNull();
+
+    // …and a press from there that fails must not undo it.
+    let failPick!: (e: Error) => void;
+    discoverPick.mockReturnValueOnce(
+      new Promise((_resolve, reject) => {
+        failPick = reject;
+      }),
+    );
+    const rerollBtn = () =>
+      screen.getByText("home.hero.reroll").closest("button") as HTMLButtonElement;
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() => expect(discoverPick).toHaveBeenCalledTimes(2));
+    expect(rerollBtn().disabled).toBe(true); // the press is outstanding
+
+    failPick(new Error("boom"));
+    // Wait for a signal that the REJECTION has landed, not for a fixed tick: react-query notifies
+    // the observer through its own `setTimeout(0)`, and the empty state is already on screen while
+    // the press is in flight — so asserting it straight away would pass with or without the fix.
+    // The button releasing is that signal (`isFetched` flips once the key settles, error included).
+    await waitFor(() => expect(rerollBtn().disabled).toBe(false));
+    expect(screen.getByText("home.hero.emptyBudget")).toBeTruthy();
+    expect(screen.queryByText("Hero v1")).toBeNull();
+  });
+
+  it("refreshes the payload the bookmark is read from", async () => {
+    mount();
+    await screen.findByText("Second thing");
+    expect(discover).toHaveBeenCalledTimes(1);
+    fireEvent.click(screen.getAllByTitle("card.saveForLater")[0]!);
+    // `VideoCard` derives the filled/empty star straight from `video.saved` in this payload and
+    // keeps no optimistic state of its own, so without re-asking, the icon never changed and the
+    // next click re-sent the same call — the control looked dead.
+    await waitFor(() => expect(discover).toHaveBeenCalledTimes(2));
+  });
+
+  it("asks for the chosen budget and keeps the previous answer on screen meanwhile", async () => {
+    mount();
+    await screen.findByText("Hero v1");
+    // A never-resolving refetch: the point is what the page shows WHILE it waits.
+    discover.mockReturnValue(new Promise(() => {}));
+    fireEvent.click(screen.getByText("home.budget.short"));
+    await waitFor(() => expect(discover).toHaveBeenLastCalledWith("short", 0));
+    // Still the old answer — not a spinner that would take the chips away with it.
+    expect(screen.getByText("Hero v1")).toBeTruthy();
+  });
+
+  it("rerolls with the shown card excluded, and holds the hero while it loads", async () => {
+    discoverPick.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "surprise", card: ytCard("v9", "Rerolled") },
+    });
+    mount();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() =>
+      expect(discoverPick).toHaveBeenCalledWith("any", expect.any(Number), ["youtube:v1"], 1),
+    );
+    expect(await screen.findByText("Rerolled")).toBeTruthy();
+  });
+
+  it("never shows the empty state while a reroll is in flight", async () => {
+    // The regression the browser round caught: a new query key has no data for a beat, so the hero
+    // fell to null and the page rendered "nothing to suggest" over a perfectly good library.
+    discoverPick.mockReturnValue(new Promise(() => {}));
+    mount();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() => expect(discoverPick).toHaveBeenCalled());
+    expect(screen.queryByText("home.hero.emptyAny")).toBeNull();
+    expect(screen.getByText("Hero v1")).toBeTruthy();
+  });
+
+  // E24 S4. The palette's "Meglepetés" is pressed on ANOTHER page, so Home's lazy chunk is not
+  // mounted yet — the request has to WAIT as a token rather than fire into an empty room. And it
+  // must be spent: a token that survived would make a later visit reroll on its own, which reads as
+  // the page overruling the answer you came back for.
+  it("acts on a pending surprise request once, and never replays it", async () => {
+    discoverPick.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "surprise", card: ytCard("v9", "Rerolled") },
+    });
+    requestSurprise();
+    const first = mount();
+    expect(await screen.findByText("Rerolled")).toBeTruthy();
+    expect(discoverPick).toHaveBeenCalledTimes(1);
+
+    first.unmount();
+    discoverPick.mockClear();
+    mount();
+    await screen.findByText("Hero v1");
+    expect(discoverPick).not.toHaveBeenCalled();
+  });
+
+  // Measured in the browser (2026-09-07), before the fix: the palette's "Meglepetés" arrived at Home
+  // as `start=2` — two picks deep before the page had painted once — because StrictMode invokes a
+  // mount effect twice with the same render snapshot, and a reroll is not idempotent. The token is
+  // taken with a compare-and-clear against the LIVE store, which is what makes the second pass moot.
+  it("does not reroll twice under StrictMode's double-invoked mount effect", async () => {
+    discoverPick.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "surprise", card: ytCard("v9", "Rerolled") },
+    });
+    requestSurprise();
+    const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+    render(
+      <StrictMode>
+        <QueryClientProvider client={qc}>
+          <Home />
+        </QueryClientProvider>
+      </StrictMode>,
+    );
+    expect(await screen.findByText("Rerolled")).toBeTruthy();
+    expect(discoverPick).toHaveBeenCalledTimes(1);
+    // …and on the press count the server reads as "which tier answers first".
+    expect(discoverPick).toHaveBeenCalledWith("any", expect.any(Number), [], 1);
+  });
+
+  it("says the shelf is empty rather than hiding it", async () => {
+    mount();
+    expect(await screen.findByText("home.comfort.empty")).toBeTruthy();
+  });
+
+  it("plays a half-watched SHOW's next episode instead of opening the show page", async () => {
+    // Reported 2026-09-06. A show tile that opens the show page hands back the very decision this
+    // surface exists to remove — six seasons to choose between. The rail row carries `next`, and the
+    // click follows it.
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: null,
+      continue_watching: [showCard()],
+      comfort: [],
+    });
+    mount();
+    fireEvent.click(await screen.findByText("A Show"));
+    expect(setJumpTo).toHaveBeenCalledWith(expect.objectContaining({ id: "ep-7", type: "play" }));
+  });
+
+  it("hands off with `replace` so Back returns HERE, not to the Plex module's root", async () => {
+    // The hand-off is a continuation of the navigation that just pushed the Plex page entry, not a
+    // second step on top of it — without this, Back landed on the Plex Discover page the user never
+    // visited (and, under StrictMode, did nothing at all the first press).
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: null,
+      continue_watching: [showCard()],
+      comfort: [],
+    });
+    mount();
+    fireEvent.click(await screen.findByText("A Show"));
+    expect(setJumpTo).toHaveBeenCalledWith(expect.objectContaining({ replace: true }));
+    expect(setPage).toHaveBeenCalledWith("plex");
+  });
+
+  it("sends the ⓘ affordance to the item's page, not to the player", async () => {
+    // `onInfo` and `onPlay` differ by one ternary arm, and confusing them is the defect the play
+    // test above was written for — but only `onPlay` was pinned, so swapping ⓘ's "movie" for "play"
+    // typechecked (both are members of `PlexJumpTarget["type"]`) and shipped green. ⓘ is the one
+    // action on this surface a user presses precisely because they do NOT want to start watching.
+    const movie = {
+      ...ytCard("m1", "A Film"),
+      source: "plex",
+      kind: "movie",
+      aspect: "poster",
+      video: null,
+      plex: { id: "m1", type: "movie", title: "A Film", thumb: "" },
+    };
+    discover.mockResolvedValue({
+      budget: "any",
+      hero: null,
+      continue_watching: [movie],
+      comfort: [],
+    });
+    mount();
+    fireEvent.click(await screen.findByLabelText("plex.info.title"));
+    expect(setJumpTo).toHaveBeenCalledWith({ id: "m1", type: "movie", replace: true });
+    expect(setPage).toHaveBeenCalledWith("plex");
+  });
+
+  it("rotates the tier on each press so the button offers a different KIND of answer", async () => {
+    // Measured 2026-09-06: exclusion alone left it walking the resume rail and cycling nine cards,
+    // never once reaching the shelf. The press count travels to the server as the rotation.
+    discoverPick.mockResolvedValue({
+      budget: "any",
+      hero: { tier: "comfort", card: ytCard("v9", "Rerolled") },
+    });
+    mount();
+    await screen.findByText("Hero v1");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() =>
+      expect(discoverPick).toHaveBeenLastCalledWith("any", expect.any(Number), ["youtube:v1"], 1),
+    );
+    await screen.findByText("Rerolled");
+    fireEvent.click(screen.getByText("home.hero.reroll"));
+    await waitFor(() =>
+      expect(discoverPick).toHaveBeenLastCalledWith(
+        "any",
+        expect.any(Number),
+        // The exact list, not `expect.any(Array)`: the window has to ACCUMULATE. A one-element list
+        // is identical whether it accumulates or replaces, so the first press cannot tell them
+        // apart — and with the loose matcher both "replace, never grow" and SEEN_WINDOW = 1 (which
+        // reinstate the measured nine-card cycle) left the whole suite green.
+        ["youtube:v1", "youtube:v9"],
+        2,
+      ),
+    );
+  });
+});

frontend/src/components/Home.pin.dom.test.tsx

@@ -0,0 +1,269 @@
+// @vitest-environment jsdom
+//
+// E24 S3: the comfort shelf's editor — the right-click menu on the Home rails. Its own file, not an
+// addition to Home.dom.test.tsx, because the shelf query is module-level react-query state that a
+// sibling test's mocks would leak into.
+//
+// What is asserted here is what tsc cannot see: that the menu the user gets over a SHELF tile is a
+// different menu from the one over a resume tile, that a move row is disabled exactly when the move
+// would go nowhere, and that a move writes the shelf's WHOLE new order rather than the pair it
+// swapped.
+//
+// Same floating-ui recipe as ContextMenu.dom.test.tsx: stub the observers, wrap in a FloatingTree,
+// and match menu items by text with `{ hidden: true }` (floating-ui never positions in jsdom, so the
+// surface stays visibility:hidden and its contents have no accessible name).
+import { describe, it, expect, afterEach, beforeAll, beforeEach, vi } from "vitest";
+import { render, screen, fireEvent, cleanup, waitFor } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { FloatingTree } from "@floating-ui/react";
+
+beforeAll(() => {
+  class Stub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+    takeRecords() {
+      return [];
+    }
+  }
+  globalThis.ResizeObserver ??= Stub as unknown as typeof ResizeObserver;
+  globalThis.IntersectionObserver ??= Stub as unknown as typeof IntersectionObserver;
+});
+
+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 discover = vi.fn();
+const comfortPins = vi.fn();
+const addComfortPin = vi.fn();
+const removeComfortPin = vi.fn();
+const reorderComfortPins = vi.fn();
+vi.mock("../lib/api", () => ({
+  api: {
+    discover: (...a: unknown[]) => discover(...a),
+    discoverPick: () => new Promise(() => {}),
+    setState: () => Promise.resolve(),
+    watchLaterAdd: () => Promise.resolve(),
+    watchLaterRemove: () => Promise.resolve(),
+    comfortPins: (...a: unknown[]) => comfortPins(...a),
+    addComfortPin: (...a: unknown[]) => addComfortPin(...a),
+    removeComfortPin: (...a: unknown[]) => removeComfortPin(...a),
+    reorderComfortPins: (...a: unknown[]) => reorderComfortPins(...a),
+  },
+  HttpError: class extends Error {},
+  DISCOVER_BUDGETS: ["short", "medium", "long", "any"],
+  discoverCardKey: (c: { source: string; id: string }) => `${c.source}:${c.id}`,
+}));
+
+vi.mock("./NavigationProvider", () => ({ useNavigationActions: () => ({ setPage: vi.fn() }) }));
+vi.mock("./PlexProvider", () => ({ usePlexActions: () => ({ setJumpTo: vi.fn() }) }));
+
+import Home from "./Home";
+
+const video = (id: string, title: string) => ({
+  id,
+  title,
+  channel_id: "UC1",
+  channel_title: "A channel",
+  channel_thumbnail: null,
+  channel_url: "https://youtube.com/channel/UC1",
+  published_at: "2026-01-01T00:00:00Z",
+  thumbnail_url: null,
+  duration_seconds: 600,
+  view_count: 10,
+  is_short: false,
+  live_status: "none",
+  status: "new",
+  position_seconds: 0,
+  saved: false,
+  watch_url: `https://www.youtube.com/watch?v=${id}`,
+});
+
+const base = (id: string, title: string) => ({
+  source: "youtube",
+  kind: "video",
+  id,
+  title,
+  subtitle: null,
+  thumb: null,
+  aspect: "wide",
+  duration_seconds: 600,
+  position_seconds: 0,
+  remaining_seconds: 600,
+  status: "new",
+  plex: null,
+  video: video(id, title),
+});
+
+/** A pinned CHANNEL — the shelf tile with no native card, and the one that is easiest to address by
+ *  its title in a test (the video tiles render a whole VideoCard). */
+const channelPin = (id: string, title: string, pinId: number) => ({
+  ...base(id, title),
+  kind: "channel",
+  video: null,
+  unwatched_count: 3,
+  pin_id: pinId,
+  next: base(`${id}-next`, `${title} next`),
+});
+
+const shelf = [
+  channelPin("UCa", "Comfort A", 3),
+  channelPin("UCb", "Comfort B", 7),
+  channelPin("UCc", "Comfort C", 9),
+];
+
+const payload = () => ({
+  budget: "any",
+  hero: null,
+  continue_watching: [base("v2", "Resume thing")],
+  comfort: shelf,
+});
+
+function mount() {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  return render(
+    <FloatingTree>
+      <QueryClientProvider client={qc}>
+        <Home />
+      </QueryClientProvider>
+    </FloatingTree>,
+  );
+}
+
+const labels = () => screen.queryAllByRole("menuitem", { hidden: true }).map((b) => b.textContent);
+const item = (label: string) => {
+  const found = screen
+    .getAllByRole("menuitem", { hidden: true })
+    .find((b) => b.textContent === label);
+  if (!found) throw new Error(`no menuitem "${label}" in [${labels().join(", ")}]`);
+  return found as HTMLButtonElement;
+};
+
+beforeEach(() => {
+  discover.mockReset().mockResolvedValue(payload());
+  comfortPins.mockReset().mockResolvedValue({ items: shelf });
+  addComfortPin.mockReset().mockResolvedValue({ ok: true, id: 1, created: true });
+  removeComfortPin.mockReset().mockResolvedValue({ deleted: 1 });
+  reorderComfortPins.mockReset().mockResolvedValue({ ok: true });
+});
+afterEach(cleanup);
+
+describe("Home — the comfort shelf's context menu", () => {
+  it("offers the four moves and the unpin over a SHELF tile", async () => {
+    mount();
+    fireEvent.contextMenu(await screen.findByText("Comfort B"));
+    expect(labels()).toEqual([
+      "home.hero.play",
+      "home.shelf.moveFirst",
+      "home.shelf.moveLeft",
+      "home.shelf.moveRight",
+      "home.shelf.moveLast",
+      "home.pin.remove",
+    ]);
+  });
+
+  it("disables exactly the moves that would go nowhere", async () => {
+    mount();
+    // The first tile can go right, but not left or to the front it is already at.
+    fireEvent.contextMenu(await screen.findByText("Comfort A"));
+    expect(item("home.shelf.moveFirst").disabled).toBe(true);
+    expect(item("home.shelf.moveLeft").disabled).toBe(true);
+    expect(item("home.shelf.moveRight").disabled).toBe(false);
+    expect(item("home.shelf.moveLast").disabled).toBe(false);
+  });
+
+  it("writes the WHOLE new order when a tile moves", async () => {
+    mount();
+    fireEvent.contextMenu(await screen.findByText("Comfort A"));
+    fireEvent.click(item("home.shelf.moveRight"));
+    // Not the swapped pair: the endpoint takes the shelf's complete order, and a short list would be
+    // the server reordering half the shelf.
+    await waitFor(() => expect(reorderComfortPins).toHaveBeenCalledWith([7, 3, 9]));
+  });
+
+  it("moves the tile under the pointer, not only in the request", async () => {
+    mount();
+    fireEvent.contextMenu(await screen.findByText("Comfort A"));
+    // Hold the refetch that follows the write: it would answer with this mock's ORIGINAL order,
+    // which is not what is under test. The claim here is that the tile moves under the pointer,
+    // before any round trip — `keepPreviousData` keeps the patched cache on screen meanwhile.
+    discover.mockReturnValue(new Promise(() => {}));
+    fireEvent.click(item("home.shelf.moveRight"));
+    await waitFor(() => expect(reorderComfortPins).toHaveBeenCalled());
+    // The RENDERED order, not just the payload sent: drop the optimistic cache write and the request
+    // is still perfectly right while the shelf visibly does not move, so the user clicks again.
+    expect(screen.getAllByText(/^Comfort [ABC]$/).map((e) => e.textContent)).toEqual([
+      "Comfort B",
+      "Comfort A",
+      "Comfort C",
+    ]);
+  });
+
+  it("re-asks the server when a move fails instead of restoring a snapshot", async () => {
+    // Writing a captured `before` back was wrong twice: two overlapping moves each reverted to their
+    // own snapshot and the shelf settled on an order neither side held, and `before` is the WHOLE
+    // payload, so the rollback also discarded any rail refresh that landed mid-flight.
+    reorderComfortPins.mockRejectedValue(new Error("nope"));
+    mount();
+    await screen.findByText("Comfort A");
+    expect(discover).toHaveBeenCalledTimes(1);
+    fireEvent.contextMenu(screen.getByText("Comfort A"));
+    fireEvent.click(item("home.shelf.moveRight"));
+    await waitFor(() => expect(discover).toHaveBeenCalledTimes(2));
+  });
+
+  it("unpins with the pin id the shelf card carries", async () => {
+    mount();
+    fireEvent.contextMenu(await screen.findByText("Comfort C"));
+    fireEvent.click(item("home.pin.remove"));
+    await waitFor(() => expect(removeComfortPin).toHaveBeenCalledWith(9));
+  });
+
+  it("offers the plain PIN over a resume tile, and never a move", async () => {
+    // The rail below the shelf is not orderable, so its menu must not grow rows that would reorder
+    // something the tile is not part of.
+    mount();
+    await screen.findByText("Comfort A");
+    fireEvent.contextMenu(screen.getByText("Resume thing"));
+    await waitFor(() => expect(labels()).toContain("home.pin.add"));
+    expect(labels().some((l) => l?.startsWith("home.shelf.move"))).toBe(false);
+    fireEvent.click(item("home.pin.add"));
+    await waitFor(() => expect(addComfortPin).toHaveBeenCalledWith("video", "v2"));
+  });
+
+  it("still opens the menu over a shelf tile that has nothing left to play", async () => {
+    // The tile with nothing left to play is the one you most want to take OFF the shelf, so its
+    // menu still has to open and its Play row still has to be honest about being dead.
+    // NOTE what this does NOT prove: jsdom delivers `contextmenu` to a real `<button disabled>`
+    // too, so swapping the tile's `aria-disabled` back to `disabled` keeps this test green. That
+    // choice was settled in a real browser instead (see the tile's own comment) — the difference
+    // is focus, which jsdom's event dispatch never exercises.
+    discover.mockResolvedValue({
+      ...payload(),
+      comfort: [{ ...channelPin("UCd", "Nothing left", 11), next: null }],
+    });
+    mount();
+    fireEvent.contextMenu(await screen.findByText("Nothing left"));
+    expect(item("home.hero.play").disabled).toBe(true);
+    fireEvent.click(item("home.pin.remove"));
+    await waitFor(() => expect(removeComfortPin).toHaveBeenCalledWith(11));
+  });
+
+  it("says so rather than guessing while the shelf is still loading", async () => {
+    // "Not pinned" and "not known yet" must not render as the same row: the pin label is only
+    // trustworthy once the shelf has answered.
+    comfortPins.mockReturnValue(new Promise(() => {}));
+    mount();
+    await screen.findByText("Comfort A");
+    fireEvent.contextMenu(screen.getByText("Resume thing"));
+    expect(item("home.pin.add").disabled).toBe(true);
+  });
+});