release: 0.117.0 (improvement/e57-files-and-small-ideas)

"Megnézem" (a first-person verb) and "Megnyitás" (a noun) labelled the same button by link kind;
the app's Hungarian buttons are nouns, so a video's reads "Megtekintés".

.gitleaksignore

@@ -0,0 +1,8 @@
+# gitleaks false positives, one fingerprint per finding (commit:file:rule:line). Each says why it is no secret.
+#
+# YouTube's public WEB InnerTube key: embedded in every youtube.com results page, read live and cached;
+# this constant is only the fallback (backend/app/youtube/innertube.py).
+8b37c470ba5d11c45757f0b2e62d660b782e816d:backend/app/youtube/innertube.py:gcp-api-key:23
+# A recorded watch-next page's continuation cursors (continuationCommand.token): page pointers, not credentials.
+8b37c470ba5d11c45757f0b2e62d660b782e816d:backend/tests/fixtures/innertube_next_first.json:generic-api-key:768
+8b37c470ba5d11c45757f0b2e62d660b782e816d:backend/tests/fixtures/innertube_next_first.json:generic-api-key:792

CHANGELOG.md

@@ -7,6 +7,127 @@ 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.117.0 — 2026-11-06
+
+### New
+
+- A share link's address now says what it opens: /file/ for a file, /folder/ for a folder, /watch/ for a video. Links you already sent keep working.
+- The upload dialog shows which folder the file goes to, and you can pick another one or make a new folder there. Opening Share copies a link at once.
+- The Channels tag chips show how many followed channels each holds. Continue watching in Plex has a See all, and a Plex item's Info shows the file size.
+
+### Fixed
+
+- An expired share link is marked as expired and is never copied. A crop of a video with wide pixels keeps exactly what its frame showed.
+- A Plex auto-skip waits 3 seconds into the marker before its countdown starts.
+
+## 0.116.3 — 2026-11-04
+
+### Fixed
+
+- If a stylesheet is lost on the way, the app now asks for it again, so a poor connection no longer leaves the page unstyled until a reload.
+
+## 0.116.2 — 2026-11-03
+
+### Fixed
+
+- A Plex video paused or muted in a background tab no longer loses its session after a minute, and if a session is lost anyway, playback comes back at once instead of after half a minute.
+
+## 0.116.1 — 2026-11-03
+
+### Fixed
+
+- A playlist now shows the order the server holds after a revert to YouTube, a sync or a change on another device, and the next drag no longer brings back the old one.
+- An Undo on a removed or moved row puts it back in the right place while another change is still saving.
+
+## 0.116.0 — 2026-11-03
+
+### New
+
+- In a playlist, tick rows with their box, Shift+click or x, then move or remove them together. An Undo puts them back at their places, and a single row's move has one too.
+- Drag rows onto another list in the rail: one row, or all the selected ones, also under a sort or a filter.
+
+### Fixed
+
+- Removing a video from inside the player no longer loses your place in the list when the player closes.
+
+## 0.115.0 — 2026-11-01
+
+### New
+
+- Clear watch progress is on every YouTube video's menu, on Home, in playlists and in the player's related videos. It forgets where you left a started video and changes nothing else.
+- Channels have an Added column, and an About card opens only when the pointer rests on it.
+- In Files, a press anywhere on a row plays the file.
+- The feed's toolbar pills are named by a glyph, with Sort and View on the filters' row.
+
+### Fixed
+
+- In a play queue, Previous and Next pass over a video that can't play, in the direction you were going, and say why when only such videos are left.
+- A Facebook download titled only “Facebook” now takes the post's text as its name.
+- The player's big view keeps its way out in sight on a tablet, and Tab no longer lands on controls hidden under it.
+
+## 0.114.3 — 2026-11-01
+
+### Fixed
+
+- Editing a file that is neither video nor audio now says why it can't be done, instead of a generic error.
+
+## 0.114.2 — 2026-10-30
+
+### Fixed
+
+- Security: a library the sign-in relies on is updated, closing two published vulnerabilities.
+
+## 0.114.1 — 2026-10-30
+
+### Fixed
+
+- Notifications follow a language switch: a notice on screen and every row in the notification center are said again in the new language, their buttons too.
+
+## 0.114.0 — 2026-10-29
+
+### New
+
+- Notifications: what asks for you comes first, then everything else as one stream, newest first. Read notices older than a week fold under Earlier, and Back returns to the row you left.
+
+### Fixed
+
+- Plex: a progress save sent just before an episode ends no longer leaves it unwatched, and a refused finish no longer sticks.
+- After a dialog closes, the keyboard focus returns to where it was, also inside a menu that stays open.
+
+## 0.113.0 — 2026-10-28
+
+### New
+
+- The address names what you see: tabs, list views, sorts and searches (the live YouTube search too), the YouTube player and the file viewer. A reload, a bookmark or a shared link opens the same view.
+- A link to a video reopens the player over its page once; Back closes it. A video the page no longer lists plays on its own and says so.
+
+### Fixed
+
+- Back and Forward step through the views as you saw them, across dialogs, players and reloads: a reload under an open player no longer leaves a Back step that does nothing.
+- Signed out on a Plex page, the sign-in card could show a button with no text.
+- The channel page's address names the channel and its own view, not the page under it.
+- A reload during a Plex binge reopens the episode playing now, not the one it started from.
+
+## 0.112.1 — 2026-10-27
+
+### Fixed
+
+- Security: the sign-in library is updated, closing two published vulnerabilities.
+
+## 0.112.0 — 2026-10-25
+
+### New
+
+- Player: a Related tab lists videos related to the one playing, leaving out what you have already watched (your uploaded YouTube history included). Channels you follow are marked, and you can switch between On topic and Trending.
+- Play a related video in place; Back returns to the one you opened. Admins set a daily per-user limit in Config › Quota (default 200, 0 turns it off).
+- Side panel: the list controls and the watched toggle are glyphs on one line, and Auto and Loop show when they are on, also under the pointer.
+
+### Fixed
+
+- Live search: a search that never reached YouTube no longer uses up a daily slot, a busy moment says so after a few seconds instead of waiting on, and a first page that failed offers Retry.
+- Menus: Play from the beginning wears the same ↺ glyph everywhere, and Reset its own eraser glyph.
+- On the day of this update, API searches made earlier that day stop counting toward the daily search limit, until Pacific midnight.
+
 ## 0.111.0 — 2026-10-24
 
 ### New

CLAUDE.md

@@ -74,7 +74,7 @@ only along a declared edge and writes them only through that unit's service; cor
 cannot (an ORM write on another unit's loaded row, SQL in `text()`, a commit by `begin()`) is review's to catch, listed in
 [`backend/app/README.md`](backend/app/README.md) with the conventions.
 Frontend, by folder under `src/`: `main.tsx` provider tree → `shell/` (`App`, header, nav rail, palette,
-boot; a shared `/watch` link boots from its own entry, `watch.html` → `watchMain.tsx` → `watch/`, held
+boot; a share link (`/watch`, `/file`, `/folder`) boots from its own entry, `watch.html` → `watchMain.tsx` → `watch/`, held
 app-free by a contract test) → **`modules/<page>/`** (one folder per page: the page, its rail, its store, its tests,
 and its `module.ts` definition — label, icon, gate, the lazy page and rail, its store — collected in nav order by
 `features/navigation/moduleRegistry`, which also mounts every store at the root; a new page is its folder, its id in
@@ -105,7 +105,7 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | Ownership check                      | `userscope.owned_by` (a filter) / `owned_row` (a row by id): a unit's `queries.own_x` returns None and its route answers `not_found`; a core route `owned_or_404`. A composite rule (own or shared, built-in or own) says so in its `queries` | an inline owner filter — `Model.user_id == …`, an alias's, `.in_()`, `filter_by(user_id=…)` (fence-held, every module) — or a `db.get` and a compare where `owned_row` fits                 |
 | 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                                                                                                                                                  |
+| User-facing error                    | structured `detail` (`{code, reason}`), its sentence named in `lib/api/refusalCodes.ts` (contract-held)                                                                                                                                       | a bare English string under a bilingual UI                                                                                                                                                  |
 | Mutation response                    | `{"ok": true, …}` (`{"deleted": id}`), test-held                                                                                                                                                                                              | a bare `{"unsubscribed"}`/`{"cleared": n}`, no `ok`                                                                                                                                         |
 | Transaction commit                   | the handler commits; a unit's `service` and every helper `flush` (fence-held, every module)                                                                                                                                                   | a helper that commits — only a listed one (what owns its session, or a core step that must land whatever its caller does next), each with its reason: the fence's `UNIT_COMMITS` / `CORE_COMMITS`, a route's `COMMITTING_HELPERS` (`test_route_conventions`) |
 | Admin knob storage                   | `sysconfig` (values)                                                                                                                                                                                                                          | env / `app_state` / a table of its own (the job intervals had one)                                                                                                                          |
@@ -115,6 +115,7 @@ CQRS, a repository/DI framework, a router library, a generic CRUD-router factory
 | FE keyboard shortcut                 | a row in `lib/keymap.ts` + `dispatch()`                                                                                                                                                                                                       | a private `keydown` listener with its own key literals                                                                                                                                      |
 | FE list/grid keys                    | `NavGrid`/`keyboardNav` + `navItemAttrs` + `data-nav-open`                                                                                                                                                                                    | a private arrow-key / roving-tabindex handler                                                                                                                                               |
 | FE view push (history)               | `rememberNavPosition()` right before `history.pushState`                                                                                                                                                                                      | a push that forgets: Back strands focus on `<body>`                                                                                                                                         |
+| FE view state                        | the module's URL codec: its keys in `urlKeys` (`module.ts`), read and written by `lib/<id>UrlState.ts` through `useUrlMirror` (contract-held, `e2e/bookmark.spec.ts`)                                                                         | `useState` / sessionStorage alone: a reload, a bookmark or a shared link loses the view                                                                                                     |
 | FE a page's header content           | the page renders it into the floating header itself (`PageHeader`, `ui/PageShell`)                                                                                                                                                            | a `page === …` branch in the shell's header, or a bridge carrying a page's state up to it                                                                                                   |
 | FE module store                      | its definition's `Store` (`module.ts`), mounted at the root by `ModuleStores`; it reads no other module's store (contract-held)                                                                                                               | a provider hand-nested in `main.tsx`                                                                                                                                                        |
 | FE saved views                       | the module's own store from `features/filters` (`createSavedViewsStore` + `useSavedViewsStore`)                                                                                                                                               | one store switched by the active page — every visit elsewhere reset it                                                                                                                      |

VERSION

@@ -1 +1 @@
-0.111.0
+0.117.0

backend/app/catalog/queries.py

@@ -158,6 +158,19 @@ def blocked_ids(db: Session, user: User) -> set[str]:
     )
 
 
+def followed_among(db: Session, user: User, channel_ids: set[str]) -> set[str]:
+    """Which of these channels the user subscribes to."""
+    if not channel_ids:
+        return set()
+    return set(
+        db.scalars(
+            select(Subscription.channel_id).where(
+                owned_by(Subscription.user_id, user), Subscription.channel_id.in_(channel_ids)
+            )
+        )
+    )
+
+
 def blocked_channels(db: Session, user: User, lang: str) -> list[Channel]:
     return list(
         db.execute(

backend/app/catalog/search.py

@@ -75,7 +75,8 @@ def ingest_candidates(
 ) -> list[str]:
     """Materialise one page of search candidates into the catalog (channel stubs + enrich,
     video stubs flagged via_search, enrich, Shorts classification) and return the KEEPABLE
-    video ids — non-Short, non-live — in the input relevance order."""
+    video ids — non-Short, non-live — in the input relevance order. A videos.list that fails
+    raises its YouTubeError: with nothing enriched, nothing could be kept."""
     ids = [it["id"] for it in candidates]
     if not ids:
         return []
@@ -132,13 +133,16 @@ def ingest_candidates(
         with quota.attribute(user.id, quota.QuotaAction.VIDEOS_ENRICH):
             detail_by_id = {it["id"]: it for it in yt.get_videos(ids)}
     except YouTubeError:
-        # Every candidate then stays unenriched, and an unenriched video cannot be judged live or
-        # Short — so it is dropped. A working search returns nothing and reads as "no results".
+        # An unenriched video cannot be judged live or Short, so none of this page could be kept:
+        # swallowed, the failure answered as a page with nothing on it — "no results" for a search
+        # that never ran (the shared budget spent, no API key). The stubs stay (`insert_stubs`
+        # committed them), as the channels' do above; the caller answers the failure (its refusal
+        # says which).
         log.warning(
             "the videos found by a search could not be enriched",
             extra=logs.event("search.video_enrich_failed", candidates=len(ids)),
         )
-        detail_by_id = {}
+        raise
     enriched_at = datetime.now(
         timezone.utc
     )  # when THIS enrich ran (distinct from the stub placeholder)
@@ -212,17 +216,25 @@ def clear(db: Session, user: User, video_ids: list[str]) -> int:
     """Discard these results "as if never added": drop this user's finds of them, then delete the
     ones nobody kept — a `via_search` video no reader holds (`reader.queries.kept_by_a_reader`),
     whose channel nobody subscribes to, and that no other user still has as a find. Returns how
-    many videos went."""
-    db.execute(
-        delete(SearchFind).where(
-            owned_by(SearchFind.user_id, user), SearchFind.video_id.in_(video_ids)
+    many videos went.
+
+    Only the ones this user found: a video in the catalog with no find at all (a related list's,
+    which records none) is in someone's list right now, and an id any user could name would let
+    them delete it from under that list."""
+    mine = list(
+        db.scalars(
+            delete(SearchFind)
+            .where(owned_by(SearchFind.user_id, user), SearchFind.video_id.in_(video_ids))
+            .returning(SearchFind.video_id)
         )
     )
+    if not mine:
+        return 0
     subscribed = select(Subscription.id).where(Subscription.channel_id == Video.channel_id).exists()
     other_find = select(SearchFind.id).where(SearchFind.video_id == Video.id).exists()
     result = db.execute(
         delete(Video).where(
-            Video.id.in_(video_ids),
+            Video.id.in_(mine),
             Video.via_search.is_(True),
             ~reader_queries.kept_by_a_reader(Video.id),
             ~subscribed,

backend/app/config.py

@@ -113,6 +113,11 @@ class Settings(BaseSettings):
     # each search.list costs 100 units, so the shared budget only affords ~80-90/day total; with
     # the zero-quota scrape source it's a pure anti-abuse rate limit. Admin-tunable.
     search_daily_limit_per_user: int = 70
+    # Per-user cap on related-video requests per day — a list opened and each "Show more" (the
+    # InnerTube watch page, no quota; its enrich is up to ~8 units: up to 4 pages, each a videos.list
+    # and a channels.list). A failed one gives its slot back. 0 turns related videos off.
+    # Admin-tunable.
+    related_daily_limit_per_user: int = 200
     # Source for live YouTube search: "scrape" (InnerTube, no API quota) or "api" (search.list,
     # 100 units/page). Scrape is the default; flip to "api" if scraping is blocked/breaks.
     search_source: SearchSource = "scrape"

backend/app/downloads/adapters.py

@@ -66,6 +66,11 @@ class SourceAdapter:
         """The download's raw title, before `titles.normalize_title` cleans it. Generic: yt-dlp's."""
         return info.get("title")
 
+    def is_placeholder_title(self, title: str | None) -> bool:
+        """Whether `title` is a stand-in the source gives in place of the real one (worth one more,
+        signed-out read of the page). Generic: never."""
+        return False
+
     def uploader_url(self, info: dict) -> str | None:
         """The channel/uploader page URL. Generic: whatever yt-dlp exposes directly (YouTube gives
         `channel_url`), else None (reddit / a raw media URL have no derivable channel page)."""
@@ -201,11 +206,17 @@ class FacebookAdapter(SourceAdapter):
     # Measured (2026-09-14): a SIGNED-IN read gives the placeholder "Video" (plain and as Chrome), and an
     # 18+ reel only readable as Chrome gives "Facebook"; the post's text is still in `description`. A
     # signed-out read titles the page with that same text behind the engagement counts, cut short.
+    # Measured (2026-11-01, yt-dlp 2026.08.19): since 2026-10-28 every signed-in reel read gives
+    # "Facebook" and NO description, while a signed-out read of the same reel still carries the text —
+    # so a placeholder left with nothing behind it gets one signed-out read (`backfill.public_title_info`).
     _PLACEHOLDER_TITLES = frozenset({"video", "facebook"})
 
+    def is_placeholder_title(self, title: str | None) -> bool:
+        return (title or "").strip().lower() in self._PLACEHOLDER_TITLES
+
     def title(self, info: dict) -> str | None:
         raw = info.get("title")
-        if (raw or "").strip().lower() not in self._PLACEHOLDER_TITLES:
+        if not self.is_placeholder_title(raw):
             return raw
         line = next(
             (ln.strip() for ln in (info.get("description") or "").splitlines() if ln.strip()), ""

backend/app/downloads/backfill.py

@@ -5,7 +5,10 @@ auto-detected channel becomes a clickable link) and `poster_path` (an ffmpeg fra
 thumbnail-less sources, so the card / watch page / link preview still shows an image). Best-effort
 and safe to re-run: it only touches assets still missing the field, and only re-fetches YouTube /
 Facebook sources (a direct media URL like a reddit HLS manifest carries no channel and its signed
-URL may have expired — those just get a locally-generated poster instead).
+URL may have expired — those just get a locally-generated poster instead). A Facebook download
+titled with the source's placeholder ("Facebook", "Video") is retitled from a signed-out read of its
+page, and so is each download name that only repeated the placeholder. That page read
+(`public_title_info`) also titles every new download, from the worker.
 
 Run once per environment:
     docker exec siftlode-worker-1 python -c "from app.downloads import backfill; print(backfill.run())"
@@ -14,7 +17,8 @@ Run once per environment:
 from urllib.parse import urlsplit
 
 import yt_dlp
-from sqlalchemy import select
+from sqlalchemy import select, update
+from sqlalchemy.orm import Session
 
 from app import logs
 from app.config import settings
@@ -22,12 +26,14 @@ from app.db import SessionLocal
 from app.downloads import adapters
 from app.downloads import edit as editmod
 from app.downloads import formats, service
-from app.downloads.models import MediaAsset
+from app.downloads.models import DownloadJob, MediaAsset
+from app.models import DISPLAY_TEXT_MAX
+from app.titles import normalize_title
 
 log = logs.get_logger(__name__)
 
 
-def _extract_meta(url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict | None:
+def extract_meta(url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict | None:
     """Metadata-only yt-dlp extraction, using the source adapter's client sets + options (YouTube
     needs the POT/player-client strategy even just to extract)."""
     with formats.hiding(url):
@@ -62,8 +68,43 @@ def _extract_meta_scoped(url: str, adapter: adapters.SourceAdapter, asset_id: in
     return None
 
 
+def public_title_info(info: dict, url: str, adapter: adapters.SourceAdapter, asset_id: int) -> dict:
+    """`info` to title a download from: itself, unless its title is a source's placeholder with
+    nothing behind it (a signed-in Facebook read: "Facebook", no description). Then one signed-out,
+    metadata-only read of the page lends its text — the description, else its title — as the
+    description the adapter takes a placeholder's title from. Nothing better there: `info` as it was."""
+    if not adapter.is_placeholder_title(adapter.title(info)):
+        return info
+    public = extract_meta(url, adapter, asset_id)
+    text = public and (public.get("description") or public.get("title"))
+    return {**info, "description": text} if text else info
+
+
+def _retitle(db: Session, a: MediaAsset, adapter: adapters.SourceAdapter, url: str) -> bool:
+    """Swap a placeholder title kept from an earlier download for the page's text, and the download
+    names that only repeated it. A name its owner gave (anything else) stays."""
+    if not adapter.is_placeholder_title(a.title):
+        return False
+    info = public_title_info({"title": a.title, "description": None}, url, adapter, a.id)
+    named = normalize_title(adapter.title(info))
+    if not named or adapter.is_placeholder_title(named):
+        return False
+    # One conditional write, not a read and a compare: a name its owner gives while the page is read
+    # is not overwritten by what was read before it. The asset first, as every other writer of the
+    # two locks them (`service.lock_own_job`): the session does not flush by itself.
+    placeholder = a.title
+    a.title = named
+    db.flush()
+    db.execute(
+        update(DownloadJob)
+        .where(DownloadJob.asset_id == a.id, DownloadJob.display_name == placeholder)
+        .values(display_name=named[:DISPLAY_TEXT_MAX])
+    )
+    return True
+
+
 def run() -> dict:
-    filled_url = filled_poster = 0
+    filled_url = filled_poster = retitled = 0
     with SessionLocal() as db:
         assets = (
             db.execute(
@@ -78,7 +119,7 @@ def run() -> dict:
             adapter = adapters.resolve_adapter(a.source_kind, a.source_ref)
             if a.uploader_url is None and adapter.wants_metadata_backfill():
                 url = a.source_webpage_url or service.source_url(a.source_kind, a.source_ref)
-                info = _extract_meta(url, adapter, a.id)
+                info = extract_meta(url, adapter, a.id)
                 uu = adapter.uploader_url(info) if info else None
                 if uu:
                     a.uploader_url = uu
@@ -86,6 +127,14 @@ def run() -> dict:
                     log.info(
                         "asset %s uploader_url filled", a.id
                     )  # the URL names what they downloaded
+            if adapter.wants_metadata_backfill():
+                url = a.source_webpage_url or service.source_url(a.source_kind, a.source_ref)
+                if _retitle(db, a, adapter, url):
+                    # Before the poster step: it can cut a frame for 30 s, and these locks held
+                    # across it block a rename and deadlock a delete.
+                    db.commit()
+                    retitled += 1
+                    log.info("asset %s retitled", a.id)  # the title names what they downloaded
             if a.poster_path is None:
                 # Record a self-hosted poster for every download (the reliable og:image source):
                 # ensure_poster returns the existing <base>.jpg thumbnail sidecar, or cuts a frame.
@@ -99,6 +148,7 @@ def run() -> dict:
         "assets": len(assets),
         "filled_uploader_url": filled_url,
         "filled_poster": filled_poster,
+        "retitled": retitled,
     }
     log.info("backfill done: %s", result)
     return result

backend/app/downloads/clip.py

@@ -22,6 +22,7 @@ import json
 import math
 import re
 from pathlib import Path
+from typing import Literal
 
 from app.downloads.edit import AAC_ARGS, EVEN_FRAME, INPUT_GUARD, X264_ARGS
 from app.plex.sync import HDR_TRANSFERS
@@ -57,12 +58,27 @@ _CROP_ASPECTS = (0.25, 4.0)
 _EDGE_SLACK = 1e-3
 
 
+# Every reason a clip is refused; the UI names each one (`clip.errors.<reason>`, held by the frontend's
+# backendIds contract, which reads this Literal).
+ClipReason = Literal[
+    "bad_source",
+    "bad_range",
+    "too_short",
+    "too_long",
+    "bad_audio",
+    "bad_crop",
+    "not_found",
+    "media_missing",
+    "past_end",
+]
+
+
 class ClipError(Exception):
     """A clip request that cannot be cut; `reason` is an i18n-mappable key, `params` the numbers its
     message names (the cap itself, so the client never says a stale one)."""
 
-    def __init__(self, reason: str, **params: float):
-        self.reason = reason
+    def __init__(self, reason: ClipReason, **params: float):
+        self.reason: ClipReason = reason
         self.params = params
         super().__init__(reason)
 
@@ -185,6 +201,16 @@ def _ratio(v: object) -> float | None:
     return n / d if n > 0 and d > 0 else None
 
 
+def quarter_turned(probe: dict) -> bool | None:
+    """Whether the first video stream of an ffprobe `-show_streams` JSON is stored turned a quarter
+    (ffmpeg stands it upright before any filter, so its filters see width and height swapped). None
+    when there is no video stream."""
+    for s in probe.get("streams") or []:
+        if s.get("codec_type") == "video":
+            return _quarter_turned(s)
+    return None
+
+
 def _quarter_turned(stream: dict) -> bool:
     rotation: object = (stream.get("tags") or {}).get("rotate")
     for sd in stream.get("side_data_list") or []:

backend/app/downloads/credentials.py

@@ -25,6 +25,7 @@ Security controls enforced here:
 
 import os
 from pathlib import Path
+from typing import Literal
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
@@ -163,9 +164,18 @@ def get_credential(db: Session, user_id: int, host_key: str) -> DownloadCredenti
     ).scalar_one_or_none()
 
 
+# Every reason a pasted cookies.txt is refused; the UI names each one (`downloads.errors.cookies.<reason>`,
+# held by the frontend's backendIds contract, which reads this Literal).
+CookieReason = Literal["empty", "format"]
+
+
 class InvalidCookies(ValueError):
     """The pasted cookies aren't a usable Netscape cookies.txt — surfaced as a 400 by the route."""
 
+    def __init__(self, reason: CookieReason):
+        super().__init__(reason)
+        self.reason: CookieReason = reason
+
 
 def validate_cookies(raw: str) -> str:
     """Sanity-check a pasted cookies.txt (Netscape format) and return the cleaned text. yt-dlp reads

backend/app/downloads/edit.py

@@ -11,7 +11,9 @@ with the worker branching on the asset's `source_kind` to run ffmpeg instead of
                        (the `-ss` seeks first), so a short clip is cheap even from a long source
   * crop (± trim)    → always re-encode (a filter can't be stream-copied), frame-accurate
 
-`edit_spec = {trim?: {start_s, end_s}, crop?: {x, y, w, h}, accurate?: bool}`. `accurate` is the
+`edit_spec = {trim?: {start_s, end_s}, crop?: {x, y, w, h, frame_w?, frame_h?}, accurate?: bool}`. A
+crop with `frame_w`/`frame_h` counts the picture as it is SHOWN, measured on a frame of that size
+(`crop_filter`); one without them is in the file's stored pixels (its older form). `accurate` is the
 per-edit user choice for a trim-only cut (ignored when a crop forces a re-encode anyway). `split`
 is a frontend concept: the
 UI fans a split out into N trim jobs, so there is one output file per job here.
@@ -60,6 +62,46 @@ class EditAborted(Exception):
 _MAX_SEGMENTS = 100
 
 
+def _crop_frame(crop: dict) -> dict | None:
+    """The picture size a crop was measured on, or None when it has none it could be scaled by (a
+    spec from before it was sent, which `crop_filter` cuts in the file's own pixels)."""
+    try:
+        w, h = int(crop["frame_w"]), int(crop["frame_h"])
+    # silent-ok: no frame is a crop's older form, and it is still the crop that was asked for. An
+    # infinite number (JSON `1e400`) is OverflowError, and it is no more a frame than "x" is.
+    except (KeyError, TypeError, ValueError, OverflowError):
+        return None
+    return {"frame_w": w, "frame_h": h} if w > 0 and h > 0 else None
+
+
+def crop_filter(crop: dict) -> str:
+    """The ffmpeg `crop` of an edit. Its numbers count the picture as the browser reports it, which
+    is its SHOWN size: a video with wide pixels (320 stored, 640 shown) would be cut off to one side
+    in ffmpeg's stored ones, so they are scaled to `iw` / `ih` by the size they were measured on. A
+    rotated file needs nothing more: both the browser and ffmpeg's filters see it upright."""
+    frame_w, frame_h = crop.get("frame_w"), crop.get("frame_h")
+    if not frame_w or not frame_h:
+        return f"crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}"
+    return (
+        f"crop=iw*{crop['w']}/{frame_w}:ih*{crop['h']}/{frame_h}"
+        f":iw*{crop['x']}/{frame_w}:ih*{crop['y']}/{frame_h}"
+    )
+
+
+def crop_stored_size(crop: dict, src_w: int | None, src_h: int | None) -> tuple[int, int] | None:
+    """The size `crop_filter` cuts out of a `src_w` x `src_h` frame, evened as `EVEN_FRAME` evens it —
+    the clip's size when ffprobe cannot tell. The frame is the one ffmpeg's filters see: a rotated
+    file's stood upright, its stored size turned (the caller's to turn). A crop counted in the shown
+    picture is a fraction of that frame, not its own pixel count; None when the size is unknown."""
+    if crop.get("frame_w") and crop.get("frame_h"):
+        if not src_w or not src_h:
+            return None
+        w, h = src_w * crop["w"] // crop["frame_w"], src_h * crop["h"] // crop["frame_h"]
+    else:
+        w, h = crop["w"], crop["h"]
+    return w // 2 * 2, h // 2 * 2
+
+
 def normalize_edit_spec(spec: dict | None) -> dict:
     """Canonicalize a raw edit spec: clamp/round trim, coerce crop to ints, drop empties.
 
@@ -72,7 +114,7 @@ def normalize_edit_spec(spec: dict | None) -> dict:
     if crop:
         try:
             c = {k: int(round(float(crop[k]))) for k in ("x", "y", "w", "h")}
-        except (KeyError, TypeError, ValueError) as exc:
+        except (KeyError, TypeError, ValueError, OverflowError) as exc:
             # The clip still renders — uncropped. The user asked for a crop, got a whole frame,
             # and nothing anywhere called it a failure; this line is the only trace there is.
             log.warning(
@@ -81,7 +123,8 @@ def normalize_edit_spec(spec: dict | None) -> dict:
             )
             c = None
         if c and c["w"] > 0 and c["h"] > 0 and c["x"] >= 0 and c["y"] >= 0:
-            out["crop"] = c
+            frame = _crop_frame(crop)
+            out["crop"] = {**c, **frame} if frame else c
 
     # Multi-segment JOIN (cut-list → one concatenated file). Takes precedence over `trim`.
     segs = spec.get("segments")
@@ -268,7 +311,7 @@ def build_edit_cmd(src: Path, dest: Path, spec: dict, out_ext: str) -> list[str]
     if reencode:
         # Input -ss + re-encode is frame-accurate (decodes from the prior keyframe, discards up to
         # the exact cut). A crop adds the filter; an accurate trim only evens the frame.
-        cropf = f"crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}," if crop else ""
+        cropf = f"{crop_filter(crop)}," if crop else ""
         cmd += ["-vf", cropf + EVEN_FRAME, *X264_ARGS, *AAC_ARGS]
     else:
         cmd += ["-c", "copy", "-avoid_negative_ts", "make_zero"]
@@ -313,7 +356,7 @@ def build_concat_plan(src: Path, dest: Path, spec: dict, out_ext: str, staging:
     ]
 
     if needs_reencode(spec):
-        cropf = f",crop={crop['w']}:{crop['h']}:{crop['x']}:{crop['y']}" if crop else ""
+        cropf = f",{crop_filter(crop)}" if crop else ""
         parts, labels = [], []
         for i, s in enumerate(segs):
             st, en = s["start_s"], s["end_s"]

backend/app/downloads/folders.py

@@ -24,6 +24,7 @@ kept it — and its `ready_at`, the moment it finished (`stamp_done`).
 
 from datetime import datetime, timedelta, timezone
 from enum import StrEnum
+from typing import Literal
 from urllib.parse import urlsplit
 
 from sqlalchemy import select
@@ -181,12 +182,22 @@ def stamp_done(db: Session, job: DownloadJob) -> None:
     job.expiry_warned = False
 
 
+# Every folder change the rules refuse, answered as a generic refusal; the UI names each one
+# (`errors.refused.<reason>`, held by the frontend's backendIds contract, which reads this Literal).
+FolderReason = Literal[
+    "file_folder_gone",
+    "file_folder_name_taken",
+    "file_folder_not_its_source",
+    "file_folder_not_own",
+]
+
+
 class FolderError(Exception):
     """A folder change the rules refuse; `reason` is the refusal the route answers with."""
 
-    def __init__(self, reason: str) -> None:
+    def __init__(self, reason: FolderReason) -> None:
         super().__init__(reason)
-        self.reason = reason
+        self.reason: FolderReason = reason
 
 
 def own_folder(db: Session, user_id: int, folder_id: int, *, hold: bool = True) -> FileFolder:

backend/app/downloads/links.py

@@ -127,14 +127,35 @@ def check_grant(token: str, grant: str | None, password_version: int) -> bool:
 # --- serialization -------------------------------------------------------------------------
 
 
-def owner_view(link: DownloadLink, base_url: str = "", token: str | None = None) -> dict:
+def opens(db: Session, link: DownloadLink) -> str:
+    """What a link opens, in the words its address and its preview use: "folder", "video" or
+    "file". A file still being made reads as the video it mostly is."""
+    from app.downloads import mediakind
+
+    if link.folder_id is not None:
+        return "folder"
+    job = db.get(DownloadJob, link.job_id)
+    asset = db.get(MediaAsset, job.asset_id) if job and job.asset_id else None
+    kind = asset.media_kind if asset else None
+    return "file" if kind and kind != mediakind.VIDEO else "video"
+
+
+def share_path(db: Session, link: DownloadLink, token: str) -> str:
+    """The address a link is given out on: its path says what it opens (`opens`). Only a word for the
+    reader, the token is the whole key: every prefix of `main.SHARE_PREFIXES` opens every link, so
+    the links already sent on /watch/ work for good."""
+    prefix = {"folder": "folder", "file": "file", "video": "watch"}[opens(db, link)]
+    return f"/{prefix}/{token}"
+
+
+def owner_view(db: Session, link: DownloadLink, token: str | None = None) -> dict:
     """What the file owner sees when managing their links. `token` is the one just made (it is in
     hand even where no copy is kept); else it is read back, and `url` is None when it cannot be."""
     token = token or recover(link)
     return {
         "id": link.id,
         "token": token,
-        "url": f"{base_url}/watch/{token}" if token else None,
+        "url": share_path(db, link, token) if token else None,
         "allow_download": link.allow_download,
         "has_password": link.password_hash is not None,
         "expires_at": link.expires_at.isoformat() if link.expires_at else None,

backend/app/downloads/models.py

@@ -234,7 +234,9 @@ class DownloadJob(Base, TimestampMixin, UpdatedAtMixin):
     source_asset_id: Mapped[int | None] = mapped_column(
         ForeignKey("media_assets.id", ondelete="SET NULL")
     )
-    # For edit jobs: the trim/crop recipe {trim?:{start_s,end_s}, crop?:{x,y,w,h}} in pixels. For clip
+    # For edit jobs: the trim/crop recipe {trim?:{start_s,end_s}, crop?:{x,y,w,h,frame_w?,frame_h?}}, its
+    # crop in the SHOWN picture's pixels when it carries the frame it was measured on (`edit.crop_filter`),
+    # else in the file's stored ones. For clip
     # jobs: the clip spec {source, ref, start_s, end_s, audio_track?, crop?:{x,y,w,h,aspect}}, its crop
     # in fractions of the box it was drawn in (`downloads.clip.normalize`).
     edit_spec: Mapped[dict | None] = mapped_column(JSON)

backend/app/downloads/og.py

@@ -1,4 +1,4 @@
-"""Server-rendered Open Graph tags for the public /watch/{token} page.
+"""Server-rendered Open Graph tags for the public page of a share link (/watch/, /file/, /folder/).
 
 The watch page is a client-side SPA, so a social crawler (facebookexternalhit, Twitterbot, …) that
 fetches /watch/{token} would otherwise only see the generic index.html — a blank/greyed link card.
@@ -76,16 +76,21 @@ def _watch_tags(token: str, db: Session) -> str | None:
     link = linksmod.find(db, token)
     if link is None or linksmod.is_expired(link):
         return None
-    url = f"{settings.app_base}/watch/{token}"
-    folder = link.folder_id is not None
+    url = f"{settings.app_base}{linksmod.share_path(db, link, token)}"
+    # What the card calls it, as its address does.
+    kind = linksmod.opens(db, link)
+    folder, video = kind == "folder", kind == "video"
     if link.password_hash:
         # Password-gated: don't leak the title/thumbnail in the unfurl.
         return "\n    ".join(
             [
                 "<title>Siftlode</title>",
-                _tag("og:title", "Password-protected " + ("folder" if folder else "video")),
+                _tag(
+                    "og:title",
+                    "Password-protected " + ("folder" if folder else "video" if video else "file"),
+                ),
                 _tag("og:description", "Shared via Siftlode"),
-                _tag("og:type", "website" if folder else "video.other"),
+                _tag("og:type", "video.other" if video else "website"),
                 _tag("og:url", url),
                 _tag("og:site_name", "Siftlode"),
             ]
@@ -96,7 +101,7 @@ def _watch_tags(token: str, db: Session) -> str | None:
     asset = db.get(MediaAsset, job.asset_id) if job and job.asset_id else None
     if job is None or asset is None or asset.status != "ready":
         return None
-    title = (job.display_name or asset.title or "Video").strip()
+    title = (job.display_name or asset.title or ("Video" if video else "File")).strip()
     channel = (job.display_uploader or asset.uploader or "").strip()
     # Pick the link-preview image. Facebook's scraper REJECTS our own poster ("Corrupted Image" in the
     # Sharing Debugger): the poster is an ffmpeg-produced JPEG whose non-standard marker order FB's
@@ -118,7 +123,7 @@ def _watch_tags(token: str, db: Session) -> str | None:
         f"<title>{html.escape(title)}</title>",
         _tag("og:title", title),
         _tag("og:description", channel or "Shared via Siftlode"),
-        _tag("og:type", "video.other"),
+        _tag("og:type", "video.other" if video else "website"),
         _tag("og:url", url),
         _tag("og:site_name", "Siftlode"),
         _tag("twitter:title", title, attr="name"),

backend/app/downloads/pipeline.py

@@ -7,6 +7,7 @@ from datetime import date, datetime, timezone
 from pathlib import Path
 
 import yt_dlp
+from sqlalchemy import update
 from yt_dlp.utils import download_range_func
 
 from app import logs, sysconfig
@@ -16,6 +17,7 @@ from app.downloads import clip as clipmod
 from app.downloads import edit as editmod
 from app.downloads import errors as dlerrors
 from app.downloads import adapters, credentials, formats, mediakind, playable, probe, quota
+from app.downloads import backfill
 from app.downloads import service, storage
 from app.downloads import urlguard
 from app.downloads.jobdb import (
@@ -585,9 +587,14 @@ def _download(
         # missing duration hid the trim action. Probed before the sidecars so the .nfo runtime has it
         # too. Same probe the upload ingest uses.
         vcodec, acodec, width, height, duration_s = probe.resolve_media_facts(produced, info)
+        # A placeholder title with nothing behind it ("Facebook" from a signed-in read) borrows the
+        # page's text from one signed-out read; the download itself stays the signed-in one. The page
+        # yt-dlp read, not the link queued: a group post's link is rewritten to its video, and
+        # signed out the post itself is the login wall.
+        titled = backfill.public_title_info(info, info.get("webpage_url") or url, adapter, asset_id)
         meta = storage.MediaMeta(
             video_id=info.get("id") or source_ref,
-            title=normalize_title(adapter.title(info)) or source_ref,
+            title=normalize_title(adapter.title(titled)) or source_ref,
             uploader=info.get("uploader") or info.get("channel") or "Unknown Channel",
             upload_date=_parse_upload_date(info.get("upload_date")),
             uniqueid_type=adapter.nfo_uniqueid_type(),
@@ -830,6 +837,18 @@ def _fail_edit(
     )
 
 
+def _filter_frame(
+    path: Path, width: int | None, height: int | None
+) -> tuple[int | None, int | None]:
+    """A file's frame as ffmpeg's filters see it: the stored size, turned when the stream is stored
+    turned a quarter (ffmpeg stands it upright first). Unknown when the file cannot be read."""
+    data = probe.probe_json(path)
+    turned = clipmod.quarter_turned(data) if data else None
+    if turned is None:
+        return None, None
+    return (height, width) if turned else (width, height)
+
+
 def _process_edit(job_id: int, asset_id: int) -> None:
     """Produce a per-user trim/crop clip from the source asset's downloaded file via ffmpeg."""
     with SessionLocal() as db:
@@ -898,6 +917,12 @@ def _process_edit(job_id: int, asset_id: int) -> None:
         size = final.stat().st_size if final.exists() else None
         # The clip's real frame: a re-encode evens an odd crop or source (`editmod.EVEN_FRAME`).
         _, _, out_w, out_h, _ = probe.probe_media(final)
+        # Unsized, a crop's own size stands in, cut from the frame the filters saw.
+        cut = (
+            editmod.crop_stored_size(edit_spec["crop"], *_filter_frame(src_path, src_w, src_h))
+            if crop and not (out_w and out_h)
+            else None
+        )
 
         with SessionLocal() as db:
             asset = db.get(MediaAsset, asset_id)
@@ -909,11 +934,10 @@ def _process_edit(job_id: int, asset_id: int) -> None:
                 asset.duration_s = total_s or asset.duration_s
                 if out_w and out_h:
                     asset.width, asset.height = out_w, out_h
-                elif crop:
-                    asset.width = edit_spec["crop"]["w"]
-                    asset.height = edit_spec["crop"]["h"]
+                elif cut:
+                    asset.width, asset.height = cut
                 else:
-                    asset.width, asset.height = src_w, src_h
+                    asset.width, asset.height = (None, None) if crop else (src_w, src_h)
                 asset.error = None
                 asset.last_access_at = datetime.now(timezone.utc)
             job = db.get(DownloadJob, job_id)
@@ -1116,14 +1140,20 @@ def _process_clip(job_id: int, asset_id: int) -> None:
             fields: dict = {"status": JobStatus.DONE, "progress": 100, "phase": None}
             # A video outside the catalog was queued as "Clip (clip)": the fetch has its title now.
             placeholder = service.clip_title(None, None)
+            named = None
             if asset and fetched_title and asset.title == placeholder:
                 named = service.clip_title(fetched_title, None)
                 asset.title = named
-                if job_row := db.get(DownloadJob, job_id):
-                    if job_row.display_name == placeholder:
-                        fields["display_name"] = named[:DISPLAY_TEXT_MAX]
             title = asset.title if asset else None
             finalized = service.finalize_if_running(db, job_id, **fields)
+            if finalized and named:
+                # Only a name that still repeats the placeholder, in one conditional write: one its
+                # owner gave meanwhile stays.
+                db.execute(
+                    update(DownloadJob)
+                    .where(DownloadJob.id == job_id, DownloadJob.display_name == placeholder)
+                    .values(display_name=named[:DISPLAY_TEXT_MAX])
+                )
             db.commit()
             if finalized:
                 _notify_download_done(db, user_id, title, job_id, kind="edit")

backend/app/downloads/quota.py

@@ -16,10 +16,12 @@ That is a per-job ceiling, not an aggregate ledger: concurrent jobs of one user
 remainder (in-flight bytes are not `ready`, so `footprint` cannot see them), so a wave of
 max_concurrent downloads can still land over the cap — the deliberate trade, since a download's size
 is unknown until it finishes. CLIP jobs consult it before their fetch or encode and again with
-their output's real size before it is placed. Edit jobs do not consult it at all (tracked as SEC-19).
+their output's real size before it is placed. Edit jobs consult it with their output's real size
+before it is placed (`test_edit_cap.py`).
 """
 
 from dataclasses import dataclass
+from typing import Literal
 
 from sqlalchemy import and_, func, or_, select
 from sqlalchemy.orm import Session
@@ -50,11 +52,16 @@ class QuotaLimits:
     unlimited: bool
 
 
-class QuotaExceeded(Exception):
-    """Raised by check_enqueue; `reason` is one of max_jobs|max_bytes (i18n key on the client)."""
+# Every cap a download can hit; the UI names each one (`downloads.errors.quota.<reason>`, held by the
+# frontend's backendIds contract, which reads this Literal).
+QuotaReason = Literal["max_jobs", "max_bytes"]
 
-    def __init__(self, reason: str, limit: int, current: int):
-        self.reason = reason
+
+class QuotaExceeded(Exception):
+    """Raised by check_enqueue; `reason` names the cap it hit (an i18n key on the client)."""
+
+    def __init__(self, reason: QuotaReason, limit: int, current: int):
+        self.reason: QuotaReason = reason
         self.limit = limit
         self.current = current
         super().__init__(f"download quota exceeded: {reason} ({current}/{limit})")

backend/app/downloads/service.py

@@ -10,6 +10,7 @@ handler); the folder, link and quota writes are `folders`, `links` and `quota`.
 
 import uuid
 from datetime import datetime, timezone
+from typing import Literal
 
 from sqlalchemy import delete as delete_rows
 from sqlalchemy import func, select, update
@@ -39,11 +40,16 @@ from app.plex import paths as plex_paths
 from app.userscope import owned_by, owned_row
 
 
-class EditError(Exception):
-    """Bad edit request (empty spec / source not ready); `reason` is an i18n-mappable key."""
+# Every reason an edit is refused; the UI names each one (`downloads.errors.edit.<reason>`, held by
+# the frontend's backendIds contract, which reads this Literal).
+EditReason = Literal["source_not_ready", "not_media", "empty_edit"]
 
-    def __init__(self, reason: str):
-        self.reason = reason
+
+class EditError(Exception):
+    """Bad edit request (empty spec / source not ready / not media); `reason` names the sentence."""
+
+    def __init__(self, reason: EditReason):
+        self.reason: EditReason = reason
         super().__init__(reason)
 
 

backend/app/downloads/urlguard.py

@@ -33,24 +33,33 @@ user-controlled destination to guard.
 
 import ipaddress
 import socket
+from typing import Literal
 from urllib.parse import urlparse
 
 # Reason codes travel to the client inside the structured 422 detail, so they are part of the API
-# vocabulary (frontend `localizeDetail`) — keep them stable.
-REASON_SCHEME = "scheme"  # not http(s)
-REASON_NO_HOST = "no_host"  # URL carries no hostname
-REASON_MALFORMED = "malformed"  # unparseable authority or port; urlparse raises late, so guard it
-REASON_UNRESOLVABLE = "unresolvable"  # DNS said nothing (honest: not the same as "blocked")
-REASON_PRIVATE = "private"  # resolves into a network the server must not fetch from
+# vocabulary — keep them stable. The UI names each one (`downloads.errors.urlBlocked.<reason>`, held by
+# the frontend's backendIds contract, which reads this Literal).
+UrlBlockedReason = Literal["scheme", "no_host", "malformed", "unresolvable", "private"]
+REASON_SCHEME: UrlBlockedReason = "scheme"  # not http(s)
+REASON_NO_HOST: UrlBlockedReason = "no_host"  # URL carries no hostname
+REASON_MALFORMED: UrlBlockedReason = (
+    "malformed"  # unparseable authority or port; urlparse raises late
+)
+REASON_UNRESOLVABLE: UrlBlockedReason = (
+    "unresolvable"  # DNS said nothing (not the same as "blocked")
+)
+REASON_PRIVATE: UrlBlockedReason = (
+    "private"  # resolves into a network the server must not fetch from
+)
 
 
 class BlockedUrl(Exception):
     """A user-supplied URL that must not be fetched server-side. ``reason`` is one of the
     REASON_* codes above."""
 
-    def __init__(self, reason: str):
+    def __init__(self, reason: UrlBlockedReason):
         super().__init__(reason)
-        self.reason = reason
+        self.reason: UrlBlockedReason = reason
 
 
 def _is_forbidden(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:

backend/app/main.py

@@ -151,7 +151,7 @@ async def _reap_hls_sessions() -> None:
     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
+    player keeps checkpointing 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."""
     while True:
@@ -368,6 +368,10 @@ INDEX_HTML = STATIC_DIR / "index.html"
 # A public share link's own page: the player alone, without the app's bundle (frontend/watch.html).
 WATCH_HTML = STATIC_DIR / "watch.html"
 INDEX_HEADERS = {"Cache-Control": "no-cache"}
+# The paths a share link opens on, by what it opens (`links.share_path`). Any of them opens any link.
+# A new one also goes in frontend/public/robots.txt, the Vite dev entry and WatchPage's token parsing
+# (watchEntry.contract.test.ts).
+SHARE_PREFIXES = ("watch/", "file/", "folder/")
 app.mount(
     "/assets",
     StaticFiles(directory=STATIC_DIR / "assets", check_dir=False),
@@ -381,8 +385,10 @@ async def index() -> FileResponse:
 
 
 @app.get("/watch/{token}")
-async def watch_page(token: str):
-    """Serve the public player page for a share link, with per-video Open Graph tags injected so the
+@app.get("/file/{token}")
+@app.get("/folder/{token}")
+async def share_page(token: str):
+    """Serve the public page of a share link, with per-link Open Graph tags injected so the
     link unfurls richly (title/channel/thumbnail) in Messenger/social crawlers. A real browser
     ignores the extra tags and boots WatchPage; invalid/expired/password links fall back to the
     generic card."""
@@ -409,8 +415,8 @@ async def spa_fallback(full_path: str) -> FileResponse:
             # Real SPA-root assets (welcome images, favicon, robots.txt) rarely change and have
             # stable names, so a moderate cache is safe and satisfies the cache-lifetime audit.
             return FileResponse(candidate, headers={"Cache-Control": "public, max-age=604800"})
-    # A /watch/ path the route above does not match (a trailing segment, no token) is still the
+    # A share path the route above does not match (a trailing segment, no token) is still the
     # player's: WatchPage reads the token off the path and says when a link is gone.
-    if full_path.startswith("watch/"):
+    if full_path.startswith(SHARE_PREFIXES):
         return FileResponse(WATCH_HTML, headers=INDEX_HEADERS)
     return FileResponse(INDEX_HTML, headers=INDEX_HEADERS)

backend/app/plex/service.py

@@ -6,9 +6,9 @@ The rest of the mirror's writes stay with the sync (`plex.sync`): a collection's
 after a write-back, its local cleanup after a delete.
 """
 
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 
-from sqlalchemy import CursorResult, delete, func, select, update
+from sqlalchemy import CursorResult, delete, func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 from sqlalchemy.orm import Session
 
@@ -271,6 +271,10 @@ def reorder_playlist(db: Session, pl: PlexPlaylist, rating_keys: list[str]) -> N
 
 # --- a user's watch state --------------------------------------------------------------------
 
+# How long after a watched mark a mid-item position is read as the finishing player's late tick
+# (`checkpoint`): the tick is every 10 s, plus the request's own latency and a retry.
+_LATE_CHECKPOINT_S = 30
+
 
 def mark_finished(db: Session, user_id: int, item_id: int, now: datetime) -> bool:
     """Mark the item watched (position cleared) and say whether THIS call made it so. Two near-end
@@ -352,16 +356,33 @@ def checkpoint(
     now: datetime,
     *,
     dirty: bool,
-) -> PlexState:
-    """Record a resume position. `dirty` marks it not yet mirrored to Plex — set before a push, so
-    the reconcile re-pushes it if the push fails and the push can settle it once Plex confirms."""
+) -> bool:
+    """Record a resume position, and say whether it was recorded. `dirty` marks it not yet mirrored
+    to Plex — set before a push, so the reconcile re-pushes it if the push fails and the push can
+    settle it once Plex confirms.
+
+    Not onto a row marked watched in the last `_LATE_CHECKPOINT_S`: that position is the player's
+    tick sent just before its own finish (or a mark from another tab), and writing it made a watched
+    item in progress again — on Plex too, through the resume push it carried. Decided by the write
+    itself, since the mark can commit between any read here and the write. A rewatch is checkpointed
+    as before once the mark is that far behind it."""
     st = state_row(db, user, item_id, st)
-    st.position_seconds = position
-    st.progress_updated_at = now
+    values: dict[str, object] = {"position_seconds": position, "progress_updated_at": now}
     if dirty:
-        st.synced_to_plex = False
+        values["synced_to_plex"] = False
+    not_just_finished = or_(
+        PlexState.status != "watched",
+        PlexState.watched_at.is_(None),
+        PlexState.watched_at <= now - timedelta(seconds=_LATE_CHECKPOINT_S),
+    )
+    result = db.execute(
+        update(PlexState)
+        .where(PlexState.id == st.id, not_just_finished)
+        .values(values)
+        .execution_options(synchronize_session="fetch")
+    )
     db.flush()
-    return st
+    return isinstance(result, CursorResult) and result.rowcount > 0
 
 
 def forget_state(db: Session, st: PlexState) -> None:

backend/app/plex/stream.py

@@ -66,7 +66,9 @@ _SESSION_IDLE_S = 600  # reap a session with no access for this long
 # restart leaves them behind like any other. `sweep_orphans` deletes ONLY names
 # matching one of those two shapes: `_HLS_ROOT` is admin-configurable (PLEX_HLS_DIR), so it may
 # legitimately point at a shared scratch path we do not own, and a blanket "delete every directory
-# under the root" would take the neighbours with it.
+# under the root" would take the neighbours with it. A torn-down session's directory is renamed to
+# its own name + `_TOMB` + 8 hex digits before it is deleted (see `_detach`), so a crash between the
+# two leaves a name this sweep still recognises.
 #
 # The KEY is anchored to digits (a Plex rating_key is a number) — that is what keeps foreign names
 # out. A `.+` there let `snapshot_2024_backup_+1.00` through, and pairing `.+` with an optional tail
@@ -74,8 +76,10 @@ _SESSION_IDLE_S = 600  # reap a session with no access for this long
 # non-numeric rating_key would merely leave its directory unswept, which is the safe direction to
 # fail. Covered by test_plex_stream.py — this regex is the only thing standing between the sweep
 # and someone else's data.
+_TOMB = ".dead-"
 _SESSION_DIR_RE = re.compile(
-    r"^\d+_\d+(_[^_]+_[+-]\d+\.\d{2})?$|^\d+_u\d+_\d+_[^_]+_[+-]\d+\.\d{2}$"
+    r"^\d+_\d+(_[^_]+_[+-]\d+\.\d{2})?$"
+    rf"|^\d+_u\d+_\d+_[^_]+_[+-]\d+\.\d{{2}}({re.escape(_TOMB)}[0-9a-f]{{8}})?$"
 )
 # When this process started. `sweep_orphans` only deletes directories older than this: everything
 # newer belongs to a session THIS run created, and since `start_session` reuses a directory path
@@ -93,7 +97,7 @@ _MTIME_GRACE_S = 2.0
 
 _lock = threading.Lock()
 # Keyed by VIEWER and item, (user_id, rating_key). Keyed by the item alone, a second account opening
-# the same film `_kill`ed the first one's session: the displaced viewer got a 404, reclaimed at its
+# the same film tore down the first one's session: the displaced viewer got a 404, reclaimed at its
 # playhead, and so evicted the other in turn — two people could not watch one film at once. (One
 # account on two devices still shares a session; that case ends in the player's bounded reclaim.)
 _sessions: dict[tuple[int, str], "HlsSession"] = {}
@@ -121,7 +125,7 @@ class HlsSession:
         # replaces the viewer's registered session for the item — and the old player's next request
         # for `seg_12.ts`, resolved by (viewer, rating_key) alone, 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.
-        # A request naming a session that is no longer registered is a 404,
+        # A request naming a session that is no longer registered is a 410,
         # which the player recovers from by restarting at the playhead.
         self.id = secrets.token_urlsafe(9)
         self.key = key  # the item's rating_key (what the logs name)
@@ -641,29 +645,82 @@ def _probe_first_pts(seg: Path) -> float | None:
     return None
 
 
-def _kill(s: HlsSession) -> None:
+# Teardown is split in two, because every segment request and checkpoint takes `_lock`: waiting up to
+# 3 s for an ffmpeg to exit and deleting a whole segmented film under it stalled every other
+# viewer's playback for one viewer's seek or one reap pass. `_detach` (under the lock) signals the
+# process and renames its directory aside — so the deletion can never hit a NEW session that reuses
+# the path — and `_finish` (after the lock is released) waits and deletes.
+#
+# What the rename cannot cover is the dying ffmpeg itself: it writes by path, so until it has exited
+# it can still put a segment, or its final ENDLIST playlist, into a new session's directory on the
+# same path. `_dying` remembers it by that path, and `_spawn` waits it out — under the lock, on
+# purpose — before it creates the directory again.
+_dying: dict[Path, subprocess.Popen] = {}
+
+
+def _await_exit(key: str, proc: subprocess.Popen) -> None:
     try:
-        s.proc.terminate()
         try:
-            s.proc.wait(timeout=3)
+            proc.wait(timeout=3)
         # silent-ok: the escalation IS the handling. A transcode that ignores TERM for three
         # seconds gets KILL, which is exactly what this branch does.
         except subprocess.TimeoutExpired:
-            s.proc.kill()
+            proc.kill()
     except Exception as exc:  # noqa: BLE001 — teardown finishes whatever the process does
         # Not nothing: what survives this is an ffmpeg nobody owns any more, holding a VAAPI
         # handle and a core, and the transcode cap that is supposed to bound them counts rows in
         # `_sessions` rather than processes. One line is the only way that ever surfaces.
+        log.info(
+            "could not stop the transcode process",
+            extra=logs.event("plex.stream.kill_failed", key=key, reason=type(exc).__name__),
+        )
+
+
+def _detach(s: HlsSession) -> tuple[HlsSession, Path | None]:
+    """Caller holds _lock and has taken `s` out of `_sessions`. Hand the result to `_finish` once the
+    lock is released."""
+    try:
+        s.proc.terminate()
+    except Exception as exc:  # noqa: BLE001 — teardown finishes whatever the process does
         log.info(
             "could not stop the transcode process",
             extra=logs.event("plex.stream.kill_failed", key=s.key, reason=type(exc).__name__),
         )
-    shutil.rmtree(s.dir, ignore_errors=True)
+    _dying[s.dir] = s.proc
+    tomb = s.dir.with_name(f"{s.dir.name}{_TOMB}{secrets.token_hex(4)}")
+    try:
+        s.dir.rename(tomb)
+    # silent-ok: nothing on disk (ffmpeg died before writing, or a sweep took it) — nothing to delete.
+    except FileNotFoundError:
+        return s, None
+    except OSError as exc:
+        # Cannot be moved aside, so it cannot be deleted outside the lock either: the path may be a
+        # new session's a moment from now. Deleted here instead, the old way.
+        log.info(
+            "a session directory could not be moved aside; deleted under the lock",
+            extra=logs.event("plex.stream.tomb_failed", key=s.key, reason=type(exc).__name__),
+        )
+        shutil.rmtree(s.dir, ignore_errors=True)
+        return s, None
+    return s, tomb
 
 
-def _enforce_caps(user_id: int, max_transcodes: int, max_sessions: int) -> None:
-    """Caller holds _lock. Three bounds, applied after a session is registered, each dropping the
-    least recently accessed sessions over it:
+def _finish(doomed: "list[tuple[HlsSession, Path | None]]") -> None:
+    """The slow half of a teardown, called WITHOUT `_lock`."""
+    for s, tomb in doomed:
+        _await_exit(s.key, s.proc)
+        with _lock:
+            if _dying.get(s.dir) is s.proc:
+                del _dying[s.dir]
+        if tomb is not None:
+            shutil.rmtree(tomb, ignore_errors=True)
+
+
+def _enforce_caps(
+    user_id: int, max_transcodes: int, max_sessions: int
+) -> "list[tuple[HlsSession, Path | None]]":
+    """Caller holds _lock, and `_finish`es what this returns once it has released it. Three bounds,
+    applied after a session is registered, each dropping the least recently accessed sessions over it:
 
     * this account's own sessions (`_MAX_SESSIONS_PER_USER`) — first, so a single account filling the
       box evicts itself before anyone else;
@@ -672,10 +729,12 @@ def _enforce_caps(user_id: int, max_transcodes: int, max_sessions: int) -> None:
       whole segmented copy of the film under `_HLS_ROOT`, written faster than realtime. Counted only
       by the transcode cap, N distinct items were N ffmpegs and N film-sized scratch directories.
 
-    Somebody's playback stops at each drop. The route turns the missing session into a retryable 404
+    Somebody's playback stops at each drop. The route turns the missing session into a 410
     and the player restarts at the playhead, so from the server nothing failed — and "my film keeps
     rebuffering" has no other explanation anywhere, hence the line."""
 
+    doomed: list[tuple[HlsSession, Path | None]] = []
+
     def cull(pool: list[tuple[tuple[int, str], HlsSession]], cap: int, bound: str) -> None:
         if len(pool) <= cap:
             return
@@ -690,12 +749,13 @@ def _enforce_caps(user_id: int, max_transcodes: int, max_sessions: int) -> None:
                     sessions=len(pool),
                 ),
             )
-            _kill(sess)
             _sessions.pop(reg, None)
+            doomed.append(_detach(sess))
 
     cull([kv for kv in _sessions.items() if kv[0][0] == user_id], _MAX_SESSIONS_PER_USER, "user")
     cull([kv for kv in _sessions.items() if kv[1].transcode], max_transcodes, "transcode")
     cull(list(_sessions.items()), max_sessions, "total")
+    return doomed
 
 
 def start_session(
@@ -759,68 +819,79 @@ def start_session(
         # can't starve the co-located API/playback. preexec_fn runs in the forked child (POSIX); on a
         # platform without fork (the API always runs in a Linux container in prod) it's simply omitted.
         preexec = _sw_child_preexec if (transcode and not hw and os.name == "posix") else None
-        with _lock:
-            if replace_only is not None and _sessions.get(reg) is not replace_only:
-                return None  # superseded/culled while we waited out of lock — don't clobber the newer one
-            old = _sessions.pop(reg, None)
-            if old is not None:
-                _kill(old)
-            shutil.rmtree(directory, ignore_errors=True)
-            directory.mkdir(parents=True, exist_ok=True)
-            proc = subprocess.Popen(
-                _ffmpeg_cmd(
-                    src,
-                    start_s,
+        doomed: list[tuple[HlsSession, Path | None]] = []
+        # Finished even when the new session fails to start (no space, no ffmpeg, a DB error): what
+        # was moved aside under the lock is otherwise left for a restart's sweep.
+        try:
+            with _lock:
+                if replace_only is not None and _sessions.get(reg) is not replace_only:
+                    return None  # superseded/culled while we waited out of lock — don't clobber the newer one
+                old = _sessions.pop(reg, None)
+                if old is not None:
+                    doomed.append(_detach(old))
+                # An ffmpeg still exiting from THIS path (the old session, or one stopped a moment ago)
+                # would write into the directory about to be made; see `_dying`.
+                prev = _dying.pop(directory, None)
+                if prev is not None:
+                    _await_exit(key, prev)
+                shutil.rmtree(directory, ignore_errors=True)
+                directory.mkdir(parents=True, exist_ok=True)
+                proc = subprocess.Popen(
+                    _ffmpeg_cmd(
+                        src,
+                        start_s,
+                        directory,
+                        audio_ord,
+                        aoff,
+                        audio_langs if is_multi else None,
+                        transcode=transcode,
+                        hw=hw,
+                        tonemap=tonemap,
+                        preset=preset,
+                        crf=crf,
+                        max_height=max_height,
+                        loudnorm=loudnorm,
+                    ),
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    preexec_fn=preexec,
+                )
+                s = HlsSession(
+                    key,
                     directory,
-                    audio_ord,
-                    aoff,
-                    audio_langs if is_multi else None,
+                    proc,
+                    start_s,
+                    variants,
                     transcode=transcode,
                     hw=hw,
                     tonemap=tonemap,
-                    preset=preset,
-                    crf=crf,
-                    max_height=max_height,
-                    loudnorm=loudnorm,
-                ),
-                stdout=subprocess.DEVNULL,
-                stderr=subprocess.DEVNULL,
-                preexec_fn=preexec,
-            )
-            s = HlsSession(
-                key,
-                directory,
-                proc,
-                start_s,
-                variants,
-                transcode=transcode,
-                hw=hw,
-                tonemap=tonemap,
-                user_id=user_id,
-            )
-            _sessions[reg] = s
-            # The one line that says which pipeline a session actually got. Everything downstream
-            # — the cap, the HW→SW fallback, the subtitle offset — is about this choice, and until
-            # now it was only inferable from the ffmpeg command nobody keeps.
-            log.info(
-                "an HLS session started",
-                extra=logs.event(
-                    "plex.stream.session_started",
-                    key=key,
-                    transcode=transcode,
-                    hw=hw,
-                    tonemap=tonemap,
-                    variants=len(variants or ()),
-                    start_s=round(start_s, 1),
-                ),
-            )
-            # Admin-configurable caps (Configuration → Plex); at least 1 each so playback can't be
-            # capped to zero.
-            _enforce_caps(
-                user_id,
-                max(1, sysconfig.get_int(db, "plex_max_transcodes")),
-                max(1, sysconfig.get_int(db, "plex_max_sessions")),
-            )
+                    user_id=user_id,
+                )
+                _sessions[reg] = s
+                # The one line that says which pipeline a session actually got. Everything downstream
+                # — the cap, the HW→SW fallback, the subtitle offset — is about this choice, and until
+                # now it was only inferable from the ffmpeg command nobody keeps.
+                log.info(
+                    "an HLS session started",
+                    extra=logs.event(
+                        "plex.stream.session_started",
+                        key=key,
+                        transcode=transcode,
+                        hw=hw,
+                        tonemap=tonemap,
+                        variants=len(variants or ()),
+                        start_s=round(start_s, 1),
+                    ),
+                )
+                # Admin-configurable caps (Configuration → Plex); at least 1 each so playback can't be
+                # capped to zero.
+                doomed += _enforce_caps(
+                    user_id,
+                    max(1, sysconfig.get_int(db, "plex_max_transcodes")),
+                    max(1, sysconfig.get_int(db, "plex_max_sessions")),
+                )
+        finally:
+            _finish(doomed)
         return s
 
     s = _spawn(*_select_encode(db, item, transcode, src))
@@ -847,7 +918,7 @@ def start_session(
             # stale and stops the session it names (`stop_session`), which stopped the playback that won.
             # Never None either: the POST /session route turns a None return into a "Media file not found
             # on disk" 404 — dishonest for a file that exists. A dead session instead degrades to a
-            # retryable 404 ("No active playback session" / "Not available yet") the client re-requests.
+            # 410 ("session_gone") on its URLs, and the client asks again.
             return s
         s = respawned
         ready = wait_for(_seg(0), timeout=25.0, proc=s.proc)
@@ -974,6 +1045,11 @@ def artifact_may_arrive(s: "HlsSession", filename: str) -> bool:
     # session, absent for a single-audio one.
     if variant not in (s.variants or (None,)):
         return False
+    # And the name must be the one ffmpeg SPELLS for that sequence: `int()` also reads `seg_007.ts`
+    # and a non-ASCII digit run as a sequence the session may have reached, and neither file is
+    # ever written — a yes there parked the request for the whole wait.
+    if filename != segment_name(seq, variant):
+        return False
     if seq == 0:
         return True
     try:
@@ -1084,9 +1160,13 @@ def sweep_orphans(older_than: float | None = None) -> int:
     return dropped
 
 
-# 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
+# The slowest heartbeat a live player sends: a browser cuts the timers of a hidden page that makes no
+# sound to one a minute (measured on Chromium: a paused and a muted player, about a minute after
+# hiding; a hidden player with sound keeps its 10 s).
+_THROTTLED_HEARTBEAT_S = 60
+# How long a session whose ffmpeg has FINISHED may go without a signal before `reap_idle` takes it:
+# the beat before the reaper looks, one lost on the way, and the time the next one takes to arrive.
+_FINISHED_IDLE_S = 3 * _THROTTLED_HEARTBEAT_S
 
 
 def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
@@ -1095,29 +1175,39 @@ def reap_idle(finished_idle_s: float = _FINISHED_IDLE_S) -> int:
 
     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.
+    and with its forward buffer full a paused player fetches nothing at all.
 
-    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. The heartbeat
+    What makes the short rule safe is that fetching is not the only signal: a player parked MID-ITEM
+    checkpoints its position and that route calls `touch_session`. That beat is every 10 s only while
+    the page is visible or making sound; a hidden, silent one sends it once a minute, which a 30 s
+    rule killed whenever the reaper happened to run more than 30 s after the beat (measured: a paused
+    session gone that way, and one that lived on the same cadence because its phase was luckier).
+    So the rule is sized to the throttled beat (`_THROTTLED_HEARTBEAT_S`). 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":
+    states where reaping is correct, and where the player's 410 → reclaim recovers a viewer who
+    scrubs back in anyway. Do not restate this as "whether or not it is playing":
     a review found that claim in two comments and not in the code. An earlier 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
+    doomed: list[tuple[HlsSession, Path | None]] = []
+    reaped: list[tuple[str, str, int]] = []
     with _lock:
         for reg, s in list(_sessions.items()):
             done = s.proc.poll() is not None
             idle = now - s.last_access
             if idle > _SESSION_IDLE_S or (done and idle > finished_idle_s):
-                _kill(s)
                 _sessions.pop(reg, None)
-                dropped += 1
-    return dropped
+                doomed.append(_detach(s))
+                reaped.append((s.key, "finished_idle" if done else "idle", int(idle)))
+    # The viewer of a session wrongly taken sees only a 410 later, so this line is the one record of why.
+    for key, reason, idle_s in reaped:
+        log.info(
+            "an idle session was reaped",
+            extra=logs.event("plex.stream.session_reaped", key=key, reason=reason, idle_s=idle_s),
+        )
+    _finish(doomed)
+    return len(doomed)
 
 
 def stop_session(user_id: int, key: str, session_id: str) -> bool:
@@ -1132,8 +1222,9 @@ def stop_session(user_id: int, key: str, session_id: str) -> bool:
         s = _sessions.get((user_id, key))
         if s is None or s.id != session_id:
             return False
-        _kill(s)
         _sessions.pop((user_id, key), None)
+        doomed = [_detach(s)]
+    _finish(doomed)
     return True
 
 

backend/app/quota.py

@@ -44,6 +44,7 @@ class QuotaAction:
     VIDEOS_ENRICH = "videos_enrich"
     VIDEOS_LOOKUP = "videos_lookup"
     VIDEOS_SEARCH = "videos_search"
+    VIDEOS_RELATED = "videos_related"
     CHANNELS_DISCOVER = "channels_discover"
     CHANNELS_EXPLORE = "channels_explore"
     CHANNELS_SUBSCRIBE = "channels_subscribe"
@@ -142,7 +143,7 @@ def backfill_reserve_reached() -> bool:
     condition for every backfill/explore path (recent, deep, immediate full-history, explore, and
     rolling revalidation).
 
-    Reads in its OWN short-lived session (like record_usage / log_action), for two reasons: it
+    Reads in its OWN short-lived session (like record_usage / claim_action), for two reasons: it
     replaces the remaining/reserve comparison that was open-coded at every call site, and — critically
     for the per-page guards in paging loops — a guard must not hold the caller's transaction open
     across the network fetch that follows it. Quota is committed independently of any caller, so a
@@ -151,24 +152,40 @@ def backfill_reserve_reached() -> bool:
         return remaining_today(qs) <= sysconfig.get_int(qs, "backfill_quota_reserve")
 
 
-def log_action(user_id: int, action: str) -> None:
-    """Record a zero-cost action event so per-user daily caps still count it.
+def claim_action(user_id: int, action: str, limit: int) -> int | None:
+    """Take one of this user's `limit` daily `action` slots, or None when they are all taken — the
+    check and the take in one transaction, under a lock per user and action. Checked first and
+    logged after the work, N requests sent together at the last free slot all passed the check
+    (the work in between is seconds of scraping). Returns the event's id, for `refund_action` when
+    the work then produced nothing.
 
-    `record_usage` only logs when units are actually charged; a scrape-based search spends no
-    quota yet must still be rate-limited per user, so it logs its event here directly.
-
-    Writes in its OWN session (like record_usage) — quota accounting is durable independent of the
-    caller's transaction and must never commit the caller's session (that would flush a job's
-    partial state mid-run, defeating its own rollback)."""
+    The ONE way to count a capped action: a claim is a zero-unit event, and `actions_today` counts
+    those alone, so a call the action then pays for (search.list's own `record_usage` event, under
+    the same action) is accounting, never a second slot. Own session, committed at once — quota
+    accounting is durable whatever the caller's transaction does next, and must never commit it."""
     with SessionLocal() as qs:
-        qs.add(QuotaEvent(user_id=user_id, action=action, units=0))
+        qs.execute(select(func.pg_advisory_xact_lock(func.hashtext(action), user_id)))
+        if actions_today(qs, user_id, action) >= limit:
+            return None
+        event = QuotaEvent(user_id=user_id, action=action, units=0)
+        qs.add(event)
+        qs.commit()
+        return event.id
+
+
+def refund_action(event_id: int) -> None:
+    """Give a slot `claim_action` took back: the work it was taken for failed outright, and a
+    request that showed the user nothing must not count against them."""
+    with SessionLocal() as qs:
+        qs.execute(delete(QuotaEvent).where(QuotaEvent.id == event_id))
         qs.commit()
 
 
 def actions_today(db: Session, user_id: int, action: str) -> int:
-    """How many quota events of `action` this user has logged so far in the current Pacific
-    day — for per-user, per-action daily caps (e.g. the live-search limit). Counts events,
-    not units, so it only works for actions charged exactly once per user action."""
+    """How many slots of `action` this user has claimed so far in the current Pacific day — for
+    per-user, per-action daily caps (the live search, the related lists). Counts the zero-unit
+    claim events (`claim_action`) only: `record_usage`'s events for units the action spent are not
+    slots (it logs only when units were charged)."""
     return (
         db.scalar(
             select(func.count())
@@ -176,6 +193,7 @@ def actions_today(db: Session, user_id: int, action: str) -> int:
             .where(
                 owned_by(QuotaEvent.user_id, user_id),
                 QuotaEvent.action == action,
+                QuotaEvent.units == 0,
                 QuotaEvent.created_at >= pacific_day_start_utc(),
             )
         )

backend/app/reader/queries.py

@@ -41,11 +41,25 @@ def video(db: Session, video_id: str) -> Video | None:
 # --- tags ------------------------------------------------------------------------------------
 
 
-def tags_with_counts(db: Session, user: User) -> list[tuple[Tag, int]]:
-    """The tags this user sees (the shared system ones and their own), each with how many channel
-    links it has, by category then name."""
+def tags_with_counts(db: Session, user: User) -> list[tuple[Tag, int, int]]:
+    """The tags this user sees (the shared system ones and their own), by category then name, each
+    with how many channel links it has and how many of the user's own links sit on a channel they
+    subscribe to and have not hidden — the rows the Channels page's tag filter shows (a hidden
+    channel has its own tab). A link outlives an unsubscribe and a hide, so the two differ."""
+    subscribed = select(Subscription.channel_id).where(
+        owned_by(Subscription.user_id, user), Subscription.hidden.is_(False)
+    )
+    on_subscribed = dict(
+        db.execute(
+            select(ChannelTag.tag_id, func.count(ChannelTag.id))
+            .where(owned_by(ChannelTag.user_id, user), ChannelTag.channel_id.in_(subscribed))
+            .group_by(ChannelTag.tag_id)
+        )
+        .tuples()
+        .all()
+    )
     return [
-        (tag, count)
+        (tag, count, on_subscribed.get(tag.id, 0))
         for tag, count in db.execute(
             select(Tag, func.count(ChannelTag.id))
             .outerjoin(ChannelTag, ChannelTag.tag_id == Tag.id)
@@ -319,6 +333,36 @@ def held_by(db: Session, user: User, video_ids: list[str]) -> set[str]:
     )
 
 
+def seen_by(db: Session, user: User, video_ids: list[str]) -> set[str]:
+    """Which of these videos the user has already seen or set aside: watched or hidden here, or in
+    their uploaded Takeout history unless they took it back to "new" here since. The ids need not
+    be in the catalog — a Takeout row names a video the catalog may never have had — so a list
+    of what YouTube suggests can drop them before anything is ingested."""
+    if not video_ids:
+        return set()
+    marked = select(VideoState.video_id).where(
+        owned_by(VideoState.user_id, user),
+        VideoState.video_id.in_(video_ids),
+        VideoState.status.in_(("watched", "hidden")),
+    )
+    unmarked_since = (
+        select(VideoUnmark.id)
+        .where(
+            owned_by(VideoUnmark.user_id, user),
+            VideoUnmark.video_id == TakeoutItem.video_id,
+            VideoUnmark.at > TakeoutItem.at,
+        )
+        .exists()
+    )
+    in_history = select(TakeoutItem.video_id).where(
+        owned_by(TakeoutItem.user_id, user),
+        TakeoutItem.kind == TakeoutKind.WATCHED,
+        TakeoutItem.video_id.in_(video_ids),
+        ~unmarked_since,
+    )
+    return set(db.scalars(marked)) | set(db.scalars(in_history))
+
+
 def feed_rows_by_ids(db: Session, user: User, video_ids: list[str]) -> list[dict]:
     """These videos serialized with the feed's projection (their channel, this user's watch state,
     saved), in the order given."""

backend/app/reader/service.py

@@ -9,7 +9,7 @@ unique key, a row lock taken before a presence check. The comfort shelf's writes
 
 from datetime import datetime, timezone
 
-from typing import cast
+from typing import Literal, cast
 
 from sqlalchemy import Table, bindparam, delete, exists, func, select, text, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
@@ -255,17 +255,6 @@ def mark(db: Session, user: User, video_id: str, status: str) -> None:
     )
 
 
-def clear_state(db: Session, user: User, video_id: str) -> None:
-    """The video back to pristine for this user: status, resume point and `watched_at` all go.
-    Playlist membership lives elsewhere and stays."""
-    lock_takeout(db, user)  # as `unmark`
-    row = queries.video_state(db, user, video_id)
-    if row is not None:
-        db.delete(row)
-        _remember_unmark(db, user, video_id)
-        db.flush()
-
-
 def set_progress(db: Session, user: User, video_id: str, position: int) -> None:
     """The player's resume point. 0 clears it: a row holding nothing else goes, one with a status
     (watched, hidden) keeps it with the position zeroed. The status itself is never changed here.
@@ -301,12 +290,17 @@ def set_progress(db: Session, user: User, video_id: str, position: int) -> None:
 # --- playlists -------------------------------------------------------------------------------
 
 
+# Every reason a move is refused; the UI names each one (`playlists.moveErrors.<reason>`, held by the
+# frontend's backendIds contract, which reads this Literal).
+MoveReason = Literal["same_playlist"]
+
+
 class MoveRefused(Exception):
     """A move between playlists that cannot happen: `reason` is the code the UI translates."""
 
-    def __init__(self, reason: str):
+    def __init__(self, reason: MoveReason):
         super().__init__(reason)
-        self.reason = reason
+        self.reason: MoveReason = reason
 
 
 def touch(pl: Playlist) -> None:
@@ -412,30 +406,6 @@ def remove_item(db: Session, pl: Playlist, video_id: str, *, mark_dirty: bool) -
     return True
 
 
-def place_item(db: Session, pl: Playlist, video_id: str, position: int) -> None:
-    """Put a video already in the list at `position` (clamped to the end), renumbering the whole
-    list: positions can have gaps after removals, so "index N" is only meaningful over the
-    ordered rows."""
-    rows = queries.items(db, pl.id)
-    new = next(r for r in rows if r.video_id == video_id)
-    rows.remove(new)
-    rows.insert(min(position, len(rows)), new)
-    for pos, row in enumerate(rows):
-        row.position = pos
-    db.flush()
-
-
-def add_to_playlist(db: Session, pl: Playlist, video_id: str, position: int | None) -> None:
-    """Add a video to one of the user's lists, at `position` when given (the list page's "Undo" of
-    a removal puts the row back where it was in ONE request), else at the end. A video already in
-    the list stays where it is."""
-    added = add_item(db, pl, video_id, mark_dirty=False)
-    if added and position is not None:
-        place_item(db, pl, video_id, position)
-    recompute_dirty(db, pl)
-    db.flush()
-
-
 def rename_playlist(db: Session, pl: Playlist, name: str) -> None:
     """A new name moves `dirty`; the caller holds the playlist's lock (the scheduled mirror refresh
     reads `dirty` under it)."""
@@ -453,39 +423,163 @@ def delete_playlist(db: Session, pl: Playlist) -> None:
     db.flush()
 
 
-def move_item(db: Session, src: Playlist, dst: Playlist, video_id: str) -> None:
-    """Move one video from `src` into `dst`, in the caller's one transaction.
+def remove_items(db: Session, pl: Playlist, video_ids: list[str]) -> list[str]:
+    """Remove these videos from a playlist, in one transaction; a video not in it any more is simply
+    not among them. Says which went: an Undo must not bring back one this removal never took."""
+    lock_playlists(db, pl.id)
+    wanted = set(video_ids)
+    rows = [it for it in queries.items(db, pl.id) if it.video_id in wanted]
+    for row in rows:
+        db.delete(row)
+    if rows:
+        recompute_dirty(db, pl)
+        touch(pl)
+    db.flush()
+    return [row.video_id for row in rows]
 
-    The client-side shape — add to the target, then remove from the source — leaves the video in
-    BOTH lists whenever the second call fails. Idempotent: a video already in the target is simply
-    dropped from the source (moving into a list that has it is a removal, not a duplicate). Raises
-    `MoveRefused` for the same list twice, or a video a concurrent edit already took out."""
+
+def _insert_at(
+    db: Session,
+    pl: Playlist,
+    placed: list[tuple[int, str]],
+    leaving: dict[str, PlaylistItem] | None = None,
+    staying_out: frozenset[str] = frozenset(),
+) -> int:
+    """Add videos at their indices (ascending, so each index is where the row stood when the rows
+    before it were back) and renumber the list 0..n-1, as positions can have gaps. A video already in
+    the list stays where it is, and one the catalog has lost or in `staying_out` is left out, the
+    ones after it closing up. A video with a row in `leaving` brings that row along, for the reason
+    `move_items` re-parents. Says how many were added; the caller holds the playlist's lock."""
+    leaving = leaving or {}
+    rows = queries.items(db, pl.id)
+    present = {r.video_id for r in rows}
+    known = queries.known_video_ids(db, [vid for _, vid in placed])
+    added = 0
+    left_out = 0
+    for at, vid in sorted(placed, key=lambda p: p[0]):
+        if vid in present or vid not in known or vid in staying_out:
+            left_out += 1
+            continue
+        row = leaving.pop(vid, None)
+        if row is None:
+            row = PlaylistItem(playlist_id=pl.id, video_id=vid, position=0)
+            db.add(row)
+        else:
+            row.playlist_id = pl.id
+        rows.insert(min(at - left_out, len(rows)), row)
+        present.add(vid)
+        added += 1
+    for pos, row in enumerate(rows):
+        row.position = pos
+    return added
+
+
+def restore_items(db: Session, pl: Playlist, video_ids: list[str], positions: list[int]) -> int:
+    """Put removed videos back at their places, in ONE request: an append plus a whole-list reorder
+    leaves them at the end whenever the second call fails. Says how many came back."""
+    lock_playlists(db, pl.id)
+    added = _insert_at(db, pl, list(zip(positions, video_ids, strict=True)))
+    if added:
+        recompute_dirty(db, pl)
+        touch(pl)
+    db.flush()
+    return added
+
+
+class ListGone(Exception):
+    """A list of a two-list write was deleted between the route's read and the lock."""
+
+    def __init__(self, *, source: bool):
+        super().__init__("source" if source else "target")
+        self.source = source
+
+
+def _lock_both(db: Session, src: Playlist, dst: Playlist) -> None:
+    """Both lists, in id order: a move A→B beside a move B→A would otherwise lock crosswise. A list
+    already gone is said here: a write into it would answer with its foreign key's 500."""
+    found = lock_playlists(db, src.id, dst.id)
+    if src.id not in found:
+        raise ListGone(source=True)
+    if dst.id not in found:
+        raise ListGone(source=False)
+
+
+def move_items(
+    db: Session, src: Playlist, dst: Playlist, video_ids: list[str]
+) -> tuple[list[str], list[str]]:
+    """Move these videos from `src` into `dst`, in the caller's one transaction, in the source's
+    order whatever order they were picked in. Returns the ones that landed in the target and the ones
+    it already held, which only left the source: the Undo needs to tell them apart. A video a
+    concurrent edit already took out of the source is in neither. Raises `MoveRefused` for the same
+    list twice."""
     if src.id == dst.id:
         raise MoveRefused("same_playlist")
-    # Both lists, in id order: a move A→B beside a move B→A would otherwise lock crosswise.
-    lock_playlists(db, src.id, dst.id)
-    row = queries.item(db, src.id, video_id)
-    if row is None:
-        raise MoveRefused("not_in_playlist")
-    dst_changed = False
-    if queries.item(db, dst.id, video_id) is None:
-        # 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. The
-        # check above holds: both lists are locked, and an insert into the target (another tab's
-        # add, a YouTube merge) waits for the lock — its foreign key needs the target row.
-        row.playlist_id = dst.id
-        row.position = next_item_position(db, dst.id)
-        dst_changed = True
-    if not dst_changed:
-        db.delete(row)
-    # The source always changed; the target only when the row landed in it. Touching a target
-    # that already had the video promoted an untouched list in the rail's "recently changed" sort.
-    recompute_dirty(db, src)
-    touch(src)
-    if dst_changed:
+    _lock_both(db, src, dst)
+    wanted = set(video_ids)
+    rows = [it for it in queries.items(db, src.id) if it.video_id in wanted]
+    held = queries.in_playlist(db, dst.id, [r.video_id for r in rows])
+    position = next_item_position(db, dst.id)
+    moved: list[str] = []
+    already_there: list[str] = []
+    for row in rows:
+        if row.video_id in held:
+            already_there.append(row.video_id)
+            db.delete(row)
+        else:
+            moved.append(row.video_id)
+            # Re-parented rather than deleted and inserted: `added_at` ("when I saved this") survives
+            # the move, and there is no window where the video belongs to neither list. `held` stays
+            # true: both lists are locked, and an insert into the target (another tab's add, a
+            # YouTube merge) waits for the lock, as its foreign key needs the target row.
+            row.playlist_id = dst.id
+            row.position = position
+            position += 1
+    if rows:
+        recompute_dirty(db, src)
+        touch(src)
+    # Only when a row landed in it: touching a target that already had the video promoted an untouched
+    # list in the rail's "recently changed" sort.
+    if moved:
         recompute_dirty(db, dst)
         touch(dst)
     db.flush()
+    return moved, already_there
+
+
+def undo_move(
+    db: Session,
+    src: Playlist,
+    dst: Playlist,
+    moved: list[str],
+    already_there: list[str],
+    positions: list[int],
+) -> int:
+    """Take a move back in one transaction: the `moved` videos leave `dst` and return to their places
+    in `src`, keeping their rows, as the move did. The `already_there` ones return too and stay in
+    `dst`, which held them before. A moved video `dst` no longer holds has gone on from there, and
+    bringing it back would leave it in lists the reader never put it in, so it stays out, as a
+    move skips a video a concurrent edit took out. `positions` pairs with `moved` + `already_there`.
+    Says how many came back. Raises `MoveRefused` for the same list twice, as a move does."""
+    if src.id == dst.id:
+        raise MoveRefused("same_playlist")
+    _lock_both(db, src, dst)
+    wanted = set(moved)
+    rows = {it.video_id: it for it in queries.items(db, dst.id) if it.video_id in wanted}
+    changed = bool(rows)
+    placed = list(zip(positions, [*moved, *already_there], strict=True))
+    back = _insert_at(db, src, placed, leaving=rows, staying_out=frozenset(wanted - rows.keys()))
+    # What `src` holds again by now only leaves `dst`.
+    for row in rows.values():
+        db.delete(row)
+    db.flush()
+    if changed:
+        recompute_dirty(db, dst)
+        touch(dst)
+    if back:
+        recompute_dirty(db, src)
+        touch(src)
+    db.flush()
+    return back
 
 
 def reorder_items(db: Session, pl: Playlist, order: list[str]) -> int:

backend/app/refusal.py

@@ -1,29 +1,39 @@
 """A request the app refuses, said in a way the UI can put in the reader's language.
 
 Every refusal the API answers carries a structured `detail` — `{code, reason, …params}` — and the client
-translates it (`lib/api/core.ts` `localizeDetail`). A bare English string reached the Hungarian UI
+translates it (`lib/api/refusalText.ts` `localizeDetail`). A bare English string reached the Hungarian UI
 verbatim: the blocking error dialog, and every inline surface that printed `HttpError.detail`, showed
 whatever sentence the route happened to hand-write. `refused` is the generic family
 (`errors.refused.<reason>`, the params interpolated into the sentence); the older specific codes
 (`not_found`, `youtube`, `playlist`, the admin refusals, …) stay, since each is already translated.
 
-A test (`test_http_details.py`) reads every `HTTPException` in the app and fails on a string detail,
-and the frontend's contract test requires every `refused(…, "<reason>")` to be named in both
-languages — so the rule is enforced, not described.
+A test (`test_http_details.py`) reads every place an `HTTPException` or a `JSONResponse` sends a detail
+and fails on one the client cannot say: a sentence, a dict without a `code`, a variable, none at all.
+`tests/refusal_sites.py` reads every `{"code": …}` detail from the syntax tree, written where it is sent
+(or returned by a factory that only ever is), with any `**` spread before its `code` and `reason`, and
+follows each reason along a closed list of shapes: a literal, a `Literal` type on the parameter or
+attribute it travels in, every call of a helper like `refused` below, a map's values; anything else is
+reported, never guessed. The frontend's contract test
+(`i18n/backendIds.contract.test.ts`) runs it and requires each code in one record of
+`lib/api/refusalCodes.ts`, and each reason's sentence in both languages; a code or reason it cannot
+follow fails it, unless no screen shows that code. So the rule is enforced, not described.
 """
 
 from fastapi import HTTPException
 
+from app.sysconfig import InvalidSetting, SettingReason
+
 
 def refused(status: int, reason: str, **params: object) -> HTTPException:
     """The refusal to raise: `raise refused(409, "view_name_taken", name=name)`. `params` travel in
-    the detail for the sentence to interpolate (`{{name}}`); keep them to values the reader may see."""
-    return HTTPException(status_code=status, detail={"code": "refused", "reason": reason, **params})
+    the detail for the sentence to interpolate (`{{name}}`); keep them to values the reader may see.
+    They are spread first, so a `code` or `reason` among them could never replace these two."""
+    return HTTPException(status_code=status, detail={**params, "code": "refused", "reason": reason})
 
 
-# `sysconfig.InvalidSetting.reason` → the refusal it answers as. A dict of literals, so the frontend's
-# contract test can read every reason this can produce.
-_SETTING_REASONS = {
+# `sysconfig.InvalidSetting.reason` → the refusal it answers as. A dict of literals, so the refusal
+# scan reads every reason this can produce, and holds its keys to `SettingReason`.
+_SETTING_REASONS: dict[SettingReason, str] = {
     "not_a_number": "setting_not_a_number",
     "too_low": "setting_too_low",
     "too_high": "setting_too_high",
@@ -32,6 +42,6 @@ _SETTING_REASONS = {
 }
 
 
-def setting_refused(exc) -> HTTPException:
+def setting_refused(exc: InvalidSetting) -> HTTPException:
     """A value the admin entered that `sysconfig.set_value` refused (`exc`: its `InvalidSetting`)."""
     return refused(400, _SETTING_REASONS[exc.reason], key=exc.key, **exc.params)

backend/app/routes/auth.py

@@ -976,7 +976,16 @@ def _resend_verify_if_eligible(email: str) -> None:
             send_verification_link(db, user)
 
 
-def _login_refused(status: int, reason: str, user: User | None = None, **extra) -> HTTPException:
+# Every refusal a password sign-in answers with; the UI names each one (`welcome.auth.blocked.<reason>`,
+# held by the frontend's backendIds contract, which reads this Literal).
+LoginRefusal = Literal[
+    "rate_limited", "invalid", "suspended", "email_unverified", "pending_approval"
+]
+
+
+def _login_refused(
+    status: int, reason: LoginRefusal, user: User | None = None, **extra
+) -> HTTPException:
     """Every refusal password_login can answer with, in the codebase's structured `{code, reason}`
     shape so the SPA can say it in the user's own language (the old bare English strings were
     unreadable under a bilingual UI, and unusable as anything but a one-line error).
@@ -992,15 +1001,15 @@ def _login_refused(status: int, reason: str, user: User | None = None, **extra)
     `email_verified` is false, and vice versa — the SPA renders whichever is actually outstanding
     rather than assuming a sequence.
     """
-    detail: dict = {"code": "login", "reason": reason}
-    if user is not None:
-        detail |= {
-            "email": user.email,
-            "email_verified": user.email_verified,
-            "approved": user.is_active,
-        }
-    detail |= {k: v for k, v in extra.items() if v is not None}
-    return HTTPException(status_code=status, detail=detail)
+    account = (
+        {"email": user.email, "email_verified": user.email_verified, "approved": user.is_active}
+        if user is not None
+        else {}
+    )
+    given = {k: v for k, v in extra.items() if v is not None}
+    return HTTPException(
+        status_code=status, detail={**account, **given, "code": "login", "reason": reason}
+    )
 
 
 @router.post("/password-login")

backend/app/routes/channels.py

@@ -76,6 +76,10 @@ def list_channels(user: User = Depends(current_user), db: Session = Depends(get_
             "details_synced": ch.details_synced_at is not None,
             "recent_synced": ch.recent_synced_at is not None,
             "backfill_done": ch.backfill_done,
+            # When the follow reached this list: written by the subscription import the run that
+            # first saw it, or by a subscribe made here — not the channel row's own date, which an
+            # explored or discovered channel had before it was followed.
+            "added_at": iso(sub.created_at),
         }
         for sub, ch in rows
     ]

backend/app/routes/downloads.py

@@ -208,7 +208,7 @@ def set_credential(
     try:
         cleaned = dlcreds.validate_cookies(body.cookies)
     except dlcreds.InvalidCookies as e:
-        raise HTTPException(status_code=400, detail={"code": "cookies", "reason": str(e)}) from e
+        raise HTTPException(status_code=400, detail={"code": "cookies", "reason": e.reason}) from e
     dlcreds.upsert_credential(db, user.id, host_key, cleaned)
     audit.record(
         db,
@@ -359,8 +359,9 @@ def enqueue_clip(
         job = service.enqueue_clip(db, user.id, spec, display_name=display_name)
     except clipmod.ClipError as e:
         status = 404 if e.reason == "not_found" else 422
-        detail = {"code": "clip", "reason": e.reason, **e.params}
-        raise HTTPException(status_code=status, detail=detail) from e
+        raise HTTPException(
+            status_code=status, detail={**e.params, "code": "clip", "reason": e.reason}
+        ) from e
     except quota.QuotaExceeded as e:
         raise HTTPException(status_code=422, detail=quota_detail(e)) from e
     db.commit()
@@ -610,7 +611,7 @@ def list_links(
     job_id: int, user: User = Depends(current_user), db: Session = Depends(get_db)
 ) -> list[dict]:
     own_job(db, user, job_id)
-    return [linksmod.owner_view(link) for link in queries.links_to(db, job_id=job_id)]
+    return [linksmod.owner_view(db, link) for link in queries.links_to(db, job_id=job_id)]
 
 
 class CreateLinkIn(BaseModel):
@@ -652,7 +653,7 @@ def create_link(
         raise refused(409, "share_unfinished")
     link, token = _new_link(db, user, body, job_id=job_id)
     db.commit()
-    return linksmod.owner_view(link, token=token)
+    return linksmod.owner_view(db, link, token=token)
 
 
 def _shareable_job(db: Session, user: User, job_id: int) -> "DownloadJob":
@@ -683,7 +684,7 @@ def list_folder_links(
     folder_id: int, user: User = Depends(current_user), db: Session = Depends(get_db)
 ) -> list[dict]:
     own_folder(db, user, folder_id)
-    return [linksmod.owner_view(link) for link in queries.links_to(db, folder_id=folder_id)]
+    return [linksmod.owner_view(db, link) for link in queries.links_to(db, folder_id=folder_id)]
 
 
 @router.post("/folders/{folder_id}/links")
@@ -696,7 +697,7 @@ def create_folder_link(
     _shareable_folder(db, user, folder_id)
     link, token = _new_link(db, user, body, folder_id=folder_id)
     db.commit()
-    return linksmod.owner_view(link, token=token)
+    return linksmod.owner_view(db, link, token=token)
 
 
 class UpdateLinkIn(BaseModel):
@@ -723,7 +724,7 @@ def update_link(
         sent=frozenset(body.model_fields_set),
     )
     db.commit()
-    return linksmod.owner_view(link)
+    return linksmod.owner_view(db, link)
 
 
 @router.delete("/links/{link_id}")

backend/app/routes/feed.py

@@ -204,22 +204,21 @@ def set_video_state(
     return {"ok": True, "video_id": video_id, "status": status}
 
 
-@router.delete("/videos/{video_id}/state")
-def clear_video_state(
+@router.delete("/videos/{video_id}/progress")
+def clear_video_progress(
     video_id: str,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    """Reset a video to pristine for this user — drop the whole VideoState row (status,
-    watch position and watched_at), as if it had never been opened. Saved/playlist membership
-    lives elsewhere and is untouched."""
+    """Forget where the user left a video: its resume point goes, its status (watched, hidden) stays.
+    Saved/playlist membership lives elsewhere and is untouched."""
     try:
-        service.clear_state(db, user, video_id)
+        service.set_progress(db, user, video_id, 0)
         db.commit()
-    # silent-ok: the row went under the delete, which is the outcome the delete wanted.
+    # silent-ok: the row went under the write, which is the outcome the write wanted.
     except StaleDataError:
         db.rollback()
-    return {"ok": True, "video_id": video_id, "status": "new", "position_seconds": 0}
+    return {"ok": True, "video_id": video_id, "position_seconds": 0}
 
 
 @router.post("/videos/{video_id}/progress")
@@ -249,6 +248,21 @@ def set_video_progress(
     return {"ok": True, "video_id": video_id, "position_seconds": position}
 
 
+@router.get("/videos/{video_id}/row")
+def get_video_row(
+    video_id: str = Path(max_length=32),
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """One catalog video as the feed lists it (its channel, this user's watch state and resume point,
+    saved): what a player opened from an address starts from. The catalog only, so it costs nothing;
+    every video a player can open (a list's row, a related one) is in it."""
+    rows = queries.feed_rows_by_ids(db, user, [video_id])
+    if not rows:
+        raise not_found("video")
+    return rows[0]
+
+
 @router.get("/videos/{video_id}")
 def get_video_detail(
     video_id: str,

backend/app/routes/files.py

@@ -139,7 +139,7 @@ def own_job_for_update(db: Session, user: User, job_id: int) -> "DownloadJob":
 
 def quota_detail(e: quota.QuotaExceeded) -> dict:
     """Structured error the trilingual client localizes (reason key + numbers), instead of a
-    pre-baked English string with a dot-decimal GB value. See lib/api.ts localizeDetail()."""
+    pre-baked English string with a dot-decimal GB value. See lib/api/refusalText.ts localizeDetail()."""
     return {"code": "quota", "reason": e.reason, "limit": e.limit, "current": e.current}
 
 

backend/app/routes/me.py

@@ -79,6 +79,10 @@ def get_me(
         # Which live-search source runs, so the search button can say what a search costs: "scrape"
         # spends no API quota, "api" spends 100 units a page.
         "search_source": sysconfig.get_str(db, "search_source"),
+        # Whether live search and related videos are on: an admin turns either off with a daily
+        # limit of 0, and the UI then leaves out what would only be refused.
+        "search_enabled": sysconfig.get_int(db, "search_daily_limit_per_user") > 0,
+        "related_enabled": sysconfig.get_int(db, "related_daily_limit_per_user") > 0,
         "can_read": has_read_scope(user),
         "can_write": has_write_scope(user),
         "pending_invites": pending_invites,

backend/app/routes/playlists.py

@@ -3,10 +3,10 @@ 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 typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 from fastapi import APIRouter, Depends, HTTPException
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, model_validator
 from sqlalchemy.orm import Session
 
 from app import quota
@@ -53,7 +53,22 @@ def _check_pull_cooldown(user: User) -> None:
         raise HTTPException(status_code=429, detail={"code": "sync_cooldown"})
 
 
-def _refused(status: int, reason: str) -> HTTPException:
+# Every playlist action the server refuses; the UI names each one (`playlists.errors.<reason>`, held by
+# the frontend's backendIds contract, which reads this Literal).
+PlaylistRefusal = Literal[
+    "name_required",
+    "not_on_youtube",
+    "quota_exceeded",
+    "sync_all_busy",
+    "sync_busy",
+    "watch_later_not_pushable",
+    "watch_later_undeletable",
+    "youtube_editing_off",
+    "youtube_read_scope",
+]
+
+
+def _refused(status: int, reason: PlaylistRefusal) -> 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})
@@ -371,24 +386,17 @@ def delete_playlist(
     return {"deleted": playlist_id}
 
 
-class AddItemIn(VideoRefIn):
-    # Where the video lands among the list's items, in their stored order (0 = first). Omitted, it
-    # is appended. The list page's "Undo" of a removal puts the row back where it was with this —
-    # ONE request, because append-then-reorder leaves it at the end whenever the second call fails.
-    position: int | None = Field(default=None, ge=0)
-
-
 @router.post("/{playlist_id}/items")
 def add_item(
     playlist_id: int,
-    body: AddItemIn,
+    body: VideoRefIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = _own_playlist(db, user, playlist_id, lock=True)
     video_id = body.video_id
     _video_or_404(db, video_id)
-    service.add_to_playlist(db, pl, video_id, body.position)
+    service.add_item(db, pl, video_id, mark_dirty=True)
     db.commit()
     return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
@@ -400,58 +408,158 @@ def remove_item(
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:
-    pl = _own_playlist(db, user, playlist_id)
+    pl = _own_playlist(db, user, playlist_id, lock=True)
     service.remove_item(db, pl, video_id, mark_dirty=True)
     db.commit()
     return {"ok": True, "playlist_id": pl.id, "video_id": video_id}
 
 
-class MoveItemIn(BaseModel):
+class VideoIdsIn(BaseModel):
+    # Required: with a default, a misnamed key answered 200 having acted on no video.
+    video_ids: list[str]
+
+
+def _paired(video_count: int, positions: list[int]) -> None:
+    """One place per video, none before the start and none twice: both undo bodies come back from
+    the client, and the insert's arithmetic counts on places that only rise."""
+    if len(positions) != video_count:
+        raise ValueError("positions must pair one-to-one with the videos")
+    if any(at < 0 for at in positions):
+        raise ValueError("positions cannot be negative")
+    if len(set(positions)) != len(positions):
+        raise ValueError("positions cannot repeat")
+
+
+class RestoreItemsIn(VideoIdsIn):
+    # Where each video goes back: an index over the ordered rows, one per video.
+    positions: list[int] = []
+
+    @model_validator(mode="after")
+    def _one_position_per_video(self):
+        _paired(len(self.video_ids), self.positions)
+        return self
+
+
+class MoveItemsIn(VideoIdsIn):
     target_playlist_id: int
 
 
-@router.post("/{playlist_id}/items/{video_id}/move")
-def move_item(
+class UndoMoveIn(BaseModel):
+    from_playlist_id: int
+    # Required, as `video_ids` is. An empty one is still a real body: the target held them all.
+    moved: list[str]
+    already_there: list[str] = []
+    # One per video of `moved` + `already_there`, in that order.
+    positions: list[int]
+
+    @model_validator(mode="after")
+    def _one_position_per_video(self):
+        _paired(len(self.moved) + len(self.already_there), self.positions)
+        return self
+
+
+def _list_gone(e: service.ListGone) -> HTTPException:
+    """Each list of a two-list write under the reason the route's own read gives it."""
+    return not_found("playlist") if e.source else not_found("move_target")
+
+
+def _move_refused(e: service.MoveRefused) -> HTTPException:
+    return HTTPException(status_code=400, detail={"code": "playlist_move", "reason": e.reason})
+
+
+def _other_list(db: Session, user: User, playlist_id: int) -> "Playlist":
+    """The other list of a move. Its own reason: "this playlist doesn't exist any more" about a list
+    that is gone was read as the one on screen, which is still there."""
+    other = queries.own_playlist(db, user, playlist_id)
+    if other is None:
+        raise not_found("move_target")
+    return other
+
+
+@router.post("/{playlist_id}/items/remove-bulk")
+def remove_items(
     playlist_id: int,
-    video_id: str,
-    body: MoveItemIn,
+    body: VideoIdsIn,
     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.
+    """Remove many videos from a playlist at once. Returns the ones that went."""
+    pl = _own_playlist(db, user, playlist_id, lock=True)
+    removed = service.remove_items(db, pl, body.video_ids)
+    db.commit()
+    return {"ok": True, "playlist_id": pl.id, "removed": removed}
+
+
+@router.post("/{playlist_id}/items/restore")
+def restore_items(
+    playlist_id: int,
+    body: RestoreItemsIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The "Undo" of a removal: the videos back at their places. Returns how many came back."""
+    pl = _own_playlist(db, user, playlist_id, lock=True)
+    added = service.restore_items(db, pl, body.video_ids, body.positions)
+    db.commit()
+    return {"ok": True, "playlist_id": pl.id, "added": added}
+
+
+@router.post("/{playlist_id}/items/move-bulk")
+def move_items(
+    playlist_id: int,
+    body: MoveItemsIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """Move videos 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)."""
+    from the source — leaves a video in BOTH lists whenever the second call fails. A video the
+    target already has only leaves the source, and one a concurrent edit (another tab, a YouTube
+    re-pull) already took out is skipped. Says which landed there and which it already held, for
+    the "Undo"."""
     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 = queries.own_playlist(db, user, body.target_playlist_id)
-    if dst is None:
-        raise not_found("move_target")
+    dst = _other_list(db, user, body.target_playlist_id)
     try:
-        service.move_item(db, src, dst, video_id)
+        moved, already_there = service.move_items(db, src, dst, body.video_ids)
     except service.MoveRefused as e:
-        # A same-list move is a bad request; a video a concurrent edit (another tab, a YouTube
-        # re-pull) already took out is gone.
-        status = 400 if e.reason == "same_playlist" else 404
-        raise HTTPException(
-            status_code=status, detail={"code": "playlist_move", "reason": e.reason}
-        ) from None
+        raise _move_refused(e) from None
+    except service.ListGone as e:
+        raise _list_gone(e) from None
     db.commit()
-    return {"ok": True, "from_playlist_id": src.id, "to_playlist_id": dst.id, "video_id": video_id}
+    return {
+        "ok": True,
+        "from_playlist_id": src.id,
+        "to_playlist_id": dst.id,
+        "moved": moved,
+        "already_there": already_there,
+    }
 
 
-class ReorderItemsIn(BaseModel):
-    video_ids: list[str] = []
+@router.post("/{playlist_id}/items/undo-move")
+def undo_move(
+    playlist_id: int,
+    body: UndoMoveIn,
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The "Undo" of a move, back into this playlist in one transaction. Returns how many came back."""
+    src = _own_playlist(db, user, playlist_id)
+    dst = _other_list(db, user, body.from_playlist_id)
+    try:
+        added = service.undo_move(db, src, dst, body.moved, body.already_there, body.positions)
+    except service.MoveRefused as e:
+        raise _move_refused(e) from None
+    except service.ListGone as e:
+        raise _list_gone(e) from None
+    db.commit()
+    return {"ok": True, "playlist_id": src.id, "added": added}
 
 
 @router.put("/{playlist_id}/order")
 def reorder_items(
     playlist_id: int,
-    body: ReorderItemsIn,
+    body: VideoIdsIn,
     user: User = Depends(current_user),
     db: Session = Depends(get_db),
 ) -> dict:

backend/app/routes/plex/detail.py

@@ -432,6 +432,7 @@ def item_detail(
         "summary": (it.summary_hu or it.summary) if hu else it.summary,
         "year": it.year,
         "duration_seconds": it.duration_s,
+        "size_bytes": it.size_bytes,
         "playable": it.playable,
         # Playback-class detail: HW/SW transcode split + the codec/bit-depth the info-page chip shows.
         "transcode_hw": it.transcode_hw,

backend/app/routes/plex/playback.py

@@ -234,6 +234,15 @@ def person_image(u: str, request: Request) -> Response:
     return imgcache.response(data, ct)
 
 
+def _supersede_resume_pushes(user_id: int, item_id: int, now: datetime) -> None:
+    """A watched mark supersedes every resume push still in flight for the item: stamping it as the
+    latest push makes `_resume_push_superseded` drop them. Popping the entry instead (to keep the map
+    small) removed the very guard, and an older resume push could then land at Plex AFTER the
+    scrobble and revive a resume point on a watched item. Eviction bounds the map."""
+    with _push_throttle_lock:
+        _last_push_at[(user_id, item_id)] = now
+
+
 def _push_resume_guarded(
     user_id: int,
     item_id: int,
@@ -314,13 +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
+    # A player parked mid-item — playing or PAUSED — keeps checkpointing (every 10 s, once a minute
+    # in a hidden silent page), 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.
+    # the same 410 → reclaim the player already handles.
     plex_stream.touch_session(user.id, str(rating_key))
     position = max(0, int(body.position_seconds))
     duration = int(body.duration_seconds)
@@ -329,12 +339,7 @@ def item_progress(
     near_end = duration > 0 and position > duration - _FINISH_MARGIN_S
     if near_end:
         flipped = service.mark_finished(db, user.id, it.id, now)
-        # The finish supersedes every resume push still in flight for this item: stamping it as the
-        # latest push makes `_resume_push_superseded` drop them. Popping the entry instead (to keep
-        # the map small) removed the very guard, and an older resume push could then land at Plex
-        # AFTER the scrobble and revive a resume point on a watched item. Eviction bounds the map.
-        with _push_throttle_lock:
-            _last_push_at[(user.id, it.id)] = now
+        _supersede_resume_pushes(user.id, it.id, now)
         db.commit()
         # Only the checkpoint that flipped the row scrobbles: a later checkpoint of the same finished
         # item — or a second one racing this one — would otherwise bump Plex's viewCount again.
@@ -352,7 +357,11 @@ def item_progress(
     push_now = _should_push_resume(user.id, it.id, now, final)
     # Marked dirty before the (background) push so the reconcile knows to re-push if it fails, and so
     # `push_state_to_plex` can settle synced_to_plex once Plex confirms.
-    service.checkpoint(db, user, it.id, st, position, now, dirty=push_now)
+    if not service.checkpoint(db, user, it.id, st, position, now, dirty=push_now):
+        # Marked watched a moment ago: this is the finishing player's late tick (see
+        # `service.checkpoint`), and the answer is the same one a near-end checkpoint gets.
+        db.commit()
+        return {"ok": True, "status": "watched", "position_seconds": 0}
     db.commit()
     if push_now:
         _push_watch(
@@ -408,6 +417,8 @@ def item_state(
             _push_watch(background, db, user.id, it.id, rating_key, "unwatched")
         return {"ok": True, "status": "new"}
     service.set_status(db, user, it.id, st, status)
+    if status == "watched":
+        _supersede_resume_pushes(user.id, it.id, datetime.now(timezone.utc))
     db.commit()
     if status == "watched" and prev_status != "watched":
         _push_watch(background, db, user.id, it.id, rating_key, "watched")
@@ -427,6 +438,10 @@ def _bulk_state(
     always reads the committed marks."""
     pushable = plex_watch.link_for_push(db, user_id) is not None
     to_push = service.bulk_state(db, user_id, eps, watched)
+    if watched:
+        now = datetime.now(timezone.utc)
+        for item_id, _rating_key, _action in to_push:
+            _supersede_resume_pushes(user_id, item_id, now)
     if pushable and to_push:
         # One coalesced background task for the whole batch (reuses a single session + Plex client),
         # not one task per episode — a 200-ep show mark is 1 task, not 200.
@@ -595,7 +610,9 @@ def stream_hls_file(
     is per (key, viewer, offset, tag) — so resolving by the key alone handed the old player 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. A request for a
-    session that is no longer the registered one is a 404, and the player reclaims at the playhead.
+    session that is no longer the registered one is a 410, and the player reclaims at the playhead.
+    410, not 404: a 404 here means "that segment is not there yet", worth hls.js's retries, and the
+    player can only read the status (a gone session retried for half a minute behind that 404).
 
     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."""
@@ -611,7 +628,7 @@ def stream_hls_file(
         raise not_found("file")
     s = plex_stream.current_session(user.id, str(rating_key))
     if s is None or s.id != session_id:
-        raise refused(404, "session_gone")
+        raise refused(410, "session_gone")
     path = s.dir / filename
     # 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
@@ -632,14 +649,15 @@ def stream_hls_file(
     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
+        # The session was torn down between the wait and the read — teardown moves the whole
+        # directory aside and deletes it, and nothing holds `_lock` across those two steps. It has
+        # to present as the same 410 a gone session does: the player's recovery is keyed on the
+        # STATUS, 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 refused(404, "session_gone") from None
+        raise refused(410, "session_gone") from None
     return Response(
         content=content,
         media_type=_HLS_CT[ext],

backend/app/routes/plex/playlists.py

@@ -183,7 +183,9 @@ def playlist_remove_item(
 
 
 class PlexItemKeysIn(BaseModel):
-    item_rating_keys: list[str] = []
+    # Required: with a default, a misnamed key answered 200 having acted on no item, and a reorder
+    # took it for an empty order.
+    item_rating_keys: list[str]
 
 
 class PlexItemAddBulkIn(PlexItemKeysIn):

backend/app/routes/public.py

@@ -176,8 +176,15 @@ def watch_meta(token: str, db: Session = Depends(get_db)) -> dict:
     returns only `needs_password` until the viewer unlocks it (no title/thumbnail leak)."""
     link = _link_or_404(db, token)
     if link.password_hash:
-        # Which kind it opens, for the password prompt's title — never what is in it.
-        return {"needs_password": True, "kind": "folder" if link.folder_id is not None else "file"}
+        # Which kind it opens, for the password prompt's words — never what is in it. `video` tells
+        # a video (watched) from any other file (opened); the address is only a hint, every
+        # prefix opens every link.
+        opens = linksmod.opens(db, link)
+        return {
+            "needs_password": True,
+            "kind": "folder" if opens == "folder" else "file",
+            "video": opens == "video",
+        }
     meta = _opened(db, link, token)
     db.commit()
     return meta

backend/app/routes/saved_views.py

@@ -128,7 +128,8 @@ def update_view(
         db.commit()
     except IntegrityError:
         db.rollback()
-        raise refused(409, "view_name_taken", name=view.name) from None
+        # The name asked for: the rollback has put the view's old name back on `view`.
+        raise refused(409, "view_name_taken", name=name) from None
     return _serialize(view)
 
 

backend/app/routes/search.py

@@ -13,10 +13,18 @@ this search-discovered "noise" by default. Shorts and currently-live/upcoming vi
 ingested this way (Shorts are confirmed by the youtube.com/shorts probe; live/upcoming are
 dropped from the search response up front).
 
+A video's related videos (`/related/{video_id}`, the list YouTube shows beside it) come in the same
+way: read from the website (`related_scrape`), ingested as search finds are, under their own daily
+cap — with what this user has already seen left out.
+
 This is the HTTP side — the paging, the caps and the refusals; what a page of results leaves in the
 catalog is `catalog/search`."""
 
-from fastapi import APIRouter, Depends
+import threading
+from collections.abc import Callable
+from typing import Literal
+
+from fastapi import APIRouter, Depends, Path
 from pydantic import BaseModel
 from sqlalchemy.orm import Session
 
@@ -26,8 +34,10 @@ from app.catalog import queries
 from app.catalog import search as catalog_search
 from app.db import get_db
 from app.models import User
+from app.ratelimit import RateLimiter
 from app.reader import queries as reader_queries
-from app.youtube import search_scrape
+from app.youtube import related_scrape, search_scrape
+from app.youtube.innertube import ScrapeError
 from app.youtube.client import YouTubeClient, YouTubeError
 from app.refusal import refused
 from app.routes._common import youtube_refusal
@@ -37,6 +47,115 @@ router = APIRouter(prefix="/api/search", tags=["search"])
 
 # search.list costs this many quota units per page.
 SEARCH_COST = 100
+# The scrape source reads at most this many pages for one search.
+SEARCH_MAX_PAGES = 12
+
+# A related list is filled to this many unseen videos, reading at most this many pages (about 20
+# videos each, measured) — the ones the user has seen are left out, so a page alone can fall short.
+RELATED_TARGET = 20
+RELATED_MAX_PAGES = 4
+# The locale YouTube fills a related list in: on the video's topic, or with what trends in Hungary.
+RELATED_REGIONS = {"topical": ("en", "US"), "hu": ("hu", "HU")}
+
+# A request that fails outright gives its slot back, but its shape is the user's (a cursor is a
+# free string): one built to fail would read YouTube for nothing, without end. So only this many
+# refunds an hour per user and list; past them a failure keeps its slot, as a success does.
+REFUNDS_PER_HOUR = 5
+_refunds = RateLimiter(max_events=REFUNDS_PER_HOUR, window_seconds=3600)
+# The API source's budget check and the search.list call it pays for run one at a time: checked
+# apart, searches sent together at the last 100 units all passed, and all spent. One process
+# serves the API (a single uvicorn worker, as `ratelimit` says), so a process lock holds them all.
+# A search waits this long for it, then is refused as busy: each waiter holds a request worker, and
+# a slow YouTube (30 s a call at worst) would otherwise park them all behind one another.
+_api_search = threading.Lock()
+API_SEARCH_WAIT_SECONDS = 10.0
+
+
+def _gather(
+    db: Session,
+    yt: YouTubeClient,
+    user: User,
+    *,
+    cursor: str | None,
+    max_pages: int,
+    fetch: Callable[[str | None], dict],
+    candidates_of: Callable[[list[dict], list[str]], list[dict]],
+    enough: Callable[[list[str]], bool],
+    scrape_failed: Callable[[Exception], None],
+    ingest_failed: Callable[[int, int], None],
+) -> tuple[list[str], str | None]:
+    """Page through a YouTube list into the catalog: fetch a page, keep its `candidates_of`, ingest
+    them, and go on from its continuation until `enough` or `max_pages`. Returns the kept ids and
+    the cursor to read further from. A page that fails after earlier ones gathered something ends
+    the list with what it has; a first page that fails raises the 422 refusal.
+
+    422, not 502: this is a JSON endpoint, and the FE treats 502/503/504 as a gateway dropout
+    (auto-retry + "connection lost" banner — lib/api/core RETRIABLE_GATEWAY), which hides the real
+    message and repeats the work. A Data API failure is logged where it happened; the scraper's is
+    not, and its text does not ride the answer — so `scrape_failed` says it. An ingest (DB writes +
+    enrich) fails the same way, guarded for any exception so a write or shape failure is a 422 with
+    a message too, not a bare 500; `ingest_failed` logs it inside the `except`, with the trace."""
+    collected: list[str] = []
+    next_cursor = cursor
+    for _ in range(max_pages):
+        try:
+            page = fetch(next_cursor)
+        except (YouTubeError, ScrapeError) as exc:
+            if collected:
+                break  # keep what earlier pages already gathered
+            if isinstance(exc, ScrapeError):
+                scrape_failed(exc)
+            raise youtube_refusal(exc) from exc
+        candidates = candidates_of(page["items"], collected)
+        try:
+            collected.extend(catalog_search.ingest_candidates(db, yt, user, candidates))
+        except Exception as exc:  # any ingest failure, not just YouTubeError
+            db.rollback()
+            ingest_failed(len(candidates), len(collected))
+            if collected:
+                break
+            raise youtube_refusal(exc) from exc
+        next_cursor = page["next_page_token"]
+        if enough(collected) or not next_cursor:
+            break
+    return collected, next_cursor
+
+
+def _give_back(claimed: int, feature: str, user_id: int) -> None:
+    """Refund the slot of a request that failed outright, while this user has refunds left."""
+    if _refunds.allow(f"{feature}:{user_id}"):
+        quota.refund_action(claimed)
+        return
+    log.info(
+        "a failed request kept its slot: this hour's refunds are spent",
+        extra=logs.event(f"{feature}.refund_refused", per_hour=REFUNDS_PER_HOUR),
+    )
+
+
+def _budget_spent() -> None:
+    """Say that a live search was refused because the shared YouTube budget cannot pay for it."""
+    log.info(
+        "a live search was refused: the shared YouTube budget is spent",
+        extra=logs.event("search.refused", reason="shared_quota", cost=SEARCH_COST),
+    )
+
+
+def _busy() -> None:
+    """Say that a live search was refused because other API searches held the line too long."""
+    log.info(
+        "a live search was refused: other searches held the line",
+        extra=logs.event("search.refused", reason="busy", waited=API_SEARCH_WAIT_SECONDS),
+    )
+
+
+def _cap_spent(feature: str, limit: int) -> None:
+    """Say that a request was refused for the per-user daily cap. The 429 is in the request line
+    either way; which of the caps produced it is not, and they are answered by different things —
+    this one by tomorrow, the shared budget by the admin."""
+    log.info(
+        "a request was refused: the per-user daily cap is spent",
+        extra=logs.event(f"{feature}.refused", reason="daily_cap", limit=limit),
+    )
 
 
 @router.get("/youtube")
@@ -59,109 +178,122 @@ def search_youtube(
     # Source: "scrape" (InnerTube, no API quota) or "api" (search.list, 100 units/page).
     source = sysconfig.get_str(db, "search_source")
 
-    # Per-user daily cap applies to both sources (anti-abuse); with scrape it's the only guard
-    # since the search itself spends no quota.
+    # Every request takes a slot of the per-user daily cap, a cursor's too (anti-abuse); with
+    # scrape it's the only guard since the search itself spends no quota. A limit of 0 turns live
+    # search off on this instance — a refusal tomorrow will not change.
     daily_limit = sysconfig.get_int(db, "search_daily_limit_per_user")
-    used = quota.actions_today(db, user.id, quota.QuotaAction.VIDEOS_SEARCH)
-    if used >= daily_limit:
-        # The 429 is in the request line either way; which of the two caps produced it is not, and
-        # they are answered by different things — this one by tomorrow, the other by the admin.
-        log.info(
-            "a live search was refused: the per-user daily cap is spent",
-            extra=logs.event("search.refused", reason="daily_cap", limit=daily_limit),
-        )
-        raise refused(429, "search_daily_limit", limit=daily_limit)
-    # The 100-unit budget pre-check only applies to the API source.
+    if daily_limit <= 0:
+        raise refused(409, "search_disabled")
+    # The 100-unit budget pre-check only applies to the API source. It is asked again under the
+    # lock, right before the call (`fetch`); this one refuses before a slot is taken.
     if source == "api" and not quota.can_spend(db, SEARCH_COST):
-        log.info(
-            "a live search was refused: the shared YouTube budget is spent",
-            extra=logs.event("search.refused", reason="shared_quota", cost=SEARCH_COST),
-        )
+        _budget_spent()
         raise refused(429, "quota_spent")
+    # The check and the take are one step (`quota.claim_action`), whichever the source: checked
+    # first and logged after, requests sent together at the last free slot all passed — and with
+    # the API source each of them spent 100 units. A search that fails outright gives it back below.
+    claimed = quota.claim_action(user.id, quota.QuotaAction.VIDEOS_SEARCH, daily_limit)
+    if claimed is None:
+        _cap_spent("search", daily_limit)
+        raise refused(429, "search_daily_limit", limit=daily_limit)
 
     # Channels this user has blocked are dropped before ingestion — never shown, never stored.
     blocked = queries.blocked_ids(db, user)
 
-    collected: list[str] = []
-    next_cursor = cursor
-    MAX_PAGES = 12  # scrape safety bound
-    with YouTubeClient(db, user) as yt:
-        for _ in range(MAX_PAGES):
-            try:
-                if source == "api":
-                    with quota.attribute(user.id, quota.QuotaAction.VIDEOS_SEARCH):
-                        page = yt.search_videos(term, page_token=next_cursor)
-                else:
-                    page = search_scrape.search(term, continuation=next_cursor)
-            except (YouTubeError, search_scrape.ScrapeError) as exc:
-                if collected:
-                    break  # keep what we already gathered
-                # 422, not 502: this is a JSON endpoint, and the FE treats 502/503/504 as a gateway
-                # dropout (auto-retry + "connection lost" banner — lib/api/core RETRIABLE_GATEWAY),
-                # which hides the real message and burns a second quota-costed search. Upstream failure
-                # on a JSON endpoint = 422 + message; reserve 5xx for the raw byte-proxies. (B-core-1)
-                # A Data API failure is logged where it happened; the scraper's is not, and its text
-                # no longer rides the answer — so it is said here.
-                if isinstance(exc, search_scrape.ScrapeError):
-                    log.warning(
-                        "the YouTube search scrape failed",
-                        extra=logs.event("search.scrape_failed", error=str(exc)),
-                    )
-                raise youtube_refusal(exc) from exc
+    # Whether search.list was paid for: YouTube charges a call it refuses too, so once the client
+    # recorded its units — or the request went out and no answer came back — the search has spent
+    # the shared budget. One that never reached YouTube (no connection, no token) has not.
+    charged = False
 
-            # Drop currently-live/upcoming, channel-less, and blocked-channel results.
-            candidates = [
-                it
-                for it in page["items"]
-                if it["live_broadcast"] == "none"
-                and it["channel_id"]
-                and it["channel_id"] not in blocked
-            ]
-            # Ingest (DB writes + enrich) runs outside the page-fetch try above; guard it too so a
-            # write/shape failure degrades to a 422 with a message on this JSON endpoint instead of a
-            # bare 500 hidden behind the FE's generic "search failed" (same rationale as B-core-1).
-            try:
-                collected.extend(catalog_search.ingest_candidates(db, yt, user, candidates))
-            except Exception as exc:  # any ingest failure, not just YouTubeError
-                db.rollback()
-                # The term is NOT in this line. A search string is exactly what the privacy
-                # policy keeps out of the log unless the user turned Teljes/TRACE on for
-                # themselves, and `redact_text` does not cover it — it scrubs addresses and
-                # credential params, not what someone typed into the search box. What the
-                # ERROR line carries instead is the shape of the failure, which is what tells
-                # an ingest bug from an upstream one; the term follows at TRACE, and only
-                # under this user's own consent — not whenever the process runs at TRACE.
-                log.exception(
-                    "live search ingest failed",
-                    extra=logs.event(
-                        "search.live.ingest_failed",
-                        source=source,
-                        candidates=len(candidates),
-                        collected=len(collected),
-                    ),
-                )
-                if logs.consented_trace():
-                    log.log(
-                        logs.TRACE,
-                        "the term the ingest failed on",
-                        # log-pii-ok: only under this user's own Teljes consent
-                        extra=logs.event("search.live.term", term=term),
-                    )
-                if collected:
-                    break  # keep what earlier pages already gathered
-                raise youtube_refusal(exc) from exc
-            next_cursor = page["next_page_token"]
-            # The API source pages cost 100 units each — never auto-page; one page per request.
-            if source == "api" or len(collected) >= limit or not next_cursor:
-                break
+    def fetch(token: str | None) -> dict:
+        if source != "api":
+            return search_scrape.search(term, continuation=token)
+        if not _api_search.acquire(timeout=API_SEARCH_WAIT_SECONDS):
+            _busy()
+            raise refused(429, "search_busy")
+        try:
+            return paid_search(token)
+        finally:
+            _api_search.release()
 
-    # Count this as ONE per-user search against the daily cap. The scrape source spends no
-    # quota, so it never logs an event on its own; the API source already logged exactly one
-    # (via record_usage — it never auto-pages). Logging once here, after a search that produced
-    # at least one page (a total failure raises 502 above and never reaches this), keeps the cap
-    # counting user searches instead of internal continuation pages.
-    if source != "api":
-        quota.log_action(user.id, quota.QuotaAction.VIDEOS_SEARCH)
+    def paid_search(token: str | None) -> dict:
+        nonlocal charged
+        with quota.attribute(user.id, quota.QuotaAction.VIDEOS_SEARCH):
+            if not quota.can_spend(db, SEARCH_COST):
+                _budget_spent()
+                raise refused(429, "quota_spent")
+            spent = yt.spent
+            try:
+                page = yt.search_videos(term, page_token=token)
+            except YouTubeError as exc:
+                charged = yt.spent > spent or exc.sent
+                raise
+            charged = True
+            return page
+
+    def candidates_of(items: list[dict], _collected: list[str]) -> list[dict]:
+        # Drop currently-live/upcoming, channel-less, and blocked-channel results.
+        return [
+            it
+            for it in items
+            if it["live_broadcast"] == "none"
+            and it["channel_id"]
+            and it["channel_id"] not in blocked
+        ]
+
+    def scrape_failed(exc: Exception) -> None:
+        log.warning(
+            "the YouTube search scrape failed",
+            extra=logs.event("search.scrape_failed", error=str(exc)),
+        )
+
+    def ingest_failed(candidates: int, collected: int) -> None:
+        # The term is NOT in this line. A search string is exactly what the privacy policy keeps
+        # out of the log unless the user turned Teljes/TRACE on for themselves, and `redact_text`
+        # does not cover it — it scrubs addresses and credential params, not what someone typed
+        # into the search box. What the ERROR line carries instead is the shape of the failure,
+        # which is what tells an ingest bug from an upstream one; the term follows at TRACE, and
+        # only under this user's own consent — not whenever the process runs at TRACE.
+        log.exception(
+            "live search ingest failed",
+            extra=logs.event(
+                "search.live.ingest_failed",
+                source=source,
+                candidates=candidates,
+                collected=collected,
+            ),
+        )
+        if logs.consented_trace():
+            log.log(
+                logs.TRACE,
+                "the term the ingest failed on",
+                # log-pii-ok: only under this user's own Teljes consent
+                extra=logs.event("search.live.term", term=term),
+            )
+
+    try:
+        with YouTubeClient(db, user) as yt:
+            collected, next_cursor = _gather(
+                db,
+                yt,
+                user,
+                cursor=cursor,
+                # The API source pages cost 100 units each — never auto-page; one page per request.
+                max_pages=1 if source == "api" else SEARCH_MAX_PAGES,
+                fetch=fetch,
+                candidates_of=candidates_of,
+                enough=lambda got: len(got) >= limit,
+                scrape_failed=scrape_failed,
+                ingest_failed=ingest_failed,
+            )
+    except Exception:
+        # A search that showed the user nothing does not count against them, unless search.list
+        # was already paid for: then the slot is what stops a failing search (a bogus cursor gets
+        # a 400 every time) from spending the shared budget without end. A busy refusal paid
+        # nothing and gives it back.
+        if not charged:
+            _give_back(claimed, "search", user.id)
+        raise
 
     ordered = collected[:limit]
 
@@ -182,7 +314,8 @@ def search_youtube(
 
 
 class ClearSearchIn(BaseModel):
-    video_ids: list[str] = []
+    # Required: a default read a misnamed key as an empty list, a 200 that cleared nothing.
+    video_ids: list[str]
 
 
 @router.post("/clear")
@@ -201,3 +334,78 @@ def clear_search(
     removed = catalog_search.clear(db, user, ids)
     db.commit()
     return {"ok": True, "removed": removed}
+
+
+@router.get("/related/{video_id}")
+def related_videos(
+    video_id: str = Path(max_length=16),
+    cursor: str | None = None,
+    region: Literal["topical", "hu"] = "topical",
+    user: User = Depends(current_user),
+    db: Session = Depends(get_db),
+) -> dict:
+    """The videos YouTube shows beside this one, materialised into the catalog like search results,
+    without the ones this user has watched or hidden here or in their Takeout history, and without
+    blocked channels. Pages on (`cursor`) until `RELATED_TARGET` are gathered; `next_cursor` reads
+    further. `region` picks the locale YouTube fills the list in (`RELATED_REGIONS`)."""
+    # Every request takes a slot, a cursor's too: each one scrapes pages and enriches what they
+    # hold, and a cursor is a free string — counting only first pages let a replayed cursor read
+    # without end. The check and the take are one step (`quota.claim_action`); a request that fails
+    # outright gives its slot back, a few an hour (`_give_back`). A limit of 0 turns related videos
+    # off on this instance.
+    daily_limit = sysconfig.get_int(db, "related_daily_limit_per_user")
+    if daily_limit <= 0:
+        raise refused(409, "related_disabled")
+    claimed = quota.claim_action(user.id, quota.QuotaAction.VIDEOS_RELATED, daily_limit)
+    if claimed is None:
+        _cap_spent("related", daily_limit)
+        raise refused(429, "related_daily_limit", limit=daily_limit)
+
+    hl, gl = RELATED_REGIONS[region]
+    blocked = queries.blocked_ids(db, user)
+
+    def candidates_of(items: list[dict], collected: list[str]) -> list[dict]:
+        ids = [it["id"] for it in items]
+        drop = reader_queries.seen_by(db, user, ids) | set(collected) | {video_id}
+        return [it for it in items if it["id"] not in drop and it["channel_id"] not in blocked]
+
+    def scrape_failed(exc: Exception) -> None:
+        log.warning(
+            "the related-videos scrape failed",
+            extra=logs.event("related.scrape_failed", error=str(exc)),
+        )
+
+    def ingest_failed(candidates: int, collected: int) -> None:
+        log.exception(
+            "a related list's ingest failed",
+            extra=logs.event("related.ingest_failed", candidates=candidates, collected=collected),
+        )
+
+    try:
+        with YouTubeClient(db, user) as yt:
+            collected, next_cursor = _gather(
+                db,
+                yt,
+                user,
+                cursor=cursor,
+                max_pages=RELATED_MAX_PAGES,
+                fetch=lambda token: related_scrape.related(
+                    video_id, continuation=token, hl=hl, gl=gl
+                ),
+                candidates_of=candidates_of,
+                enough=lambda got: len(got) >= RELATED_TARGET,
+                scrape_failed=scrape_failed,
+                ingest_failed=ingest_failed,
+            )
+    except Exception:
+        _give_back(claimed, "related", user.id)
+        raise
+
+    rows = reader_queries.feed_rows_by_ids(db, user, collected)
+    # A related list mixes channels the user follows with ones they never met: each row says which.
+    followed = queries.followed_among(db, user, {r["channel_id"] for r in rows})
+    return {
+        "items": [{**r, "followed": r["channel_id"] in followed} for r in rows],
+        "next_cursor": next_cursor,
+        "has_more": bool(next_cursor),
+    }

backend/app/routes/tags.py

@@ -48,8 +48,9 @@ def list_tags(user: User = Depends(current_user), db: Session = Depends(get_db))
             "category": tag.category,
             "system": tag.user_id is None,
             "channel_count": count,
+            "subscribed_count": subscribed,
         }
-        for tag, count in queries.tags_with_counts(db, user)
+        for tag, count, subscribed in queries.tags_with_counts(db, user)
     ]
 
 
@@ -107,7 +108,8 @@ def update_tag(
         db.commit()
     except IntegrityError:
         db.rollback()
-        raise refused(409, "tag_name_taken", name=tag.name) from None
+        # The name asked for: the rollback has put the tag's old name back on `tag`.
+        raise refused(409, "tag_name_taken", name=name) from None
     return {
         "ok": True,
         "id": tag.id,

backend/app/sysconfig.py

@@ -140,6 +140,15 @@ SPECS: tuple[ConfigSpec, ...] = (
         max=100_000,
         applies=LIVE,
     ),
+    ConfigSpec(
+        "related_daily_limit_per_user",
+        "int",
+        "quota",
+        "related_daily_limit_per_user",
+        min=0,
+        max=100_000,
+        applies=LIVE,
+    ),
     # Live-search source: "scrape" (InnerTube, zero API quota) or "api" (search.list, 100u/page).
     ConfigSpec("search_source", "choice", "quota", "search_source", applies=LIVE),
     ConfigSpec(
@@ -434,15 +443,20 @@ def _default(s: ConfigSpec):
     return getattr(settings, s.default_attr)
 
 
+# Every reason `set_value` refuses with. `refusal.setting_refused` looks each one up in its map, which
+# the refusal scan holds to exactly these keys: a reason the map lacks would answer a 500.
+SettingReason = Literal["not_a_number", "too_low", "too_high", "not_a_choice", "no_encryption_key"]
+
+
 class InvalidSetting(ValueError):
     """A value `set_value` refuses, as a reason the UI translates (`errors.refused.setting_<reason>`)
     plus what the sentence needs — the English message is for logs only. A ValueError still, so a
     caller that only needs "refused or not" keeps working."""
 
-    def __init__(self, key: str, reason: str, **params: object):
+    def __init__(self, key: str, reason: SettingReason, **params: object):
         super().__init__(f"{key}: {reason} {params}")
         self.key = key
-        self.reason = reason
+        self.reason: SettingReason = reason
         self.params = params
 
 

backend/app/youtube/client.py

@@ -30,12 +30,26 @@ class YouTubeError(Exception):
     message is prose, it changes under us, and it is deliberately the poorer of the two here.
 
     `path` is the API endpoint that ANSWERED with the failure (`playlistItems`); empty when no
-    endpoint did — the request never got through (`transport`) or the token step refused first."""
+    endpoint did — the request never got through (`transport`) or the token step refused first.
 
-    def __init__(self, message: str, *, reason: str = "", path: str = ""):
+    `sent` is a `transport` failure that came after the request may have gone out (a read timeout,
+    a dropped answer): nothing answered, but YouTube may have counted the call."""
+
+    def __init__(self, message: str, *, reason: str = "", path: str = "", sent: bool = False):
         super().__init__(message)
         self.reason = reason
         self.path = path
+        self.sent = sent
+
+
+# The transport failures that stop a request before it reaches YouTube: nothing went out.
+_UNSENT = (
+    httpx.ConnectError,
+    httpx.ConnectTimeout,
+    httpx.PoolTimeout,
+    httpx.ProxyError,
+    httpx.UnsupportedProtocol,
+)
 
 
 def _error_reason(resp: httpx.Response) -> str:
@@ -162,6 +176,9 @@ def best_thumbnail(thumbnails: dict | None) -> str | None:
 
 
 class YouTubeClient:
+    # The quota units this client has recorded: what its calls have spent of the shared budget.
+    spent: int = 0
+
     def __init__(self, db, user: User):
         self.db = db
         self.user = user
@@ -189,9 +206,16 @@ class YouTubeClient:
             return self._http.request(method, url, **kwargs)
         except httpx.HTTPError as exc:
             raise YouTubeError(
-                f"YouTube API unreachable ({exc.__class__.__name__}: {exc})", reason="transport"
+                f"YouTube API unreachable ({exc.__class__.__name__}: {exc})",
+                reason="transport",
+                sent=not isinstance(exc, _UNSENT),
             ) from exc
 
+    def _spend(self, units: int) -> None:
+        """Record what a call YouTube answered cost — a refused one too: it is charged all the same."""
+        quota.record_usage(units)
+        self.spent += units
+
     # --- auth ---
     def _access_token(self) -> str:
         tok = self.user.token
@@ -269,7 +293,7 @@ class YouTubeClient:
         else:
             headers["Authorization"] = f"Bearer {self._access_token()}"
         resp = self._send("GET", f"{API_BASE}/{path}", params=p, headers=headers)
-        quota.record_usage(cost)
+        self._spend(cost)
         if resp.status_code != 200:
             raise _upstream_failure("GET", path, resp, expected)
         return resp.json()
@@ -401,7 +425,7 @@ class YouTubeClient:
             params={"id": subscription_id},
             headers={"Authorization": f"Bearer {self._access_token()}"},
         )
-        quota.record_usage(50)
+        self._spend(50)
         if resp.status_code not in (200, 204):
             raise _upstream_failure("DELETE", "subscriptions", resp)
 
@@ -431,7 +455,7 @@ class YouTubeClient:
     def _write(self, method: str, path: str, *, params: dict, json: dict | None = None) -> dict:
         headers = {"Authorization": f"Bearer {self._access_token()}"}
         resp = self._send(method, f"{API_BASE}/{path}", params=params, json=json, headers=headers)
-        quota.record_usage(50)
+        self._spend(50)
         if resp.status_code not in (200, 204):
             raise _upstream_failure(method, path, resp)
         return resp.json() if resp.content else {}

backend/app/youtube/innertube.py

@@ -0,0 +1,160 @@
+"""The website's own InnerTube API (`youtubei/v1/*`), read the way the website reads it — no quota.
+
+The zero-quota search (`search_scrape`) and the related videos (`related_scrape`) both POST here with
+the public WEB key and a client version, read out of a live results page. This deliberately calls an
+undocumented endpoint: if YouTube changes the JSON shape or blocks the host, each caller says so as a
+`ScrapeError`, never as an empty answer.
+
+The SOCS=CAI consent-skip cookie is sent like the Shorts probe's, so a server-side request isn't
+bounced to consent.youtube.com."""
+
+import re
+
+import httpx
+
+from app import logs
+
+log = logs.get_logger(__name__)
+
+_API_URL = "https://www.youtube.com/youtubei/v1/"
+_RESULTS_URL = "https://www.youtube.com/results"
+# Public WEB InnerTube key + a recent client version. These are also embedded in every results
+# page; we fetch the live pair once and cache it, falling back to these constants.
+_FALLBACK_KEY = "AIzaSyAO_FJ2SlqU8Q4STEHLGCilw_Y9_11qcW8"  # gitleaks:allow -- the public WEB key, in every results page
+_FALLBACK_CLIENT_VERSION = "2.20240101.00.00"
+
+_HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
+    # SOCS skips YouTube's cookie-consent interstitial (otherwise every server-side request is
+    # redirected to consent.youtube.com).
+    "Cookie": "SOCS=CAI",
+    "Accept-Language": "en-US,en;q=0.9",
+}
+
+_KEY_RE = re.compile(r'"INNERTUBE_API_KEY":"([^"]+)"')
+_VER_RE = re.compile(r'"INNERTUBE_CLIENT_VERSION":"([^"]+)"')
+
+# Cached (api_key, client_version) extracted from a results page; refreshed on demand.
+_config: tuple[str, str] | None = None
+
+
+class ScrapeError(Exception):
+    """An InnerTube read could not be completed (network, blocked, or unexpected shape)."""
+
+
+def runs_text(node: dict | None) -> str | None:
+    """The text of an InnerTube text node: a `simpleText`, or its `runs` joined."""
+    if not node:
+        return None
+    if node.get("simpleText"):
+        return node["simpleText"]
+    runs = node.get("runs") or []
+    if runs:
+        return "".join(r.get("text", "") for r in runs)
+    return None
+
+
+def scraped_video(
+    vid: str, channel_id: object, channel_title: object, title: object, thumbnails: object
+) -> dict:
+    """One scraped video in the shape `YouTubeClient.search_videos` answers, so a page of either
+    source is ingested the same way. `published_at` is None (the website shows only a relative
+    "3 years ago"; the enrich fills the real date) and `live_broadcast` "none" (live/upcoming are
+    judged after the enrich, by `live_status`). The largest thumbnail is the last."""
+    thumbs = thumbnails if isinstance(thumbnails, list) else []
+    last = thumbs[-1] if thumbs else None
+    return {
+        "id": vid,
+        "channel_id": channel_id if isinstance(channel_id, str) and channel_id else None,
+        "channel_title": channel_title if isinstance(channel_title, str) else None,
+        "title": title if isinstance(title, str) else None,
+        "published_at": None,
+        "thumbnail_url": last.get("url") if isinstance(last, dict) else None,
+        "live_broadcast": "none",
+    }
+
+
+def video_renderer(node: dict) -> dict | None:
+    """A `videoRenderer` (search) or `compactVideoRenderer` (the older related column) flattened —
+    the two draw a video the same way. None without a video id; the channel is None when the byline
+    names none."""
+    vid = node.get("videoId")
+    if not isinstance(vid, str) or not vid:
+        return None
+    owner = node.get("ownerText") or node.get("longBylineText") or {}
+    runs = owner.get("runs") if isinstance(owner, dict) else None
+    first = runs[0] if isinstance(runs, list) and runs and isinstance(runs[0], dict) else {}
+    endpoint = (first.get("navigationEndpoint") or {}).get("browseEndpoint") or {}
+    return scraped_video(
+        vid,
+        endpoint.get("browseId"),
+        first.get("text"),
+        runs_text(node.get("title")),
+        (node.get("thumbnail") or {}).get("thumbnails"),
+    )
+
+
+def continuation_token(node: object) -> str | None:
+    """The "load more" cursor of a `continuationItemRenderer`, or None when `node` is not one."""
+    if not isinstance(node, dict):
+        return None
+    command = (node.get("continuationEndpoint") or {}).get("continuationCommand") or {}
+    token = command.get("token")
+    return token if isinstance(token, str) and token else None
+
+
+def _get_config(client: httpx.Client) -> tuple[str, str]:
+    """The current InnerTube (api_key, client_version), cached after the first fetch that FOUND them.
+
+    The fallback pair is never cached: it used to be, so one failed fetch (or a consent page with no
+    keys on it) at the wrong moment pinned every later search to a hard-coded key and version for
+    the life of the process — and when those went stale, search returned nothing, with no error
+    anywhere. Now the next call simply tries the live pair again."""
+    global _config
+    if _config is not None:
+        return _config
+    try:
+        html = client.get(_RESULTS_URL, params={"search_query": "music"}).text
+    except httpx.HTTPError as exc:
+        log.warning(
+            "the InnerTube config could not be fetched; falling back to the pinned key",
+            extra=logs.event("youtube.scrape.config_fallback", reason=type(exc).__name__),
+        )
+        return (_FALLBACK_KEY, _FALLBACK_CLIENT_VERSION)
+    key = _KEY_RE.search(html)
+    ver = _VER_RE.search(html)
+    if key and ver:
+        _config = (key.group(1), ver.group(1))
+        return _config
+    log.warning(
+        "the results page carried no InnerTube config; falling back to the pinned key",
+        extra=logs.event("youtube.scrape.config_fallback", reason="not_on_page"),
+    )
+    return (
+        key.group(1) if key else _FALLBACK_KEY,
+        ver.group(1) if ver else _FALLBACK_CLIENT_VERSION,
+    )
+
+
+def post(endpoint: str, body: dict, *, hl: str = "en", gl: str = "US") -> dict:
+    """POST `body` to `youtubei/v1/<endpoint>` as the WEB client in the `hl`/`gl` locale and return
+    the decoded JSON object. A network failure, an HTTP error or a body that is not a JSON object (a
+    block, consent or captcha page) raises `ScrapeError`; the caller judges the shape."""
+    with httpx.Client(timeout=20.0, headers=_HEADERS) as client:
+        api_key, client_version = _get_config(client)
+        context = {
+            "client": {"clientName": "WEB", "clientVersion": client_version, "hl": hl, "gl": gl}
+        }
+        try:
+            resp = client.post(
+                _API_URL + endpoint, params={"key": api_key}, json={"context": context, **body}
+            )
+            resp.raise_for_status()
+            data = resp.json()
+        except httpx.HTTPError as exc:
+            raise ScrapeError(f"InnerTube request failed: {exc}") from exc
+        except ValueError as exc:  # non-JSON body (blocked / consent / captcha)
+            raise ScrapeError("InnerTube returned a non-JSON response") from exc
+    if not isinstance(data, dict):
+        raise ScrapeError("InnerTube returned an unexpected shape")
+    return data

backend/app/youtube/related_scrape.py

@@ -0,0 +1,141 @@
+"""A video's related videos, read from the watch page's InnerTube `next` endpoint — no quota.
+
+The Data API has no related-videos call any more, so this is the only source: the same list the
+website shows beside a playing video. A page holds about 20 videos and a continuation token for the
+next 20. The returned page has the search scrape's shape (``{"items": [...], "next_page_token"}``)
+so the catalog ingests it the same way (`catalog.search.ingest_candidates`).
+
+YouTube draws each item as a `lockupViewModel` now; the older `compactVideoRenderer` is read too, so
+a rollback on its side does not empty the list. An item that names no single channel — a video by
+several channels draws an avatar stack, not one avatar — is left out: the catalog row needs its
+channel up front, and the stack does not say which one uploaded it.
+
+`hl`/`gl` pick the locale YouTube fills the list in: ``en``/``US`` keeps it on the video's topic,
+``hu``/``HU`` mixes in what is trending in Hungary (measured)."""
+
+from app.youtube.innertube import (
+    ScrapeError,
+    continuation_token,
+    post,
+    scraped_video,
+    video_renderer,
+)
+
+__all__ = ["ScrapeError", "related"]
+
+# Where a first page and a continuation page put their item list.
+_FIRST = (
+    "contents",
+    "twoColumnWatchNextResults",
+    "secondaryResults",
+    "secondaryResults",
+    "results",
+)
+_APPENDS = ("appendContinuationItemsAction", "reloadContinuationItemsCommand")
+
+
+def _at(node: object, *path: str | int) -> object:
+    """The value under `path` in nested dicts/lists, or None where the path stops."""
+    for key in path:
+        if isinstance(node, dict) and isinstance(key, str):
+            node = node.get(key)
+        elif isinstance(node, list) and isinstance(key, int) and -len(node) <= key < len(node):
+            node = node[key]
+        else:
+            return None
+    return node
+
+
+def _lockup(node: dict) -> dict | None:
+    if node.get("contentType") != "LOCKUP_CONTENT_TYPE_VIDEO" or not node.get("contentId"):
+        return None
+    meta = _at(node, "metadata", "lockupMetadataViewModel")
+    channel_id = _at(
+        meta,
+        "image",
+        "decoratedAvatarViewModel",
+        "rendererContext",
+        "commandContext",
+        "onTap",
+        "innertubeCommand",
+        "browseEndpoint",
+        "browseId",
+    )
+    channel_title = _at(
+        meta, "metadata", "contentMetadataViewModel", "metadataRows", 0, "metadataParts", 0
+    )
+    return scraped_video(
+        node["contentId"],
+        channel_id,
+        _at(channel_title, "text", "content"),
+        _at(meta, "title", "content"),
+        _at(node, "contentImage", "thumbnailViewModel", "image", "sources"),
+    )
+
+
+def _unavailable(data: dict) -> bool:
+    """Whether the watch page says the video is not available: its main column draws a
+    `backgroundPromoRenderer` ("This video isn't available anymore") and there is no related column.
+    YouTube's own word for "nothing related" — the one empty page that is not a shape we lost."""
+    sections = _at(data, "contents", "twoColumnWatchNextResults", "results", "results", "contents")
+    for section in sections if isinstance(sections, list) else []:
+        inner = _at(section, "itemSectionRenderer", "contents")
+        for node in inner if isinstance(inner, list) else []:
+            if isinstance(node, dict) and "backgroundPromoRenderer" in node:
+                return True
+    return False
+
+
+def _items(data: dict) -> list | None:
+    """The page's item list (first page or continuation), or None when it has neither frame."""
+    first = _at(data, *_FIRST)
+    if isinstance(first, list):
+        return first
+    if _unavailable(data):
+        return []
+    for endpoint in data.get("onResponseReceivedEndpoints") or []:
+        for key in _APPENDS:
+            items = _at(endpoint, key, "continuationItems")
+            if isinstance(items, list):
+                return items
+    return None
+
+
+def related(
+    video_id: str, continuation: str | None = None, *, hl: str = "en", gl: str = "US"
+) -> dict:
+    """One page of `video_id`'s related videos (`continuation` = the token a previous page gave).
+
+    A video YouTube says it no longer has is an empty page. An answer of a shape this does not know
+    — no related column, or one whose entries are all renderers it cannot read — is a `ScrapeError`:
+    not an empty page, which would read as "nothing related"."""
+    body = {"continuation": continuation} if continuation else {"videoId": video_id}
+    data = post("next", body, hl=hl, gl=gl)
+    items = _items(data)
+    if items is None:
+        raise ScrapeError("InnerTube returned no related list")
+    out: list[dict] = []
+    seen: set[str] = set()
+    token = None
+    known = 0  # entries drawn by a renderer read here (a video's, or the cursor)
+    for entry in items:
+        if not isinstance(entry, dict):
+            continue
+        if "lockupViewModel" in entry:
+            item = _lockup(entry["lockupViewModel"])
+        elif "compactVideoRenderer" in entry:
+            item = video_renderer(entry["compactVideoRenderer"])
+        else:
+            found = continuation_token(entry.get("continuationItemRenderer"))
+            known += found is not None
+            token = token or found
+            continue
+        known += 1
+        # A video by several channels draws an avatar stack, not one: no channel, left out.
+        if item and item["channel_id"] and item["id"] not in seen:
+            seen.add(item["id"])
+            out.append(item)
+    # A list with entries but none of them one we read: YouTube draws its items some new way.
+    if items and not known:
+        raise ScrapeError("InnerTube's related list holds no renderer this reads")
+    return {"items": out, "next_page_token": token}

backend/app/youtube/search_scrape.py

@@ -6,9 +6,9 @@ calls — and read the result list straight out of the JSON. The returned video
 through the normal enrich path (videos.list, 1 unit / 50), exactly as the official search does,
 so the search itself is effectively free and only the (cheap, shared) enrichment is charged.
 
-The SOCS=CAI consent-skip cookie is used like the Shorts probe so a server-side request isn't
-bounced to consent.youtube.com. This deliberately scrapes an undocumented endpoint: if YouTube
-changes the JSON shape or blocks the host, an admin can flip ``search_source`` back to ``api``.
+The request itself (the live key, the consent cookie) is `innertube`'s. This deliberately scrapes an
+undocumented endpoint: if YouTube changes the JSON shape or blocks the host, an admin can flip
+``search_source`` back to ``api``.
 
 The returned page mirrors :meth:`YouTubeClient.search_videos` exactly
 (``{"items": [...], "next_page_token": str | None}``) so the route is source-agnostic — the
@@ -17,110 +17,16 @@ only difference is the cursor is an InnerTube *continuation token*, not a Data A
 the real date is filled by the videos.list enrich. ``live_broadcast`` is reported as ``"none"``
 and live/upcoming filtering happens post-enrich via ``live_status`` (same as the API path)."""
 
-import re
+from app.youtube.innertube import ScrapeError, continuation_token, post, video_renderer
 
-import httpx
+__all__ = ["ScrapeError", "search"]
 
-from app import logs
-
-log = logs.get_logger(__name__)
-
-_SEARCH_URL = "https://www.youtube.com/youtubei/v1/search"
-_RESULTS_URL = "https://www.youtube.com/results"
-# Public WEB InnerTube key + a recent client version. These are also embedded in every results
-# page; we fetch the live pair once and cache it, falling back to these constants.
-_FALLBACK_KEY = "AIzaSyAO_FJ2SlqU8Q4STEHLGCilw_Y9_11qcW8"
-_FALLBACK_CLIENT_VERSION = "2.20240101.00.00"
 # sp / params value selecting the "type: video" search filter (base64 protobuf EgIQAQ==).
 _TYPE_VIDEO = "EgIQAQ=="
 
-_HEADERS = {
-    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
-    # SOCS skips YouTube's cookie-consent interstitial (otherwise every server-side request is
-    # redirected to consent.youtube.com).
-    "Cookie": "SOCS=CAI",
-    "Accept-Language": "en-US,en;q=0.9",
-}
-
 # The top-level keys a first page (contents) and a continuation page (onResponseReceivedCommands)
 # put their result list under.
 _RESULT_FRAMES = {"contents", "onResponseReceivedCommands"}
-_KEY_RE = re.compile(r'"INNERTUBE_API_KEY":"([^"]+)"')
-_VER_RE = re.compile(r'"INNERTUBE_CLIENT_VERSION":"([^"]+)"')
-
-# Cached (api_key, client_version) extracted from a results page; refreshed on demand.
-_config: tuple[str, str] | None = None
-
-
-class ScrapeError(Exception):
-    """A scrape-based search could not be completed (network, blocked, or unexpected shape)."""
-
-
-def _runs_text(node: dict | None) -> str | None:
-    if not node:
-        return None
-    if node.get("simpleText"):
-        return node["simpleText"]
-    runs = node.get("runs") or []
-    if runs:
-        return "".join(r.get("text", "") for r in runs)
-    return None
-
-
-def _get_config(client: httpx.Client) -> tuple[str, str]:
-    """The current InnerTube (api_key, client_version), cached after the first fetch that FOUND them.
-
-    The fallback pair is never cached: it used to be, so one failed fetch (or a consent page with no
-    keys on it) at the wrong moment pinned every later search to a hard-coded key and version for
-    the life of the process — and when those went stale, search returned nothing, with no error
-    anywhere. Now the next search simply tries the live pair again."""
-    global _config
-    if _config is not None:
-        return _config
-    try:
-        html = client.get(_RESULTS_URL, params={"search_query": "music"}).text
-    except httpx.HTTPError as exc:
-        log.warning(
-            "the InnerTube config could not be fetched; falling back to the pinned key",
-            extra=logs.event("youtube.scrape.config_fallback", reason=type(exc).__name__),
-        )
-        return (_FALLBACK_KEY, _FALLBACK_CLIENT_VERSION)
-    key = _KEY_RE.search(html)
-    ver = _VER_RE.search(html)
-    if key and ver:
-        _config = (key.group(1), ver.group(1))
-        return _config
-    log.warning(
-        "the results page carried no InnerTube config; falling back to the pinned key",
-        extra=logs.event("youtube.scrape.config_fallback", reason="not_on_page"),
-    )
-    return (
-        key.group(1) if key else _FALLBACK_KEY,
-        ver.group(1) if ver else _FALLBACK_CLIENT_VERSION,
-    )
-
-
-def _video_item(vr: dict) -> dict | None:
-    """Flatten a YouTube `videoRenderer` into the same shape as YouTubeClient.search_videos."""
-    vid = vr.get("videoId")
-    if not vid:
-        return None
-    owner = vr.get("ownerText") or vr.get("longBylineText") or {}
-    runs = owner.get("runs") or []
-    channel_id = channel_title = None
-    if runs:
-        channel_title = runs[0].get("text")
-        channel_id = runs[0].get("navigationEndpoint", {}).get("browseEndpoint", {}).get("browseId")
-    thumbs = (vr.get("thumbnail") or {}).get("thumbnails") or []
-    return {
-        "id": vid,
-        "channel_id": channel_id,
-        "channel_title": channel_title,
-        "title": _runs_text(vr.get("title")),
-        "published_at": None,  # scrape exposes only a relative time; enrich fills the real date
-        "thumbnail_url": thumbs[-1]["url"] if thumbs else None,
-        "live_broadcast": "none",  # live/upcoming filtered post-enrich via live_status
-    }
 
 
 def _collect_videos(obj, out: list[dict], seen: set[str]) -> None:
@@ -130,7 +36,7 @@ def _collect_videos(obj, out: list[dict], seen: set[str]) -> None:
     if isinstance(obj, dict):
         vr = obj.get("videoRenderer")
         if isinstance(vr, dict):
-            item = _video_item(vr)
+            item = video_renderer(vr)
             if item and item["id"] not in seen:
                 seen.add(item["id"])
                 out.append(item)
@@ -144,11 +50,9 @@ def _collect_videos(obj, out: list[dict], seen: set[str]) -> None:
 def _find_continuation(obj) -> str | None:
     """First continuationItemRenderer token (the 'load more' cursor), or None at the end."""
     if isinstance(obj, dict):
-        cir = obj.get("continuationItemRenderer")
-        if isinstance(cir, dict):
-            tok = cir.get("continuationEndpoint", {}).get("continuationCommand", {}).get("token")
-            if tok:
-                return tok
+        tok = continuation_token(obj.get("continuationItemRenderer"))
+        if tok:
+            return tok
         for v in obj.values():
             tok = _find_continuation(v)
             if tok:
@@ -167,34 +71,14 @@ def search(q: str, continuation: str | None = None) -> dict:
     `continuation` is the InnerTube continuation token from a previous page (None for the first
     page). Returns ``{"items": [...], "next_page_token": str | None}`` — the same shape as
     YouTubeClient.search_videos so the route handles both sources identically."""
-    with httpx.Client(timeout=20.0, headers=_HEADERS) as client:
-        api_key, client_version = _get_config(client)
-        context = {
-            "client": {
-                "clientName": "WEB",
-                "clientVersion": client_version,
-                "hl": "en",
-                "gl": "US",
-            }
-        }
-        body: dict = {"context": context}
-        if continuation:
-            body["continuation"] = continuation
-        else:
-            body["query"] = q
-            body["params"] = _TYPE_VIDEO
-        try:
-            resp = client.post(_SEARCH_URL, params={"key": api_key}, json=body)
-            resp.raise_for_status()
-            data = resp.json()
-        except httpx.HTTPError as exc:
-            raise ScrapeError(f"InnerTube request failed: {exc}") from exc
-        except ValueError as exc:  # non-JSON body (blocked / consent / captcha)
-            raise ScrapeError("InnerTube returned a non-JSON response") from exc
+    body: dict = (
+        {"continuation": continuation} if continuation else {"query": q, "params": _TYPE_VIDEO}
+    )
+    data = post("search", body)
 
     # Even a search with no results carries its result list's frame. Without one this is not "no
     # results" but a shape we do not know (YouTube moved, or a block page in JSON) — say so.
-    if not isinstance(data, dict) or not _RESULT_FRAMES & data.keys():
+    if not _RESULT_FRAMES & data.keys():
         raise ScrapeError("InnerTube returned an unexpected shape")
     items: list[dict] = []
     _collect_videos(data, items, set())

backend/requirements.lock

@@ -6,9 +6,10 @@
 # bumped in place instead of a full regeneration, which would move every other package too — then
 # `pip install -r requirements.lock && pip check` must pass. In place so far: urllib3 2.7.0 -> 2.8.0 (PYSEC-2026-4175/4176/4177); yt-dlp 2026.7.4 -> 2026.8.19
 # (it marks the clients that need a stream PO token, so the downloader stops fetching into a 403);
-# certifi 2026.7.22 -> 2026.10.19 (GHSA-6q48-6c7w-9gw2); brotli 1.2.0 -> 1.2.1 (PYSEC-2026-4322).
+# certifi 2026.7.22 -> 2026.10.19 (GHSA-6q48-6c7w-9gw2); brotli 1.2.0 -> 1.2.1 (PYSEC-2026-4322);
+# Authlib 1.7.2 -> 1.9.1 (CVE-2026-96760, CVE-2026-114616); joserfc 1.7.4 -> 1.7.6 (CVE-2026-119283, CVE-2026-119284).
 APScheduler==3.11.3
-Authlib==1.7.2
+Authlib==1.9.1
 Mako==1.4.1
 MarkupSafe==3.0.3
 PyYAML==6.0.3
@@ -38,7 +39,7 @@ httptools==0.8.0
 httpx==0.28.1
 idna==3.18
 itsdangerous==2.2.0
-joserfc==1.7.4
+joserfc==1.7.6
 markdown-it-py==4.2.0
 mdurl==0.1.2
 mutagen==1.48.1

backend/tests/fixtures/innertube_next_continuation.json

@@ -0,0 +1,527 @@
+{
+ "onResponseReceivedEndpoints": [
+  {
+   "appendContinuationItemsAction": {
+    "continuationItems": [
+     {
+      "lockupViewModel": {
+       "contentImage": {
+        "thumbnailViewModel": {
+         "image": {
+          "sources": [
+           {
+            "url": "https://i.ytimg.com/vi/_HfdncCbMOE/hqdefault.jpg?sqp=-oaymwEiCKgBEF5IWvKriqkDFQgBFQAAAAAYASUAAMhCPQCAokN4AQ==&rs=AOn4CLARvB39pkdsiuUUQTsZjkhvbKrfcQ",
+            "width": 168,
+            "height": 94
+           },
+           {
+            "url": "https://i.ytimg.com/vi/_HfdncCbMOE/hqdefault.jpg?sqp=-oaymwEjCNACELwBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLB15aZU5-tzwYCEbNTnZK3UX6ZCzQ",
+            "width": 336,
+            "height": 188
+           }
+          ]
+         },
+         "overlays": [
+          {
+           "thumbnailBottomOverlayViewModel": {
+            "badges": [
+             {
+              "thumbnailBadgeViewModel": {
+               "text": "1:08:18",
+               "badgeStyle": "THUMBNAIL_OVERLAY_BADGE_STYLE_DEFAULT",
+               "animationActivationTargetId": "_HfdncCbMOE",
+               "animatedText": "Now playing",
+               "animationActivationEntitySelectorType": "THUMBNAIL_BADGE_ANIMATION_ENTITY_SELECTOR_TYPE_PLAYER_STATE"
+              }
+             }
+            ]
+           }
+          }
+         ]
+        }
+       },
+       "metadata": {
+        "lockupMetadataViewModel": {
+         "title": {
+          "content": "MIT 6.S191 (2025): Large Language Models (Liquid AI)"
+         },
+         "image": {
+          "decoratedAvatarViewModel": {
+           "avatar": {
+            "avatarViewModel": {
+             "image": {
+              "sources": [
+               {
+                "url": "https://yt3.ggpht.com/ytc/AIdro_k517G0Dt8QgsF86GKzYkG3Rs8jSGCiYGJw04lx4_1KXQ=s68-c-k-c0x00ffffff-no-rj",
+                "width": 68,
+                "height": 68
+               }
+              ]
+             },
+             "avatarImageSize": "AVATAR_SIZE_M"
+            }
+           },
+           "a11yLabel": "Go to channel Alexander Amini",
+           "rendererContext": {
+            "commandContext": {
+             "onTap": {
+              "innertubeCommand": {
+               "browseEndpoint": {
+                "browseId": "UCtslD4DGH6PKyG_1gFAX7sg"
+               }
+              }
+             }
+            }
+           }
+          }
+         },
+         "metadata": {
+          "contentMetadataViewModel": {
+           "metadataRows": [
+            {
+             "metadataParts": [
+              {
+               "text": {
+                "content": "Alexander Amini"
+               }
+              }
+             ]
+            },
+            {
+             "metadataParts": [
+              {
+               "text": {
+                "content": "62K"
+               },
+               "accessibilityLabel": "62 thousand views",
+               "leadingIcon": {
+                "name": "PLAY_ARROW_OUTLINED",
+                "height": 12,
+                "width": 12,
+                "marginEndToken": {
+                 "spacing": 2
+                }
+               }
+              },
+              {
+               "text": {
+                "content": "1y ago"
+               },
+               "accessibilityLabel": "1 year ago"
+              }
+             ]
+            }
+           ],
+           "delimiter": " "
+          }
+         }
+        }
+       },
+       "contentId": "_HfdncCbMOE",
+       "contentType": "LOCKUP_CONTENT_TYPE_VIDEO",
+       "themedPalette": {
+        "lightThemePalette": {
+         "baseBackground": 4294964720,
+         "raisedBackground": 4294964720,
+         "additiveBackground": 566850118,
+         "textPrimary": 4281800969,
+         "textSecondary": 4285876787,
+         "outline": 860759827,
+         "keyLight": 4292983720,
+         "collectionStack": 4291337092,
+         "invertedBackground": 4287578649,
+         "textPrimaryInverse": 4294964720,
+         "textDisabled": 2135828243,
+         "dropShadow": 432632390,
+         "cardOutline": 180974150,
+         "overlayBackground": 3426162953,
+         "overlayTextPrimary": 4294964720,
+         "solidWash": 4283311891,
+         "solidRim": 4281800969,
+         "overlaySolidWash": 4294699488,
+         "overlaySolidRim": 4294964720,
+         "tonalWash": 2583688688,
+         "tonalRim": 202310912,
+         "overlayTonalWash": 436205040,
+         "overlayTonalRim": 436205040,
+         "outlineRim": 1280190227,
+         "overlayOutlineRim": 871618504,
+         "solidWashInverse": 4294170568,
+         "solidRimInverse": 2147215840,
+         "tonalWashInverse": 654308848,
+         "tonalRimInverse": 654043616,
+         "outlineRimInverse": 654308848,
+         "solidBackground": 4283311891,
+         "solidBackgroundInverse": 4291337092,
+         "tonalBackground": 868785028,
+         "tonalBackgroundInverse": 435410888,
+         "outlineInverse": 872147424,
+         "directionalLightStopPrimary": 4294699488,
+         "directionalLightStopSecondary": 4294964720,
+         "primary": 4279174400,
+         "filledStateLayer": 4281800969,
+         "tonalTouchLight": 4294964720,
+         "tonalHoverLight": 3439061472,
+         "tonalStateLayer": 420414720,
+         "overlayDisabledContainer": 871618504,
+         "overlayTonalTouchLight": 1291577824,
+         "overlayTonalHoverLight": 1291577824,
+         "overlayTonalStateLayer": 436205040,
+         "disabledContainer": 420414720,
+         "filledTouchLight": 4285876787,
+         "filledHoverLight": 4284627235,
+         "onOverlayDisabledContainer": 2583688688,
+         "overlayTonalContainer": 2583423456,
+         "overlayOutline": 872412656,
+         "onFilledContainer": 4294964720,
+         "filledContainer": 4280027906,
+         "tonalContainer": 641145097,
+         "overlayPrimary": 4294964720,
+         "onOverlayFilledContainer": 4279174400,
+         "overlayFilledTouchLight": 4294964720,
+         "overlayFilledHoverLight": 4294699488,
+         "overlayFilledStateLayer": 4292983720,
+         "overlayFilledContainer": 4294170568,
+         "onDisabledContainer": 1712260352,
+         "temporaryOutline": 860759827
+        },
+        "darkThemePalette": {
+         "baseBackground": 4280027906,
+         "raisedBackground": 4281800969,
+         "additiveBackground": 734622278,
+         "textPrimary": 4294699488,
+         "textSecondary": 4292983720,
+         "outline": 1072945096,
+         "keyLight": 4284627235,
+         "collectionStack": 4285876787,
+         "invertedBackground": 4293107837,
+         "textPrimaryInverse": 4280027906,
+         "textDisabled": 2146686920,
+         "dropShadow": 432632390,
+         "cardOutline": 180974150,
+         "overlayBackground": 3426162953,
+         "overlayTextPrimary": 4294964720,
+         "solidWash": 4294699488,
+         "solidRim": 4294964720,
+         "overlaySolidWash": 4294699488,
+         "overlaySolidRim": 4294964720,
+         "tonalWash": 217307080,
+         "tonalRim": 218101232,
+         "overlayTonalWash": 436205040,
+         "overlayTonalRim": 436205040,
+         "outlineRim": 871618504,
+         "overlayOutlineRim": 871618504,
+         "solidWashInverse": 4285876787,
+         "solidRimInverse": 871618504,
+         "tonalWashInverse": 872412656,
+         "tonalRimInverse": 870431656,
+         "outlineRimInverse": 1291843056,
+         "solidBackground": 4291337092,
+         "solidBackgroundInverse": 4283311891,
+         "tonalBackground": 435410888,
+         "tonalBackgroundInverse": 868785028,
+         "outlineInverse": 860759827,
+         "directionalLightStopPrimary": 4281800969,
+         "directionalLightStopSecondary": 4280027906,
+         "primary": 4294964720,
+         "filledStateLayer": 4292983720,
+         "tonalTouchLight": 1073474016,
+         "tonalHoverLight": 654043616,
+         "tonalStateLayer": 436205040,
+         "overlayDisabledContainer": 871618504,
+         "overlayTonalTouchLight": 1291577824,
+         "overlayTonalHoverLight": 1291577824,
+         "overlayTonalStateLayer": 436205040,
+         "disabledContainer": 436205040,
+         "filledTouchLight": 4294964720,
+         "filledHoverLight": 4294699488,
+         "onOverlayDisabledContainer": 2583688688,
+         "overlayTonalContainer": 2583423456,
+         "overlayOutline": 872412656,
+         "onFilledContainer": 4279174400,
+         "filledContainer": 4294170568,
+         "tonalContainer": 435410888,
+         "overlayPrimary": 4294964720,
+         "onOverlayFilledContainer": 4279174400,
+         "overlayFilledTouchLight": 4294964720,
+         "overlayFilledHoverLight": 4294699488,
+         "overlayFilledStateLayer": 4292983720,
+         "overlayFilledContainer": 4294170568,
+         "onDisabledContainer": 1728050672,
+         "temporaryOutline": 871618504
+        }
+       }
+      }
+     },
+     {
+      "lockupViewModel": {
+       "contentImage": {
+        "thumbnailViewModel": {
+         "image": {
+          "sources": [
+           {
+            "url": "https://i.ytimg.com/vi/P7Hkh2zOGQ0/hqdefault.jpg?sqp=-oaymwEiCKgBEF5IWvKriqkDFQgBFQAAAAAYASUAAMhCPQCAokN4AQ==&rs=AOn4CLAHInNtMierSAgtrGl5rLSKc-vdzQ",
+            "width": 168,
+            "height": 94
+           },
+           {
+            "url": "https://i.ytimg.com/vi/P7Hkh2zOGQ0/hqdefault.jpg?sqp=-oaymwEjCNACELwBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLDXrm5g-rdjRIqqK309ImTdqpw4CA",
+            "width": 336,
+            "height": 188
+           }
+          ]
+         },
+         "overlays": [
+          {
+           "thumbnailBottomOverlayViewModel": {
+            "badges": [
+             {
+              "thumbnailBadgeViewModel": {
+               "text": "1:08:19",
+               "badgeStyle": "THUMBNAIL_OVERLAY_BADGE_STYLE_DEFAULT",
+               "animationActivationTargetId": "P7Hkh2zOGQ0",
+               "animatedText": "Now playing",
+               "animationActivationEntitySelectorType": "THUMBNAIL_BADGE_ANIMATION_ENTITY_SELECTOR_TYPE_PLAYER_STATE"
+              }
+             }
+            ]
+           }
+          }
+         ]
+        }
+       },
+       "metadata": {
+        "lockupMetadataViewModel": {
+         "title": {
+          "content": "MIT 6.S191 (2024): Google - Generative AI for Media"
+         },
+         "image": {
+          "decoratedAvatarViewModel": {
+           "avatar": {
+            "avatarViewModel": {
+             "image": {
+              "sources": [
+               {
+                "url": "https://yt3.ggpht.com/ytc/AIdro_k517G0Dt8QgsF86GKzYkG3Rs8jSGCiYGJw04lx4_1KXQ=s68-c-k-c0x00ffffff-no-rj",
+                "width": 68,
+                "height": 68
+               }
+              ]
+             },
+             "avatarImageSize": "AVATAR_SIZE_M"
+            }
+           },
+           "a11yLabel": "Go to channel Alexander Amini",
+           "rendererContext": {
+            "commandContext": {
+             "onTap": {
+              "innertubeCommand": {
+               "browseEndpoint": {
+                "browseId": "UCtslD4DGH6PKyG_1gFAX7sg"
+               }
+              }
+             }
+            }
+           }
+          }
+         },
+         "metadata": {
+          "contentMetadataViewModel": {
+           "metadataRows": [
+            {
+             "metadataParts": [
+              {
+               "text": {
+                "content": "Alexander Amini"
+               }
+              }
+             ]
+            },
+            {
+             "metadataParts": [
+              {
+               "text": {
+                "content": "49K"
+               },
+               "accessibilityLabel": "49 thousand views",
+               "leadingIcon": {
+                "name": "PLAY_ARROW_OUTLINED",
+                "height": 12,
+                "width": 12,
+                "marginEndToken": {
+                 "spacing": 2
+                }
+               }
+              },
+              {
+               "text": {
+                "content": "2y ago"
+               },
+               "accessibilityLabel": "2 years ago"
+              }
+             ]
+            }
+           ],
+           "delimiter": " "
+          }
+         }
+        }
+       },
+       "contentId": "P7Hkh2zOGQ0",
+       "contentType": "LOCKUP_CONTENT_TYPE_VIDEO",
+       "themedPalette": {
+        "lightThemePalette": {
+         "baseBackground": 4293981951,
+         "raisedBackground": 4293981951,
+         "additiveBackground": 558201801,
+         "textPrimary": 4278655801,
+         "textSecondary": 4280831104,
+         "outline": 856631890,
+         "keyLight": 4288855783,
+         "collectionStack": 4286094803,
+         "invertedBackground": 4279847311,
+         "textPrimaryInverse": 4293981951,
+         "textDisabled": 2131700306,
+         "dropShadow": 423984073,
+         "cardOutline": 172325833,
+         "overlayBackground": 3423017785,
+         "overlayTextPrimary": 4293981951,
+         "solidWash": 4279183954,
+         "solidRim": 4278655801,
+         "overlaySolidWash": 4292864764,
+         "overlaySolidRim": 4293981951,
+         "tonalWash": 2582705919,
+         "tonalRim": 201328143,
+         "overlayTonalWash": 435222271,
+         "overlayTonalRim": 435222271,
+         "outlineRim": 1276062290,
+         "overlayOutlineRim": 868669942,
+         "solidWashInverse": 4291222006,
+         "solidRimInverse": 2145381116,
+         "tonalWashInverse": 653326079,
+         "tonalRimInverse": 652208892,
+         "outlineRimInverse": 653326079,
+         "solidBackground": 4279183954,
+         "solidBackgroundInverse": 4286094803,
+         "tonalBackground": 863542739,
+         "tonalBackgroundInverse": 432462326,
+         "outlineInverse": 870312700,
+         "directionalLightStopPrimary": 4292864764,
+         "directionalLightStopSecondary": 4293981951,
+         "primary": 4278191631,
+         "filledStateLayer": 4278655801,
+         "tonalTouchLight": 4293981951,
+         "tonalHoverLight": 3437226748,
+         "tonalStateLayer": 419431951,
+         "overlayDisabledContainer": 868669942,
+         "overlayTonalTouchLight": 1289743100,
+         "overlayTonalHoverLight": 1289743100,
+         "overlayTonalStateLayer": 435222271,
+         "disabledContainer": 419431951,
+         "filledTouchLight": 4280831104,
+         "filledHoverLight": 4280040297,
+         "onOverlayDisabledContainer": 2582705919,
+         "overlayTonalContainer": 2581588732,
+         "overlayOutline": 871429887,
+         "onFilledContainer": 4293981951,
+         "filledContainer": 4278324509,
+         "tonalContainer": 637999929,
+         "overlayPrimary": 4293981951,
+         "onOverlayFilledContainer": 4278191631,
+         "overlayFilledTouchLight": 4293981951,
+         "overlayFilledHoverLight": 4292864764,
+         "overlayFilledStateLayer": 4288855783,
+         "overlayFilledContainer": 4291222006,
+         "onDisabledContainer": 1711277583,
+         "temporaryOutline": 856631890
+        },
+        "darkThemePalette": {
+         "baseBackground": 4278324509,
+         "raisedBackground": 4278655801,
+         "additiveBackground": 725973961,
+         "textPrimary": 4292864764,
+         "textSecondary": 4288855783,
+         "outline": 1069996534,
+         "keyLight": 4280040297,
+         "collectionStack": 4280831104,
+         "invertedBackground": 4286359267,
+         "textPrimaryInverse": 4278324509,
+         "textDisabled": 2143738358,
+         "dropShadow": 423984073,
+         "cardOutline": 172325833,
+         "overlayBackground": 3423017785,
+         "overlayTextPrimary": 4293981951,
+         "solidWash": 4292864764,
+         "solidRim": 4293981951,
+         "overlaySolidWash": 4292864764,
+         "overlaySolidRim": 4293981951,
+         "tonalWash": 214358518,
+         "tonalRim": 217118463,
+         "overlayTonalWash": 435222271,
+         "overlayTonalRim": 435222271,
+         "outlineRim": 868669942,
+         "overlayOutlineRim": 868669942,
+         "solidWashInverse": 4280831104,
+         "solidRimInverse": 868669942,
+         "tonalWashInverse": 871429887,
+         "tonalRimInverse": 866303719,
+         "outlineRimInverse": 1290860287,
+         "solidBackground": 4286094803,
+         "solidBackgroundInverse": 4279183954,
+         "tonalBackground": 432462326,
+         "tonalBackgroundInverse": 863542739,
+         "outlineInverse": 856631890,
+         "directionalLightStopPrimary": 4278655801,
+         "directionalLightStopSecondary": 4278324509,
+         "primary": 4293981951,
+         "filledStateLayer": 4288855783,
+         "tonalTouchLight": 1071639292,
+         "tonalHoverLight": 652208892,
+         "tonalStateLayer": 435222271,
+         "overlayDisabledContainer": 868669942,
+         "overlayTonalTouchLight": 1289743100,
+         "overlayTonalHoverLight": 1289743100,
+         "overlayTonalStateLayer": 435222271,
+         "disabledContainer": 435222271,
+         "filledTouchLight": 4293981951,
+         "filledHoverLight": 4292864764,
+         "onOverlayDisabledContainer": 2582705919,
+         "overlayTonalContainer": 2581588732,
+         "overlayOutline": 871429887,
+         "onFilledContainer": 4278191631,
+         "filledContainer": 4291222006,
+         "tonalContainer": 432462326,
+         "overlayPrimary": 4293981951,
+         "onOverlayFilledContainer": 4278191631,
+         "overlayFilledTouchLight": 4293981951,
+         "overlayFilledHoverLight": 4292864764,
+         "overlayFilledStateLayer": 4288855783,
+         "overlayFilledContainer": 4291222006,
+         "onDisabledContainer": 1727067903,
+         "temporaryOutline": 868669942
+        }
+       }
+      }
+     },
+     {
+      "continuationItemRenderer": {
+       "trigger": "CONTINUATION_TRIGGER_ON_ITEM_SHOWN",
+       "continuationEndpoint": {
+        "commandMetadata": {
+         "webCommandMetadata": {
+          "sendPost": true,
+          "apiUrl": "/youtubei/v1/next"
+         }
+        },
+        "continuationCommand": {
+         "token": "CCgSDRILU2RUWkFNREtyTlkYACqPDE1nb0lodVQ4eG9EdXVLSUYyczZMNnd6NENBcjFDQW9EOGo0QUNnN0NQZ3NJbk1XcnZzbWo2Y2UyQVFvRDhqNEFDZzNDUGdvSW90N0czWnVCMy1KSENnUHlQZ0FLRGNJLUNnaTVfOGVUbjV5cTJSd0tBX0ktQUFvT3dqNExDSkQydWJfNXp2ZXZfUUVLQV9JLUFBb053ajRLQ1BXWjVQakt2cjZWU2dvRDhqNEFDZzNDUGdvSW9aTDd1OUtGdF85NkNnUHlQZ0FLRGNJLUNnaUh3N2FLMzd6YzVIZ0tBX0ktQUFvT3dqNExDUE94aHRQTWtfVzB1UUVLQV9JLUFBb093ajRMQ092eTBzaXNsSWZScGdFS0FfSS1BQW9Pd2o0TENKS1FxdHpBeE5lZHJBRUtBX0ktQUFvTndqNEtDTFdteWE2cHNPMkJPZ29EOGo0QUNnM0NQZ29JanYtdy1wQ3k1YVozQ2dQeVBnQUtEc0ktQ3dqMmtmVF9tYlB1XzRvQkNnUHlQZ0FLRHNJLUN3aVpuYWZjc0tQVmpZUUJDZ1B5UGdBS0RjSS1DZ2lxM3BxM3FyX2s0U0VLQV9JLUFBb053ajRLQ0phNXU5eVJvTmJOS0FvRDhqNEFDZzNDUGdvSXFMeWR3T1NhNGJkV0NnUHlQZ0FLRGNJLUNnakh3X2ZucktlSDdXUUtBX0ktQUFvTndqNEtDUG4xak1mcXg4QzJNQW9EOGo0QUNnM0NQZ29JeWRpdXV0VDQ3UHNhQ2dQeVBnQUtEc0ktQ3dqaDRleUUzTFAzdV93QkNnUHlQZ0FLRGNJLUNnaU5zcmptOXBENTJEOEtBX0ktQUFvTndqNEtDTExudjR5ZXg3U1dTUW9EOGo0QUNnM0NQZ29JNnZHODhaR1JpTWNnQ2dQeVBnQUtEc0ktQ3dpRF85S3Z5WS1hbThJQkNnUHlQZ0FLRHNJLUN3alppNmJYbWR6YWxZb0JDZ1B5UGdBS0RzSS1Dd2lkemJfS2dPdWN0YUFCQ2dQeVBnQUtEY0ktQ2dqMXktMjYyb2JQeFdNS0FfSS1BQW9Pd2o0TENPLUE4SWVaMUlESXJRRUtBX0ktQUFvTndqNEtDUHlZNDVhUzhkeWpJZ29EOGo0QUNnM0NQZ29Jb191aWtfSE05ZHdTQ2dQeVBnQUtEc0ktQ3dqaTBiemlrdnpBbkxvQkNnUHlQZ0FLRHNJLUN3aW05cXI1eXNtTWlzOEJDZ1B5UGdBS0RjSS1DZ2k3M2V5NXlzQ1pzMG9LQV9JLUFBb093ajRMQ0xmT281WFU1X2JPbFFFS0FfSS1BQW9Od2o0S0NLTEVwYXlXOTliWkdnb0Q4ajRBQ2c3Q1Bnc0k2dWZSMnRPM3hLem9BUW9EOGo0QUNnN0NQZ3NJN2ZlZXZQRHV2WlRXQVFvRDhqNEFDZzNDUGdvSXFibS0zYXVBdDVWcUNnUHlQZ0FLRGNJLUNnaUc1UHpHZ082NG9nVVNLQUFDQkFZSUNnd09FQklVRmhnYUhCNGdJaVFtS0Nvc0xqQXlORFk0T2p3LVFFSkVSa2hLVEU0YUJBZ0FFQUVhQkFnQ0VBTWFCQWdFRUFVYUJBZ0dFQWNhQkFnSUVBa2FCQWdLRUFzYUJBZ01FQTBhQkFnT0VBOGFCQWdRRUJFYUJBZ1NFQk1hQkFnVUVCVWFCQWdXRUJjYUJBZ1lFQmthQkFnYUVCc2FCQWdjRUIwYUJBZ2VFQjhhQkFnZ0VDRWFCQWdpRUNNYUJBZ2tFQ1VhQkFnbUVDY2FCQWdvRUNrYUJBZ3FFQ3NhQkFnc0VDMGFCQWd1RUM4YUJBZ3dFREVhQkFneUVETWFCQWcwRURVYUJBZzJFRGNhQkFnNEVEa2FCQWc2RURzYUJBZzhFRDBhQkFnLUVEOGFCQWhBRUVFYUJBaENFRU1hQkFoRUVFVWFCQWhHRUVjYUJBaElFRWthQkFoS0VFc2FCQWhNRUUwYUJBaE9FRThxS0FBQ0JBWUlDZ3dPRUJJVUZoZ2FIQjRnSWlRbUtDb3NMakF5TkRZNE9qdy1RRUpFUmtoS1RFNGoPd2F0Y2gtbmV4dC1mZWVk",
+         "request": "CONTINUATION_REQUEST_TYPE_WATCH_NEXT"
+        }
+       }
+      }
+     }
+    ]
+   }
+  }
+ ]
+}

backend/tests/fixtures/innertube_next_first.json

@@ -0,0 +1,805 @@
+{
+ "contents": {
+  "twoColumnWatchNextResults": {
+   "secondaryResults": {
+    "secondaryResults": {
+     "results": [
+      {
+       "lockupViewModel": {
+        "contentImage": {
+         "thumbnailViewModel": {
+          "image": {
+           "sources": [
+            {
+             "url": "https://i.ytimg.com/vi/to-lHJfK4pw/hqdefault.jpg?sqp=-oaymwEiCKgBEF5IWvKriqkDFQgBFQAAAAAYASUAAMhCPQCAokN4AQ==&rs=AOn4CLBKP_oFChvoqvwVrKAy_PG9bn2_AA",
+             "width": 168,
+             "height": 94
+            },
+            {
+             "url": "https://i.ytimg.com/vi/to-lHJfK4pw/hqdefault.jpg?sqp=-oaymwEjCNACELwBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLDyH3Z8DJhXMmFJ5eKEWMufk7ql9g",
+             "width": 336,
+             "height": 188
+            }
+           ]
+          },
+          "overlays": [
+           {
+            "thumbnailBottomOverlayViewModel": {
+             "badges": [
+              {
+               "thumbnailBadgeViewModel": {
+                "text": "1:02:00",
+                "badgeStyle": "THUMBNAIL_OVERLAY_BADGE_STYLE_DEFAULT",
+                "animationActivationTargetId": "to-lHJfK4pw",
+                "animatedText": "Now playing",
+                "animationActivationEntitySelectorType": "THUMBNAIL_BADGE_ANIMATION_ENTITY_SELECTOR_TYPE_PLAYER_STATE"
+               }
+              }
+             ]
+            }
+           }
+          ]
+         }
+        },
+        "metadata": {
+         "lockupMetadataViewModel": {
+          "title": {
+           "content": "MIT 6.S191 (2025): Reinforcement Learning"
+          },
+          "image": {
+           "decoratedAvatarViewModel": {
+            "avatar": {
+             "avatarViewModel": {
+              "image": {
+               "sources": [
+                {
+                 "url": "https://yt3.ggpht.com/ytc/AIdro_k517G0Dt8QgsF86GKzYkG3Rs8jSGCiYGJw04lx4_1KXQ=s68-c-k-c0x00ffffff-no-rj",
+                 "width": 68,
+                 "height": 68
+                }
+               ]
+              },
+              "avatarImageSize": "AVATAR_SIZE_M"
+             }
+            },
+            "a11yLabel": "Go to channel Alexander Amini",
+            "rendererContext": {
+             "commandContext": {
+              "onTap": {
+               "innertubeCommand": {
+                "browseEndpoint": {
+                 "browseId": "UCtslD4DGH6PKyG_1gFAX7sg"
+                }
+               }
+              }
+             }
+            }
+           }
+          },
+          "metadata": {
+           "contentMetadataViewModel": {
+            "metadataRows": [
+             {
+              "metadataParts": [
+               {
+                "text": {
+                 "content": "Alexander Amini"
+                }
+               }
+              ]
+             },
+             {
+              "metadataParts": [
+               {
+                "text": {
+                 "content": "128K"
+                },
+                "accessibilityLabel": "128 thousand views",
+                "leadingIcon": {
+                 "name": "PLAY_ARROW_OUTLINED",
+                 "height": 12,
+                 "width": 12,
+                 "marginEndToken": {
+                  "spacing": 2
+                 }
+                }
+               },
+               {
+                "text": {
+                 "content": "1y ago"
+                },
+                "accessibilityLabel": "1 year ago"
+               }
+              ]
+             }
+            ],
+            "delimiter": " "
+           }
+          }
+         }
+        },
+        "contentId": "to-lHJfK4pw",
+        "contentType": "LOCKUP_CONTENT_TYPE_VIDEO",
+        "themedPalette": {
+         "lightThemePalette": {
+          "baseBackground": 4293981439,
+          "raisedBackground": 4293981439,
+          "additiveBackground": 558196425,
+          "textPrimary": 4278850870,
+          "textSecondary": 4282009454,
+          "outline": 857088843,
+          "keyLight": 4289509597,
+          "collectionStack": 4287338944,
+          "invertedBackground": 4279842703,
+          "textPrimaryInverse": 4293981439,
+          "textDisabled": 2132157259,
+          "dropShadow": 423978697,
+          "cardOutline": 172320457,
+          "overlayBackground": 3423212854,
+          "overlayTextPrimary": 4293981439,
+          "solidWash": 4279640907,
+          "solidRim": 4278850870,
+          "overlaySolidWash": 4292929530,
+          "overlaySolidRim": 4293981439,
+          "tonalWash": 2582705407,
+          "tonalRim": 201327631,
+          "overlayTonalWash": 435221759,
+          "overlayTonalRim": 435221759,
+          "outlineRim": 1276519243,
+          "overlayOutlineRim": 868930802,
+          "solidWashInverse": 4291482866,
+          "solidRimInverse": 2145445882,
+          "tonalWashInverse": 653325567,
+          "tonalRimInverse": 652273658,
+          "outlineRimInverse": 653325567,
+          "solidBackground": 4279640907,
+          "solidBackgroundInverse": 4287338944,
+          "tonalBackground": 864786880,
+          "tonalBackgroundInverse": 432723186,
+          "outlineInverse": 870377466,
+          "directionalLightStopPrimary": 4292929530,
+          "directionalLightStopSecondary": 4293981439,
+          "primary": 4278191119,
+          "filledStateLayer": 4278850870,
+          "tonalTouchLight": 4293981439,
+          "tonalHoverLight": 3437291514,
+          "tonalStateLayer": 419431439,
+          "overlayDisabledContainer": 868930802,
+          "overlayTonalTouchLight": 1289807866,
+          "overlayTonalHoverLight": 1289807866,
+          "overlayTonalStateLayer": 435221759,
+          "disabledContainer": 419431439,
+          "filledTouchLight": 4282009454,
+          "filledHoverLight": 4280825181,
+          "onOverlayDisabledContainer": 2582705407,
+          "overlayTonalContainer": 2581653498,
+          "overlayOutline": 871429375,
+          "onFilledContainer": 4293981439,
+          "filledContainer": 4278323484,
+          "tonalContainer": 638194998,
+          "overlayPrimary": 4293981439,
+          "onOverlayFilledContainer": 4278191119,
+          "overlayFilledTouchLight": 4293981439,
+          "overlayFilledHoverLight": 4292929530,
+          "overlayFilledStateLayer": 4289509597,
+          "overlayFilledContainer": 4291482866,
+          "onDisabledContainer": 1711277071,
+          "temporaryOutline": 857088843
+         },
+         "darkThemePalette": {
+          "baseBackground": 4278323484,
+          "raisedBackground": 4278850870,
+          "additiveBackground": 725968585,
+          "textPrimary": 4292929530,
+          "textSecondary": 4289509597,
+          "outline": 1070257394,
+          "keyLight": 4280825181,
+          "collectionStack": 4282009454,
+          "invertedBackground": 4286355427,
+          "textPrimaryInverse": 4278323484,
+          "textDisabled": 2143999218,
+          "dropShadow": 423978697,
+          "cardOutline": 172320457,
+          "overlayBackground": 3423212854,
+          "overlayTextPrimary": 4293981439,
+          "solidWash": 4292929530,
+          "solidRim": 4293981439,
+          "overlaySolidWash": 4292929530,
+          "overlaySolidRim": 4293981439,
+          "tonalWash": 214619378,
+          "tonalRim": 217117951,
+          "overlayTonalWash": 435221759,
+          "overlayTonalRim": 435221759,
+          "outlineRim": 868930802,
+          "overlayOutlineRim": 868930802,
+          "solidWashInverse": 4282009454,
+          "solidRimInverse": 868930802,
+          "tonalWashInverse": 871429375,
+          "tonalRimInverse": 866957533,
+          "outlineRimInverse": 1290859775,
+          "solidBackground": 4287338944,
+          "solidBackgroundInverse": 4279640907,
+          "tonalBackground": 432723186,
+          "tonalBackgroundInverse": 864786880,
+          "outlineInverse": 857088843,
+          "directionalLightStopPrimary": 4278850870,
+          "directionalLightStopSecondary": 4278323484,
+          "primary": 4293981439,
+          "filledStateLayer": 4289509597,
+          "tonalTouchLight": 1071704058,
+          "tonalHoverLight": 652273658,
+          "tonalStateLayer": 435221759,
+          "overlayDisabledContainer": 868930802,
+          "overlayTonalTouchLight": 1289807866,
+          "overlayTonalHoverLight": 1289807866,
+          "overlayTonalStateLayer": 435221759,
+          "disabledContainer": 435221759,
+          "filledTouchLight": 4293981439,
+          "filledHoverLight": 4292929530,
+          "onOverlayDisabledContainer": 2582705407,
+          "overlayTonalContainer": 2581653498,
+          "overlayOutline": 871429375,
+          "onFilledContainer": 4278191119,
+          "filledContainer": 4291482866,
+          "tonalContainer": 432723186,
+          "overlayPrimary": 4293981439,
+          "onOverlayFilledContainer": 4278191119,
+          "overlayFilledTouchLight": 4293981439,
+          "overlayFilledHoverLight": 4292929530,
+          "overlayFilledStateLayer": 4289509597,
+          "overlayFilledContainer": 4291482866,
+          "onDisabledContainer": 1727067391,
+          "temporaryOutline": 868930802
+         }
+        }
+       }
+      },
+      {
+       "lockupViewModel": {
+        "contentImage": {
+         "thumbnailViewModel": {
+          "image": {
+           "sources": [
+            {
+             "url": "https://i.ytimg.com/vi/R8V8CbuxryI/hqdefault.jpg?sqp=-oaymwEiCKgBEF5IWvKriqkDFQgBFQAAAAAYASUAAMhCPQCAokN4AQ==&rs=AOn4CLDqXMjrpgDyQKHL2lWrxczwxKoefw",
+             "width": 168,
+             "height": 94
+            },
+            {
+             "url": "https://i.ytimg.com/vi/R8V8CbuxryI/hqdefault.jpg?sqp=-oaymwEjCNACELwBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLB7JX9Z238s6DGqIS5-fhcEIkUxKw",
+             "width": 336,
+             "height": 188
+            }
+           ]
+          },
+          "overlays": [
+           {
+            "thumbnailBottomOverlayViewModel": {
+             "badges": [
+              {
+               "thumbnailBadgeViewModel": {
+                "text": "49:36",
+                "badgeStyle": "THUMBNAIL_OVERLAY_BADGE_STYLE_DEFAULT",
+                "animationActivationTargetId": "R8V8CbuxryI",
+                "animatedText": "Now playing",
+                "animationActivationEntitySelectorType": "THUMBNAIL_BADGE_ANIMATION_ENTITY_SELECTOR_TYPE_PLAYER_STATE"
+               }
+              }
+             ]
+            }
+           }
+          ]
+         }
+        },
+        "metadata": {
+         "lockupMetadataViewModel": {
+          "title": {
+           "content": "MIT 6.S191: Deep Generative Modeling"
+          },
+          "image": {
+           "decoratedAvatarViewModel": {
+            "avatar": {
+             "avatarViewModel": {
+              "image": {
+               "sources": [
+                {
+                 "url": "https://yt3.ggpht.com/ytc/AIdro_k517G0Dt8QgsF86GKzYkG3Rs8jSGCiYGJw04lx4_1KXQ=s68-c-k-c0x00ffffff-no-rj",
+                 "width": 68,
+                 "height": 68
+                }
+               ]
+              },
+              "avatarImageSize": "AVATAR_SIZE_M"
+             }
+            },
+            "a11yLabel": "Go to channel Alexander Amini",
+            "rendererContext": {
+             "commandContext": {
+              "onTap": {
+               "innertubeCommand": {
+                "browseEndpoint": {
+                 "browseId": "UCtslD4DGH6PKyG_1gFAX7sg"
+                }
+               }
+              }
+             }
+            }
+           }
+          },
+          "metadata": {
+           "contentMetadataViewModel": {
+            "metadataRows": [
+             {
+              "metadataParts": [
+               {
+                "text": {
+                 "content": "Alexander Amini"
+                }
+               }
+              ]
+             },
+             {
+              "metadataParts": [
+               {
+                "text": {
+                 "content": "38K"
+                },
+                "accessibilityLabel": "38 thousand views",
+                "leadingIcon": {
+                 "name": "PLAY_ARROW_OUTLINED",
+                 "height": 12,
+                 "width": 12,
+                 "marginEndToken": {
+                  "spacing": 2
+                 }
+                }
+               },
+               {
+                "text": {
+                 "content": "6mo ago"
+                },
+                "accessibilityLabel": "6 months ago"
+               }
+              ]
+             }
+            ],
+            "delimiter": " "
+           }
+          }
+         }
+        },
+        "contentId": "R8V8CbuxryI",
+        "contentType": "LOCKUP_CONTENT_TYPE_VIDEO",
+        "themedPalette": {
+         "lightThemePalette": {
+          "baseBackground": 4294965488,
+          "raisedBackground": 4294965488,
+          "additiveBackground": 566856261,
+          "textPrimary": 4281737226,
+          "textSecondary": 4285420858,
+          "outline": 860565782,
+          "keyLight": 4292724140,
+          "collectionStack": 4290815883,
+          "invertedBackground": 4287583769,
+          "textPrimaryInverse": 4294965488,
+          "textDisabled": 2135634198,
+          "dropShadow": 432638533,
+          "cardOutline": 180980293,
+          "overlayBackground": 3426099210,
+          "overlayTextPrimary": 4294965488,
+          "solidWash": 4283117846,
+          "solidRim": 4281737226,
+          "overlaySolidWash": 4294635232,
+          "overlaySolidRim": 4294965488,
+          "tonalWash": 2583689456,
+          "tonalRim": 202311680,
+          "overlayTonalWash": 436205808,
+          "overlayTonalRim": 436205808,
+          "outlineRim": 1279996182,
+          "overlayOutlineRim": 871554762,
+          "solidWashInverse": 4294106826,
+          "solidRimInverse": 2147151584,
+          "tonalWashInverse": 654309616,
+          "tonalRimInverse": 653979360,
+          "outlineRimInverse": 654309616,
+          "solidBackground": 4283117846,
+          "solidBackgroundInverse": 4290815883,
+          "tonalBackground": 868263819,
+          "tonalBackgroundInverse": 435347146,
+          "outlineInverse": 872083168,
+          "directionalLightStopPrimary": 4294635232,
+          "directionalLightStopSecondary": 4294965488,
+          "primary": 4279175168,
+          "filledStateLayer": 4281737226,
+          "tonalTouchLight": 4294965488,
+          "tonalHoverLight": 3438997216,
+          "tonalStateLayer": 420415488,
+          "overlayDisabledContainer": 871554762,
+          "overlayTonalTouchLight": 1291513568,
+          "overlayTonalHoverLight": 1291513568,
+          "overlayTonalStateLayer": 436205808,
+          "disabledContainer": 420415488,
+          "filledTouchLight": 4285420858,
+          "filledHoverLight": 4284302120,
+          "onOverlayDisabledContainer": 2583689456,
+          "overlayTonalContainer": 2583359200,
+          "overlayOutline": 872413424,
+          "onFilledContainer": 4294965488,
+          "filledContainer": 4280029186,
+          "tonalContainer": 641081354,
+          "overlayPrimary": 4294965488,
+          "onOverlayFilledContainer": 4279175168,
+          "overlayFilledTouchLight": 4294965488,
+          "overlayFilledHoverLight": 4294635232,
+          "overlayFilledStateLayer": 4292724140,
+          "overlayFilledContainer": 4294106826,
+          "onDisabledContainer": 1712261120,
+          "temporaryOutline": 860565782
+         },
+         "darkThemePalette": {
+          "baseBackground": 4280029186,
+          "raisedBackground": 4281737226,
+          "additiveBackground": 734628421,
+          "textPrimary": 4294635232,
+          "textSecondary": 4292724140,
+          "outline": 1072881354,
+          "keyLight": 4284302120,
+          "collectionStack": 4285420858,
+          "invertedBackground": 4293112700,
+          "textPrimaryInverse": 4280029186,
+          "textDisabled": 2146623178,
+          "dropShadow": 432638533,
+          "cardOutline": 180980293,
+          "overlayBackground": 3426099210,
+          "overlayTextPrimary": 4294965488,
+          "solidWash": 4294635232,
+          "solidRim": 4294965488,
+          "overlaySolidWash": 4294635232,
+          "overlaySolidRim": 4294965488,
+          "tonalWash": 217243338,
+          "tonalRim": 218102000,
+          "overlayTonalWash": 436205808,
+          "overlayTonalRim": 436205808,
+          "outlineRim": 871554762,
+          "overlayOutlineRim": 871554762,
+          "solidWashInverse": 4285420858,
+          "solidRimInverse": 871554762,
+          "tonalWashInverse": 872413424,
+          "tonalRimInverse": 870172076,
+          "outlineRimInverse": 1291843824,
+          "solidBackground": 4290815883,
+          "solidBackgroundInverse": 4283117846,
+          "tonalBackground": 435347146,
+          "tonalBackgroundInverse": 868263819,
+          "outlineInverse": 860565782,
+          "directionalLightStopPrimary": 4281737226,
+          "directionalLightStopSecondary": 4280029186,
+          "primary": 4294965488,
+          "filledStateLayer": 4292724140,
+          "tonalTouchLight": 1073409760,
+          "tonalHoverLight": 653979360,
+          "tonalStateLayer": 436205808,
+          "overlayDisabledContainer": 871554762,
+          "overlayTonalTouchLight": 1291513568,
+          "overlayTonalHoverLight": 1291513568,
+          "overlayTonalStateLayer": 436205808,
+          "disabledContainer": 436205808,
+          "filledTouchLight": 4294965488,
+          "filledHoverLight": 4294635232,
+          "onOverlayDisabledContainer": 2583689456,
+          "overlayTonalContainer": 2583359200,
+          "overlayOutline": 872413424,
+          "onFilledContainer": 4279175168,
+          "filledContainer": 4294106826,
+          "tonalContainer": 435347146,
+          "overlayPrimary": 4294965488,
+          "onOverlayFilledContainer": 4279175168,
+          "overlayFilledTouchLight": 4294965488,
+          "overlayFilledHoverLight": 4294635232,
+          "overlayFilledStateLayer": 4292724140,
+          "overlayFilledContainer": 4294106826,
+          "onDisabledContainer": 1728051440,
+          "temporaryOutline": 871554762
+         }
+        }
+       }
+      },
+      {
+       "lockupViewModel": {
+        "contentImage": {
+         "thumbnailViewModel": {
+          "image": {
+           "sources": [
+            {
+             "url": "https://i.ytimg.com/vi/HLKo4fJx_7k/hqdefault.jpg?sqp=-oaymwEiCKgBEF5IWvKriqkDFQgBFQAAAAAYASUAAMhCPQCAokN4AQ==&rs=AOn4CLAQcvMQEX1ny9Z8qu2mIMogpEMaVA",
+             "width": 168,
+             "height": 94
+            },
+            {
+             "url": "https://i.ytimg.com/vi/HLKo4fJx_7k/hqdefault.jpg?sqp=-oaymwEjCNACELwBSFryq4qpAxUIARUAAAAAGAElAADIQj0AgKJDeAE=&rs=AOn4CLCkoPSkHifs5ifpWXXcb96XG_Ly1w",
+             "width": 336,
+             "height": 188
+            }
+           ]
+          },
+          "overlays": [
+           {
+            "thumbnailBottomOverlayViewModel": {
+             "badges": [
+              {
+               "thumbnailBadgeViewModel": {
+                "text": "47:36",
+                "badgeStyle": "THUMBNAIL_OVERLAY_BADGE_STYLE_DEFAULT",
+                "animationActivationTargetId": "HLKo4fJx_7k",
+                "animatedText": "Now playing",
+                "animationActivationEntitySelectorType": "THUMBNAIL_BADGE_ANIMATION_ENTITY_SELECTOR_TYPE_PLAYER_STATE"
+               }
+              }
+             ]
+            }
+           }
+          ]
+         }
+        },
+        "metadata": {
+         "lockupMetadataViewModel": {
+          "title": {
+           "content": "MIT 6.S191 (2025): Language Models and New Frontiers"
+          },
+          "image": {
+           "decoratedAvatarViewModel": {
+            "avatar": {
+             "avatarViewModel": {
+              "image": {
+               "sources": [
+                {
+                 "url": "https://yt3.ggpht.com/ytc/AIdro_k517G0Dt8QgsF86GKzYkG3Rs8jSGCiYGJw04lx4_1KXQ=s68-c-k-c0x00ffffff-no-rj",
+                 "width": 68,
+                 "height": 68
+                }
+               ]
+              },
+              "avatarImageSize": "AVATAR_SIZE_M"
+             }
+            },
+            "a11yLabel": "Go to channel Alexander Amini",
+            "rendererContext": {
+             "commandContext": {
+              "onTap": {
+               "innertubeCommand": {
+                "browseEndpoint": {
+                 "browseId": "UCtslD4DGH6PKyG_1gFAX7sg"
+                }
+               }
+              }
+             }
+            }
+           }
+          },
+          "metadata": {
+           "contentMetadataViewModel": {
+            "metadataRows": [
+             {
+              "metadataParts": [
+               {
+                "text": {
+                 "content": "Alexander Amini"
+                }
+               }
+              ]
+             },
+             {
+              "metadataParts": [
+               {
+                "text": {
+                 "content": "63K"
+                },
+                "accessibilityLabel": "63 thousand views",
+                "leadingIcon": {
+                 "name": "PLAY_ARROW_OUTLINED",
+                 "height": 12,
+                 "width": 12,
+                 "marginEndToken": {
+                  "spacing": 2
+                 }
+                }
+               },
+               {
+                "text": {
+                 "content": "1y ago"
+                },
+                "accessibilityLabel": "1 year ago"
+               }
+              ]
+             }
+            ],
+            "delimiter": " "
+           }
+          }
+         }
+        },
+        "contentId": "HLKo4fJx_7k",
+        "contentType": "LOCKUP_CONTENT_TYPE_VIDEO",
+        "themedPalette": {
+         "lightThemePalette": {
+          "baseBackground": 4294964208,
+          "raisedBackground": 4294964208,
+          "additiveBackground": 566847045,
+          "textPrimary": 4281734410,
+          "textSecondary": 4285417018,
+          "outline": 860561942,
+          "keyLight": 4292720812,
+          "collectionStack": 4290812043,
+          "invertedBackground": 4287575065,
+          "textPrimaryInverse": 4294964208,
+          "textDisabled": 2135630358,
+          "dropShadow": 432629317,
+          "cardOutline": 180971077,
+          "overlayBackground": 3426096394,
+          "overlayTextPrimary": 4294964208,
+          "solidWash": 4283114006,
+          "solidRim": 4281734410,
+          "overlaySolidWash": 4294633184,
+          "overlaySolidRim": 4294964208,
+          "tonalWash": 2583688176,
+          "tonalRim": 202310656,
+          "overlayTonalWash": 436204528,
+          "overlayTonalRim": 436204528,
+          "outlineRim": 1279992342,
+          "overlayOutlineRim": 871551946,
+          "solidWashInverse": 4294104010,
+          "solidRimInverse": 2147149536,
+          "tonalWashInverse": 654308336,
+          "tonalRimInverse": 653977312,
+          "outlineRimInverse": 654308336,
+          "solidBackground": 4283114006,
+          "solidBackgroundInverse": 4290812043,
+          "tonalBackground": 868259979,
+          "tonalBackgroundInverse": 435344330,
+          "outlineInverse": 872081120,
+          "directionalLightStopPrimary": 4294633184,
+          "directionalLightStopSecondary": 4294964208,
+          "primary": 4279174144,
+          "filledStateLayer": 4281734410,
+          "tonalTouchLight": 4294964208,
+          "tonalHoverLight": 3438995168,
+          "tonalStateLayer": 420414464,
+          "overlayDisabledContainer": 871551946,
+          "overlayTonalTouchLight": 1291511520,
+          "overlayTonalHoverLight": 1291511520,
+          "overlayTonalStateLayer": 436204528,
+          "disabledContainer": 420414464,
+          "filledTouchLight": 4285417018,
+          "filledHoverLight": 4284298280,
+          "onOverlayDisabledContainer": 2583688176,
+          "overlayTonalContainer": 2583357152,
+          "overlayOutline": 872412144,
+          "onFilledContainer": 4294964208,
+          "filledContainer": 4280027394,
+          "tonalContainer": 641078538,
+          "overlayPrimary": 4294964208,
+          "onOverlayFilledContainer": 4279174144,
+          "overlayFilledTouchLight": 4294964208,
+          "overlayFilledHoverLight": 4294633184,
+          "overlayFilledStateLayer": 4292720812,
+          "overlayFilledContainer": 4294104010,
+          "onDisabledContainer": 1712260096,
+          "temporaryOutline": 860561942
+         },
+         "darkThemePalette": {
+          "baseBackground": 4280027394,
+          "raisedBackground": 4281734410,
+          "additiveBackground": 734619205,
+          "textPrimary": 4294633184,
+          "textSecondary": 4292720812,
+          "outline": 1072878538,
+          "keyLight": 4284298280,
+          "collectionStack": 4285417018,
+          "invertedBackground": 4293105020,
+          "textPrimaryInverse": 4280027394,
+          "textDisabled": 2146620362,
+          "dropShadow": 432629317,
+          "cardOutline": 180971077,
+          "overlayBackground": 3426096394,
+          "overlayTextPrimary": 4294964208,
+          "solidWash": 4294633184,
+          "solidRim": 4294964208,
+          "overlaySolidWash": 4294633184,
+          "overlaySolidRim": 4294964208,
+          "tonalWash": 217240522,
+          "tonalRim": 218100720,
+          "overlayTonalWash": 436204528,
+          "overlayTonalRim": 436204528,
+          "outlineRim": 871551946,
+          "overlayOutlineRim": 871551946,
+          "solidWashInverse": 4285417018,
+          "solidRimInverse": 871551946,
+          "tonalWashInverse": 872412144,
+          "tonalRimInverse": 870168748,
+          "outlineRimInverse": 1291842544,
+          "solidBackground": 4290812043,
+          "solidBackgroundInverse": 4283114006,
+          "tonalBackground": 435344330,
+          "tonalBackgroundInverse": 868259979,
+          "outlineInverse": 860561942,
+          "directionalLightStopPrimary": 4281734410,
+          "directionalLightStopSecondary": 4280027394,
+          "primary": 4294964208,
+          "filledStateLayer": 4292720812,
+          "tonalTouchLight": 1073407712,
+          "tonalHoverLight": 653977312,
+          "tonalStateLayer": 436204528,
+          "overlayDisabledContainer": 871551946,
+          "overlayTonalTouchLight": 1291511520,
+          "overlayTonalHoverLight": 1291511520,
+          "overlayTonalStateLayer": 436204528,
+          "disabledContainer": 436204528,
+          "filledTouchLight": 4294964208,
+          "filledHoverLight": 4294633184,
+          "onOverlayDisabledContainer": 2583688176,
+          "overlayTonalContainer": 2583357152,
+          "overlayOutline": 872412144,
+          "onFilledContainer": 4279174144,
+          "filledContainer": 4294104010,
+          "tonalContainer": 435344330,
+          "overlayPrimary": 4294964208,
+          "onOverlayFilledContainer": 4279174144,
+          "overlayFilledTouchLight": 4294964208,
+          "overlayFilledHoverLight": 4294633184,
+          "overlayFilledStateLayer": 4292720812,
+          "overlayFilledContainer": 4294104010,
+          "onDisabledContainer": 1728050160,
+          "temporaryOutline": 871551946
+         }
+        }
+       }
+      },
+      {
+       "continuationItemRenderer": {
+        "trigger": "CONTINUATION_TRIGGER_ON_ITEM_SHOWN",
+        "continuationEndpoint": {
+         "commandMetadata": {
+          "webCommandMetadata": {
+           "sendPost": true,
+           "apiUrl": "/youtubei/v1/next"
+          }
+         },
+         "continuationCommand": {
+          "token": "CBQSDRILU2RUWkFNREtyTlkYACqXBk1nb0l5ZGl1dXRUNDdQc2EyczZMNnd5LUJBcTdCQW9EOGo0QUNnN0NQZ3NJbk1XcnZzbWo2Y2UyQVFvRDhqNEFDZzNDUGdvSW90N0czWnVCMy1KSENnUHlQZ0FLRGNJLUNnaTVfOGVUbjV5cTJSd0tBX0ktQUFvT3dqNExDSkQydWJfNXp2ZXZfUUVLQV9JLUFBb053ajRLQ1BXWjVQakt2cjZWU2dvRDhqNEFDZzNDUGdvSW9aTDd1OUtGdF85NkNnUHlQZ0FLRGNJLUNnaUh3N2FLMzd6YzVIZ0tBX0ktQUFvT3dqNExDUE94aHRQTWtfVzB1UUVLQV9JLUFBb093ajRMQ092eTBzaXNsSWZScGdFS0FfSS1BQW9Pd2o0TENKS1FxdHpBeE5lZHJBRUtBX0ktQUFvTndqNEtDTFdteWE2cHNPMkJPZ29EOGo0QUNnM0NQZ29JanYtdy1wQ3k1YVozQ2dQeVBnQUtEc0ktQ3dqMmtmVF9tYlB1XzRvQkNnUHlQZ0FLRHNJLUN3aVpuYWZjc0tQVmpZUUJDZ1B5UGdBS0RjSS1DZ2lxM3BxM3FyX2s0U0VLQV9JLUFBb053ajRLQ0phNXU5eVJvTmJOS0FvRDhqNEFDZzNDUGdvSXFMeWR3T1NhNGJkV0NnUHlQZ0FLRGNJLUNnakh3X2ZucktlSDdXUUtBX0ktQUFvTndqNEtDUG4xak1mcXg4QzJNQW9EOGo0QUNnM0NQZ29JeWRpdXV0VDQ3UHNhRWhRQUFnUUdDQW9NRGhBU0ZCWVlHaHdlSUNJa0pob0VDQUFRQVJvRUNBSVFBeG9FQ0FRUUJSb0VDQVlRQnhvRUNBZ1FDUm9FQ0FvUUN4b0VDQXdRRFJvRUNBNFFEeG9FQ0JBUUVSb0VDQklRRXhvRUNCUVFGUm9FQ0JZUUZ4b0VDQmdRR1JvRUNCb1FHeG9FQ0J3UUhSb0VDQjRRSHhvRUNDQVFJUm9FQ0NJUUl4b0VDQ1FRSlJvRUNDWVFKeW9VQUFJRUJnZ0tEQTRRRWhRV0dCb2NIaUFpSkNZag93YXRjaC1uZXh0LWZlZWQ%3D",
+          "request": "CONTINUATION_REQUEST_TYPE_WATCH_NEXT"
+         }
+        },
+        "button": {
+         "buttonRenderer": {
+          "style": "STYLE_SUGGESTIVE",
+          "size": "SIZE_DEFAULT",
+          "isDisabled": false,
+          "text": {
+           "runs": [
+            {
+             "text": "Show more"
+            }
+           ]
+          },
+          "command": {
+           "commandMetadata": {
+            "webCommandMetadata": {
+             "sendPost": true,
+             "apiUrl": "/youtubei/v1/next"
+            }
+           },
+           "continuationCommand": {
+            "token": "CBQSDRILU2RUWkFNREtyTlkYACqXBk1nb0l5ZGl1dXRUNDdQc2EyczZMNnd5LUJBcTdCQW9EOGo0QUNnN0NQZ3NJbk1XcnZzbWo2Y2UyQVFvRDhqNEFDZzNDUGdvSW90N0czWnVCMy1KSENnUHlQZ0FLRGNJLUNnaTVfOGVUbjV5cTJSd0tBX0ktQUFvT3dqNExDSkQydWJfNXp2ZXZfUUVLQV9JLUFBb053ajRLQ1BXWjVQakt2cjZWU2dvRDhqNEFDZzNDUGdvSW9aTDd1OUtGdF85NkNnUHlQZ0FLRGNJLUNnaUh3N2FLMzd6YzVIZ0tBX0ktQUFvT3dqNExDUE94aHRQTWtfVzB1UUVLQV9JLUFBb093ajRMQ092eTBzaXNsSWZScGdFS0FfSS1BQW9Pd2o0TENKS1FxdHpBeE5lZHJBRUtBX0ktQUFvTndqNEtDTFdteWE2cHNPMkJPZ29EOGo0QUNnM0NQZ29JanYtdy1wQ3k1YVozQ2dQeVBnQUtEc0ktQ3dqMmtmVF9tYlB1XzRvQkNnUHlQZ0FLRHNJLUN3aVpuYWZjc0tQVmpZUUJDZ1B5UGdBS0RjSS1DZ2lxM3BxM3FyX2s0U0VLQV9JLUFBb053ajRLQ0phNXU5eVJvTmJOS0FvRDhqNEFDZzNDUGdvSXFMeWR3T1NhNGJkV0NnUHlQZ0FLRGNJLUNnakh3X2ZucktlSDdXUUtBX0ktQUFvTndqNEtDUG4xak1mcXg4QzJNQW9EOGo0QUNnM0NQZ29JeWRpdXV0VDQ3UHNhRWhRQUFnUUdDQW9NRGhBU0ZCWVlHaHdlSUNJa0pob0VDQUFRQVJvRUNBSVFBeG9FQ0FRUUJSb0VDQVlRQnhvRUNBZ1FDUm9FQ0FvUUN4b0VDQXdRRFJvRUNBNFFEeG9FQ0JBUUVSb0VDQklRRXhvRUNCUVFGUm9FQ0JZUUZ4b0VDQmdRR1JvRUNCb1FHeG9FQ0J3UUhSb0VDQjRRSHhvRUNDQVFJUm9FQ0NJUUl4b0VDQ1FRSlJvRUNDWVFKeW9VQUFJRUJnZ0tEQTRRRWhRV0dCb2NIaUFpSkNZag93YXRjaC1uZXh0LWZlZWQ%3D",
+            "request": "CONTINUATION_REQUEST_TYPE_WATCH_NEXT"
+           }
+          }
+         }
+        }
+       }
+      }
+     ]
+    }
+   }
+  }
+ }
+}

backend/tests/refusal_sites.py

@@ -0,0 +1,738 @@
+"""Every refusal the backend can answer, read from its syntax tree: each `{"code": …, "reason": …}` detail,
+with every reason its code can be sent with.
+
+The frontend's contract (`i18n/backendIds.contract.test.ts`) runs this and requires a sentence for each
+code and reason in both languages. A scan that tries to follow every shape opens a silent gap with each one
+it learns, and following how a value flows through Python (variables, scopes, aliases, a dict changed in
+place) never closes. So the CODE keeps to a narrow form, and this reads a CLOSED list of it, reporting
+everything else, never guessing:
+
+- where a detail stands: where it is sent — `HTTPException`'s second argument or `detail=`, the `"detail"`
+  value of a `JSONResponse`'s content dict — through the arms of `a if c else b`, or as what a module-level
+  factory returns when every return of it is a detail and every reference to it is a call sent as one. A
+  detail held in a variable is not followed;
+- the code: one literal. A `**` spread, or a key that is not a literal, stands BEFORE a literal `code` and
+  `reason`, both of which the detail then carries: the later key wins, so no spread can change them;
+- a reason: a string literal (`None` sends none: the site counts as reasonless); both arms of
+  `a if c else b`; a function's local bound only by plain `x = …`; a module constant reached as `mod.NAME`;
+  a call's `Literal` return annotation;
+- a parameter typed with a `Literal` (basedpyright holds every value passed in), or a `str` one of a
+  module-level helper (`refused`, `not_found`), followed to every call, each of which must pass it by
+  position or by name; a parameter its body binds again is unread;
+- an attribute: `e.x` of the exception an `except C as e` catches, or of a parameter typed `C`, when a
+  method of `C` declares `self.x: <Literal>`;
+- a map lookup (`_SETTING_REASONS[exc.reason]`): the map's values, and its keys must be exactly what the
+  index can be.
+
+A name bound twice at module level, inside a module-level `if`/`try`/loop, named by a `global`, or imported
+from two places is not looked up; nor is a local a lambda or a comprehension binds, or one a `nonlocal` or
+`global` names. A module constant or map that anything stores into, deletes from or (a map) uses but by
+`map[k]` or a read method is unread. A reference named like a followed helper that the scan cannot resolve
+(`import app.x`, a relative import, an app module that does not bind it) is unread. Anything else is UNREAD,
+or an unread code, and the contract fails on it unless no screen shows that code. Stdlib only: it runs on
+the host, beside the frontend's tests (`python -I backend/tests/refusal_sites.py` → JSON).
+"""
+
+import ast
+import json
+import pathlib
+import sys
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+APP = pathlib.Path(__file__).resolve().parents[1] / "app"
+
+# Files whose `"code"` dicts are data, not refusals: a subtitle track's status payload, TMDB country codes.
+NOT_REFUSALS = {
+    "plex/subtitles.py": "a subtitle track's status payload (its own `code`)",
+    "plex/tmdb.py": "a production country's ISO code",
+}
+
+# What a map may be used by besides `map[k]`: a method that only reads it.
+READS = {"get", "items", "keys", "values"}
+
+Node = ast.AST
+FUNCS = (ast.FunctionDef, ast.AsyncFunctionDef)
+SCOPES = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda, ast.ClassDef)
+COMPREHENSIONS = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
+COMPOUND = (
+    ast.If,
+    ast.Try,
+    ast.TryStar,
+    ast.For,
+    ast.AsyncFor,
+    ast.While,
+    ast.With,
+    ast.AsyncWith,
+    ast.Match,
+)
+
+
+@dataclass
+class Res:
+    values: set[str] = field(default_factory=set)
+    unread: list[str] = field(default_factory=list)
+    none: bool = False  # an arm sends no reason
+
+    def __or__(self, other: "Res") -> "Res":
+        return Res(self.values | other.values, self.unread + other.unread, self.none or other.none)
+
+
+@dataclass
+class Module:
+    path: str  # relative to app/, posix
+    name: str  # dotted, `app.…`
+    tree: ast.Module
+    parents: dict[Node, Node]
+    # local name → (module, symbol or None for the module)
+    imports: dict[str, tuple[str, str | None]]
+    top: dict[str, Node]  # module-level bindings: def, class, or the assignment
+    ambiguous: set[
+        str
+    ]  # bound more than once, conditionally, by a `global`, or imported from two places
+    slots: set[int]  # the ids of the nodes sent as a detail
+
+
+def _own_scope(node: Node) -> Iterator[Node]:
+    """`node` and what it holds in its own scope: a nested def, class or lambda is itself, not its body."""
+    stack = [node]
+    while stack:
+        n = stack.pop()
+        yield n
+        if n is not node and isinstance(n, SCOPES):
+            continue
+        stack.extend(ast.iter_child_nodes(n))
+
+
+def _stored(target: Node) -> set[str]:
+    """The names an assignment target binds, not the ones it reads (`LABELS[k] = v` binds none)."""
+    return {
+        n.id for n in ast.walk(target) if isinstance(n, ast.Name) and isinstance(n.ctx, ast.Store)
+    }
+
+
+def _binds(node: Node) -> set[str]:
+    """The names one node binds in the scope it sits in."""
+    if isinstance(node, ast.Assign):
+        return set().union(*(_stored(t) for t in node.targets))
+    if isinstance(node, (ast.AnnAssign, ast.AugAssign, ast.For, ast.AsyncFor, ast.NamedExpr)):
+        return _stored(node.target)
+    if isinstance(node, (ast.With, ast.AsyncWith)):
+        return set().union(*(_stored(i.optional_vars) for i in node.items if i.optional_vars))
+    if isinstance(node, (ast.Import, ast.ImportFrom)):
+        return {(a.asname or a.name).split(".")[0] for a in node.names}
+    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+        return {node.name}
+    if isinstance(node, (ast.MatchAs, ast.MatchStar, ast.ExceptHandler)) and node.name:
+        return {node.name}
+    return set()
+
+
+def _sender(call: ast.Call) -> str | None:
+    return getattr(call.func, "id", None) or getattr(call.func, "attr", None)
+
+
+def detail_slots(tree: Node) -> Iterator[tuple[ast.Call, Node | None]]:
+    """Every place a detail is sent from, with what it holds: `HTTPException`'s second argument or
+    `detail=` (None: sent without one), and the `"detail"` value of a `JSONResponse`'s content dict (a
+    content without one is an answer, not a refusal)."""
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        kw = {k.arg: k.value for k in node.keywords}
+        if _sender(node) == "HTTPException":
+            yield node, kw.get("detail", node.args[1] if len(node.args) > 1 else None)
+        elif _sender(node) == "JSONResponse":
+            content = kw.get("content", node.args[0] if node.args else None)
+            if isinstance(content, ast.Dict):
+                for k, v in zip(content.keys, content.values, strict=True):
+                    if isinstance(k, ast.Constant) and k.value == "detail":
+                        yield node, v
+
+
+def _code_dict(node: Node) -> bool:
+    """A `{"code": …}` dict, or a `dict(code=…)` call."""
+    if isinstance(node, ast.Dict):
+        return any(isinstance(k, ast.Constant) and k.value == "code" for k in node.keys)
+    return (
+        isinstance(node, ast.Call)
+        and getattr(node.func, "id", None) == "dict"
+        and any(k.arg == "code" for k in node.keywords)
+    )
+
+
+def _module_name(path: str) -> str:
+    parts = path.removesuffix(".py").split("/")
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    return ".".join(["app", *parts])
+
+
+def _load(sources: dict[str, str]) -> dict[str, Module]:
+    mods: dict[str, Module] = {}
+    for path, src in sources.items():
+        tree = ast.parse(src)
+        parents = {child: node for node in ast.walk(tree) for child in ast.iter_child_nodes(node)}
+        origins: dict[str, set[tuple[str, str | None]]] = {}
+        ambiguous: set[str] = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+                for a in node.names:
+                    origins.setdefault(a.asname or a.name, set()).add((node.module, a.name))
+            elif isinstance(node, ast.Import):
+                for a in node.names:
+                    if a.asname:
+                        origins.setdefault(a.asname, set()).add((a.name, None))
+            elif isinstance(node, ast.Global):
+                ambiguous |= set(node.names)
+        top: dict[str, Node] = {}
+        count: dict[str, int] = {}
+        ambiguous |= {name for name, o in origins.items() if len(o) > 1}
+        for stmt in tree.body:
+            if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+                top[stmt.name] = stmt
+            elif isinstance(stmt, ast.Assign):
+                for t in stmt.targets:
+                    if isinstance(t, ast.Name):
+                        top[t.id] = stmt
+            elif isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                top[stmt.target.id] = stmt
+            for n in [stmt] if isinstance(stmt, SCOPES) else _own_scope(stmt):
+                for name in _binds(n):
+                    count[name] = count.get(name, 0) + 1
+                    if isinstance(stmt, COMPOUND):
+                        ambiguous.add(name)
+        ambiguous |= {name for name, c in count.items() if c > 1}
+        imports = {name: next(iter(o)) for name, o in origins.items() if name not in ambiguous}
+        slots = {id(d) for _, d in detail_slots(tree) if d is not None}
+        name = _module_name(path)
+        mods[name] = Module(path, name, tree, parents, imports, top, ambiguous, slots)
+    return mods
+
+
+class Scan:
+    def __init__(self, sources: dict[str, str]):
+        self.mods = _load(sources)
+        self.errors: list[str] = []
+        self._following: set[tuple[str, str, str]] = set()
+        self._followed: dict[tuple[str, str, str], Res] = {}
+        self._resolving: set[int] = set()
+        self._factory: dict[int, bool] = {}
+        self._changed: dict[int, bool] = {}
+
+    # --- names ---------------------------------------------------------------------------------------
+
+    def lookup(
+        self, m: Module, name: str, seen: frozenset[tuple[str, str]] = frozenset()
+    ) -> tuple[Module, Node] | tuple[str, None] | None:
+        """What a module-level name is: (its module, its binding), or (a module's name, None)."""
+        if name in m.ambiguous:
+            return None
+        if name in m.top:
+            return m, m.top[name]
+        if name in m.imports:
+            mod, sym = m.imports[name]
+            if sym is None:
+                return (mod, None) if mod in self.mods else None
+            if f"{mod}.{sym}" in self.mods:
+                return f"{mod}.{sym}", None
+            if mod in self.mods and (mod, sym) not in seen:
+                return self.lookup(self.mods[mod], sym, seen | {(mod, sym)})
+        return None
+
+    def lookup_expr(self, m: Module, e: Node) -> tuple[Module, Node] | tuple[str, None] | None:
+        if isinstance(e, ast.Name):
+            return None if self.binder(m, e) is not None else self.lookup(m, e.id)
+        if isinstance(e, ast.Attribute):
+            base = self.lookup_expr(m, e.value)
+            if base and base[1] is None and isinstance(base[0], str):
+                return self.lookup(self.mods[base[0]], e.attr)
+        return None
+
+    def binder(self, m: Module, e: ast.Name) -> Node | None:
+        """The innermost scope `e` is bound in: a function (a parameter, or a binding in its own body), a
+        lambda (a parameter), a comprehension (its target); None: a module-level name."""
+        node = m.parents.get(e)
+        while node is not None:
+            if isinstance(node, (*FUNCS, ast.Lambda)):
+                a = node.args
+                params = [*a.posonlyargs, *a.args, *a.kwonlyargs, a.vararg, a.kwarg]
+                if e.id in {p.arg for p in params if p}:
+                    return node
+                if isinstance(node, FUNCS) and self.assignments(node, e.id):
+                    return node
+            elif isinstance(node, COMPREHENSIONS) and any(
+                e.id in _stored(g.target) for g in node.generators
+            ):
+                return node
+            node = m.parents.get(node)
+        return None
+
+    def at(self, m: Module, e: Node) -> str:
+        return f"{m.path}:{getattr(e, 'lineno', '?')}: {ast.unparse(e)}"
+
+    def enclosing(self, m: Module, e: Node, kind: type | tuple[type, ...]) -> Node | None:
+        node = m.parents.get(e)
+        while node is not None and not isinstance(node, kind):
+            node = m.parents.get(node)
+        return node
+
+    def assignments(self, fn: Node, name: str) -> list[Node]:
+        """What binds `name` in this function's own body (not in a nested one)."""
+        return [n for n in _own_scope(fn) if n is not fn and name in _binds(n)]
+
+    def caught_as(self, m: Module, e: Node, name: str) -> ast.ExceptHandler | None:
+        node = m.parents.get(e)
+        while node is not None and not isinstance(node, FUNCS):
+            if isinstance(node, ast.ExceptHandler) and node.name == name:
+                return node
+            node = m.parents.get(node)
+        return None
+
+    def references(
+        self, m: Module, target: Node
+    ) -> Iterator[tuple[Module, Node, ast.Call | None, bool]]:
+        """Every reference to a module-level def or class: the call it makes (None: not a call), and
+        whether it resolved. A reference named like it that the scan cannot resolve is yielded too."""
+        name = getattr(target, "name", None)
+        for cm in self.mods.values():
+            for node in ast.walk(cm.tree):
+                if not isinstance(node, (ast.Name, ast.Attribute)) or not isinstance(
+                    node.ctx, ast.Load
+                ):
+                    continue
+                if (node.id if isinstance(node, ast.Name) else node.attr) != name:
+                    continue
+                parent = cm.parents.get(node)
+                if isinstance(parent, ast.Attribute) and parent.value is node:
+                    continue
+                found = self.lookup_expr(cm, node)
+                if found:
+                    if not (found[0] is m and found[1] is target):
+                        continue
+                elif not self.unresolved(cm, node):
+                    continue
+                call = parent if isinstance(parent, ast.Call) and parent.func is node else None
+                yield cm, node, call, found is not None
+
+    def unresolved(self, m: Module, node: Node) -> bool:
+        """A name, or a dotted path, the app could mean that the scan cannot resolve: not a local, nor an
+        outside module's (an attribute of an object the function holds is not one)."""
+        root = node
+        while isinstance(root, ast.Attribute):
+            root = root.value
+        if not isinstance(root, ast.Name) or self.binder(m, root) is not None:
+            return False
+        if root.id in m.ambiguous or (root.id not in m.top and root.id not in m.imports):
+            return True
+        if root.id in m.top:
+            return False
+        if root is node:  # imported from an app module that does not bind it where the scan can see
+            mod = m.imports[root.id][0]
+            return (mod == "app" or mod.startswith("app.")) and self.lookup(m, root.id) is None
+        found = self.lookup(m, root.id)
+        return (
+            found is not None and found[1] is None
+        )  # an app module whose dotted path went nowhere
+
+    def changed(self, m: Module, stmt: Node, name: str, *, only_read: bool) -> bool:
+        """Something in the app stores into, deletes or rebinds the module-level `name` that `stmt` binds,
+        or (`only_read`, a map) uses it but by `map[k]` or a method that only reads it."""
+        key = id(stmt) * 2 + only_read
+        if key in self._changed:
+            return self._changed[key]
+        own = stmt.targets if isinstance(stmt, ast.Assign) else [getattr(stmt, "target", None)]
+        out = False
+        for cm in self.mods.values():
+            for node in ast.walk(cm.tree):
+                if out:
+                    break
+                if not (
+                    isinstance(node, ast.Name)
+                    and node.id == name
+                    or isinstance(node, ast.Attribute)
+                    and node.attr == name
+                ) or (cm is m and node in own):
+                    continue
+                found = self.lookup_expr(cm, node)
+                if not (found and found[0] is m and found[1] is stmt):
+                    continue
+                if not isinstance(node.ctx, ast.Load):
+                    out = True
+                elif only_read:
+                    p = cm.parents.get(node)
+                    out = not (
+                        isinstance(p, ast.Subscript)
+                        and p.value is node
+                        and isinstance(p.ctx, ast.Load)
+                        or isinstance(p, ast.Attribute)
+                        and p.attr in READS
+                    )
+        self._changed[key] = out
+        return out
+
+    # --- types ---------------------------------------------------------------------------------------
+
+    def ann_values(self, m: Module, ann: Node | None, depth: int = 0) -> set[str] | None:
+        """The values a `Literal[…]` annotation, or an alias of one, allows; None when it is not one."""
+        if isinstance(ann, ast.Subscript) and getattr(ann.value, "id", None) == "Literal":
+            items = ann.slice.elts if isinstance(ann.slice, ast.Tuple) else [ann.slice]
+            if all(isinstance(i, ast.Constant) and isinstance(i.value, str) for i in items):
+                return {i.value for i in items}
+            return None
+        if isinstance(ann, (ast.Name, ast.Attribute)) and depth < 8:
+            found = self.lookup_expr(m, ann)
+            if found and isinstance(found[0], Module) and isinstance(found[1], ast.Assign):
+                return self.ann_values(found[0], found[1].value, depth + 1)
+        return None
+
+    def classes(self, m: Module, e: Node | None) -> list[tuple[Module, ast.ClassDef]] | None:
+        found = self.lookup_expr(m, e) if e is not None else None
+        if found and isinstance(found[0], Module) and isinstance(found[1], ast.ClassDef):
+            return [(found[0], found[1])]
+        return None
+
+    def typed(self, m: Module, at: Node, name: str) -> list[tuple[Module, ast.ClassDef]] | None:
+        """The class `name` holds where `at` sits: the one an `except C as name` catches, or a parameter's
+        annotation (a parameter its body binds again holds no known class)."""
+        handler = self.caught_as(m, at, name)
+        if handler is not None:
+            return self.classes(m, handler.type)
+        fn = self.enclosing(m, at, FUNCS)
+        if fn is None:
+            return None
+        params = {a.arg: a for a in [*fn.args.posonlyargs, *fn.args.args, *fn.args.kwonlyargs]}
+        if name in params and not self.assignments(fn, name):
+            return self.classes(m, params[name].annotation)
+        return None
+
+    def attr_values(self, cm: Module, cls: ast.ClassDef, attr: str) -> set[str] | None:
+        """An attribute's `Literal` values, from `self.attr: T` in a method of the class."""
+        for node in ast.walk(cls):
+            if (
+                isinstance(node, ast.AnnAssign)
+                and isinstance(node.target, ast.Attribute)
+                and node.target.attr == attr
+                and getattr(node.target.value, "id", None) == "self"
+            ):
+                return self.ann_values(cm, node.annotation)
+        return None
+
+    # --- reasons -------------------------------------------------------------------------------------
+
+    def resolve(self, m: Module, e: Node) -> Res:
+        if isinstance(e, ast.Constant):
+            if e.value is None:
+                return Res(none=True)
+            if isinstance(e.value, str):
+                return Res({e.value})
+        if isinstance(e, ast.IfExp):
+            return self.resolve(m, e.body) | self.resolve(m, e.orelse)
+        if isinstance(e, ast.Name):
+            return self.resolve_name(m, e)
+        if isinstance(e, ast.Attribute):
+            return self.resolve_attr(m, e)
+        if isinstance(e, ast.Call):
+            found = self.lookup_expr(m, e.func)
+            if found and isinstance(found[0], Module) and isinstance(found[1], FUNCS):
+                v = self.ann_values(found[0], found[1].returns)
+                if v is not None:
+                    return Res(v)
+        if isinstance(e, ast.Subscript):
+            return self.resolve_lookup(m, e)
+        return Res(unread=[self.at(m, e)])
+
+    def resolve_name(self, m: Module, e: ast.Name) -> Res:
+        if self.caught_as(m, e, e.id) is not None:
+            return Res(unread=[self.at(m, e)])  # the exception itself, not a reason
+        fn = self.binder(m, e)
+        if fn is None:
+            return Res(unread=[self.at(m, e)])
+        if not isinstance(fn, FUNCS):
+            return Res(unread=[f"{self.at(m, e)} (bound by a lambda or a comprehension)"])
+        if any(isinstance(n, (ast.Nonlocal, ast.Global)) and e.id in n.names for n in ast.walk(fn)):
+            return Res(unread=[f"{self.at(m, e)} (named by a nonlocal or a global)"])
+        a = fn.args
+        params = {p.arg: p for p in [*a.posonlyargs, *a.args, *a.kwonlyargs]}
+        assigned = self.assignments(fn, e.id)
+        if e.id in params:
+            if assigned:
+                return Res(unread=[f"{self.at(m, e)} (a parameter its body binds again)"])
+            return self.resolve_param(m, fn, params[e.id], e)
+        out = Res(unread=[] if assigned else [self.at(m, e)])  # `*args`, `**kwargs`
+        for s in assigned:
+            if not (isinstance(s, ast.Assign) and all(isinstance(t, ast.Name) for t in s.targets)):
+                out = out | Res(unread=[self.at(m, e)])
+            elif id(s) in self._resolving:
+                out = out | Res(unread=[f"{self.at(m, e)} (reached again while it is resolved)"])
+            else:
+                self._resolving.add(id(s))
+                out = out | self.resolve(m, s.value)
+                self._resolving.discard(id(s))
+        return out
+
+    def resolve_param(self, m: Module, fn: Node, param: ast.arg, e: Node) -> Res:
+        v = self.ann_values(m, param.annotation)
+        if v is not None:
+            return Res(v)
+        if param.annotation is not None and getattr(param.annotation, "id", None) != "str":
+            return Res(unread=[self.at(m, e)])
+        return self.follow(m, fn, param)
+
+    def follow(self, m: Module, fn: Node, param: ast.arg) -> Res:
+        """A `str` parameter of a helper: what every call of the helper passes it."""
+        assert isinstance(fn, FUNCS)
+        key = (m.name, fn.name, param.arg)
+        if key in self._followed:
+            return self._followed[key]
+        where = f"{m.path}:{fn.lineno}: {fn.name}({param.arg})"
+        if key in self._following:
+            return Res(unread=[f"{where} reached again while it is followed"])
+        if m.top.get(fn.name) is not fn or fn.name in m.ambiguous:
+            return Res(unread=[f"{where} is not a module-level helper"])
+        self._following.add(key)
+        positional = [a.arg for a in [*fn.args.posonlyargs, *fn.args.args]]
+        by_name = param not in fn.args.posonlyargs
+        out = Res()
+        for cm, node, call, resolved in self.references(m, fn):
+            if not resolved:
+                out = out | Res(
+                    unread=[f"{self.at(cm, node)} (a reference the scan cannot resolve)"]
+                )
+                continue
+            if call is None:
+                out = out | Res(unread=[f"{self.at(cm, node)} (the helper used as a value)"])
+                continue
+            kw = {k.arg: k.value for k in call.keywords}
+            given = param.arg in positional and positional.index(param.arg) < len(call.args)
+            if by_name and param.arg in kw:
+                out = out | self.resolve(cm, kw[param.arg])
+            elif any(isinstance(a, ast.Starred) for a in call.args):
+                out = out | Res(unread=[self.at(cm, call)])
+            elif given:
+                out = out | self.resolve(cm, call.args[positional.index(param.arg)])
+            else:
+                out = out | Res(unread=[f"{self.at(cm, call)} (does not pass {param.arg})"])
+        self._followed[key] = out  # once followed, its key answers from here: never reached again
+        return out
+
+    def resolve_attr(self, m: Module, e: ast.Attribute) -> Res:
+        base = e.value
+        if isinstance(base, ast.Name):
+            typed = self.typed(m, e, base.id)
+            if typed is not None:
+                out = Res()
+                for cm, cls in typed:
+                    v = self.attr_values(cm, cls, e.attr)
+                    out = out | (
+                        Res(v)
+                        if v is not None
+                        else Res(
+                            unread=[f"{self.at(m, e)} ({cls.name}.{e.attr} has no Literal type)"]
+                        )
+                    )
+                return out
+        found = self.lookup_expr(m, e)
+        if (
+            found
+            and isinstance(found[0], Module)
+            and isinstance(found[1], (ast.Assign, ast.AnnAssign))
+            and isinstance(found[1].value, ast.Constant)
+        ):
+            if self.changed(found[0], found[1], e.attr, only_read=False):
+                return Res(unread=[f"{self.at(m, e)} (bound again or deleted elsewhere)"])
+            return self.resolve(found[0], found[1].value)
+        return Res(unread=[self.at(m, e)])
+
+    def resolve_lookup(self, m: Module, e: ast.Subscript) -> Res:
+        found = self.lookup_expr(m, e.value)
+        if not (
+            found
+            and isinstance(found[0], Module)
+            and isinstance(found[1], (ast.Assign, ast.AnnAssign))
+        ):
+            return Res(unread=[self.at(m, e)])
+        table = found[1].value
+        if not isinstance(table, ast.Dict) or not all(
+            isinstance(k, ast.Constant) and isinstance(k.value, str) for k in table.keys
+        ):
+            return Res(unread=[self.at(m, e)])
+        name = e.value.attr if isinstance(e.value, ast.Attribute) else getattr(e.value, "id", "")
+        if self.changed(found[0], found[1], name, only_read=True):
+            return Res(unread=[f"{self.at(m, e)} (the map is changed after it is built)"])
+        out = Res()
+        for v in table.values:
+            out = out | self.resolve(found[0], v)
+        index = self.resolve(m, e.slice)
+        keys = {k.value for k in table.keys if isinstance(k, ast.Constant)}
+        if index.unread or index.none or index.values != keys:
+            self.errors.append(
+                f"{self.at(m, e)}: the map's keys {sorted(keys)} are not what its index can be "
+                f"{sorted(index.values)}{' + unread ' + str(index.unread) if index.unread else ''}"
+            )
+        return out
+
+    # --- sites ---------------------------------------------------------------------------------------
+
+    def is_detail(self, node: Node | None) -> bool:
+        if isinstance(node, ast.IfExp):
+            return self.is_detail(node.body) and self.is_detail(node.orelse)
+        return _code_dict(node)
+
+    def factory(self, m: Module, fn: Node) -> bool:
+        """A module-level function each return of which is a detail, and each reference to which is a
+        call sent as one (`quota_detail`)."""
+        assert isinstance(fn, FUNCS)
+        if id(fn) in self._factory:
+            return self._factory[id(fn)]
+        returns = [n for n in _own_scope(fn) if isinstance(n, ast.Return)]
+        ok = (
+            m.top.get(fn.name) is fn  # a name bound twice: its calls are unresolved below
+            and bool(returns)
+            and all(self.is_detail(r.value) for r in returns)
+        )
+        for cm, _, call, resolved in self.references(m, fn) if ok else []:
+            ok = resolved and id(call) in cm.slots  # a bare reference is no call: never sent
+            if not ok:
+                break
+        self._factory[id(fn)] = ok
+        return ok
+
+    def placed(self, m: Module, d: Node) -> bool:
+        """`d` is sent as a detail: from a sender's slot, through the arms of `a if c else b`, or as what a
+        factory returns."""
+        holder, p = d, m.parents.get(d)
+        while isinstance(p, ast.IfExp) and holder is not p.test:
+            holder, p = p, m.parents.get(p)
+        if id(holder) in m.slots:
+            return True
+        fn = self.enclosing(m, p, FUNCS) if isinstance(p, ast.Return) else None
+        return fn is not None and self.factory(m, fn)
+
+    def sayable(self, m: Module, d: Node | None) -> bool:
+        """What a slot holds is a detail the client can say: a code dict, or a factory's call."""
+        if isinstance(d, ast.IfExp):
+            return self.sayable(m, d.body) and self.sayable(m, d.orelse)
+        if _code_dict(d):
+            return True
+        found = self.lookup_expr(m, d.func) if isinstance(d, ast.Call) else None
+        return bool(
+            found
+            and isinstance(found[0], Module)
+            and isinstance(found[1], FUNCS)
+            and self.factory(found[0], found[1])
+        )
+
+    def entries(self, d: Node) -> list[tuple[str | None, Node]]:
+        """A dict's (key, value) pairs: None for a `**` spread, "?" for a key that is not a literal."""
+        if isinstance(d, ast.Dict):
+            return [
+                (
+                    k.value
+                    if isinstance(k, ast.Constant) and isinstance(k.value, str)
+                    else None
+                    if k is None
+                    else "?",
+                    v,
+                )
+                for k, v in zip(d.keys, d.values, strict=True)
+            ]
+        assert isinstance(d, ast.Call)
+        return [(None, a) for a in d.args] + [(k.arg, k.value) for k in d.keywords]
+
+    def site(self, m: Module, d: Node, out: dict) -> None:
+        items = self.entries(d)
+        code = Res()
+        for v in (v for k, v in items if k == "code"):
+            code = code | self.resolve(m, v)
+        problems = [
+            f"{self.at(m, v)} (a spread in dict())"
+            for k, v in items
+            if k is None and isinstance(d, ast.Call)
+        ] + [
+            f"{self.at(m, v)} (a spread or a computed key the code and the reason do not follow)"
+            for i, (k, v) in enumerate(items)
+            if k in (None, "?") and not {"code", "reason"} <= {k2 for k2, _ in items[i + 1 :]}
+        ]
+        if not self.placed(m, d):
+            problems.append(f"{self.at(m, d)} (a detail put where the scan cannot follow it)")
+        if code.unread or code.none or len(code.values) != 1 or problems:
+            out["unreadCodes"] += problems or [self.at(m, d)]
+            return
+        entry = out["codes"].setdefault(
+            next(iter(code.values)), {"reasons": set(), "unread": [], "sites": 0, "reasonless": []}
+        )
+        entry["sites"] += 1
+        res, has_reason = Res(), False
+        for k, v in items:
+            if k == "reason":
+                res, has_reason = res | self.resolve(m, v), True
+        if not has_reason or res.none:
+            entry["reasonless"].append(f"{m.path}:{d.lineno}")
+        entry["reasons"] |= res.values
+        entry["unread"] += res.unread
+
+    def other_details(self) -> list[tuple[str, int, str | None]]:
+        """Each slot that sends what the client cannot say — nothing, or anything but a code dict or a
+        factory's call: (its file, its line, the function it is sent from)."""
+        out = []
+        for m in self.mods.values():
+            for call, d in detail_slots(m.tree):
+                if self.sayable(m, d):
+                    continue
+                fn = self.enclosing(m, call, FUNCS)
+                out.append((m.path, call.lineno, getattr(fn, "name", None)))
+        return sorted(out)
+
+    def run(self) -> dict:
+        out: dict = {
+            "codes": {},
+            "unreadCodes": [],
+            "errors": self.errors,
+            "excluded": {},
+            "aliases": {},
+            "notRefusals": sorted(NOT_REFUSALS),
+        }
+        for m in self.mods.values():
+            for name, stmt in m.top.items():
+                if (
+                    isinstance(stmt, ast.Assign)
+                    and isinstance(stmt.value, ast.Subscript)
+                    and (v := self.ann_values(m, stmt.value))
+                ):
+                    out["aliases"].setdefault(m.path, {})[name] = sorted(v)
+            for node in ast.walk(m.tree):
+                if not _code_dict(node):
+                    continue
+                if m.path in NOT_REFUSALS:
+                    out["excluded"][m.path] = out["excluded"].get(m.path, 0) + 1
+                    continue
+                self.site(m, node, out)
+        for entry in out["codes"].values():
+            entry["reasons"] = sorted(entry["reasons"])
+        return out
+
+
+def scan(sources: dict[str, str]) -> dict:
+    return Scan(sources).run()
+
+
+def app_sources(app: pathlib.Path = APP) -> dict[str, str]:
+    return {
+        p.relative_to(app).as_posix(): p.read_text(encoding="utf-8")
+        for p in sorted(app.rglob("*.py"))
+        if "__pycache__" not in p.parts
+    }
+
+
+def scan_app(app: pathlib.Path = APP) -> dict:
+    return scan(app_sources(app))
+
+
+if __name__ == "__main__":
+    json.dump(
+        scan_app(pathlib.Path(sys.argv[1]) if len(sys.argv) > 1 else APP),
+        sys.stdout,
+        indent=1,
+        sort_keys=True,
+    )

backend/tests/test_catalog_routes.py

@@ -72,3 +72,23 @@ def test_the_sync_status_counts_the_callers_subscriptions(db, make_user, as_user
     assert (body["subscriptions"], body["channels_total"]) == (1, 1)
     mine = as_user(user).get("/api/sync/my-status").json()
     assert (mine["channels_total"], mine["channels_recent_pending"]) == (1, 1)
+
+
+def test_a_channel_lists_when_it_entered_this_users_list_not_when_the_channel_did(
+    db, make_user, as_user
+):
+    from datetime import datetime, timezone
+
+    user = make_user()
+    db.add(Channel(id="UCa", title="A", created_at=datetime(2026, 6, 10, tzinfo=timezone.utc)))
+    db.flush()
+    db.add(
+        Subscription(
+            user_id=user.id,
+            channel_id="UCa",
+            created_at=datetime(2026, 10, 12, 8, 30, tzinfo=timezone.utc),
+        )
+    )
+    db.commit()
+    listed = as_user(user).get("/api/channels").json()
+    assert [(c["id"], c["added_at"]) for c in listed] == [("UCa", "2026-10-12T08:30:00+00:00")]

backend/tests/test_discover.py

@@ -1105,10 +1105,16 @@ def test_two_overlapping_reorders_never_share_a_slot(db, as_user):
 
         worker = threading.Thread(target=second_tab)
         worker.start()
-        # Commit A only once B is blocked on a row lock, so B's read is the stale snapshot.
+        # Commit A only once B is blocked on a row lock, so B's read is the stale snapshot. pg_locks is
+        # the whole server's: only a wait in this database is B's (a parallel worker's is not).
         waiting = 0
         for _ in range(200):
-            waiting = probe.scalar(text("SELECT count(*) FROM pg_locks WHERE NOT granted"))
+            waiting = probe.scalar(
+                text(
+                    "SELECT count(*) FROM pg_locks WHERE NOT granted AND pid IN"
+                    " (SELECT pid FROM pg_stat_activity WHERE datname = current_database())"
+                )
+            )
             probe.rollback()
             if waiting:
                 break

backend/tests/test_edit_crop_frame.py

@@ -0,0 +1,209 @@
+"""The editor's crop lands on the part of the picture the frame was drawn on, also when a video's
+pixels are not square. The browser reports such a video by its shown size (320 stored, 640 shown),
+and ffmpeg's `crop` counts stored pixels: measured on a real clip, a frame over the middle half kept
+half the frame's red surroundings. So a crop carries the size it was measured on.
+
+Real ffmpeg: the pixels of the output are the oracle.
+"""
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from app.config import settings
+from app.downloads import edit, pipeline, service, storage
+from app.downloads import upload as uploadmod
+from app.downloads.models import DownloadJob, MediaAsset
+
+pytestmark = pytest.mark.skipif(shutil.which("ffmpeg") is None, reason="ffmpeg not available")
+
+
+def _source(path: Path, size: str, box: str, sar: int, rotate: int = 0) -> None:
+    """Red, with a green box: a crop of the box holds no red. `rotate` tags the file to be shown
+    turned by that many degrees counter-clockwise, as a phone records a portrait video."""
+    tag = ["-display_rotation:v:0", str(rotate)] if rotate else []
+    subprocess.run(
+        [
+            "ffmpeg", "-y", "-loglevel", "error",
+            "-f", "lavfi", "-i", f"color=c=red:s={size}:d=2:r=10",
+            "-f", "lavfi", "-i", "sine=duration=2",
+            "-vf", f"drawbox={box}:c=lime:t=fill,setsar={sar}",
+            "-c:v", "libx264", "-pix_fmt", "yuv420p", "-c:a", "aac", str(path),
+        ],
+        check=True,
+    )  # fmt: skip
+    if tag:
+        tagged = path.with_name("tagged-" + path.name)
+        subprocess.run(
+            ["ffmpeg", "-y", "-loglevel", "error", *tag, "-i", str(path), "-c", "copy", str(tagged)],
+            check=True,
+        )  # fmt: skip
+        tagged.replace(path)
+
+
+def _red_and_green(path: Path) -> tuple[int, int]:
+    raw = subprocess.run(
+        ["ffmpeg", "-loglevel", "error", "-i", str(path), "-frames:v", "1",
+         "-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
+        check=True,
+        capture_output=True,
+    ).stdout  # fmt: skip
+    red = green = 0
+    for i in range(0, len(raw) - 2, 3):
+        if raw[i] > 180 and raw[i + 1] < 80:
+            red += 1
+        elif raw[i + 1] > 180 and raw[i] < 80:
+            green += 1
+    return red, green
+
+
+def _cut_asset(db, make_user, src: Path, spec: dict, then=lambda: None) -> MediaAsset:
+    user = make_user()
+    source = uploadmod.ingest_upload(
+        db, user.id, filename="clip.mp4", src_path=src, size=src.stat().st_size
+    )
+    assert source.status == "done"
+    then()
+    job = service.enqueue_edit(db, user.id, source, spec)
+    asset = db.get(MediaAsset, job.asset_id)
+    job.status, asset.status = "running", "downloading"  # the worker's claim
+    db.commit()
+
+    pipeline._process_edit(job.id, asset.id)
+
+    db.expire_all()
+    job, asset = db.get(DownloadJob, job.id), db.get(MediaAsset, job.asset_id)
+    assert (job.status, job.error, asset.status) == ("done", None, "ready")
+    return asset
+
+
+def _cut(db, make_user, tmp_path, src: Path, crop: dict, **spec) -> Path:
+    asset = _cut_asset(db, make_user, src, {"crop": crop, **spec})
+    return storage.abs_path(str(tmp_path), asset.rel_path)
+
+
+def test_a_crop_of_a_video_with_wide_pixels_keeps_what_the_frame_showed(
+    db, make_user, tmp_path, monkeypatch
+):
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    src = tmp_path / "in.mp4"
+    _source(src, "320x240", "x=80:y=60:w=160:h=120", sar=2)
+
+    # What the editor sends for the middle half of this video: the browser shows it at 640 x 240.
+    final = _cut(
+        db, make_user, tmp_path, src,
+        {"x": 160, "y": 60, "w": 320, "h": 120, "frame_w": 640, "frame_h": 240},
+    )  # fmt: skip
+
+    red, green = _red_and_green(final)
+    assert (red, green) == (0, 160 * 120)
+
+
+def test_a_crop_of_square_pixels_is_cut_where_it_was_drawn(db, make_user, tmp_path, monkeypatch):
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    src = tmp_path / "in.mp4"
+    _source(src, "480x640", "x=120:y=160:w=240:h=320", sar=1)
+
+    final = _cut(
+        db, make_user, tmp_path, src,
+        {"x": 120, "y": 160, "w": 240, "h": 320, "frame_w": 480, "frame_h": 640},
+    )  # fmt: skip
+
+    assert _red_and_green(final) == (0, 240 * 320)
+
+
+def test_a_crop_stored_before_it_carried_its_frame_is_cut_as_it_always_was():
+    spec = edit.normalize_edit_spec({"crop": {"x": 4, "y": 6, "w": 100, "h": 50}})
+    assert spec["crop"] == {"x": 4, "y": 6, "w": 100, "h": 50}
+    cmd = edit.build_edit_cmd(Path("in.mp4"), Path("out.mp4"), spec, "mp4")
+    assert cmd[cmd.index("-vf") + 1].startswith("crop=100:50:4:6,")
+
+
+@pytest.mark.parametrize("frame", [{"frame_w": 0, "frame_h": 240}, {"frame_w": "x", "frame_h": 2}])
+def test_a_frame_that_cannot_be_read_is_not_divided_by(frame):
+    spec = edit.normalize_edit_spec({"crop": {"x": 4, "y": 6, "w": 100, "h": 50, **frame}})
+    assert spec["crop"] == {"x": 4, "y": 6, "w": 100, "h": 50}
+
+
+def test_a_crop_of_a_join_keeps_what_the_frame_showed(db, make_user, tmp_path, monkeypatch):
+    """A cut-list joins through `filter_complex`, a crop path of its own."""
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    src = tmp_path / "in.mp4"
+    _source(src, "320x240", "x=80:y=60:w=160:h=120", sar=2)
+
+    final = _cut(
+        db, make_user, tmp_path, src,
+        {"x": 160, "y": 60, "w": 320, "h": 120, "frame_w": 640, "frame_h": 240},
+        segments=[{"start_s": 0, "end_s": 0.5}, {"start_s": 1, "end_s": 1.5}], accurate=True,
+    )  # fmt: skip
+
+    assert _red_and_green(final) == (0, 160 * 120)
+
+
+def test_a_crop_of_a_rotated_video_is_cut_where_it_was_drawn(db, make_user, tmp_path, monkeypatch):
+    """The browser shows a rotated file upright, so the frame was drawn on the upright picture."""
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    src = tmp_path / "in.mp4"
+    # Stored 320 x 240, green on its left half; shown turned a quarter, 240 x 320.
+    _source(src, "320x240", "x=0:y=0:w=160:h=240", sar=1, rotate=90)
+
+    # Turned counter-clockwise, the stored left half is the shown bottom half.
+    final = _cut(
+        db, make_user, tmp_path, src,
+        {"x": 0, "y": 160, "w": 240, "h": 160, "frame_w": 240, "frame_h": 320},
+    )  # fmt: skip
+
+    assert _red_and_green(final) == (0, 240 * 160)
+
+
+def test_a_clip_ffprobe_cannot_size_gets_the_size_its_crop_cut(
+    db, make_user, tmp_path, monkeypatch
+):
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    src = tmp_path / "in.mp4"
+    _source(src, "320x240", "x=80:y=60:w=160:h=120", sar=2)
+
+    def probe_fails():
+        monkeypatch.setattr(pipeline.probe, "probe_media", lambda _p: (None,) * 5)
+
+    asset = _cut_asset(
+        db, make_user, src,
+        {"crop": {"x": 160, "y": 60, "w": 320, "h": 120, "frame_w": 640, "frame_h": 240}},
+        then=probe_fails,
+    )  # fmt: skip
+
+    # Half the shown width of a 320-wide file: 160 stored, not the 320 the frame counted.
+    assert (asset.width, asset.height) == (160, 120)
+
+
+def test_a_rotated_clip_ffprobe_cannot_size_gets_the_upright_size_its_crop_cut(
+    db, make_user, tmp_path, monkeypatch
+):
+    """The frame was drawn on the upright picture, which is the stored one turned: so is its cut."""
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    src = tmp_path / "in.mp4"
+    _source(src, "320x240", "x=0:y=0:w=160:h=240", sar=1, rotate=90)
+
+    def probe_fails():
+        monkeypatch.setattr(pipeline.probe, "probe_media", lambda _p: (None,) * 5)
+
+    asset = _cut_asset(
+        db, make_user, src,
+        {"crop": {"x": 0, "y": 160, "w": 240, "h": 160, "frame_w": 240, "frame_h": 320}},
+        then=probe_fails,
+    )  # fmt: skip
+
+    # What ffmpeg cut (the rotated test above): 240 x 160, not the stored 320 x 120.
+    assert (asset.width, asset.height) == (240, 160)
+
+
+@pytest.mark.parametrize("key", ["frame_w", "x"])
+def test_an_infinite_number_in_a_crop_is_dropped_not_a_crash(key):
+    crop = {"x": 4, "y": 6, "w": 100, "h": 50, "frame_w": 640, "frame_h": 240}
+    spec = edit.normalize_edit_spec({"crop": {**crop, key: float("inf")}})
+    if key == "frame_w":
+        assert spec["crop"] == {"x": 4, "y": 6, "w": 100, "h": 50}
+    else:
+        assert "crop" not in spec

backend/tests/test_facebook_titles.py

@@ -0,0 +1,299 @@
+"""A Facebook download's title when the signed-in read gives only a placeholder.
+
+Measured on prod (2026-11-01): every Facebook download since 2026-10-28 is titled "Facebook" — the
+signed-in read (the owner's cookie) now gives that placeholder and NO description, so the adapter had
+no post text to fall back on, and the download name copied the placeholder too. A signed-out read of
+the same reel (yt-dlp 2026.08.19, as on prod) still carries the post's text in its description.
+"""
+
+from sqlalchemy import select, update
+
+from app.config import settings
+from app.db import SessionLocal
+from app.downloads import adapters, backfill, pipeline
+from app.downloads.models import DownloadJob, MediaAsset
+
+_URL = "https://www.facebook.com/reel/1860682468422402/"
+# The page yt-dlp says it read for it (`webpage_url`); a group post's link resolves the same way.
+_PAGE = "https://www.facebook.com/watch/?v=1860682468422402"
+# The measured signed-out read of that reel.
+_PUBLIC = {
+    "title": "163K reactions · 14K shares | sorry not helping #workhumor #officelife | Work dot exe",
+    "description": "sorry not helping\n\n#workhumor #officelife",
+    "uploader": "Work dot exe",
+}
+
+
+def _fake_ydl(monkeypatch, outcome):
+    """yt-dlp faked at its `YoutubeDL` boundary: records each read (its options and its `url`),
+    answers `outcome`."""
+    seen: list[dict] = []
+
+    class FakeYDL:
+        def __init__(self, opts):
+            self.opts = opts
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, *exc):
+            return False
+
+        def extract_info(self, url, download):
+            seen.append({**self.opts, "url": url})
+            return outcome
+
+    monkeypatch.setattr(backfill.yt_dlp, "YoutubeDL", FakeYDL)
+    return seen
+
+
+def test_a_placeholder_with_nothing_behind_it_takes_the_signed_out_pages_text(monkeypatch):
+    seen = _fake_ydl(monkeypatch, _PUBLIC)
+    fb = adapters.FacebookAdapter()
+
+    info = backfill.public_title_info({"title": "Facebook", "description": None}, _URL, fb, 7)
+
+    assert fb.title(info) == "sorry not helping"
+    # One metadata-only read, and signed out: no cookie goes with it.
+    assert len(seen) == 1
+    assert seen[0]["skip_download"] is True
+    assert not seen[0].get("cookiefile")
+
+
+def test_a_real_title_reads_nothing_more(monkeypatch):
+    seen = _fake_ydl(monkeypatch, _PUBLIC)
+    info = {"title": "Funny Dark Humor Dad Joke!", "description": None}
+
+    assert backfill.public_title_info(info, _URL, adapters.FacebookAdapter(), 7) is info
+    assert seen == []
+
+
+def test_a_placeholder_with_the_posts_text_behind_it_reads_nothing_more(monkeypatch):
+    seen = _fake_ydl(monkeypatch, _PUBLIC)
+    info = {"title": "Video", "description": "Office jokes, part two"}
+
+    assert backfill.public_title_info(info, _URL, adapters.FacebookAdapter(), 7) is info
+    assert seen == []
+
+
+def test_a_placeholder_the_signed_out_page_cannot_better_stays(monkeypatch):
+    _fake_ydl(monkeypatch, {"title": "Facebook", "description": None})
+    fb = adapters.FacebookAdapter()
+
+    info = backfill.public_title_info({"title": "Facebook", "description": None}, _URL, fb, 7)
+
+    assert fb.title(info) == "Facebook"
+
+
+def test_another_source_is_never_read_again(monkeypatch):
+    seen = _fake_ydl(monkeypatch, _PUBLIC)
+    info = {"title": "Video", "description": None}
+
+    assert backfill.public_title_info(info, _URL, adapters.SourceAdapter(), 7) is info
+    assert seen == []
+
+
+def test_the_backfill_retitles_a_placeholder_download_and_the_names_that_repeated_it(
+    db, make_user, monkeypatch
+):
+    seen = _fake_ydl(monkeypatch, _PUBLIC)
+    owner, other = make_user(), make_user()
+    asset = MediaAsset(
+        source_kind="url",
+        source_ref=_URL,
+        format_sig="fb",
+        status="ready",
+        rel_path="facebook/x.mp4",
+        poster_path="facebook/x.jpg",
+        uploader_url="https://www.facebook.com/1",
+        title="Facebook",
+        ref_count=2,
+    )
+    db.add(asset)
+    db.flush()
+    copied = DownloadJob(
+        user_id=owner.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref=_URL,
+        status="done",
+        queue_pos=0,
+        profile_snapshot={},
+        display_name="Facebook",
+    )
+    renamed = DownloadJob(
+        user_id=other.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref=_URL,
+        status="done",
+        queue_pos=0,
+        profile_snapshot={},
+        display_name="Office jokes",
+    )
+    db.add_all([copied, renamed])
+    db.commit()
+
+    assert backfill.run()["retitled"] == 1
+    assert len(seen) == 1
+
+    db.expire_all()
+    assert db.get(MediaAsset, asset.id).title == "sorry not helping"
+    assert db.get(DownloadJob, copied.id).display_name == "sorry not helping"
+    assert db.get(DownloadJob, renamed.id).display_name == "Office jokes"
+    # Run again: nothing left to retitle, and no page read for it.
+    assert backfill.run()["retitled"] == 0
+    assert len(seen) == 1
+
+
+def test_a_name_given_while_the_backfill_runs_stays(db, make_user, monkeypatch):
+    # The owner renames the download while the backfill reads the page: the owner's name wins, it is
+    # not overwritten by what was read before it.
+    _fake_ydl(monkeypatch, _PUBLIC)
+    owner = make_user()
+    asset = MediaAsset(
+        source_kind="url",
+        source_ref=_URL,
+        format_sig="fb",
+        status="ready",
+        rel_path="facebook/x.mp4",
+        uploader_url="https://www.facebook.com/1",
+        title="Facebook",
+        ref_count=1,
+    )
+    db.add(asset)
+    db.flush()
+    job = DownloadJob(
+        user_id=owner.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref=_URL,
+        status="done",
+        queue_pos=0,
+        profile_snapshot={},
+        display_name="Facebook",
+    )
+    db.add(job)
+    db.commit()
+
+    read_page = backfill.public_title_info
+
+    def renamed_while_reading(*args):
+        with SessionLocal() as other:
+            other.execute(
+                update(DownloadJob)
+                .where(DownloadJob.id == job.id)
+                .values(display_name="Office jokes")
+            )
+            other.commit()
+        return read_page(*args)
+
+    monkeypatch.setattr(backfill, "public_title_info", renamed_while_reading)
+    monkeypatch.setattr(backfill.editmod, "ensure_poster", lambda a, root: None)
+
+    assert backfill.run()["retitled"] == 1
+
+    db.expire_all()
+    assert db.get(DownloadJob, job.id).display_name == "Office jokes"
+
+
+def test_the_poster_step_holds_no_row_lock(db, make_user, monkeypatch):
+    # It can cut a frame for 30 s. A delete locks the asset and then the job: with the job held here
+    # and the asset still to write, that is a deadlock, and a rename waits out the whole cut.
+    _fake_ydl(monkeypatch, _PUBLIC)
+    owner = make_user()
+    asset = MediaAsset(
+        source_kind="url",
+        source_ref=_URL,
+        format_sig="fb",
+        status="ready",
+        rel_path="facebook/x.mp4",
+        uploader_url="https://www.facebook.com/1",
+        title="Facebook",
+        ref_count=1,
+    )
+    db.add(asset)
+    db.flush()
+    job = DownloadJob(
+        user_id=owner.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref=_URL,
+        status="done",
+        queue_pos=0,
+        profile_snapshot={},
+        display_name="Facebook",
+    )
+    db.add(job)
+    db.commit()
+    asset_id, job_id = asset.id, job.id
+
+    def poster_finds_rows_free(a, root):
+        with SessionLocal() as other:
+            other.execute(
+                select(MediaAsset).where(MediaAsset.id == asset_id).with_for_update(nowait=True)
+            )
+            other.execute(
+                select(DownloadJob).where(DownloadJob.id == job_id).with_for_update(nowait=True)
+            )
+            other.rollback()
+        return None
+
+    monkeypatch.setattr(backfill.editmod, "ensure_poster", poster_finds_rows_free)
+
+    assert backfill.run()["retitled"] == 1
+
+
+def test_a_download_titled_facebook_is_named_from_the_signed_out_page(
+    db, make_user, monkeypatch, tmp_path
+):
+    # The whole download path with yt-dlp and the media tools faked: the signed-in read gives only
+    # the placeholder, and the file and the download's name get the post's text.
+    seen = _fake_ydl(monkeypatch, _PUBLIC)
+    monkeypatch.setattr(settings, "files_root", str(tmp_path))
+    monkeypatch.setattr(pipeline.urlguard, "check_url", lambda url: None)
+    monkeypatch.setattr(pipeline, "_ensure_phone_safe", lambda _j, produced, *_a: produced)
+    monkeypatch.setattr(
+        pipeline.probe, "resolve_media_facts", lambda produced, info: ("h264", "aac", 720, 1280, 9)
+    )
+    monkeypatch.setattr(pipeline.editmod, "thumbnail_to_jpg", lambda *a: None)
+    monkeypatch.setattr(pipeline.editmod, "ensure_poster", lambda *a: None)
+    owner = make_user()
+    asset = MediaAsset(
+        source_kind="url", source_ref=_URL, format_sig="fb", status="downloading", ref_count=1
+    )
+    db.add(asset)
+    db.flush()
+    job = DownloadJob(
+        user_id=owner.id,
+        asset_id=asset.id,
+        source_kind="url",
+        source_ref=_URL,
+        status="running",
+        queue_pos=0,
+        profile_snapshot={},
+    )
+    db.add(job)
+    db.commit()
+
+    def signed_in_read(job_id, asset_id, url, spec, staging, adapter, **kw):
+        f = staging / "1860682468422402.mp4"
+        f.write_bytes(b"v" * 100)
+        return {
+            "id": "1860682468422402",
+            "title": "Facebook",
+            "uploader": "Work dot exe",
+            "webpage_url": _PAGE,
+            "requested_downloads": [{"filepath": str(f)}],
+        }
+
+    monkeypatch.setattr(pipeline, "_extract_with_fallback", signed_in_read)
+    pipeline._download(job.id, asset.id, "url", _URL, {}, owner.id)
+
+    # The signed-out read goes to the page yt-dlp read, not the link queued: a group post's link
+    # resolves to its video, and signed out the post itself is the login wall.
+    assert [r["url"] for r in seen] == [_PAGE]
+    db.expire_all()
+    assert db.get(DownloadJob, job.id).status == "done"
+    assert db.get(MediaAsset, asset.id).title == "sorry not helping"
+    assert db.get(DownloadJob, job.id).display_name == "sorry not helping"

backend/tests/test_failure_lines.py

@@ -368,7 +368,7 @@ def test_the_metadata_backfill_names_the_asset_and_not_the_download(sink, monkey
             )
 
     monkeypatch.setattr(backfill.yt_dlp, "YoutubeDL", _Refusing)
-    assert backfill._extract_meta(url, adapters.YouTubeAdapter(), 11) is None
+    assert backfill.extract_meta(url, adapters.YouTubeAdapter(), 11) is None
 
     lines = [o for o in sink.objects() if "meta extract failed" in o["msg"]]
     assert lines and all("dQw4w9WgXcQ" not in json.dumps(o) for o in lines)
@@ -393,7 +393,7 @@ def test_the_metadata_backfill_takes_out_a_generic_name_whatever_it_holds(sink,
             raise yt_dlp.utils.DownloadError("ERROR: [generic] Our Trip: Day 1: Unable to download")
 
     monkeypatch.setattr(backfill.yt_dlp, "YoutubeDL", _Refusing)
-    assert backfill._extract_meta(url, adapters.SourceAdapter(), 11) is None
+    assert backfill.extract_meta(url, adapters.SourceAdapter(), 11) is None
 
     lines = [o for o in sink.objects() if "meta extract failed" in o["msg"]]
     assert lines and all("Day 1" not in json.dumps(o) for o in lines)

backend/tests/test_folder_links.py

@@ -150,6 +150,7 @@ def test_a_password_folder_link_shows_nothing_until_unlocked(shelf, client):
     assert client.get(f"/api/public/watch/{token}").json() == {
         "needs_password": True,
         "kind": "folder",
+        "video": False,
     }
     bare = f"/api/public/watch/{token}/files/{shelf['inside'][0]}/file"
     assert client.get(bare).status_code == 403
@@ -312,7 +313,7 @@ def test_a_password_file_link_says_it_opens_a_file(shelf, client):
         .json()
     )
     meta = client.get(f"/api/public/watch/{made['token']}").json()
-    assert meta == {"needs_password": True, "kind": "file"}
+    assert meta == {"needs_password": True, "kind": "file", "video": True}
 
 
 def test_a_file_whose_bytes_are_gone_is_not_offered(shelf, client, db):

backend/tests/test_hls_reaper.py

@@ -5,11 +5,11 @@ POST /session: after the last playback, an abandoned session (its ffmpeg still w
 film, its directory a whole segmented copy of it) lived until somebody pressed play again.
 
 And it must not take a PAUSED viewer's session: a remux finishes long before the film does, and a
-paused player with a full buffer fetches nothing, so "finished and unfetched for 30 s" does not mean
+paused player with a full buffer fetches nothing, so "finished and unfetched for a while" does not mean
 "abandoned". An earlier fix 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. Its successor replaced the blanket retention with the signal that already existed: a player
-parked mid-item checkpoints its position every 10 s, paused or not, and that route says "still
+parked mid-item keeps checkpointing its position, paused or not, and that route says "still
 here" (it stops once the item is finished, where reaping is correct).
 
 Both call sites are pinned here, because the bug each time was that only one of them moved: the
@@ -81,8 +81,12 @@ class _Proc:
         return 0
 
 
+_PAST_THE_RULE = stream._FINISHED_IDLE_S + 5
+
+
 class _Session:
     def __init__(self, tmp_path, name: str, finished: bool, idle_s: float):
+        self.key = name
         self.dir = tmp_path / name
         self.dir.mkdir()
         self.proc = _Proc(finished)
@@ -97,11 +101,29 @@ def sessions(monkeypatch):
 
 
 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)
+    sessions["12345"] = _Session(tmp_path, "done", finished=True, idle_s=_PAST_THE_RULE)
     assert stream.reap_idle() == 1
     assert sessions == {}
 
 
+@pytest.mark.parametrize("idle_s", [65, 125])
+def test_a_heartbeat_throttled_to_once_a_minute_keeps_a_finished_session(
+    tmp_path, sessions, idle_s
+):
+    """A hidden page that makes no sound gets its timers cut to one a minute (measured on a paused and
+    on a muted player, about a minute after hiding), so that is the viewer's heartbeat there: the
+    reaper can see a beat over a minute old, and two if one is lost on the way."""
+    s = _Session(tmp_path, "hidden", finished=True, idle_s=idle_s)
+    sessions[(1, "12345")] = s
+    assert stream.reap_idle() == 0
+    assert (1, "12345") in sessions and s.dir.exists() and not s.proc.killed
+
+
+def test_an_abandoned_finished_session_is_still_gone_within_minutes(tmp_path, sessions):
+    sessions[(1, "12345")] = _Session(tmp_path, "gone", finished=True, idle_s=185)
+    assert stream.reap_idle() == 1
+
+
 def test_the_periodic_pass_still_reaps_what_nobody_has_touched_for_the_idle_limit(
     tmp_path, sessions
 ):
@@ -115,8 +137,32 @@ def test_the_periodic_pass_still_reaps_what_nobody_has_touched_for_the_idle_limi
     assert sessions == {}
 
 
+def test_every_reap_says_which_rule_took_the_session(tmp_path, sessions, caplog):
+    """A session that vanishes leaves the viewer a 410 and nothing else: with no line here, a live
+    stall could only ever be blamed on the reaper by inference."""
+    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
+    )
+    sessions["3"] = _Session(tmp_path, "kept", finished=False, idle_s=5)
+    with caplog.at_level("INFO"):
+        assert stream.reap_idle() == 2
+    reaped = {
+        r.attrs["key"]: r.attrs
+        for r in caplog.records
+        if getattr(r, "event", "") == "plex.stream.session_reaped"
+    }
+    assert set(reaped) == {"gone_done", "gone_live"}
+    assert reaped["gone_done"]["reason"] == "finished_idle"
+    assert reaped["gone_live"]["reason"] == "idle"
+    assert reaped["gone_done"]["idle_s"] == pytest.approx(stream._SESSION_IDLE_S - 5, abs=2)
+    assert reaped["gone_live"]["idle_s"] == pytest.approx(stream._SESSION_IDLE_S + 5, abs=2)
+
+
 def test_touching_a_session_keeps_it_through_the_short_rule(tmp_path, sessions):
-    s = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    s = _Session(tmp_path, "paused", finished=True, idle_s=_PAST_THE_RULE)
     sessions[(1, "12345")] = s
     stream.touch_session(1, "12345")
     assert stream.reap_idle() == 0
@@ -159,7 +205,7 @@ def test_a_paused_viewers_checkpoint_keeps_their_session_alive(
     user = User(email="paused@example.com")
     db.add(user)
     db.commit()
-    s = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    s = _Session(tmp_path, "paused", finished=True, idle_s=_PAST_THE_RULE)
     sessions[(user.id, "paused1")] = s
     resp = _client(db, user, override_dep).post(
         f"/api/plex/item/{it.rating_key}/progress",
@@ -174,7 +220,7 @@ def test_starting_a_session_leaves_another_viewers_paused_one_alone(
     db, monkeypatch, tmp_path, sessions, override_dep
 ):
     """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
+    walked the WHOLE registry with the finished rule, so pressing play on any item killed a
     paused viewer's session — the very case the retention fix set out to protect."""
     monkeypatch.setattr(state, "_configured_cache", True)
     monkeypatch.setattr(plex_paths, "local_media_path", lambda db_, fp: "/local/a.mkv")
@@ -182,7 +228,7 @@ def test_starting_a_session_leaves_another_viewers_paused_one_alone(
     user = User(email="starter@example.com")
     db.add(user)
     db.commit()
-    paused = _Session(tmp_path, "paused", finished=True, idle_s=90)
+    paused = _Session(tmp_path, "paused", finished=True, idle_s=_PAST_THE_RULE)
     sessions[(999, "someone-else")] = paused
 
     def fake_start(db_, item, user_id, start, audio=None, aoff=0.0, multi=False, transcode=False):

backend/tests/test_hls_teardown.py

@@ -0,0 +1,158 @@
+"""Tearing a session down does not stall everybody else's playback.
+
+Every segment request (`current_session`) and every checkpoint (`touch_session`) takes the one
+registry `_lock`. Stopping a session waits up to 3 s for its ffmpeg to exit and then deletes a whole
+segmented film, ~1200 files — and that used to happen under the same lock, so one viewer's seek, a
+cap cull or a reap pass held up every other viewer's HLS requests for seconds, each one a parked
+threadpool worker and its pooled DB connection.
+
+What still has to be atomic is pinned too: a session directory is reused for the same item, offset
+and tag, so a new session on that path must not start before the old ffmpeg — which writes by path
+— has exited.
+"""
+
+import threading
+import time
+
+import pytest
+
+from app.plex import stream
+
+
+class _SlowProc:
+    """An ffmpeg that takes a while to exit after TERM: `wait` blocks until `exited` is set."""
+
+    def __init__(self, order: list[str], name: str):
+        self.order = order
+        self.name = name
+        self.waiting = threading.Event()
+        self.exited = threading.Event()
+
+    def poll(self):
+        return 0 if self.exited.is_set() else None
+
+    def terminate(self):
+        pass
+
+    def kill(self):
+        self.exited.set()
+
+    def wait(self, timeout=None):
+        self.waiting.set()
+        if not self.exited.wait(timeout):
+            raise stream.subprocess.TimeoutExpired("ffmpeg", timeout)
+        self.order.append(f"{self.name} exited")
+        return 0
+
+
+class _Session:
+    def __init__(self, directory, proc, key: str):
+        self.id = f"sid-{key}"
+        self.key = key
+        self.dir = directory
+        self.proc = proc
+        self.last_access = time.time()
+        self.transcode = False
+
+
+@pytest.fixture
+def sessions(monkeypatch):
+    live: dict = {}
+    monkeypatch.setattr(stream, "_sessions", live)
+    monkeypatch.setattr(stream, "_dying", {}, raising=False)
+    return live
+
+
+def test_stopping_a_session_does_not_hold_up_another_viewers_requests(tmp_path, sessions):
+    order: list[str] = []
+    slow = _SlowProc(order, "a")
+    d = tmp_path / "1_u1_0_0_+0.00"
+    d.mkdir()
+    (d / "seg_0.ts").write_bytes(b"x")
+    sessions[(1, "a")] = _Session(d, slow, "a")
+    sessions[(2, "b")] = _Session(tmp_path / "2_u2_0_0_+0.00", _SlowProc(order, "b"), "b")
+
+    stopper = threading.Thread(target=stream.stop_session, args=(1, "a", "sid-a"))
+    stopper.start()
+    try:
+        assert slow.waiting.wait(2.0), "the stop never waited for its ffmpeg"
+        got: list = []
+        reader = threading.Thread(target=lambda: got.append(stream.current_session(2, "b")))
+        reader.start()
+        reader.join(1.0)
+        assert not reader.is_alive(), "a segment request waited on another viewer's teardown"
+        assert got and got[0] is sessions[(2, "b")]
+    finally:
+        slow.exited.set()
+        stopper.join(5.0)
+    # The teardown still finishes: the session is gone and nothing of its directory is left behind.
+    assert (1, "a") not in sessions
+    assert sorted(p.name for p in tmp_path.iterdir()) == []
+
+
+def test_a_reap_pass_does_not_hold_up_another_viewers_requests(tmp_path, sessions):
+    order: list[str] = []
+    slow = _SlowProc(order, "a")
+    d = tmp_path / "1_u1_0_0_+0.00"
+    d.mkdir()
+    gone = _Session(d, slow, "a")
+    gone.last_access = time.time() - stream._SESSION_IDLE_S - 5
+    sessions[(1, "a")] = gone
+    sessions[(2, "b")] = _Session(tmp_path / "2_u2_0_0_+0.00", _SlowProc(order, "b"), "b")
+
+    reaper = threading.Thread(target=stream.reap_idle)
+    reaper.start()
+    try:
+        assert slow.waiting.wait(2.0), "the reap never waited for its ffmpeg"
+        toucher = threading.Thread(target=stream.touch_session, args=(2, "b"))
+        toucher.start()
+        toucher.join(1.0)
+        assert not toucher.is_alive(), "a checkpoint waited on another viewer's teardown"
+    finally:
+        slow.exited.set()
+        reaper.join(5.0)
+    assert list(sessions) == [(2, "b")]
+    assert not d.exists()
+
+
+class _FakeItem:
+    rating_key = "12345"
+    file_path = "/media/movie.mkv"
+    playable = "remux"
+    codec_video = "h264"
+
+
+def test_a_new_session_on_a_dying_ones_path_starts_only_after_it_exited(
+    tmp_path, sessions, monkeypatch
+):
+    """The same item at the same second gets the same directory. The old ffmpeg writes by PATH, so
+    while it is still winding down after TERM it can write a segment — or, on a clean exit, a final
+    playlist with ENDLIST — into the NEW session's directory."""
+    order: list[str] = []
+    procs = iter([_SlowProc(order, "old"), _SlowProc(order, "new")])
+
+    def popen(*a, **k):
+        order.append("popen")
+        return next(procs)
+
+    monkeypatch.setattr(stream, "_HLS_ROOT", tmp_path)
+    src = tmp_path / "movie.mkv"
+    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", popen)
+    monkeypatch.setattr(stream, "wait_for", lambda *a, **k: True)
+
+    first = stream.start_session(db=None, user_id=7, item=_FakeItem(), start_s=0.0)
+    assert first is not None
+    stopper = threading.Thread(target=stream.stop_session, args=(7, "12345", first.id))
+    stopper.start()
+    assert first.proc.waiting.wait(2.0)
+    threading.Timer(0.3, first.proc.exited.set).start()
+    second = stream.start_session(db=None, user_id=7, item=_FakeItem(), start_s=0.0)
+    stopper.join(5.0)
+    assert second is not None and second.dir == first.dir
+    assert order.index("old exited") < order.index("popen", 1)
+    assert second.dir.is_dir(), "the old teardown deleted the new session's directory"
+    second.proc.exited.set()

backend/tests/test_http_details.py

@@ -1,53 +1,88 @@
-"""No refusal answers in a hand-written English sentence.
+"""No refusal answers in a way the client cannot say.
 
 The UI is bilingual and translates a structured `detail` (`{code, reason, …}`), but a string detail it
 can only print as it came — so ~150 of them reached the Hungarian UI verbatim, in the blocking error
 dialog and on every inline surface that shows `HttpError.detail`. `app/refusal.py` is the family they
-became; this test is what keeps a new one from being written the old way. Pure: it reads the sources.
+became; this test is what keeps a new one from being written the old way. It reads the same slots the
+refusal scan does (`refusal_sites.detail_slots`), so the two cannot disagree on where a detail is sent.
+Pure: it reads the sources.
 """
 
-import ast
-import pathlib
+import textwrap
 
-APP = pathlib.Path(__file__).resolve().parents[1] / "app"
+from tests.refusal_sites import Scan, app_sources
+
+# Answers that are no refusal of the app's, by the function they are sent from: the client shows a
+# detail only when it is an object (`lib/api/core.ts`), so these read as its generic line, and no screen
+# needs more from them.
+NO_REFUSAL = {
+    ("main.py", "setup_gate"): "the 503 before setup: the setup screen is what the user sees",
+    ("main.py", "spa_fallback"): "a bare 404 for an api path no route matches: no screen calls one",
+    ("main.py", "_validation_error"): "FastAPI's own 422 list: a body the client itself got wrong",
+    ("routes/diagnostics.py", "_parsed_events"): "the client-events beacon's 422: nothing shows it",
+}
 
 
-def _is_text(node: ast.AST) -> bool:
-    """A detail that is a sentence: a literal, an f-string, `str(exc)`, or `"…" + x`."""
-    if isinstance(node, ast.Constant) and isinstance(node.value, str):
-        return True
-    if isinstance(node, ast.JoinedStr):
-        return True
-    if isinstance(node, ast.Call) and getattr(node.func, "id", "") == "str":
-        return True
-    if isinstance(node, ast.BoolOp):
-        return any(_is_text(v) for v in node.values)
-    if isinstance(node, ast.BinOp):
-        return _is_text(node.left) or _is_text(node.right)
-    return False
+def _offenders(sources: dict[str, str]) -> list[str]:
+    return [
+        f"{path}:{line}"
+        for path, line, fn in Scan(sources).other_details()
+        if (path, fn) not in NO_REFUSAL
+    ]
 
 
-def test_no_http_exception_carries_a_sentence():
-    offenders = []
-    for path in sorted(APP.rglob("*.py")):
-        for node in ast.walk(ast.parse(path.read_text(encoding="utf-8"))):
-            if not (
-                isinstance(node, ast.Call)
-                and getattr(node.func, "id", getattr(node.func, "attr", "")) == "HTTPException"
-            ):
-                continue
-            kw = {k.arg: k.value for k in node.keywords}
-            detail = kw.get("detail", node.args[1] if len(node.args) > 1 else None)
-            if detail is not None and _is_text(detail):
-                offenders.append(f"{path.relative_to(APP).as_posix()}:{node.lineno}")
+def test_every_detail_is_one_the_client_can_say():
+    offenders = _offenders(app_sources())
     assert offenders == [], (
-        "a refusal with an English sentence for a detail — raise `refused(status, reason)` "
-        f"(app/refusal.py) and name the reason in both locales: {offenders}"
+        "a refusal the client can only answer with its generic line — send `{code, reason}` "
+        f"(`refused(status, reason)`), or list it in NO_REFUSAL with why: {offenders}"
     )
 
 
-def test_the_scan_sees_a_sentence_when_there_is_one():
+def test_the_detail_scan_sees_each_shape_the_client_cannot_say():
     """A guard that matches nothing is green over nothing."""
-    sample = ast.parse('HTTPException(status_code=400, detail=f"bad {x}")').body[0].value
-    assert _is_text(sample.keywords[1].value)
-    assert not _is_text(ast.parse('{"code": "refused", "reason": "x"}').body[0].value)
+    src = textwrap.dedent(
+        """
+        def f(x):
+            raise HTTPException(409, detail={"reason": "view_name_taken"})
+        def g(x):
+            raise HTTPException(409, dict(reason="taken"))
+        def h(x):
+            raise HTTPException(status_code=404)
+        def i(x):
+            return JSONResponse({"detail": "This instance isn't set up yet."}, status_code=503)
+        def j(x):
+            return JSONResponse(content={"detail": {"reason": "x"}}, status_code=409)
+        def k(x):
+            raise HTTPException(400, detail=f"bad {x}")
+        def l(x):
+            raise HTTPException(404, None)
+        def n(x, msg):
+            raise HTTPException(400, detail=msg)
+        def o(x):
+            raise HTTPException(400, detail=["a sentence"])
+        def p(x):
+            raise HTTPException(400, detail=describe(x))
+        def q(x):
+            raise HTTPException(400, detail={"code": "a"} if x else "text")
+        def r(x):
+            raise HTTPException(400, detail=nothing(x))
+        def nothing(x):
+            pass
+        def ok(x):
+            raise HTTPException(409, {"code": "refused", "reason": "x"})
+            raise HTTPException(409, detail=quota(x))
+            raise HTTPException(409, detail={"code": "a"} if x else {"code": "b"})
+            return JSONResponse({"detail": {"code": "too_large"}}, status_code=413)
+            return JSONResponse({"ok": True})
+        def quota(x):
+            return {"code": "quota", "reason": "files"}
+        def setup_gate(x):
+            return JSONResponse({"detail": "listed"}, status_code=503)
+        """
+    )
+    lines = (3, 5, 7, 9, 11, 13, 15, 17, 19, 21, 23, 25)
+    assert _offenders({"main.py": src}) == [f"main.py:{n}" for n in lines]
+    # A file whose code dicts are data still answers its refusals in a way the client can say.
+    data = 'def f():\n    raise HTTPException(400, "text")\n'
+    assert _offenders({"plex/tmdb.py": data}) == ["plex/tmdb.py:2"]

backend/tests/test_me_search_source.py

@@ -1,5 +1,6 @@
 """`/api/me` names the live-search source, so the search button's tooltip can say what a search costs
-under the source that actually runs (the default website source spends no API quota)."""
+under the source that actually runs (the default website source spends no API quota), and says
+whether live search and related videos are on at all."""
 
 from app import sysconfig
 
@@ -24,3 +25,24 @@ def test_me_names_the_running_search_source(client, db, make_user):
     sysconfig.set_value(db, "search_source", "api")
     db.commit()
     assert _me(client)["search_source"] == "api"
+
+
+def test_me_says_whether_live_search_and_related_videos_are_on(client, db, make_user):
+    # A daily limit of 0 turns the feature off; the UI leaves it out instead of offering a refusal.
+    user = make_user(password=_PW)
+    login = client.post("/auth/password-login", json={"email": user.email, "password": _PW})
+    assert login.status_code == 200
+
+    me = _me(client)
+    assert (me["search_enabled"], me["related_enabled"]) == (True, True)
+
+    sysconfig.set_value(db, "search_daily_limit_per_user", 0)
+    db.commit()
+    me = _me(client)
+    assert (me["search_enabled"], me["related_enabled"]) == (False, True)
+
+    sysconfig.set_value(db, "search_daily_limit_per_user", 5)
+    sysconfig.set_value(db, "related_daily_limit_per_user", 0)
+    db.commit()
+    me = _me(client)
+    assert (me["search_enabled"], me["related_enabled"]) == (True, False)

backend/tests/test_name_taken_detail.py

@@ -0,0 +1,46 @@
+"""A rename onto a name already taken says WHICH name is taken: the one asked for, not the row's
+old name (the rollback that follows the conflict puts the old name back on the row). DB lane.
+"""
+
+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 User
+
+
+def _client(db, monkeypatch, override_dep):
+    u = User(email="taken@example.com")
+    db.add(u)
+    db.commit()
+    monkeypatch.setattr(
+        state, "_configured_cache", True
+    )  # the request gate 503s an unconfigured app
+    override_dep(get_db, db.info["request"])
+    override_dep(current_user, lambda: u)
+    return TestClient(app)
+
+
+def test_renaming_a_view_onto_a_taken_name_names_the_taken_one(db, monkeypatch, override_dep):
+    c = _client(db, monkeypatch, override_dep)
+    gaming = c.post("/api/saved-views", json={"name": "gaming", "filters": {}, "source": "feed"})
+    assert gaming.status_code == 200
+    hh = c.post("/api/saved-views", json={"name": "hh", "filters": {}, "source": "feed"}).json()
+
+    r = c.patch(f"/api/saved-views/{hh['id']}", json={"name": "gaming"})
+
+    assert r.status_code == 409
+    assert r.json()["detail"] == {"code": "refused", "reason": "view_name_taken", "name": "gaming"}
+
+
+def test_renaming_a_tag_onto_a_taken_name_names_the_taken_one(db, monkeypatch, override_dep):
+    c = _client(db, monkeypatch, override_dep)
+    assert c.post("/api/tags", json={"name": "music"}).status_code == 200
+    news = c.post("/api/tags", json={"name": "news"}).json()
+
+    r = c.patch(f"/api/tags/{news['id']}", json={"name": "music"})
+
+    assert r.status_code == 409
+    assert r.json()["detail"] == {"code": "refused", "reason": "tag_name_taken", "name": "music"}

backend/tests/test_owner_scoping.py

@@ -75,9 +75,9 @@ def test_trimming_read_notifications_trims_only_mine(db, make_user):
 
 def test_todays_actions_count_only_mine(db, make_user):
     me, other = make_user(), make_user()
-    quota.log_action(me.id, quota.QuotaAction.VIDEOS_SEARCH)
-    quota.log_action(other.id, quota.QuotaAction.VIDEOS_SEARCH)
-    quota.log_action(other.id, quota.QuotaAction.VIDEOS_SEARCH)
+    quota.claim_action(me.id, quota.QuotaAction.VIDEOS_SEARCH, 5)
+    quota.claim_action(other.id, quota.QuotaAction.VIDEOS_SEARCH, 5)
+    quota.claim_action(other.id, quota.QuotaAction.VIDEOS_SEARCH, 5)
     assert quota.actions_today(db, me.id, quota.QuotaAction.VIDEOS_SEARCH) == 1
 
 
@@ -181,7 +181,7 @@ def test_clearing_a_video_leaves_another_users_state(db, make_user, as_user):
     _videos(db, "v1")
     db.add(VideoState(user_id=other.id, video_id="v1", status="hidden", position_seconds=90))
     db.commit()
-    assert as_user(me).delete("/api/videos/v1/state").status_code == 200
+    assert as_user(me).delete("/api/videos/v1/progress").status_code == 200
     assert _video_state(db, other) == ("hidden", 90)
 
 

backend/tests/test_playlist_add_position.py

@@ -1,4 +1,4 @@
-"""Adding a video AT a position: the list page's "Undo" of a removal.
+"""Putting a video back AT a position: the list page's "Undo" of a removal.
 
 The row has to come back where it was in ONE request. The two-call shape (append, then send the
 whole order) leaves it at the end of the list whenever the second call fails, and the reorder would
@@ -38,14 +38,17 @@ def _ids(db, pl_id):
     ]
 
 
-def _add(client, pl_id, body):
-    return client.post(f"/api/playlists/{pl_id}/items", json=body)
+def _restore(client, pl_id, video_id, position):
+    return client.post(
+        f"/api/playlists/{pl_id}/items/restore",
+        json={"video_ids": [video_id], "positions": [position]},
+    )
 
 
 def test_a_position_puts_the_video_back_in_its_place(db, make_user, as_user):
     user = make_user()
     pl = _seed(db, user, ["a", "b", "c"])
-    r = _add(as_user(user), pl.id, {"video_id": "vX", "position": 1})
+    r = _restore(as_user(user), pl.id, "vX", 1)
     assert r.status_code == 200
     assert _ids(db, pl.id) == ["a", "vX", "b", "c"]
 
@@ -54,36 +57,37 @@ def test_the_position_counts_rows_not_stored_numbers(db, make_user, as_user):
     # A removal leaves a gap (0, 5, 9): index 2 is before the THIRD row, not "position 2".
     user = make_user()
     pl = _seed(db, user, ["a", "b", "c"], positions=[0, 5, 9])
-    _add(as_user(user), pl.id, {"video_id": "vX", "position": 2})
+    _restore(as_user(user), pl.id, "vX", 2)
     assert _ids(db, pl.id) == ["a", "b", "vX", "c"]
 
 
 def test_a_position_past_the_end_appends(db, make_user, as_user):
     user = make_user()
     pl = _seed(db, user, ["a", "b"])
-    _add(as_user(user), pl.id, {"video_id": "vX", "position": 40})
+    _restore(as_user(user), pl.id, "vX", 40)
     assert _ids(db, pl.id) == ["a", "b", "vX"]
 
 
-def test_no_position_still_appends(db, make_user, as_user):
+def test_an_add_appends(db, make_user, as_user):
     user = make_user()
     pl = _seed(db, user, ["a", "b"])
-    _add(as_user(user), pl.id, {"video_id": "vX"})
+    r = as_user(user).post(f"/api/playlists/{pl.id}/items", json={"video_id": "vX"})
+    assert r.status_code == 200
     assert _ids(db, pl.id) == ["a", "b", "vX"]
 
 
 def test_a_video_already_in_the_list_does_not_move(db, make_user, as_user):
-    # The add is idempotent; a position must not turn it into a reorder.
+    # A restore is idempotent; a position must not turn it into a reorder.
     user = make_user()
     pl = _seed(db, user, ["a", "b", "c"])
-    _add(as_user(user), pl.id, {"video_id": "c", "position": 0})
+    _restore(as_user(user), pl.id, "c", 0)
     assert _ids(db, pl.id) == ["a", "b", "c"]
 
 
 def test_a_negative_position_is_refused(db, make_user, as_user):
     user = make_user()
     pl = _seed(db, user, ["a"])
-    r = _add(as_user(user), pl.id, {"video_id": "vX", "position": -1})
+    r = _restore(as_user(user), pl.id, "vX", -1)
     assert r.status_code == 422
     assert _ids(db, pl.id) == ["a"]
 
@@ -101,6 +105,6 @@ def test_putting_a_removed_video_back_leaves_a_linked_list_clean(db, make_user,
     assert client.delete(f"/api/playlists/{pl.id}/items/b").status_code == 200
     db.expire_all()
     assert db.get(Playlist, pl.id).dirty is True
-    _add(client, pl.id, {"video_id": "b", "position": 1})
+    _restore(client, pl.id, "b", 1)
     db.expire_all()
     assert db.get(Playlist, pl.id).dirty is False

backend/tests/test_playlist_bulk.py

@@ -0,0 +1,640 @@
+"""Many videos at once: remove, move, and the Undo of each. Every test reads both lists after the call,
+as `test_playlist_move` does: a half-applied move is the failure these routes exist to rule out."""
+
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from sqlalchemy import select
+
+from app.catalog.models import Channel, Video
+from app.reader import queries, service
+from app.reader.models import Playlist, PlaylistItem
+from app.sync.playlists import current_fingerprint
+
+
+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):
+    db.expire_all()
+    return list(
+        db.execute(
+            select(PlaylistItem.video_id)
+            .where(PlaylistItem.playlist_id == pl_id)
+            .order_by(PlaylistItem.position)
+        ).scalars()
+    )
+
+
+def _positions(db, pl_id):
+    db.expire_all()
+    return list(
+        db.execute(
+            select(PlaylistItem.position)
+            .where(PlaylistItem.playlist_id == pl_id)
+            .order_by(PlaylistItem.position)
+        ).scalars()
+    )
+
+
+def test_remove_bulk_takes_out_the_named_videos_and_counts_what_was_there(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c", "d"])
+    pl = _playlist(db, user, "L", ["a", "b", "c", "d"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/remove-bulk", json={"video_ids": ["b", "d", "gone"]}
+    )
+
+    assert r.status_code == 200
+    assert r.json() == {"ok": True, "playlist_id": pl.id, "removed": ["b", "d"]}
+    assert _ids(db, pl.id) == ["a", "c"]
+
+
+def test_remove_bulk_of_nothing_leaves_the_list_untouched(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    pl = _playlist(db, user, "L", ["a"])
+    stamp = datetime.now(timezone.utc) - timedelta(days=3)
+    pl.updated_at = stamp
+    db.commit()
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/remove-bulk", json={"video_ids": ["gone"]}
+    )
+
+    assert r.json()["removed"] == []
+    db.expire_all()
+    assert db.get(Playlist, pl.id).updated_at == stamp
+
+
+def test_restore_puts_the_videos_back_at_their_places(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c", "d"])
+    pl = _playlist(db, user, "L", ["b", "d"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/restore",
+        json={"video_ids": ["c", "a"], "positions": [2, 0]},
+    )
+
+    assert r.json() == {"ok": True, "playlist_id": pl.id, "added": 2}
+    assert _ids(db, pl.id) == ["a", "b", "c", "d"]
+    assert _positions(db, pl.id) == [0, 1, 2, 3]
+
+
+def test_restore_leaves_a_video_already_back_where_it_is_and_skips_one_the_catalog_lost(
+    db, make_user, as_user
+):
+    user = make_user()
+    _seed_videos(db, ["a", "b"])
+    pl = _playlist(db, user, "L", ["b", "a"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/restore",
+        json={"video_ids": ["a", "lost"], "positions": [0, 1]},
+    )
+
+    assert r.json()["added"] == 0
+    assert _ids(db, pl.id) == ["b", "a"]
+
+
+@pytest.mark.parametrize(
+    "body",
+    [
+        {"video_ids": ["a"], "positions": []},
+        {"video_ids": ["a"], "positions": [0, 1]},
+        {"video_ids": ["a"], "positions": [-1]},
+    ],
+)
+def test_restore_refuses_positions_that_do_not_pair(db, make_user, as_user, body):
+    user = make_user()
+    pl = _playlist(db, user, "L", [])
+
+    assert as_user(user).post(f"/api/playlists/{pl.id}/items/restore", json=body).status_code == 422
+
+
+def test_move_bulk_lands_in_the_sources_order_whatever_order_they_were_picked_in(
+    db, make_user, as_user
+):
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c", "x"])
+    src = _playlist(db, user, "Source", ["a", "b", "c"])
+    dst = _playlist(db, user, "Target", ["x"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["c", "a"], "target_playlist_id": dst.id},
+    )
+
+    assert r.status_code == 200
+    assert r.json() == {
+        "ok": True,
+        "from_playlist_id": src.id,
+        "to_playlist_id": dst.id,
+        "moved": ["a", "c"],
+        "already_there": [],
+    }
+    assert _ids(db, src.id) == ["b"]
+    assert _ids(db, dst.id) == ["x", "a", "c"]
+
+
+def test_move_bulk_says_which_the_target_already_held_and_skips_one_already_gone(
+    db, make_user, as_user
+):
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c"])
+    src = _playlist(db, user, "Source", ["a", "b"])
+    dst = _playlist(db, user, "Target", ["b"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["a", "b", "c"], "target_playlist_id": dst.id},
+    )
+
+    assert r.json()["moved"] == ["a"]
+    assert r.json()["already_there"] == ["b"]
+    assert _ids(db, src.id) == []
+    assert _ids(db, dst.id) == ["b", "a"]
+
+
+def test_move_bulk_keeps_when_each_video_was_saved(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", ["a"])
+    dst = _playlist(db, user, "Target", [])
+    saved = datetime(2020, 1, 2, tzinfo=timezone.utc)
+    row = db.scalar(select(PlaylistItem).where(PlaylistItem.playlist_id == src.id))
+    row.added_at = saved
+    db.commit()
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["a"], "target_playlist_id": dst.id},
+    )
+    assert r.status_code == 200
+
+    db.expire_all()
+    moved = db.scalar(select(PlaylistItem).where(PlaylistItem.playlist_id == dst.id))
+    assert moved.added_at == saved
+
+
+def test_a_target_that_gained_nothing_does_not_rise_in_the_recently_changed_sort(
+    db, make_user, as_user
+):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", ["a"])
+    dst = _playlist(db, user, "Target", ["a"])
+    stamp = datetime.now(timezone.utc) - timedelta(days=3)
+    dst.updated_at = stamp
+    db.commit()
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["a"], "target_playlist_id": dst.id},
+    )
+    assert r.status_code == 200
+
+    db.expire_all()
+    assert db.get(Playlist, dst.id).updated_at == stamp
+
+
+def test_move_bulk_into_the_same_list_is_refused(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    pl = _playlist(db, user, "L", ["a"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/move-bulk",
+        json={"video_ids": ["a"], "target_playlist_id": pl.id},
+    )
+
+    assert r.status_code == 400
+    assert r.json()["detail"] == {"code": "playlist_move", "reason": "same_playlist"}
+    assert _ids(db, pl.id) == ["a"]
+
+
+def test_move_bulk_marks_a_linked_list_on_both_sides_as_unsynced(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", ["a"], yt_playlist_id="PLs")
+    dst = _playlist(db, user, "Target", [], yt_playlist_id="PLd")
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["a"], "target_playlist_id": dst.id},
+    )
+    assert r.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_undo_move_restores_both_lists_as_they_stood(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c", "d"])
+    src = _playlist(db, user, "Source", ["a", "b", "c", "d"])
+    dst = _playlist(db, user, "Target", ["c"])
+    client = as_user(user)
+
+    moved = client.post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["a", "c"], "target_playlist_id": dst.id},
+    ).json()
+    assert _ids(db, src.id) == ["b", "d"]
+    assert _ids(db, dst.id) == ["c", "a"]
+
+    r = client.post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={
+            "from_playlist_id": dst.id,
+            "moved": moved["moved"],
+            "already_there": moved["already_there"],
+            "positions": [0, 2],
+        },
+    )
+
+    assert r.json() == {"ok": True, "playlist_id": src.id, "added": 2}
+    assert _ids(db, src.id) == ["a", "b", "c", "d"]
+    # The one the target held before the move stays there.
+    assert _ids(db, dst.id) == ["c"]
+
+
+def test_undo_move_keeps_when_each_video_was_saved(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", [])
+    dst = _playlist(db, user, "Target", ["a"])
+    saved = datetime(2020, 1, 2, tzinfo=timezone.utc)
+    row = db.scalar(select(PlaylistItem).where(PlaylistItem.playlist_id == dst.id))
+    row.added_at = saved
+    db.commit()
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": ["a"], "positions": [0]},
+    )
+
+    assert r.json()["added"] == 1
+    db.expire_all()
+    back = db.scalar(select(PlaylistItem).where(PlaylistItem.playlist_id == src.id))
+    assert back.added_at == saved
+
+
+def test_undo_move_leaves_a_video_that_moved_on_where_it_is(db, make_user, as_user):
+    """A to B, then B to C, then the first Undo: the video is not in the list the Undo takes it from,
+    and coming back would leave it in two lists the reader never put it in."""
+    user = make_user()
+    _seed_videos(db, ["a", "b"])
+    src = _playlist(db, user, "Source", [])
+    dst = _playlist(db, user, "Target", ["b"])
+    third = _playlist(db, user, "Third", ["a"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": ["a", "b"], "positions": [0, 1]},
+    )
+
+    assert r.json()["added"] == 1
+    assert _ids(db, src.id) == ["b"]
+    assert _ids(db, dst.id) == []
+    assert _ids(db, third.id) == ["a"]
+
+
+def test_an_undo_closes_up_the_places_of_a_video_that_stayed_out(db, make_user, as_user):
+    """Each index counts the rows put back before it, so one that stays out moves the rest up."""
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c", "d"])
+    src = _playlist(db, user, "Source", ["c", "d"])
+    dst = _playlist(db, user, "Target", ["b"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": ["a", "b"], "positions": [0, 1]},
+    )
+
+    assert r.json()["added"] == 1
+    assert _ids(db, src.id) == ["b", "c", "d"]
+
+
+def test_a_restore_closes_up_the_places_of_a_video_the_catalog_lost(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["b", "c", "d"])
+    pl = _playlist(db, user, "L", ["c", "d"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/restore",
+        json={"video_ids": ["lost", "b"], "positions": [0, 1]},
+    )
+
+    assert r.json()["added"] == 1
+    assert _ids(db, pl.id) == ["b", "c", "d"]
+
+
+def test_undo_move_takes_a_video_out_of_the_target_when_the_source_has_it_again(
+    db, make_user, as_user
+):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", ["a"])
+    dst = _playlist(db, user, "Target", ["a"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": ["a"], "positions": [0]},
+    )
+
+    assert r.json()["added"] == 0
+    assert _ids(db, src.id) == ["a"]
+    assert _ids(db, dst.id) == []
+
+
+@pytest.mark.parametrize(
+    ("path", "body", "gone", "reason"),
+    [
+        ("move-bulk", {"video_ids": ["a"], "target_playlist_id": "dst"}, "dst", "move_target"),
+        ("move-bulk", {"video_ids": ["a"], "target_playlist_id": "dst"}, "src", "playlist"),
+        (
+            "undo-move",
+            {"from_playlist_id": "dst", "moved": ["a"], "positions": [0]},
+            "src",
+            "playlist",
+        ),
+        (
+            "undo-move",
+            {"from_playlist_id": "dst", "moved": ["a"], "positions": [0]},
+            "dst",
+            "move_target",
+        ),
+    ],
+)
+def test_a_list_deleted_before_the_lock_is_not_found(
+    db, make_user, as_user, monkeypatch, path, body, gone, reason
+):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", ["a"])
+    dst = _playlist(db, user, "Target", ["a"])
+    ids = {"src": src.id, "dst": dst.id}
+    body = {k: (dst.id if v == "dst" else v) for k, v in body.items()}
+    # Another tab's delete committed between the route's read and this lock.
+    monkeypatch.setattr(service, "lock_playlists", lambda _db, *got: set(got) - {ids[gone]})
+
+    r = as_user(user).post(f"/api/playlists/{src.id}/items/{path}", json=body)
+
+    assert r.status_code == 404
+    assert reason in str(r.json()["detail"])
+
+
+@pytest.mark.parametrize(
+    ("method", "path", "body"),
+    [
+        ("post", "items", {"video_id": "a"}),
+        ("delete", "items/a", None),
+        ("post", "items/remove-bulk", {"video_ids": ["a"]}),
+        ("post", "items/restore", {"video_ids": ["a"], "positions": [0]}),
+    ],
+)
+def test_a_one_list_write_finds_its_list_under_the_lock(
+    db, make_user, as_user, monkeypatch, method, path, body
+):
+    """Read with its lock, so a delete that won the row answers 404 rather than a foreign key's 500."""
+    user = make_user()
+    _seed_videos(db, ["a"])
+    pl = _playlist(db, user, "L", [])
+    real = queries.own_playlist
+
+    def locked_read_finds_nothing(db_, user_, playlist_id, *, lock=False):
+        return None if lock else real(db_, user_, playlist_id)
+
+    monkeypatch.setattr(queries, "own_playlist", locked_read_finds_nothing)
+    kw = {"json": body} if body is not None else {}
+
+    r = getattr(as_user(user), method)(f"/api/playlists/{pl.id}/{path}", **kw)
+
+    assert r.status_code == 404
+
+
+@pytest.mark.parametrize(
+    ("path", "body"),
+    [
+        ("items/remove-bulk", {"ids": ["a"]}),
+        ("items/move-bulk", {"ids": ["a"], "target_playlist_id": 1}),
+        ("items/undo-move", {"ids": ["a"], "from_playlist_id": 1}),
+    ],
+)
+def test_a_body_without_its_videos_is_refused_rather_than_acting_on_none(
+    db, make_user, as_user, path, body
+):
+    user = make_user()
+    pl = _playlist(db, user, "L", [])
+
+    assert as_user(user).post(f"/api/playlists/{pl.id}/{path}", json=body).status_code == 422
+
+
+def test_an_undo_of_only_videos_the_target_held_names_no_moved_ones(db, make_user, as_user):
+    """An empty `moved` is a real body: every video of the move was already in the target."""
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", [])
+    dst = _playlist(db, user, "Target", ["a"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": [], "already_there": ["a"], "positions": [0]},
+    )
+
+    assert r.json()["added"] == 1
+    assert _ids(db, src.id) == ["a"]
+    assert _ids(db, dst.id) == ["a"]
+
+
+def test_an_undo_within_one_list_is_refused_and_keeps_its_videos(db, make_user, as_user):
+    """A move refuses the same list twice, so no Undo of one exists; a row must not go for asking."""
+    user = make_user()
+    _seed_videos(db, ["a", "b"])
+    pl = _playlist(db, user, "L", ["a", "b"])
+
+    r = as_user(user).post(
+        f"/api/playlists/{pl.id}/items/undo-move",
+        json={"from_playlist_id": pl.id, "moved": ["a"], "positions": [0]},
+    )
+
+    assert r.status_code == 400
+    assert r.json()["detail"] == {"code": "playlist_move", "reason": "same_playlist"}
+    assert _ids(db, pl.id) == ["a", "b"]
+
+
+@pytest.mark.parametrize(
+    ("path", "key", "extra"),
+    [
+        ("items/restore", "video_ids", {}),
+        ("items/undo-move", "moved", {"from_playlist_id": None}),
+    ],
+)
+def test_two_videos_cannot_ask_for_one_place(db, make_user, as_user, path, key, extra):
+    user = make_user()
+    _seed_videos(db, ["a", "b", "c"])
+    pl = _playlist(db, user, "L", ["c"])
+    other = _playlist(db, user, "Other", ["a", "b"])
+    body = {key: ["a", "b"], "positions": [0, 0]}
+    body.update({k: other.id for k in extra})
+
+    r = as_user(user).post(f"/api/playlists/{pl.id}/{path}", json=body)
+
+    assert r.status_code == 422
+    assert _ids(db, pl.id) == ["c"]
+
+
+def test_a_reorder_without_its_videos_is_refused(db, make_user, as_user):
+    user = make_user()
+    pl = _playlist(db, user, "L", [])
+
+    assert as_user(user).put(f"/api/playlists/{pl.id}/order", json={"ids": []}).status_code == 422
+
+
+def _synced(db, pl):
+    pl.synced_fingerprint = current_fingerprint(db, pl)
+    pl.dirty = False
+    db.commit()
+
+
+def test_a_bulk_remove_and_its_undo_leave_a_linked_list_as_it_was(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a", "b"])
+    pl = _playlist(db, user, "L", ["a", "b"], yt_playlist_id="PLx")
+    _synced(db, pl)
+    client = as_user(user)
+
+    r = client.post(f"/api/playlists/{pl.id}/items/remove-bulk", json={"video_ids": ["a"]})
+    assert r.status_code == 200
+    db.expire_all()
+    assert db.get(Playlist, pl.id).dirty is True
+
+    r = client.post(
+        f"/api/playlists/{pl.id}/items/restore", json={"video_ids": ["a"], "positions": [0]}
+    )
+    assert r.status_code == 200
+    db.expire_all()
+    assert db.get(Playlist, pl.id).dirty is False
+
+
+def test_a_move_and_its_undo_leave_both_linked_lists_as_they_were(db, make_user, as_user):
+    user = make_user()
+    _seed_videos(db, ["a", "b"])
+    src = _playlist(db, user, "Source", ["a", "b"], yt_playlist_id="PLs")
+    dst = _playlist(db, user, "Target", ["b"], yt_playlist_id="PLd")
+    _synced(db, src)
+    _synced(db, dst)
+    client = as_user(user)
+
+    moved = client.post(
+        f"/api/playlists/{src.id}/items/move-bulk",
+        json={"video_ids": ["a"], "target_playlist_id": dst.id},
+    ).json()
+    assert moved["moved"] == ["a"]
+    db.expire_all()
+    assert db.get(Playlist, src.id).dirty is True
+    assert db.get(Playlist, dst.id).dirty is True
+
+    r = client.post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": ["a"], "positions": [0]},
+    )
+    assert r.status_code == 200
+    db.expire_all()
+    assert db.get(Playlist, src.id).dirty is False
+    assert db.get(Playlist, dst.id).dirty is False
+
+
+def test_undo_move_is_one_transaction(db, make_user, as_user, monkeypatch):
+    user = make_user()
+    _seed_videos(db, ["a"])
+    src = _playlist(db, user, "Source", [])
+    dst = _playlist(db, user, "Target", ["a"])
+
+    def boom(*a, **kw):
+        raise RuntimeError("second step failed")
+
+    monkeypatch.setattr(service, "_insert_at", boom)
+    client = as_user(user)
+    body = {"from_playlist_id": dst.id, "moved": ["a"], "already_there": [], "positions": [0]}
+    with pytest.raises(RuntimeError):
+        _ = client.post(f"/api/playlists/{src.id}/items/undo-move", json=body)
+
+    db.rollback()
+    assert _ids(db, dst.id) == ["a"]
+    assert _ids(db, src.id) == []
+
+
+def test_undo_move_refuses_positions_that_do_not_pair(db, make_user, as_user):
+    user = make_user()
+    src = _playlist(db, user, "Source", [])
+    dst = _playlist(db, user, "Target", [])
+
+    r = as_user(user).post(
+        f"/api/playlists/{src.id}/items/undo-move",
+        json={"from_playlist_id": dst.id, "moved": ["a"], "already_there": ["b"], "positions": [0]},
+    )
+
+    assert r.status_code == 422
+
+
+@pytest.mark.parametrize(
+    ("path", "body"),
+    [
+        ("remove-bulk", {"video_ids": ["a"]}),
+        ("restore", {"video_ids": ["a"], "positions": [0]}),
+        ("move-bulk", {"video_ids": ["a"], "target_playlist_id": 0}),
+        ("undo-move", {"from_playlist_id": 0, "moved": ["a"], "positions": [0]}),
+    ],
+)
+def test_another_accounts_list_is_not_found(db, make_user, as_user, path, body):
+    owner, other = make_user(), make_user()
+    _seed_videos(db, ["a"])
+    theirs = _playlist(db, owner, "Theirs", ["a"])
+    mine = _playlist(db, other, "Mine", [])
+    body = {
+        k: (mine.id if k in ("target_playlist_id", "from_playlist_id") else v)
+        for k, v in body.items()
+    }
+
+    r = as_user(other).post(f"/api/playlists/{theirs.id}/items/{path}", json=body)
+
+    assert r.status_code == 404
+    assert _ids(db, theirs.id) == ["a"]
+
+
+@pytest.mark.parametrize(
+    ("path", "key"), [("move-bulk", "target_playlist_id"), ("undo-move", "from_playlist_id")]
+)
+def test_the_other_list_of_a_move_must_be_the_callers_too(db, make_user, as_user, path, key):
+    owner, other = make_user(), make_user()
+    _seed_videos(db, ["a"])
+    theirs = _playlist(db, owner, "Theirs", ["a"])
+    mine = _playlist(db, other, "Mine", ["a"])
+    body = {"video_ids": ["a"], "moved": ["a"], "positions": [0], key: theirs.id}
+
+    r = as_user(other).post(f"/api/playlists/{mine.id}/items/{path}", json=body)
+
+    assert r.status_code == 404
+    assert "move_target" in str(r.json()["detail"])
+    assert _ids(db, theirs.id) == ["a"]
+    assert _ids(db, mine.id) == ["a"]

backend/tests/test_playlist_move.py

@@ -51,7 +51,8 @@ def _ids(db, pl_id):
 
 def _move(client, src, video_id, dst):
     return client.post(
-        f"/api/playlists/{src}/items/{video_id}/move", json={"target_playlist_id": dst}
+        f"/api/playlists/{src}/items/move-bulk",
+        json={"video_ids": [video_id], "target_playlist_id": dst},
     )
 
 
@@ -67,7 +68,8 @@ def test_move_leaves_the_video_in_exactly_one_list(db, make_user, as_user):
         "ok": True,
         "from_playlist_id": src.id,
         "to_playlist_id": dst.id,
-        "video_id": "v1",
+        "moved": ["v1"],
+        "already_there": [],
     }
     db.expire_all()
     assert _ids(db, src.id) == ["v2"]
@@ -116,8 +118,9 @@ def test_move_of_a_video_that_left_the_source_reports_it(db, make_user, as_user)
     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"}
+    assert r.status_code == 200
+    assert (r.json()["moved"], r.json()["already_there"]) == ([], [])
+    assert _ids(db, dst.id) == []
 
 
 def test_move_into_someone_elses_list_404s_and_changes_nothing(db, make_user, as_user):

backend/tests/test_playlist_position_lock.py

@@ -102,16 +102,24 @@ PLEX = PlexPlaylist.__table__.name
     "call",
     [
         lambda c, pid, other: c.post(f"/api/playlists/{pid}/items", json={"video_id": "v2"}),
-        lambda c, pid, other: c.post(
-            f"/api/playlists/{pid}/items", json={"video_id": "v2", "position": 0}
-        ),
         lambda c, pid, other: c.post("/api/playlists/watch-later", json={"video_id": "v2"}),
         lambda c, pid, other: c.post(
-            f"/api/playlists/{pid}/items/v1/move", json={"target_playlist_id": other}
+            f"/api/playlists/{pid}/items/move-bulk",
+            json={"video_ids": ["v1"], "target_playlist_id": other},
         ),
         lambda c, pid, other: c.put(f"/api/playlists/{pid}/order", json={"video_ids": ["v1"]}),
+        lambda c, pid, other: c.post(
+            f"/api/playlists/{pid}/items/remove-bulk", json={"video_ids": ["v1"]}
+        ),
+        lambda c, pid, other: c.post(
+            f"/api/playlists/{pid}/items/restore", json={"video_ids": ["v2"], "positions": [0]}
+        ),
+        lambda c, pid, other: c.post(
+            f"/api/playlists/{pid}/items/undo-move",
+            json={"from_playlist_id": other, "moved": ["v2"], "positions": [0]},
+        ),
     ],
-    ids=["add", "add-at", "watch-later", "move", "reorder"],
+    ids=["add", "watch-later", "move", "reorder", "remove-bulk", "restore", "undo-move"],
 )
 def test_a_youtube_playlist_write_locks_the_playlist(db, make_user, as_user, locks, call):
     user = make_user()
@@ -168,18 +176,35 @@ PLEX_ITEMS = PlexPlaylistItem.__table__.name
     "call",
     [
         lambda c, pid, other: c.post(f"/api/playlists/{pid}/items", json={"video_id": "v1"}),
-        lambda c, pid, other: c.post(
-            f"/api/playlists/{pid}/items", json={"video_id": "v2", "position": 0}
-        ),
         lambda c, pid, other: c.delete(f"/api/playlists/{pid}/items/v1"),
         lambda c, pid, other: c.post(
-            f"/api/playlists/{pid}/items/v1/move", json={"target_playlist_id": other}
+            f"/api/playlists/{pid}/items/move-bulk",
+            json={"video_ids": ["v1"], "target_playlist_id": other},
         ),
         lambda c, pid, other: c.put(f"/api/playlists/{pid}/order", json={"video_ids": ["v1"]}),
         # the ORM cascade deletes the items before the list row
         lambda c, pid, other: c.delete(f"/api/playlists/{pid}"),
+        lambda c, pid, other: c.post(
+            f"/api/playlists/{pid}/items/remove-bulk", json={"video_ids": ["v1"]}
+        ),
+        lambda c, pid, other: c.post(
+            f"/api/playlists/{pid}/items/restore", json={"video_ids": ["v2"], "positions": [0]}
+        ),
+        lambda c, pid, other: c.post(
+            f"/api/playlists/{pid}/items/undo-move",
+            json={"from_playlist_id": other, "moved": ["v2"], "positions": [0]},
+        ),
+    ],
+    ids=[
+        "add-present",
+        "remove",
+        "move",
+        "reorder",
+        "delete",
+        "remove-bulk",
+        "restore",
+        "undo-move",
     ],
-    ids=["add-present", "add-at", "remove", "move", "reorder", "delete"],
 )
 def test_a_youtube_item_write_locks_the_playlist_before_any_item(
     db, make_user, as_user, statements, call
@@ -193,14 +218,23 @@ def test_a_youtube_item_write_locks_the_playlist_before_any_item(
     assert _locked_before_items(statements, YT, YT_ITEMS), statements
 
 
-def test_a_move_locks_both_lists_in_one_ordered_statement(db, make_user, as_user, statements):
-    """Two moves A→B and B→A each locking "its" list first would lock crosswise."""
+@pytest.mark.parametrize(
+    ("path", "body"),
+    [
+        ("move-bulk", lambda other: {"video_ids": ["v1"], "target_playlist_id": other}),
+        ("undo-move", lambda other: {"from_playlist_id": other, "moved": ["v2"], "positions": [0]}),
+    ],
+    ids=["move", "undo"],
+)
+def test_a_move_locks_both_lists_in_one_ordered_statement(
+    db, make_user, as_user, statements, path, body
+):
+    """Two moves A→B and B→A each locking "its" list first would lock crosswise, and an Undo runs the
+    other way round from a move by its nature."""
     user = make_user()
     pid, other = _yt(db, user)
     statements.clear()
-    r = as_user(user).post(
-        f"/api/playlists/{pid}/items/v1/move", json={"target_playlist_id": other}
-    )
+    r = as_user(user).post(f"/api/playlists/{pid}/items/{path}", json=body(other))
     assert r.status_code == 200, r.text
     lock = _locked_before_items(statements, YT, YT_ITEMS)
     assert lock and "ORDER BY" in lock, lock

backend/tests/test_playlist_sync_claim.py

@@ -89,9 +89,13 @@ def test_a_claim_is_released_when_its_block_raises(db, make_user):
     except RuntimeError:
         pass
     # Asked of pg_locks, not by claiming again: a lock leaked on a pooled connection would be granted
-    # again to that same connection (advisory locks are re-entrant per session).
+    # again to that same connection (advisory locks are re-entrant per session). pg_locks is the whole
+    # server's, so only this database's: a parallel worker's own claim on the same id counted here.
     held = db.scalar(
-        text("SELECT count(*) FROM pg_locks WHERE locktype = 'advisory' AND objid = :id"),
+        text(
+            "SELECT count(*) FROM pg_locks WHERE locktype = 'advisory' AND objid = :id"
+            " AND database = (SELECT oid FROM pg_database WHERE datname = current_database())"
+        ),
         {"id": pl.id},
     )
     assert held == 0

backend/tests/test_plex_detail.py

@@ -219,6 +219,7 @@ def test_item_detail_movie_serves_from_row_despite_live_outage(db, monkeypatch,
         library_id=lib.id,
         kind="movie",
         title="The Godfather",
+        size_bytes=15_000_000_000,
         genres=["Crime", "Drama"],
         directors=["Francis Ford Coppola"],
         studio="Paramount",
@@ -238,6 +239,7 @@ def test_item_detail_movie_serves_from_row_despite_live_outage(db, monkeypatch,
     resp = _get(db, user, monkeypatch, override_dep, "/api/plex/item/m1")
     assert resp.status_code == 200, resp.text
     body = resp.json()
+    assert body["size_bytes"] == 15_000_000_000
     assert body["imdb_rating"] == 8.7
     assert body["imdb_id"] == "tt0068646"
     assert body["imdb_url"] == "https://www.imdb.com/title/tt0068646/"

backend/tests/test_plex_finish.py

@@ -13,7 +13,7 @@ from datetime import datetime, timedelta, timezone
 from sqlalchemy import select
 
 from app.db import SessionLocal
-from app.plex.models import PlexItem, PlexLibrary, PlexState
+from app.plex.models import PlexItem, PlexLibrary, PlexSeason, PlexShow, PlexState
 from app.plex import service as plex_service
 from app.routes.plex import playback
 
@@ -81,3 +81,150 @@ def test_the_finish_supersedes_a_resume_push_still_in_flight(db, as_user, make_u
     )
     assert r.json() == {"ok": True, "status": "watched", "position_seconds": 0}
     assert playback._resume_push_superseded(user.id, item.id, earlier) is True
+
+
+def test_a_checkpoint_sent_before_the_finish_does_not_land_on_the_watched_row(
+    db, as_user, make_user, monkeypatch
+):
+    """The 10 s tick posted at 2699 of 3000 s (not near the end) races the credits auto-skip's
+    "watched". When the mark commits first, the late checkpoint used to write its position onto the
+    watched row and schedule a resume push after the scrobble: Plex showed the item in progress, and
+    a Plex-authoritative pull imported it back."""
+    user = make_user()
+    item = _item(db)
+    monkeypatch.setattr(playback.plex_stream, "touch_session", lambda uid, key: None)
+    client = as_user(user)
+    assert client.post("/api/plex/item/m1/state", json={"status": "watched"}).status_code == 200
+
+    r = client.post(
+        "/api/plex/item/m1/progress", json={"position_seconds": 2699, "duration_seconds": 3000}
+    )
+    assert r.status_code == 200, r.text
+    assert r.json() == {"ok": True, "status": "watched", "position_seconds": 0}
+    db.expire_all()
+    st = db.execute(select(PlexState).where(PlexState.item_id == item.id)).scalars().one()
+    assert (st.status, st.position_seconds) == ("watched", 0)
+
+
+def test_a_rewatch_records_its_position_once_the_finish_is_behind_it(
+    db, as_user, make_user, monkeypatch
+):
+    """The other half: a watched item played again is still checkpointed — only a position arriving
+    right on the heels of the mark is read as that mark's late tick."""
+    user = make_user()
+    item = _item(db)
+    long_ago = datetime.now(timezone.utc) - timedelta(days=3)
+    db.add(PlexState(user_id=user.id, item_id=item.id, status="watched", watched_at=long_ago))
+    db.commit()
+    monkeypatch.setattr(playback.plex_stream, "touch_session", lambda uid, key: None)
+    r = as_user(user).post(
+        "/api/plex/item/m1/progress", json={"position_seconds": 600, "duration_seconds": 3000}
+    )
+    assert r.json() == {"ok": True, "position_seconds": 600}
+    db.expire_all()
+    st = db.execute(select(PlexState).where(PlexState.item_id == item.id)).scalars().one()
+    assert (st.status, st.position_seconds) == ("watched", 600)
+
+
+def test_marking_watched_supersedes_a_resume_push_still_in_flight(
+    db, as_user, make_user, monkeypatch
+):
+    """The same guard the near-end finish has: a resume push scheduled before the mark must not reach
+    Plex after its scrobble."""
+    user = make_user()
+    item = _item(db)
+    earlier = datetime.now(timezone.utc) - timedelta(seconds=5)
+    assert playback._should_push_resume(user.id, item.id, earlier, final=True)
+    r = as_user(user).post("/api/plex/item/m1/state", json={"status": "watched"})
+    assert r.status_code == 200, r.text
+    assert playback._resume_push_superseded(user.id, item.id, earlier) is True
+
+
+def _state(db, user, item):
+    db.expire_all()
+    st = (
+        db.execute(
+            select(PlexState).where(PlexState.user_id == user.id, PlexState.item_id == item.id)
+        )
+        .scalars()
+        .one()
+    )
+    return st.status, st.position_seconds
+
+
+def test_a_mark_committed_after_the_checkpoints_read_still_refuses_it(db, make_user):
+    """The race itself, not its sequential shadow: the route read the row while it was still in
+    progress, and the finish committed from another session before the checkpoint wrote. Only a write
+    conditional on the row as it is NOW refuses that position."""
+    user = make_user()
+    item = _item(db)
+    db.add(PlexState(user_id=user.id, item_id=item.id, status="new", position_seconds=2690))
+    db.commit()
+    now = datetime.now(timezone.utc)
+    read = plex_service.state_row(db, user, item.id)  # what the checkpoint's route read: "new"
+    assert read.status == "new"
+
+    other = SessionLocal()
+    try:
+        assert plex_service.mark_finished(other, user.id, item.id, now) is True
+        other.commit()
+    finally:
+        other.close()
+
+    assert plex_service.checkpoint(db, user, item.id, read, 2699, now, dirty=True) is False
+    db.commit()
+    assert _state(db, user, item) == ("watched", 0)
+
+
+def test_a_tick_seconds_behind_the_mark_is_refused_a_rewatch_a_minute_later_is_not(db, make_user):
+    """A position right behind the mark is that mark's late tick; one a minute later is a rewatch.
+    Literal times on purpose: a window widened to an hour must fail here, not move with it."""
+    user = make_user()
+    item = _item(db)
+    now = datetime.now(timezone.utc)
+    st = PlexState(user_id=user.id, item_id=item.id, status="watched", watched_at=now)
+    db.add(st)
+    db.commit()
+
+    st.watched_at = now - timedelta(seconds=20)
+    db.commit()
+    assert plex_service.checkpoint(db, user, item.id, st, 600, now, dirty=True) is False
+    db.commit()
+    st.watched_at = now - timedelta(seconds=60)
+    db.commit()
+    assert plex_service.checkpoint(db, user, item.id, st, 600, now, dirty=True) is True
+    db.commit()
+    assert _state(db, user, item) == ("watched", 600)
+
+
+def test_marking_a_season_watched_supersedes_its_episodes_resume_pushes(db, as_user, make_user):
+    """The bulk mark has the same guard as one item's: an episode's resume push scheduled before
+    the season was marked must not reach Plex after the scrobble."""
+    user = make_user()
+    lib = PlexLibrary(plex_key="2", title="Shows", kind="show", enabled=True)
+    db.add(lib)
+    db.flush()
+    sh = PlexShow(rating_key="sh1", library_id=lib.id, title="Show")
+    db.add(sh)
+    db.flush()
+    se = PlexSeason(rating_key="se1", show_id=sh.id, season_number=1)
+    db.add(se)
+    db.flush()
+    ep = PlexItem(
+        rating_key="e1",
+        library_id=lib.id,
+        kind="episode",
+        title="E1",
+        show_id=sh.id,
+        season_id=se.id,
+        season_number=1,
+        episode_number=1,
+    )
+    db.add(ep)
+    db.commit()
+    earlier = datetime.now(timezone.utc) - timedelta(seconds=5)
+    assert playback._should_push_resume(user.id, ep.id, earlier, final=True)
+
+    r = as_user(user).post("/api/plex/season/se1/state", json={"watched": True})
+    assert r.json() == {"ok": True, "changed": 1, "watched": True}
+    assert playback._resume_push_superseded(user.id, ep.id, earlier) is True

backend/tests/test_plex_hls_file_route.py

@@ -5,7 +5,7 @@ seek-restart — or a second viewer of the same item — replaces the registered
 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 client's reclaim-on-404 could never fire on it.
+notice, and the client's reclaim could never fire on it.
 
 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
@@ -88,10 +88,10 @@ def test_another_viewers_session_of_the_same_item_is_not_this_viewers(client, tm
     (d / "index.m3u8").write_bytes(b"#EXTM3U")
     sessions[(7, "m1")] = _Session("sid-a", d)
     r = client.get("/api/plex/stream/m1/hls/sid-a/index.m3u8")
-    assert r.status_code == 404, r.text
+    assert r.status_code == 410, r.text
 
 
-def test_a_segment_of_a_replaced_session_is_a_404_not_the_new_sessions_bytes(
+def test_a_segment_of_a_replaced_session_is_gone_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
@@ -102,15 +102,15 @@ def test_a_segment_of_a_replaced_session_is_a_404_not_the_new_sessions_bytes(
     (theirs / "seg_12.ts").write_bytes(b"theirs")
     sessions[(VIEWER, "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 r.status_code == 410, 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(
+def test_a_playlist_with_no_live_session_is_gone_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,
+    silently throwing away the viewer's position. A 410 sends the player through its own reclaim,
     which restarts at the playhead."""
     started: list[float] = []
     monkeypatch.setattr(
@@ -119,7 +119,7 @@ def test_a_playlist_with_no_live_session_is_a_404_not_a_silent_restart_at_zero(
         lambda *a, **k: started.append(a[3] if len(a) > 3 else 0.0),
     )
     r = client.get("/api/plex/stream/m1/hls/sid-gone/index.m3u8")
-    assert r.status_code == 404, r.text
+    assert r.status_code == 410, r.text
     assert started == []
 
 
@@ -198,6 +198,31 @@ def test_a_name_the_session_cannot_produce_fails_at_once(client, tmp_path, sessi
     assert elapsed < 2.0, f"waited {elapsed:.1f}s for a playlist this session never writes"
 
 
+@pytest.mark.parametrize(
+    ("name", "audio_langs"),
+    [
+        ("seg_00.ts", None),  # `int()` reads it as segment 0, which needs no predecessor
+        ("seg_007.ts", None),  # …as segment 7, whose predecessor seg_6.ts is on disk
+        ("seg_٧.ts", None),  # an Arabic-Indic 7: `\d` and `int()` both take it
+        ("seg_a0_07.ts", ["hu", "en"]),
+        ("seg_0_00.ts", ["hu", "en"]),
+    ],
+)
+def test_a_segment_name_ffmpeg_never_spells_is_refused(tmp_path, name, audio_langs):
+    """ffmpeg writes `seg_%d.ts`: no padding, ASCII digits. A name that only PARSES to a sequence the
+    session has reached is still a file that will never appear, and saying yes to it parked the
+    request for the full 20 s wait — the parking this guard exists to end."""
+    d = tmp_path / "m1_0_0_+0.00"
+    d.mkdir()
+    for v in plex_stream.session_variants(audio_langs) or (None,):
+        (d / plex_stream.segment_name(6, v)).write_bytes(b"x")
+    sess = _Session("sid-a", d, running=True, audio_langs=audio_langs)
+    assert not plex_stream.artifact_may_arrive(sess, name)
+    # The canonical spelling of the same next segment is still accepted.
+    v = (plex_stream.session_variants(audio_langs) or (None,))[0]
+    assert plex_stream.artifact_may_arrive(sess, plex_stream.segment_name(7, v))
+
+
 @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
@@ -210,12 +235,12 @@ def test_an_absurd_segment_index_is_a_404_not_a_500(client, tmp_path, sessions,
     assert r.status_code == 404, r.text
 
 
-def test_a_session_torn_down_during_the_read_is_a_404_not_a_500(
+def test_a_session_torn_down_during_the_read_is_gone_not_a_500(
     client, monkeypatch, tmp_path, sessions
 ):
-    """`_kill` rmtrees the whole directory and nothing holds `_lock` across the wait and the read,
+    """Teardown moves the whole directory aside 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
+    session before destroying the old hls instance. The player's recovery is keyed on the
     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()
@@ -224,7 +249,7 @@ def test_a_session_torn_down_during_the_read_is_a_404_not_a_500(
     # 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
+    assert r.status_code == 410, r.text
 
 
 def test_a_dead_producer_is_not_waited_out(client, tmp_path, sessions):

backend/tests/test_plex_playlist_add_positions.py

@@ -6,6 +6,8 @@ rows, since positions have gaps after a removal. One request: an append plus a s
 leaves the rows at the end whenever that call fails, and would overwrite another tab's changes.
 """
 
+import pytest
+
 from app.plex.models import PlexItem, PlexLibrary, PlexPlaylist, PlexPlaylistItem
 
 
@@ -101,6 +103,22 @@ def test_positions_must_pair_with_the_keys(db, make_user, as_user):
     assert _order(db, pl.id)[0] == ["a"]
 
 
+@pytest.mark.parametrize(
+    ("method", "path"),
+    [("post", "items/bulk"), ("post", "items/remove-bulk"), ("put", "order")],
+)
+def test_a_body_without_its_keys_is_refused_rather_than_acting_on_none(
+    db, make_user, as_user, method, path
+):
+    user = make_user()
+    pl = _seed(db, user, ["a"], extra=())
+
+    r = getattr(as_user(user), method)(f"/api/plex/playlists/{pl.id}/{path}", json={"keys": ["a"]})
+
+    assert r.status_code == 422
+    assert _order(db, pl.id)[0] == ["a"]
+
+
 def test_remove_then_put_back_is_no_change(db, make_user, as_user):
     user = make_user()
     pl = _seed(db, user, ["a", "b", "c", "d"], extra=())

backend/tests/test_plex_service.py

@@ -348,7 +348,8 @@ def test_an_early_checkpoint_drops_a_bare_state_and_zeroes_a_marked_one(db, make
     user = make_user()
     lib = _lib(db)
     bare, hid = _movie(db, lib, "bare"), _movie(db, lib, "hid")
-    st = service.checkpoint(db, user, bare.id, None, 120, NOW, dirty=True)
+    assert service.checkpoint(db, user, bare.id, None, 120, NOW, dirty=True)
+    st = queries.state(db, user, bare.id)
     assert (st.position_seconds, st.synced_to_plex) == (120, False)
     _state(db, user, hid, status="hidden", position_seconds=40)
     service.clear_progress(db, queries.state(db, user, bare.id), NOW)
@@ -429,7 +430,8 @@ def test_a_first_write_that_lost_the_race_updates_the_winners_row(db, make_user)
     user = make_user()
     it = _movie(db, _lib(db), "m-race")
     _state(db, user, it, position_seconds=10)  # the request that won, committed
-    st = service.checkpoint(db, user, it.id, None, 42, NOW, dirty=True)  # read "none" before it
+    assert service.checkpoint(db, user, it.id, None, 42, NOW, dirty=True)  # read "none" before it
+    st = queries.state(db, user, it.id)
     assert (st.position_seconds, st.synced_to_plex) == (42, False)
     st = service.set_status(db, user, it.id, None, "hidden")
     assert st.status == "hidden"

backend/tests/test_plex_session_stop.py

@@ -39,6 +39,7 @@ class _Proc:
 class _Session:
     def __init__(self, session_id: str, directory):
         self.id = session_id
+        self.key = "m1"
         self.dir = directory
         self.proc = _Proc()
         self.last_access = time.time()

backend/tests/test_plex_stream.py

@@ -26,6 +26,9 @@ from app.plex.stream import _SESSION_DIR_RE
         "12345_0_2_+0.00",  # current shape, explicit audio_ord
         "12345_842_multi_-1.25",  # multi-audio, negative offset
         "12345_842_multi_+12.50",
+        # a torn-down session's directory, moved aside to be deleted outside the lock — left behind
+        # only if the process died between the rename and the delete
+        "12345_u7_842_multi_+12.50.dead-0123abcd",
     ],
 )
 def test_our_session_directories_are_swept(name):
@@ -47,6 +50,9 @@ def test_our_session_directories_are_swept(name):
         "snapshot_2024_backup_+1.00",  # session-ish tail, but the key isn't a rating_key
         "backup_2024_multi_+0.00",
         ".config",
+        "12345_u7_0_0_+0.00.dead-",  # a tombstone suffix with no id
+        "12345_u7_0_0_+0.00.dead-notours!",
+        "backup_u7_0_0_+0.00.dead-0123abcd",
     ],
 )
 def test_foreign_directories_are_left_alone(name):
@@ -159,7 +165,7 @@ class TestSweepOrphans:
 
 
 class _FakeProc:
-    """Stand-in for the ffmpeg Popen — start_session only stores it (and _kill/reap poll it later)."""
+    """Stand-in for the ffmpeg Popen — start_session only stores it (and teardown/reap poll it later)."""
 
     def poll(self):
         return None
@@ -1052,3 +1058,63 @@ class TestSessionsPerViewer:
             self._start(monkeypatch, user_id=uid)
         assert len(stream._sessions) == 3 and (1, "12345") not in stream._sessions
         assert oldest.proc.killed and not oldest.transcode
+
+
+class TestTeardownFinishes:
+    """A session taken down by a cap or replaced by its own viewer is only renamed aside under the
+    lock; it is deleted after. The rename alone already moves the directory and `terminate()` alone
+    already marks the proc killed — so what is pinned here is the tomb: a whole segmented copy of the
+    film that only a restart's sweep would otherwise reclaim."""
+
+    capturing_env = TestTranscodeStartSession.capturing_env
+
+    @staticmethod
+    def _left_behind(root):
+        return sorted(p.name for p in root.iterdir() if stream._TOMB in p.name) + sorted(
+            str(p) for p in stream._dying
+        )
+
+    def test_a_culled_session_is_deleted_not_only_moved_aside(self, capturing_env, monkeypatch):
+        monkeypatch.setattr(stream, "_dying", {})
+        first = TestSessionsPerViewer._start(monkeypatch, user_id=1, rating_key="1")
+        first.last_access -= 60
+        TestSessionsPerViewer._start(monkeypatch, user_id=1, rating_key="2")
+        TestSessionsPerViewer._start(monkeypatch, user_id=1, rating_key="3")
+        assert first.proc.killed and not first.dir.exists()
+        assert self._left_behind(capturing_env) == []
+
+    def test_a_viewers_restart_deletes_the_session_it_replaces(self, capturing_env, monkeypatch):
+        monkeypatch.setattr(stream, "_dying", {})
+        monkeypatch.setattr(
+            stream, "_select_encode", lambda db, item, transcode, src: (False, False)
+        )
+        monkeypatch.setattr(
+            stream, "_probe_first_pts", lambda seg: None
+        )  # no real segment to probe
+        old = stream.start_session(db=None, user_id=1, item=_FakeItem(), start_s=0.0)
+        new = stream.start_session(db=None, user_id=1, item=_FakeItem(), start_s=600.0)
+        assert old.proc.killed and new.dir.exists() and not old.dir.exists()
+        assert self._left_behind(capturing_env) == []
+
+    def test_a_restart_that_fails_to_start_still_deletes_what_it_replaced(
+        self, capturing_env, monkeypatch
+    ):
+        # The new ffmpeg cannot start (a full disk, no ffmpeg, no memory): the old session is already
+        # moved aside, and nothing else in this process would ever delete it.
+        monkeypatch.setattr(stream, "_dying", {})
+        monkeypatch.setattr(
+            stream, "_select_encode", lambda db, item, transcode, src: (False, False)
+        )
+        monkeypatch.setattr(
+            stream, "_probe_first_pts", lambda seg: None
+        )  # no real segment to probe
+        old = stream.start_session(db=None, user_id=1, item=_FakeItem(), start_s=0.0)
+
+        def no_ffmpeg(*args, **kwargs):
+            raise OSError(28, "No space left on device")
+
+        monkeypatch.setattr(stream.subprocess, "Popen", no_ffmpeg)
+        with pytest.raises(OSError):
+            stream.start_session(db=None, user_id=1, item=_FakeItem(), start_s=600.0)
+        assert old.proc.killed and not old.dir.exists()
+        assert self._left_behind(capturing_env) == []

backend/tests/test_quota_ownership.py

@@ -44,15 +44,15 @@ def test_reads_see_separate_session_spend_mid_transaction(db):
     assert after - before == 7
 
 
-def test_log_action_survives_caller_rollback(db):
+def test_a_claimed_slot_survives_caller_rollback(db):
     user = User(email="searcher@example.com")
     db.add(user)
     db.commit()  # a committed user to attribute the (free) action to
     db.add(User(email="pending@example.com"))  # uncommitted caller work
-    quota.log_action(user.id, quota.QuotaAction.VIDEOS_SEARCH)
+    assert quota.claim_action(user.id, quota.QuotaAction.VIDEOS_SEARCH, 5) is not None
     db.rollback()
 
-    # The zero-cost action event survived (per-user daily caps must still count it) ...
+    # The zero-cost claim event survived (per-user daily caps must still count it) ...
     events = db.execute(select(QuotaEvent)).scalars().all()
     assert len(events) == 1
     assert events[0].user_id == user.id

backend/tests/test_reader_service.py

@@ -14,7 +14,7 @@ from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 
 from app.discover import pins
-from app.catalog.models import Channel, Video
+from app.catalog.models import Channel, Subscription, Video
 from app.reader import queries, service
 from app.reader.models import ChannelTag, ComfortPin, Playlist, PlaylistItem, Tag, VideoState
 
@@ -60,12 +60,44 @@ def test_a_system_tag_is_nobodys_to_edit(db, make_user):
     service.create_tag(db, other, "Theirs", "other", None)  # another user's tag stays theirs
     db.commit()
     assert queries.own_tag(db, user, system.id) is None
-    assert [t.id for t, _ in queries.tags_with_counts(db, user)] == [system.id]
+    assert [t.id for t, *_ in queries.tags_with_counts(db, user)] == [system.id]
 
 
 # --- tags ------------------------------------------------------------------------------------
 
 
+def _music_on_four(db, make_user):
+    """A tag on four channels: two followed, one followed but hidden, one no longer followed."""
+    user, other = make_user(), make_user()
+    tag = service.create_tag(db, user, "Music", "other", None)
+    for cid in ("UCa", "UCb", "UChid", "UCgone"):
+        db.add(Channel(id=cid, title=cid))
+    db.flush()
+    for cid in ("UCa", "UCb"):
+        db.add(Subscription(user_id=user.id, channel_id=cid))
+    db.add(Subscription(user_id=user.id, channel_id="UChid", hidden=True))
+    db.add(Subscription(user_id=other.id, channel_id="UCgone"))
+    for cid in ("UCa", "UCb", "UChid", "UCgone"):
+        db.add(ChannelTag(channel_id=cid, tag_id=tag.id, user_id=user.id, source="user"))
+    db.commit()
+    return user, tag
+
+
+def test_a_tag_counts_apart_the_links_on_channels_the_user_still_follows(db, make_user):
+    """An unsubscribe and a hide keep the channel's tag links; the Channels page's filter lists only
+    the followed channels not hidden, so its count must not hold the others."""
+    user, tag = _music_on_four(db, make_user)
+    [(_, count, subscribed)] = [r for r in queries.tags_with_counts(db, user) if r[0].id == tag.id]
+    assert (count, subscribed) == (4, 2)
+
+
+def test_the_tag_list_sends_each_count_under_its_own_name(db, make_user, as_user):
+    """Both counts are ints, so a swap would type-check: the answer itself pins which is which."""
+    user, tag = _music_on_four(db, make_user)
+    [row] = [t for t in as_user(user).get("/api/tags").json() if t["id"] == tag.id]
+    assert (row["channel_count"], row["subscribed_count"]) == (4, 2)
+
+
 def test_a_tag_is_made_once_per_name_and_an_unknown_category_is_other(db, make_user):
     user = make_user()
     tag = service.create_tag(db, user, "Later", "nonsense", "#fff")
@@ -190,9 +222,6 @@ def test_a_cleared_resume_point_drops_a_bare_row_and_zeroes_one_with_a_status(db
     db.commit()
     assert _state(db, user, "v1") is None
     assert (_state(db, user, "v2").status, _state(db, user, "v2").position_seconds) == ("hidden", 0)
-    service.clear_state(db, user, "v2")
-    db.commit()
-    assert _state(db, user, "v2") is None
 
 
 # --- playlists -------------------------------------------------------------------------------
@@ -213,9 +242,8 @@ def test_an_add_is_idempotent_and_lands_where_asked(db, make_user):
     pl = service.create_playlist(db, user, "L")
     assert service.add_item(db, pl, "a", mark_dirty=False) is True
     assert service.add_item(db, pl, "a", mark_dirty=False) is False
-    service.add_to_playlist(db, pl, "b", None)
-    service.add_to_playlist(db, pl, "c", 0)
-    service.add_to_playlist(db, pl, "a", 2)  # already there: stays put
+    assert service.add_item(db, pl, "b", mark_dirty=True) is True
+    assert service.restore_items(db, pl, ["c", "a"], [0, 2]) == 1  # "a" is there: it stays put
     assert _uncommitted(db)
     db.commit()
     assert _ids(db, pl) == ["c", "a", "b"]
@@ -238,14 +266,13 @@ def test_a_move_never_leaves_a_video_in_two_lists(db, make_user):
     service.add_item(db, dst, "b", mark_dirty=False)
     db.commit()
     with pytest.raises(service.MoveRefused, match="same_playlist"):
-        service.move_item(db, src, src, "a")
-    service.move_item(db, src, dst, "a")
-    service.move_item(db, src, dst, "b")  # already in the target: dropped from the source
+        service.move_items(db, src, src, ["a"])
+    assert service.move_items(db, src, dst, ["a"]) == (["a"], [])
+    # already in the target: dropped from the source
+    assert service.move_items(db, src, dst, ["b"]) == ([], ["b"])
     db.commit()
     assert (_ids(db, src), _ids(db, dst)) == ([], ["b", "a"])
-    with pytest.raises(service.MoveRefused, match="not_in_playlist"):
-        service.move_item(db, src, dst, "a")
-    db.rollback()
+    assert service.move_items(db, src, dst, ["a"]) == ([], [])
 
 
 def test_a_reorder_keeps_what_it_left_out_after_the_listed(db, make_user):

backend/tests/test_refusal_sites.py

@@ -0,0 +1,770 @@
+"""The refusal scan (`refusal_sites.py`) on small sources: each shape on its closed list is followed to its
+values, and each exit from that list is reported, unread or as an unread code. A scan that silently drops a
+shape is a guard green over nothing, so every exit is pinned here, not only the paths the app takes. Pure:
+no app import, no database."""
+
+import textwrap
+
+from tests.refusal_sites import scan, scan_app
+
+
+def _scan(**files: str) -> dict:
+    return scan(
+        {f"{name.replace('__', '/')}.py": textwrap.dedent(src) for name, src in files.items()}
+    )
+
+
+def _code(result: dict, code: str) -> dict:
+    return result["codes"][code]
+
+
+def _unread(result: dict, code: str) -> list[str]:
+    return [u.split(": ", 1)[1] for u in _code(result, code)["unread"]]
+
+
+REFUSAL = """
+    from fastapi import HTTPException
+
+    def refused(status: int, reason: str, **params: object) -> HTTPException:
+        return HTTPException(status_code=status, detail={**params, "code": "refused", "reason": reason})
+"""
+
+
+def test_a_literal_wherever_it_sits_in_the_dict():
+    r = _scan(
+        a="""
+        def f(x):
+            raise HTTPException(409, {"code": "clip", "limit_s": 5, "reason": "too_long"})
+        def g(x):
+            raise HTTPException(409, {"reason": "before", "code": "clip"})
+        def h(x):
+            raise HTTPException(409, {
+                "code": "clip",  # a comment between
+                "reason": "after_comment",
+            })
+        def i(x):
+            raise HTTPException(409, detail=dict(code="clip", reason="by_call"))
+        """
+    )
+    assert _code(r, "clip")["reasons"] == ["after_comment", "before", "by_call", "too_long"]
+    assert _code(r, "clip")["unread"] == []
+
+
+def test_both_arms_of_a_conditional_and_a_none_arm_makes_the_site_reasonless():
+    r = _scan(
+        a="""
+        def f(x):
+            raise HTTPException(409, {"code": "edit", "reason": "a" if x else "b"})
+        def g(x):
+            raise HTTPException(409, {"code": "playlist", "reason": "lit" if x else None})
+        def h(x):
+            raise HTTPException(409, {"code": "busy", "reason": None})
+        """
+    )
+    assert _code(r, "edit")["reasons"] == ["a", "b"] and _code(r, "edit")["reasonless"] == []
+    assert _code(r, "playlist")["reasons"] == ["lit"]
+    assert _code(r, "playlist")["reasonless"] == ["a.py:5"]
+    assert _code(r, "busy")["reasonless"] == ["a.py:7"]
+
+
+def test_what_the_list_does_not_hold_is_unread():
+    r = _scan(
+        a="""
+        def f(x, svc):
+            raise HTTPException(409, {"code": "edit", "reason": x.why or "c"})
+        def g(svc):
+            raise HTTPException(409, {"code": "edit", "reason": svc.reason()})
+        def h():
+            raise HTTPException(409, {"code": "edit", "reason": 5})
+        def i(e):
+            raise HTTPException(409, {"code": "edit", "reason": f"x{e}"})
+        """
+    )
+    assert _unread(r, "edit") == ["x.why or 'c'", "svc.reason()", "5", "f'x{e}'"]
+    assert _code(r, "edit")["reasons"] == []
+
+
+def test_a_helper_is_followed_to_every_call_however_it_is_written():
+    r = _scan(
+        refusal=REFUSAL,
+        routes__a="""
+        from http import HTTPStatus
+        from app import refusal
+        from app.refusal import refused
+
+        def f(status):
+            raise refused(status, "by_name_status")
+        def g():
+            raise refused(HTTPStatus.CONFLICT, reason="by_keyword")
+        def h():
+            raise refusal.refused(409, "qualified")
+        def i(x):
+            raise refused(409, "a" if x else "second_arm")
+        """,
+        routes__b="""
+        from other.lib import refused
+
+        def f():
+            refused("an outside library's, not the app's")
+        """,
+    )
+    assert _code(r, "refused")["reasons"] == [
+        "a",
+        "by_keyword",
+        "by_name_status",
+        "qualified",
+        "second_arm",
+    ]
+    assert _code(r, "refused")["unread"] == []
+
+
+def test_a_call_the_helper_cannot_be_followed_through_is_unread():
+    r = _scan(
+        refusal=REFUSAL,
+        routes__a="""
+        from app.refusal import refused
+
+        def f(args, kw):
+            pick = refused
+            raise refused(*args)
+        def g(kw):
+            raise refused(409, **kw)
+        def h():
+            raise refused(409)
+        """,
+        routes__b="""
+        import app.refusal
+
+        def f():
+            raise app.refusal.refused(409, "dotted")
+        """,
+        routes__c="""
+        from ..refusal import refused
+
+        def f():
+            raise refused(409, "relative")
+        """,
+    )
+    unread = _unread(r, "refused")
+    assert len(unread) == 6
+    assert sum("the helper used as a value" in u for u in unread) == 1
+    assert sum("a reference the scan cannot resolve" in u for u in unread) == 2
+    assert sum("does not pass reason" in u for u in unread) == 2  # `**kw`, and nothing at all
+    assert any(u == "refused(*args)" for u in unread)
+    assert _code(r, "refused")["reasons"] == []
+
+
+def test_a_default_is_not_followed_a_call_must_pass_the_reason():
+    r = _scan(
+        routes___common="""
+        def not_found(what: str = "generic"):
+            return HTTPException(404, {"code": "not_found", "reason": what})
+
+        def get_or_404(db, id_, *, what: str = "generic"):
+            raise not_found(what)
+        """,
+        routes__a="""
+        from app.routes._common import get_or_404, not_found
+
+        def f(db):
+            get_or_404(db, 1, what="user")
+            get_or_404(db, 2)
+            raise not_found("debug_session")
+        def g():
+            raise not_found()
+        """,
+    )
+    assert _code(r, "not_found")["reasons"] == ["debug_session", "user"]
+    assert [u.endswith("(does not pass what)") for u in _unread(r, "not_found")] == [True, True]
+
+
+def test_a_positional_only_reason_passed_by_name_is_not_bound_to_it():
+    r = _scan(
+        a="""
+        def deny(reason: str, /, **params):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+
+        def f():
+            raise deny("by_position")
+        def g():
+            raise deny(reason="lands_in_params")
+        """
+    )
+    assert _code(r, "playlist")["reasons"] == ["by_position"]
+    assert _unread(r, "playlist") == ["deny(reason='lands_in_params') (does not pass reason)"]
+
+
+def test_a_helper_reaching_two_sites_gives_both_its_reasons_and_one_reached_again_is_unread():
+    r = _scan(
+        a="""
+        def deny(reason: str, admin):
+            if admin:
+                return HTTPException(409, {"code": "activate", "reason": reason})
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+
+        def again(reason: str, n):
+            if n:
+                return again(reason, n - 1)
+            return HTTPException(409, {"code": "edit", "reason": reason})
+
+        def f():
+            raise deny("foo", True)
+        def g():
+            raise again("bar", 3)
+        """
+    )
+    assert _code(r, "activate")["reasons"] == ["foo"]
+    assert _code(r, "playlist")["reasons"] == ["foo"]
+    assert _code(r, "edit")["reasons"] == ["bar"]
+    assert any("reached again while it is followed" in u for u in _unread(r, "edit"))
+
+
+def test_a_parameter_its_body_binds_again_is_unread():
+    r = _scan(
+        a="""
+        from typing import Literal
+
+        def refused(status, reason: str = ""):
+            reason = reason or "fallback"
+            return HTTPException(status, {"code": "refused", "reason": reason})
+
+        def typed(reason: Literal["a"]):
+            if not reason:
+                reason = "b"
+            return HTTPException(409, {"code": "edit", "reason": reason})
+
+        def f():
+            raise refused(409, "x")
+        """
+    )
+    assert _code(r, "refused")["reasons"] == []
+    assert _unread(r, "refused") == ["reason (a parameter its body binds again)"]
+    assert _unread(r, "edit") == ["reason (a parameter its body binds again)"]
+
+
+def test_a_local_is_followed_only_through_plain_assignments():
+    r = _scan(
+        a="""
+        from typing import Literal
+
+        def f(x):
+            why = "first"
+            if x:
+                why = "second" if x > 1 else "third"
+            raise HTTPException(409, {"code": "edit", "reason": why})
+        def g(svc):
+            hit, why = svc.fetch()
+            raise HTTPException(409, {"code": "playlist", "reason": why})
+        def h(items):
+            for why in items:
+                pass
+            raise HTTPException(409, {"code": "playlist", "reason": why})
+        def i():
+            why: Literal["typed"] = pick()
+            raise HTTPException(409, {"code": "playlist", "reason": why})
+        def j(items):
+            LABELS[why] = "NotAReason"
+            raise HTTPException(409, {"code": "playlist", "reason": why})
+        def k(*why):
+            raise HTTPException(409, {"code": "playlist", "reason": why})
+        """
+    )
+    assert _code(r, "edit")["reasons"] == ["first", "second", "third"]
+    assert _code(r, "playlist")["reasons"] == []
+    assert _unread(r, "playlist") == [
+        "why",
+        "why",
+        "why",
+        "why",
+        "why",
+    ]  # unpacked, a loop, annotated, unbound, `*args`
+
+
+def test_a_call_answers_with_its_literal_return_type():
+    r = _scan(
+        a="""
+        from typing import Literal
+
+        def why(x) -> Literal["quota", "gone"]:
+            return "quota"
+        def how(x) -> str:
+            return "x"
+
+        def f(x):
+            raise HTTPException(409, {"code": "youtube", "reason": why(x)})
+        def g(x):
+            raise HTTPException(409, {"code": "youtube", "reason": how(x)})
+        """
+    )
+    assert _code(r, "youtube")["reasons"] == ["gone", "quota"]
+    assert _unread(r, "youtube") == ["how(x)"]
+
+
+def test_a_module_constant_is_read_only_as_mod_name_and_only_when_bound_once():
+    r = _scan(
+        urlguard="""
+        REASON_MALFORMED = "malformed"
+        TWICE = "a"
+        TWICE = "b"
+        if FLAG:
+            LATER = "c"
+        """,
+        routes__a="""
+        from app import urlguard
+
+        BARE = "bare"
+
+        def f():
+            raise HTTPException(409, {"code": "url_blocked", "reason": urlguard.REASON_MALFORMED})
+        def g():
+            raise HTTPException(409, {"code": "url_blocked", "reason": urlguard.TWICE})
+        def h():
+            raise HTTPException(409, {"code": "url_blocked", "reason": urlguard.LATER})
+        def i():
+            raise HTTPException(409, {"code": "url_blocked", "reason": BARE})
+        """,
+    )
+    assert _code(r, "url_blocked")["reasons"] == ["malformed"]
+    assert _unread(r, "url_blocked") == ["urlguard.TWICE", "urlguard.LATER", "BARE"]
+
+
+def test_a_name_imported_from_two_places_or_under_an_if_is_not_looked_up():
+    r = _scan(
+        m1='R = Literal["one"]',
+        m2='R = Literal["two"]',
+        a="""
+        def f():
+            from app.m1 import R
+        def g():
+            from app.m2 import R
+        def h(reason: R):
+            return HTTPException(409, {"code": "edit", "reason": reason})
+        """,
+        b="""
+        if FLAG:
+            from app.m1 import R
+        def h(reason: R):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+        """,
+        c="""
+        from app.m1 import R
+        def h(reason: R):
+            return HTTPException(409, {"code": "clip", "reason": reason})
+        """,
+    )
+    assert _code(r, "edit")["reasons"] == [] and _unread(r, "edit") == ["reason"]
+    assert _code(r, "playlist")["reasons"] == [] and _unread(r, "playlist") == ["reason"]
+    assert _code(r, "clip")["reasons"] == ["one"]
+
+
+def test_a_caught_exception_answers_with_the_literal_its_class_declares_on_self():
+    r = _scan(
+        errors="""
+        from typing import Literal
+        ClipReason = Literal["bad_range", "too_short"]
+        EditReason = Literal["not_media"]
+
+        class ClipError(Exception):
+            def __init__(self, reason: ClipReason, **params: float):
+                self.reason: ClipReason = reason
+                self.params = params
+
+        class EditError(Exception):
+            reason: EditReason
+
+        class Untyped(Exception):
+            def __init__(self, reason: str):
+                self.reason = reason
+
+        class Narrower(ClipError):
+            pass
+        """,
+        routes__a="""
+        from app import errors
+
+        def f():
+            try:
+                pass
+            except errors.ClipError as e:
+                raise HTTPException(422, {"code": "clip", "reason": e.reason})
+            except (errors.ClipError, errors.EditError) as e:
+                raise HTTPException(422, {"code": "clip", "reason": e.reason})
+            except errors.EditError as e:
+                raise HTTPException(422, {"code": "clip", "reason": e.reason})
+            except errors.Untyped as e:
+                raise HTTPException(422, {"code": "clip", "reason": e.reason})
+            except errors.Narrower as e:
+                raise HTTPException(422, {"code": "clip", "reason": e.reason})
+            except errors.ClipError as e:
+                raise HTTPException(422, {"code": "clip", "reason": e})
+        """,
+    )
+    assert _code(r, "clip")["reasons"] == ["bad_range", "too_short"]
+    assert _unread(r, "clip") == [
+        "e.reason",  # a tuple of classes
+        "e.reason (EditError.reason has no Literal type)",  # declared on the class body only
+        "e.reason (Untyped.reason has no Literal type)",
+        "e.reason (Narrower.reason has no Literal type)",  # a subclass: not looked up the bases
+        "e",  # the exception itself
+    ]
+
+
+def test_a_parameter_answers_with_its_literal_or_its_class_and_any_other_type_is_unread():
+    r = _scan(
+        a="""
+        from typing import Literal
+        Why = Literal["one", "two"]
+
+        class Err(Exception):
+            def __init__(self, reason: Literal["three"]):
+                self.reason: Literal["three"] = reason
+
+        def typed(reason: Why):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+        def inline(reason: Literal["four"]):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+        def by_class(exc: Err):
+            return HTTPException(409, {"code": "playlist", "reason": exc.reason})
+        def rebound(exc: Err):
+            exc = other()
+            return HTTPException(409, {"code": "playlist", "reason": exc.reason})
+        def optional(reason: Literal["five"] | None = None):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+        def quoted(reason: "Why"):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+        def number(reason: int):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+
+        class C:
+            def method(self, reason: str):
+                return HTTPException(409, {"code": "playlist", "reason": reason})
+        """
+    )
+    assert _code(r, "playlist")["reasons"] == ["four", "one", "three", "two"]
+    unread = _unread(r, "playlist")
+    # a parameter bound again, `| None`, a quoted annotation, `int`
+    assert unread[:4] == ["exc.reason", "reason", "reason", "reason"]
+    assert "method(reason) is not a module-level helper" in unread[4]
+    assert len(unread) == 5
+
+
+def test_a_str_helper_nobody_calls_sends_nothing():
+    r = _scan(
+        a="""
+        def helper(reason: str):
+            return HTTPException(409, {"code": "playlist", "reason": reason})
+        """
+    )
+    assert _code(r, "playlist") == {"reasons": [], "unread": [], "sites": 1, "reasonless": []}
+
+
+def test_a_map_lookup_is_its_values_and_its_keys_must_be_exactly_what_the_index_can_be():
+    src = """
+        from typing import Literal
+        SettingReason = Literal["too_low", "too_high"]
+
+        class InvalidSetting(ValueError):
+            def __init__(self, key: str, reason: SettingReason, **params: object):
+                self.reason: SettingReason = reason
+                self.params = params
+
+        _MAP: dict[SettingReason, str] = {{{keys}}}
+
+        def refused(status: int, reason: str, **params: object):
+            return HTTPException(status, {{**params, "code": "refused", "reason": reason}})
+
+        def setting_refused(exc: InvalidSetting):
+            return refused(400, _MAP[{index}], **exc.params)
+    """
+    both = '"too_low": "setting_too_low", "too_high": "setting_too_high"'
+    whole = _scan(a=src.format(keys=both, index="exc.reason"))
+    assert _code(whole, "refused")["reasons"] == ["setting_too_high", "setting_too_low"]
+    assert whole["errors"] == [] and whole["unreadCodes"] == []
+    for keys, index in [
+        ('"too_low": "setting_too_low"', "exc.reason"),  # a key short
+        (both + ', "gone": "setting_gone"', "exc.reason"),  # a key no index can be
+        (both, "exc.key"),  # an index the scan cannot read
+    ]:
+        r = _scan(a=src.format(keys=keys, index=index))
+        assert len(r["errors"]) == 1 and "not what its index can be" in r["errors"][0]
+
+
+def test_a_lookup_in_anything_but_a_module_dict_of_literal_keys_is_unread():
+    r = _scan(
+        a="""
+        BUILT = make()
+        NUMBERED = {1: "one"}
+
+        def f(table, k):
+            raise HTTPException(409, {"code": "edit", "reason": table[k]})
+        def g(k):
+            raise HTTPException(409, {"code": "edit", "reason": BUILT[k]})
+        def h(k):
+            raise HTTPException(409, {"code": "edit", "reason": NUMBERED[k]})
+        """
+    )
+    assert _unread(r, "edit") == ["table[k]", "BUILT[k]", "NUMBERED[k]"]
+    assert r["errors"] == []
+
+
+def test_a_code_must_be_one_literal():
+    r = _scan(
+        a="""
+        BUSY = "busy"
+        def f(code):
+            raise HTTPException(409, {"code": "busy"})
+        def g(code):
+            raise HTTPException(409, {"code": code})
+        def h():
+            raise HTTPException(409, {"code": BUSY})
+        def i(x):
+            raise HTTPException(409, {"code": "a" if x else "b"})
+        def j(x):
+            raise HTTPException(409, {"code": "a" if x else None})
+        def k(key):
+            raise HTTPException(409, {"code": "edit", key: "late"})
+        """
+    )
+    assert r["codes"]["busy"]["reasonless"] == ["a.py:4"]
+    assert set(r["codes"]) == {"busy"}
+    assert len(r["unreadCodes"]) == 5
+    assert r["unreadCodes"][-1].endswith(
+        "(a spread or a computed key the code and the reason do not follow)"
+    )
+
+
+def test_a_spread_or_a_computed_key_stands_before_both_the_code_and_the_reason():
+    def unread_codes(detail: str) -> list[str]:
+        return _scan(a=f"def f(x, more, key):\n    raise HTTPException(409, {detail})\n")[
+            "unreadCodes"
+        ]
+
+    assert unread_codes('{**more, "code": "refused", "reason": "a"}') == []
+    assert unread_codes('{key: 1, **more, "reason": "a", "code": "refused"}') == []
+    for late in [
+        '{"code": "refused", "reason": "a", **more}',  # the spread may replace both
+        '{"code": "refused", **more, "reason": "a"}',  # … the code
+        '{"reason": "a", **more, "code": "refused"}',  # … the reason
+        '{**more, "code": "refused"}',  # no reason after it: the spread may carry one
+        '{"code": "refused", "reason": "a", key: "x"}',  # a key that may be either
+        'dict(**more, code="refused", reason="a")',  # dict() raises on a repeated key
+        'dict(more, code="refused", reason="a")',
+    ]:
+        assert unread_codes(late), late
+
+
+def test_a_detail_stands_only_where_it_is_sent():
+    def result(body: str, extra: str = "") -> dict:
+        return _scan(a=f"def f(x, cached, fix):\n{textwrap.indent(body, '    ')}\n{extra}")
+
+    for body in [
+        'detail = {"code": "login", "reason": "a"}\nraise HTTPException(401, detail)',
+        'if (detail := {"code": "login", "reason": "a"}):\n    raise HTTPException(401, detail)',
+        'raise HTTPException(401, {"code": "login", "reason": "a"}.copy())',
+        'raise HTTPException(401, fix({"code": "login", "reason": "a"}))',
+        'raise HTTPException(401, cached or {"code": "login", "reason": "a"})',
+        'return JSONResponse({"code": "login", "reason": "a"}, status_code=401)',  # the whole body
+        'raise HTTPException(401, None, {"code": "login", "reason": "a"})',  # the headers
+        'raise HTTPException(401, headers={"code": "login", "reason": "a"})',
+        'raise HTTPException(401, "a" if {"code": "login", "reason": "a"} else "b")',
+    ]:
+        r = result(body)
+        assert r["unreadCodes"] and "login" not in r["codes"], body
+        assert "(a detail put where the scan cannot follow it)" in r["unreadCodes"][0], body
+    held = _scan(a='class C:\n    detail = {"code": "login"}\n')
+    assert "(a detail put where the scan cannot follow it)" in held["unreadCodes"][0]
+
+    sent = result(
+        'raise HTTPException(401, {"code": "login", "reason": "a"} if x else {"code": "login"})\n'
+        'raise HTTPException(401, detail=dict(code="login", reason="b"))\n'
+        'return JSONResponse(content={"detail": {"code": "login", "reason": "c"}})'
+    )
+    assert sent["unreadCodes"] == [] and _code(sent, "login")["reasons"] == ["a", "b", "c"]
+
+
+def test_a_factory_is_a_detail_only_when_each_return_is_one_and_each_call_is_sent():
+    factory = """
+def quota(e) -> dict:
+    return {"code": "quota", "reason": "files"}
+"""
+    sent = "def f(e):\n    raise HTTPException(422, detail=quota(e))\n"
+    assert _scan(a=factory + sent)["codes"]["quota"]["reasons"] == ["files"]
+    for change in [
+        "def g(e):\n    d = quota(e)\n    d['code'] = 'other'\n    raise HTTPException(422, d)\n",
+        "def g(e):\n    raise HTTPException(422, detail=quota(e).copy())\n",
+        "pick = quota\n",
+    ]:
+        r = _scan(a=factory + sent + change)
+        assert r["unreadCodes"] and "quota" not in r["codes"], change
+    twice = _scan(a="quota = None\n" + factory + sent)  # the def is the last of two bindings
+    assert twice["unreadCodes"] and "quota" not in twice["codes"]
+    for other in [
+        "    if e:\n        return None\n",
+        "    if e:\n        return cached\n",
+        "    if e:\n        return {'code': 'quota', 'reason': 'x'} if e > 1 else None\n",
+        "    log({'code': 'quota', 'reason': 'logged'})\n",  # a detail it does not return
+    ]:
+        bent = factory.replace("-> dict:\n", "-> dict:\n" + other)
+        assert _scan(a=bent + sent)["unreadCodes"], other
+    method = "class C:\n    def quota(self):\n        return {'code': 'quota', 'reason': 'm'}\n"
+    assert _scan(a=method)["unreadCodes"]
+    dotted = _scan(
+        a=factory,
+        routes__b="import app.a\n\ndef g(e):\n    raise HTTPException(422, detail=app.a.quota(e))\n",
+    )
+    assert dotted["unreadCodes"] and "quota" not in dotted["codes"]
+
+
+def test_a_name_a_lambda_a_comprehension_a_nonlocal_or_a_global_binds_is_unread():
+    r = _scan(
+        a="""
+        def f(svc):
+            why = "invalid"
+            make = lambda why: HTTPException(401, {"code": "login", "reason": why})
+            raise make(svc.state)
+        def g(svc):
+            why = "invalid"
+            raise [HTTPException(401, {"code": "login", "reason": why}) for why in svc.all][0]
+        def h(svc):
+            why = "invalid"
+            def inner():
+                nonlocal why
+                why = svc.reason
+            inner()
+            raise HTTPException(401, {"code": "login", "reason": why})
+        def i(svc):
+            global why
+            why = "invalid"
+            raise HTTPException(401, {"code": "login", "reason": why})
+        """
+    )
+    assert _code(r, "login")["reasons"] == []
+    assert sorted(_unread(r, "login")) == [
+        "why (bound by a lambda or a comprehension)",
+        "why (bound by a lambda or a comprehension)",
+        "why (named by a nonlocal or a global)",
+        "why (named by a nonlocal or a global)",
+    ]
+
+
+def test_a_local_that_reaches_itself_is_unread():
+    r = _scan(
+        a="""
+        def f(x):
+            why = "a"
+            if x:
+                why = why if x > 1 else "b"
+            raise HTTPException(409, {"code": "edit", "reason": why})
+        def g(x):
+            a = "z"
+            b = a
+            a = b
+            raise HTTPException(409, {"code": "playlist", "reason": a})
+        def h(x):
+            why = "c"
+            if x:
+                raise HTTPException(409, {"code": "busy", "reason": why})
+            raise HTTPException(409, {"code": "busy", "reason": why})
+        """
+    )
+    assert _code(r, "busy")["reasons"] == ["c"] and _code(r, "busy")["unread"] == []
+    assert _code(r, "edit")["reasons"] == ["a", "b"]
+    assert _unread(r, "edit") == ["why (reached again while it is resolved)"]
+    assert _code(r, "playlist")["reasons"] == ["z"]
+    assert any("reached again while it is resolved" in u for u in _unread(r, "playlist"))
+
+
+def test_a_module_constant_or_a_map_changed_elsewhere_is_unread():
+    def reasons(urlguard: str, route: str = "", **more: str) -> tuple[list[str], list[str]]:
+        r = _scan(
+            **more,
+            urlguard="REASON = 'malformed'\n_MAP = {'a': 'map_a'}\n" + urlguard,
+            routes__a="from app import urlguard\n"
+            + route
+            + "\ndef f(k: Literal['a']):\n"
+            + "    raise HTTPException(409, {'code': 'url_blocked', 'reason': urlguard.REASON})\n"
+            + "    raise HTTPException(409, {'code': 'url_blocked', 'reason': urlguard._MAP[k]})\n",
+        )
+        return _code(r, "url_blocked")["reasons"], _unread(r, "url_blocked")
+
+    assert reasons("def get(k):\n    return _MAP.get(k)\n") == (["malformed", "map_a"], [])
+    other = "from app import other\ndef g():\n    other.REASON = 'x'\n"  # another module's REASON
+    assert reasons("", other, other="REASON = 'y'\n") == (["malformed", "map_a"], [])
+    shadow = (
+        "def h(*urlguard):\n"
+        "    raise HTTPException(409, {'code': 'url_blocked', 'reason': urlguard.REASON})\n"
+    )
+    assert reasons("", shadow)[1] == ["urlguard.REASON"]
+    for urlguard, route in [
+        ("def reset():\n    global REASON\n    REASON = 'x'\n", ""),
+        ("", "def g():\n    urlguard.REASON = 'x'\n"),
+        ("", "def g():\n    del urlguard.REASON\n"),
+    ]:
+        assert reasons(urlguard, route)[0] == ["map_a"], (urlguard, route)
+    for urlguard in [
+        "_MAP['a'] = compute()\n",
+        "def init(x):\n    _MAP['a'] = x\n",
+        "_MAP.update(a='other')\n",
+        "def drop():\n    del _MAP['a']\n",
+        "register(_MAP)\n",
+    ]:
+        got, unread = reasons(urlguard)
+        assert got == ["malformed"] and "(the map is changed after it is built)" in unread[0]
+
+
+def test_a_helper_bound_twice_is_not_followed():
+    r = _scan(
+        refusal="refused = None\n" + textwrap.dedent(REFUSAL),
+        routes__a="from app.refusal import refused\n\ndef f():\n    raise refused(409, 'lost')\n",
+    )
+    assert _code(r, "refused")["reasons"] == []
+    assert _unread(r, "refused")[0].endswith("refused(reason) is not a module-level helper")
+
+
+def test_a_dotted_path_through_an_app_module_that_goes_nowhere_is_unread():
+    r = scan(
+        {
+            "__init__.py": "",
+            "refusal.py": textwrap.dedent(REFUSAL),
+            "routes/a.py": "import app as a\n\ndef f():\n    raise a.refusal.refused(409, 'dotted')\n",
+        }
+    )
+    assert _unread(r, "refused") == ["a.refusal.refused (a reference the scan cannot resolve)"]
+
+
+def test_a_helper_reached_through_an_app_module_that_does_not_bind_it_is_unread():
+    for shim in [
+        "from app.refusal import *\n",
+        "try:\n    from app.refusal import refused\nexcept ImportError:\n    refused = None\n",
+    ]:
+        r = _scan(
+            refusal=REFUSAL,
+            shim=shim,
+            routes__a="from app.shim import refused\n\ndef f():\n    raise refused(409, 'hidden')\n",
+        )
+        assert _unread(r, "refused") == ["refused (a reference the scan cannot resolve)"], shim
+    package = scan(
+        {
+            "pkg/refusal.py": textwrap.dedent(REFUSAL),
+            "pkg/__init__.py": "from .refusal import refused\n",
+            "routes/a.py": "from app.pkg import refused\n\ndef f():\n    raise refused(409, 'hidden')\n",
+        }
+    )
+    assert _unread(package, "refused") == ["refused (a reference the scan cannot resolve)"]
+
+
+def test_the_data_files_are_excluded_by_name_only():
+    r = _scan(
+        plex__tmdb='def f():\n    return {"code": "HU", "name": "Hungary"}',
+        plex__other='def f():\n    return {"code": "HU"}',
+    )
+    assert r["excluded"] == {"plex/tmdb.py": 1}
+    assert "HU" in r["codes"]
+
+
+def test_the_app_scans():
+    """The real tree, on the interpreter the backend runs: every refusal it holds is read (the
+    frontend's contract judges what is read)."""
+    result = scan_app()
+    assert {"refused", "not_found", "login", "clip"} <= set(result["codes"])
+    assert result["errors"] == [] and result["unreadCodes"] == []

backend/tests/test_related_route.py

@@ -0,0 +1,428 @@
+"""`GET /api/search/related/{video_id}` — a video's related videos, without what the user has seen.
+
+The scrape is replaced by pages the test hands out, and YouTube's videos.list by an offline enrich
+(30-minute videos, so no Shorts probe goes out). What is held: the list leaves out what this user
+watched or hid — here or in their Takeout history, unless taken back to "new" since — blocked
+channels and the video itself; it pages on until it has enough; it lands in the catalog the way
+search finds do; and a failure, or the day's cap, says so instead of answering an empty list."""
+
+import threading
+from datetime import datetime, timedelta, timezone
+
+import pytest
+from sqlalchemy import func, select, text
+
+from app import quota, sysconfig
+from app.catalog.models import BlockedChannel, Channel, Subscription, Video
+from app.models import QuotaEvent
+from app.reader.models import TakeoutItem, TakeoutKind, VideoState, VideoUnmark
+from app.routes import search as search_routes
+from app.youtube.client import YouTubeError
+from app.youtube.innertube import ScrapeError
+
+T0 = datetime(2026, 10, 1, tzinfo=timezone.utc)
+SOURCE = "srcvideo001"
+
+
+def _vid(n: int) -> str:
+    return f"rel{n:08d}"
+
+
+def _item(n: int, channel: str = "UCrelated01") -> dict:
+    return {
+        "id": _vid(n),
+        "channel_id": channel,
+        "channel_title": f"Chan {channel}",
+        "title": f"Related {n}",
+        "published_at": None,
+        "thumbnail_url": None,
+        "live_broadcast": "none",
+    }
+
+
+class _FakeYT:
+    def __init__(self, *_a, **_kw):
+        pass
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def get_channels(self, ids):
+        return []
+
+    def get_videos(self, ids):
+        return [
+            {
+                "id": i,
+                "snippet": {"title": f"T {i}", "publishedAt": "2025-01-01T00:00:00Z"},
+                "contentDetails": {"duration": "PT30M"},
+                "statistics": {},
+                "status": {},
+            }
+            for i in ids
+        ]
+
+
+@pytest.fixture
+def pages(monkeypatch, db):
+    """The scrape answers with the pages in `state["pages"]`, one per call, recording each call."""
+    sysconfig.set_value(db, "shorts_probe_max_seconds", 60)
+    state: dict = {"pages": [], "calls": []}
+
+    def related(video_id, continuation=None, *, hl="en", gl="US"):
+        state["calls"].append((video_id, continuation, hl, gl))
+        page = state["pages"].pop(0)
+        if isinstance(page, Exception):
+            raise page
+        return page
+
+    monkeypatch.setattr(search_routes.related_scrape, "related", related)
+    monkeypatch.setattr(search_routes, "YouTubeClient", _FakeYT)
+    return state
+
+
+def _page(items: list[dict], token: str | None = "NEXT") -> dict:
+    return {"items": items, "next_page_token": token}
+
+
+def _ids(resp) -> list[str]:
+    assert resp.status_code == 200, resp.text
+    return [it["id"] for it in resp.json()["items"]]
+
+
+def _known(db, *ns: int, channel: str = "UCrelated01") -> None:
+    """These related videos already in the catalog (a state needs the row)."""
+    if db.get(Channel, channel) is None:
+        db.add(Channel(id=channel, title="Chan"))
+    for n in ns:
+        db.add(Video(id=_vid(n), channel_id=channel, title=f"Related {n}", published_at=T0))
+    db.commit()
+
+
+def test_a_related_list_comes_into_the_catalog_as_search_finds_do(db, make_user, as_user, pages):
+    user = make_user()
+    pages["pages"] = [_page([_item(n) for n in range(1, 21)])]
+    resp = as_user(user).get(f"/api/search/related/{SOURCE}")
+    assert _ids(resp) == [_vid(n) for n in range(1, 21)]
+    assert resp.json()["next_cursor"] == "NEXT" and resp.json()["has_more"] is True
+    video = db.get(Video, _vid(1))
+    # Flagged like a search find: hidden from the shared Library, reclaimed when nobody keeps it.
+    assert video.via_search is True and video.enriched_at is not None
+    assert pages["calls"] == [(SOURCE, None, "en", "US")]
+
+
+def test_what_the_user_watched_or_hid_here_is_left_out(db, make_user, as_user, pages):
+    user = make_user()
+    other = make_user()
+    _known(db, 1, 2, 3, 4)
+    db.add_all(
+        [
+            VideoState(user_id=user.id, video_id=_vid(1), status="watched", watched_at=T0),
+            VideoState(user_id=user.id, video_id=_vid(2), status="hidden"),
+            # In progress is not "seen": it stays, to be finished.
+            VideoState(user_id=user.id, video_id=_vid(3), status="new", position_seconds=120),
+            # Someone else's watch is theirs.
+            VideoState(user_id=other.id, video_id=_vid(4), status="watched", watched_at=T0),
+        ]
+    )
+    db.commit()
+    pages["pages"] = [_page([_item(n) for n in range(1, 6)], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(3), _vid(4), _vid(5)]
+
+
+def test_what_the_takeout_history_shows_watched_is_left_out_unless_taken_back(
+    db, make_user, as_user, pages
+):
+    user = make_user()
+    other = make_user()
+    _known(db, 2)
+    db.add_all(
+        [
+            # Not in the catalog at all: the history alone names it.
+            TakeoutItem(user_id=user.id, kind=TakeoutKind.WATCHED, video_id=_vid(1), at=T0),
+            # Watched on YouTube, then taken back to "new" here: it may come again.
+            TakeoutItem(user_id=user.id, kind=TakeoutKind.WATCHED, video_id=_vid(2), at=T0),
+            VideoUnmark(user_id=user.id, video_id=_vid(2), at=T0 + timedelta(days=1)),
+            # Only in Watch later: not watched.
+            TakeoutItem(user_id=user.id, kind=TakeoutKind.WATCH_LATER, video_id=_vid(3), at=T0),
+            # Another user's history.
+            TakeoutItem(user_id=other.id, kind=TakeoutKind.WATCHED, video_id=_vid(4), at=T0),
+        ]
+    )
+    db.commit()
+    pages["pages"] = [_page([_item(n) for n in range(1, 5)], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(2), _vid(3), _vid(4)]
+    # Left out before the ingest: what the user has seen is not stored for a list that hides it.
+    assert db.get(Video, _vid(1)) is None
+
+
+def test_an_unmark_older_than_the_history_row_does_not_bring_it_back(db, make_user, as_user, pages):
+    user = make_user()
+    _known(db, 1)
+    db.add_all(
+        [
+            VideoUnmark(user_id=user.id, video_id=_vid(1), at=T0 - timedelta(days=1)),
+            TakeoutItem(user_id=user.id, kind=TakeoutKind.WATCHED, video_id=_vid(1), at=T0),
+        ]
+    )
+    db.commit()
+    pages["pages"] = [_page([_item(1), _item(2)], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(2)]
+
+
+def test_another_users_unmark_does_not_bring_it_back(db, make_user, as_user, pages):
+    user = make_user()
+    other = make_user()
+    _known(db, 1)
+    db.add_all(
+        [
+            TakeoutItem(user_id=user.id, kind=TakeoutKind.WATCHED, video_id=_vid(1), at=T0),
+            VideoUnmark(user_id=other.id, video_id=_vid(1), at=T0 + timedelta(days=1)),
+        ]
+    )
+    db.commit()
+    pages["pages"] = [_page([_item(1), _item(2)], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(2)]
+
+
+def test_blocked_channels_and_the_video_itself_are_left_out_and_never_stored(
+    db, make_user, as_user, pages
+):
+    user = make_user()
+    db.add(Channel(id="UCblocked01", title="Blocked"))
+    db.commit()
+    db.add(BlockedChannel(user_id=user.id, channel_id="UCblocked01"))
+    db.commit()
+    own = {**_item(9), "id": SOURCE}
+    pages["pages"] = [_page([_item(1), _item(2, "UCblocked01"), own], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(1)]
+    assert db.get(Video, _vid(2)) is None
+
+
+def test_it_pages_on_until_enough_unseen_videos_are_gathered(db, make_user, as_user, pages):
+    user = make_user()
+    _known(db, *range(1, 16))
+    for n in range(1, 16):
+        db.add(VideoState(user_id=user.id, video_id=_vid(n), status="watched", watched_at=T0))
+    db.commit()
+    pages["pages"] = [
+        _page([_item(n) for n in range(1, 21)], token="page2"),  # 15 seen, 5 new
+        _page([_item(n) for n in range(21, 41)], token="page3"),  # 20 new: 25 now
+        _page([_item(n) for n in range(41, 61)], token="page4"),  # never asked
+    ]
+    ids = _ids(resp := as_user(user).get(f"/api/search/related/{SOURCE}"))
+    assert ids == [_vid(n) for n in range(16, 41)]
+    assert [c[1] for c in pages["calls"]] == [None, "page2"]
+    assert resp.json()["next_cursor"] == "page3"
+
+
+def test_a_repeat_on_a_later_page_counts_once(db, make_user, as_user, pages):
+    user = make_user()
+    pages["pages"] = [
+        _page([_item(n) for n in range(1, 11)], token="page2"),
+        _page([_item(n) for n in range(5, 25)], token=None),
+    ]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [
+        _vid(n) for n in range(1, 25)
+    ]
+
+
+def test_it_reads_at_most_four_pages(db, make_user, as_user, pages):
+    user = make_user()
+    pages["pages"] = [_page([_item(n)], token=f"page{n + 1}") for n in range(1, 7)]
+    ids = _ids(resp := as_user(user).get(f"/api/search/related/{SOURCE}"))
+    assert ids == [_vid(n) for n in range(1, 5)]
+    assert len(pages["calls"]) == 4 and resp.json()["next_cursor"] == "page5"
+
+
+def test_the_cursor_and_the_hungarian_locale_reach_the_scrape(db, make_user, as_user, pages):
+    user = make_user()
+    pages["pages"] = [_page([_item(1)], token=None)]
+    resp = as_user(user).get(f"/api/search/related/{SOURCE}?cursor=C1&region=hu")
+    assert _ids(resp) == [_vid(1)]
+    assert pages["calls"] == [(SOURCE, "C1", "hu", "HU")]
+    assert resp.json()["has_more"] is False
+
+
+def test_an_unknown_region_is_refused(db, make_user, as_user, pages):
+    user = make_user()
+    assert as_user(user).get(f"/api/search/related/{SOURCE}?region=xx").status_code == 422
+    assert pages["calls"] == []
+
+
+def test_a_failed_scrape_says_youtube_is_unavailable(db, make_user, as_user, pages):
+    user = make_user()
+    pages["pages"] = [ScrapeError("blocked")]
+    resp = as_user(user).get(f"/api/search/related/{SOURCE}")
+    assert resp.status_code == 422
+    assert resp.json()["detail"] == {"code": "youtube", "reason": "unavailable"}
+
+
+def test_a_failure_on_a_later_page_keeps_what_came_before(db, make_user, as_user, pages):
+    user = make_user()
+    pages["pages"] = [_page([_item(1), _item(2)], token="page2"), ScrapeError("blocked")]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(1), _vid(2)]
+
+
+def test_one_list_is_one_event_against_the_days_cap(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "related_daily_limit_per_user", 1)
+    pages["pages"] = [
+        _page([_item(1)], token="page2"),
+        _page([_item(2)], token=None),
+    ]
+    client = as_user(user)
+    assert client.get(f"/api/search/related/{SOURCE}").status_code == 200
+    events = db.scalars(
+        select(QuotaEvent).where(
+            QuotaEvent.user_id == user.id, QuotaEvent.action == quota.QuotaAction.VIDEOS_RELATED
+        )
+    ).all()
+    assert len(events) == 1
+    refused = client.get(f"/api/search/related/{SOURCE}")
+    assert refused.status_code == 429
+    assert refused.json()["detail"] == {
+        "code": "refused",
+        "reason": "related_daily_limit",
+        "limit": 1,
+    }
+    assert len(pages["calls"]) == 2  # the refused one asked YouTube nothing
+
+
+def test_reading_further_takes_a_slot_too(db, make_user, as_user, pages):
+    # Each request scrapes and enriches; a cursor is a free string, so one that cost nothing let a
+    # replayed cursor read without end.
+    user = make_user()
+    sysconfig.set_value(db, "related_daily_limit_per_user", 1)
+    pages["pages"] = [_page([_item(1)], token=None), _page([_item(2)], token=None)]
+    client = as_user(user)
+    assert client.get(f"/api/search/related/{SOURCE}").status_code == 200
+    refused = client.get(f"/api/search/related/{SOURCE}?cursor=more")
+    assert refused.status_code == 429
+    assert refused.json()["detail"]["reason"] == "related_daily_limit"
+    assert len(pages["calls"]) == 1
+
+
+def test_a_list_that_failed_gives_its_slot_back(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "related_daily_limit_per_user", 1)
+    pages["pages"] = [ScrapeError("blocked"), _page([_item(1)], token=None)]
+    client = as_user(user)
+    assert client.get(f"/api/search/related/{SOURCE}").status_code == 422
+    assert quota.actions_today(db, user.id, quota.QuotaAction.VIDEOS_RELATED) == 0
+    assert _ids(client.get(f"/api/search/related/{SOURCE}")) == [_vid(1)]
+
+
+def test_failures_past_the_hours_refunds_keep_their_slot(db, make_user, as_user, pages):
+    # A cursor is a free string: a request built to fail would otherwise read YouTube without end.
+    user = make_user()
+    sysconfig.set_value(db, "related_daily_limit_per_user", 50)
+    n = search_routes.REFUNDS_PER_HOUR
+    pages["pages"] = [ScrapeError("bad cursor") for _ in range(n + 1)]
+    client = as_user(user)
+    for _ in range(n + 1):
+        assert client.get(f"/api/search/related/{SOURCE}?cursor=bogus").status_code == 422
+    assert quota.actions_today(db, user.id, quota.QuotaAction.VIDEOS_RELATED) == 1
+
+
+def test_a_zero_limit_turns_related_videos_off(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "related_daily_limit_per_user", 0)
+    resp = as_user(user).get(f"/api/search/related/{SOURCE}")
+    assert resp.status_code == 409
+    assert resp.json()["detail"] == {"code": "refused", "reason": "related_disabled"}
+    assert pages["calls"] == []
+
+
+def test_the_last_slot_is_taken_under_a_lock(db, make_user):
+    # Checked first and logged after seconds of scraping, requests sent together at the last free
+    # slot all passed. The claim waits for one already taking a slot for this user and action.
+    user = make_user()
+    action = quota.QuotaAction.VIDEOS_RELATED
+    db.execute(select(func.pg_advisory_xact_lock(func.hashtext(action), user.id)))
+    got: list[int | None] = []
+    t = threading.Thread(target=lambda: got.append(quota.claim_action(user.id, action, 1)))
+    t.start()
+    t.join(timeout=1)
+    assert t.is_alive()  # it waits for the one holding the lock
+    # ...and counts only once it has the lock: the one holding it takes the last slot meanwhile.
+    db.add(QuotaEvent(user_id=user.id, action=action, units=0))
+    db.commit()
+    t.join(timeout=10)
+    assert got == [None]
+
+
+def _videos_list_fails(monkeypatch, *, on_call: int = 1, reason: str = "quotaExceeded") -> None:
+    """YouTube's videos.list refuses from its `on_call`-th call on."""
+    calls = {"n": 0}
+    real = _FakeYT.get_videos
+
+    def get_videos(self, ids):
+        calls["n"] += 1
+        if calls["n"] >= on_call:
+            raise YouTubeError("videos -> 403", reason=reason, path="videos")
+        return real(self, ids)
+
+    monkeypatch.setattr(_FakeYT, "get_videos", get_videos)
+
+
+def test_a_lookup_that_fails_says_why_not_no_videos(db, make_user, as_user, pages, monkeypatch):
+    # Nothing it found can be kept unenriched; an empty list would read as "nothing related".
+    user = make_user()
+    _videos_list_fails(monkeypatch)
+    pages["pages"] = [_page([_item(1)], token=None)]
+    resp = as_user(user).get(f"/api/search/related/{SOURCE}")
+    assert resp.status_code == 422
+    assert resp.json()["detail"] == {"code": "youtube", "reason": "quota"}
+    assert quota.actions_today(db, user.id, quota.QuotaAction.VIDEOS_RELATED) == 0
+
+
+def test_a_lookup_failing_on_a_later_page_keeps_what_came_before(
+    db, make_user, as_user, pages, monkeypatch
+):
+    user = make_user()
+    _videos_list_fails(monkeypatch, on_call=2)
+    pages["pages"] = [_page([_item(1)], token="page2"), _page([_item(2)], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(1)]
+
+
+def test_an_ingest_that_breaks_the_session_is_rolled_back(
+    db, make_user, as_user, pages, monkeypatch
+):
+    # A database error leaves the session unusable until it is rolled back: the rows of the pages
+    # before could not be read for the answer.
+    user = make_user()
+    real = search_routes.catalog_search.ingest_candidates
+    calls = {"n": 0}
+
+    def ingest(db_, yt, user_, candidates):
+        calls["n"] += 1
+        if calls["n"] == 2:
+            db_.execute(text("SELECT 1/0"))
+        return real(db_, yt, user_, candidates)
+
+    monkeypatch.setattr(search_routes.catalog_search, "ingest_candidates", ingest)
+    pages["pages"] = [_page([_item(1)], token="page2"), _page([_item(2)], token=None)]
+    assert _ids(as_user(user).get(f"/api/search/related/{SOURCE}")) == [_vid(1)]
+
+
+def test_each_row_says_whether_the_user_follows_its_channel(db, make_user, as_user, pages):
+    user = make_user()
+    stranger = make_user()
+    _known(db, 1, channel="UCfollowed1")
+    _known(db, 2, channel="UCstranger1")
+    db.add(Subscription(user_id=user.id, channel_id="UCfollowed1"))
+    db.add(Subscription(user_id=stranger.id, channel_id="UCstranger1"))
+    db.commit()
+    pages["pages"] = [
+        _page([_item(1, "UCfollowed1"), _item(2, "UCstranger1"), _item(3, "UCnobody01")], None)
+    ]
+    rows = as_user(user).get(f"/api/search/related/{SOURCE}").json()["items"]
+    assert {r["id"]: r["followed"] for r in rows} == {
+        _vid(1): True,
+        _vid(2): False,  # another user's follow is not this one's
+        _vid(3): False,
+    }

backend/tests/test_related_scrape.py

@@ -0,0 +1,232 @@
+"""youtube/related_scrape — a video's related videos from the InnerTube `next` endpoint.
+
+The two pages under `fixtures/` are real answers (2026-10-24), trimmed to three items and the
+continuation: they hold the `lockupViewModel` shape YouTube draws today. Everything here breaks
+silently when YouTube moves — a parser that stops finding videos, a cursor that stops paging — so a
+shape it does not know must say so, never read as "nothing related". The network is an httpx
+MockTransport."""
+
+import copy
+import json
+from pathlib import Path
+
+import httpx
+import pytest
+
+from app.youtube import innertube, related_scrape
+
+FIXTURES = Path(__file__).parent / "fixtures"
+FIRST = json.loads((FIXTURES / "innertube_next_first.json").read_text(encoding="utf-8"))
+CONTINUATION = json.loads(
+    (FIXTURES / "innertube_next_continuation.json").read_text(encoding="utf-8")
+)
+RESULTS_HTML = (
+    '<script>{"INNERTUBE_API_KEY":"live-key","INNERTUBE_CLIENT_VERSION":"2.20261001"}</script>'
+)
+
+
+def _results(page: dict) -> list:
+    return page["contents"]["twoColumnWatchNextResults"]["secondaryResults"]["secondaryResults"][
+        "results"
+    ]
+
+
+@pytest.fixture
+def net(monkeypatch):
+    """Route every httpx.Client the InnerTube module opens through a handler the test sets."""
+    calls: list[httpx.Request] = []
+    state: dict = {"handler": None, "calls": calls}
+
+    def transport(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        if request.url.path == "/results":
+            return httpx.Response(200, text=RESULTS_HTML)
+        return state["handler"](request)
+
+    real = httpx.Client
+    monkeypatch.setattr(
+        innertube.httpx,
+        "Client",
+        lambda **kw: real(transport=httpx.MockTransport(transport), **kw),
+    )
+    monkeypatch.setattr(innertube, "_config", None)
+    return state
+
+
+def _answer(net, page, status=200):
+    net["handler"] = lambda request: (
+        httpx.Response(status, text=page)
+        if isinstance(page, str)
+        else httpx.Response(status, json=page)
+    )
+
+
+def test_a_first_page_gives_its_videos_with_their_channel_and_the_next_cursor(net):
+    _answer(net, FIRST)
+    page = related_scrape.related("SdTZAMDKrNY")
+    assert [it["id"] for it in page["items"]] == ["to-lHJfK4pw", "R8V8CbuxryI", "HLKo4fJx_7k"]
+    first = page["items"][0]
+    assert first["channel_id"] == "UCtslD4DGH6PKyG_1gFAX7sg"
+    assert first["channel_title"] == "Alexander Amini"
+    assert first["title"] == "MIT 6.S191 (2025): Reinforcement Learning"
+    assert first["thumbnail_url"].startswith("https://i.ytimg.com/vi/to-lHJfK4pw/")
+    assert first["published_at"] is None and first["live_broadcast"] == "none"
+    assert page["next_page_token"]
+    body = json.loads(net["calls"][-1].content)
+    assert body["videoId"] == "SdTZAMDKrNY" and "continuation" not in body
+    assert net["calls"][-1].url.path == "/youtubei/v1/next"
+
+
+def test_the_largest_thumbnail_is_taken(net):
+    _answer(net, FIRST)
+    item = related_scrape.related("SdTZAMDKrNY")["items"][0]
+    sources = _results(FIRST)[0]["lockupViewModel"]["contentImage"]["thumbnailViewModel"]["image"][
+        "sources"
+    ]
+    assert item["thumbnail_url"] == sources[-1]["url"]
+
+
+def test_a_continuation_page_reads_its_videos_and_sends_only_the_cursor(net):
+    _answer(net, CONTINUATION)
+    page = related_scrape.related("SdTZAMDKrNY", continuation="TOKEN", hl="hu", gl="HU")
+    assert len(page["items"]) == 2
+    assert all(it["channel_id"].startswith("UC") for it in page["items"])
+    assert page["next_page_token"]
+    body = json.loads(net["calls"][-1].content)
+    assert body["continuation"] == "TOKEN" and "videoId" not in body
+    assert body["context"]["client"]["hl"] == "hu" and body["context"]["client"]["gl"] == "HU"
+
+
+def test_the_locale_defaults_to_the_topical_one(net):
+    _answer(net, FIRST)
+    related_scrape.related("SdTZAMDKrNY")
+    client = json.loads(net["calls"][-1].content)["context"]["client"]
+    assert (client["hl"], client["gl"]) == ("en", "US")
+
+
+def test_a_video_by_several_channels_is_left_out(net):
+    page = copy.deepcopy(FIRST)
+    meta = _results(page)[1]["lockupViewModel"]["metadata"]["lockupMetadataViewModel"]
+    meta["image"] = {"avatarStackViewModel": {"avatars": []}}
+    _answer(net, page)
+    ids = [it["id"] for it in related_scrape.related("SdTZAMDKrNY")["items"]]
+    assert ids == ["to-lHJfK4pw", "HLKo4fJx_7k"]
+
+
+def test_what_is_not_a_video_is_left_out_and_a_repeat_counts_once(net):
+    page = copy.deepcopy(FIRST)
+    results = _results(page)
+    playlist = copy.deepcopy(results[0])
+    playlist["lockupViewModel"]["contentType"] = "LOCKUP_CONTENT_TYPE_PLAYLIST"
+    playlist["lockupViewModel"]["contentId"] = "PLxyz"
+    results.insert(0, playlist)
+    results.insert(2, copy.deepcopy(results[1]))
+    results.insert(0, {"adSlotRenderer": {}})
+    _answer(net, page)
+    ids = [it["id"] for it in related_scrape.related("SdTZAMDKrNY")["items"]]
+    assert ids == ["to-lHJfK4pw", "R8V8CbuxryI", "HLKo4fJx_7k"]
+
+
+def test_the_previous_compact_renderer_is_still_read(net):
+    page = copy.deepcopy(FIRST)
+    _results(page).insert(
+        0,
+        {
+            "compactVideoRenderer": {
+                "videoId": "oldshape001",
+                "title": {"simpleText": "Old shape"},
+                "longBylineText": {
+                    "runs": [
+                        {
+                            "text": "Old Chan",
+                            "navigationEndpoint": {"browseEndpoint": {"browseId": "UColdchan"}},
+                        }
+                    ]
+                },
+                "thumbnail": {"thumbnails": [{"url": "s.jpg"}, {"url": "b.jpg"}]},
+            }
+        },
+    )
+    _answer(net, page)
+    first = related_scrape.related("SdTZAMDKrNY")["items"][0]
+    assert first == {
+        "id": "oldshape001",
+        "channel_id": "UColdchan",
+        "channel_title": "Old Chan",
+        "title": "Old shape",
+        "published_at": None,
+        "thumbnail_url": "b.jpg",
+        "live_broadcast": "none",
+    }
+
+
+def test_the_last_page_has_no_cursor(net):
+    page = copy.deepcopy(FIRST)
+    _results(page).pop()  # the continuationItemRenderer
+    _answer(net, page)
+    assert related_scrape.related("SdTZAMDKrNY")["next_page_token"] is None
+
+
+def test_a_video_youtube_no_longer_has_is_an_empty_page(net):
+    _answer(
+        net,
+        {
+            "contents": {
+                "twoColumnWatchNextResults": {
+                    "results": {
+                        "results": {
+                            "contents": [
+                                {
+                                    "itemSectionRenderer": {
+                                        "contents": [{"backgroundPromoRenderer": {}}]
+                                    }
+                                }
+                            ]
+                        }
+                    }
+                }
+            }
+        },
+    )
+    assert related_scrape.related("aaaaaaaaaaa") == {"items": [], "next_page_token": None}
+
+
+def test_a_watch_frame_with_no_related_column_and_no_word_why_is_an_error(net):
+    # The frame alone, its related column moved somewhere this does not look: a lost shape, not
+    # "nothing related".
+    page = copy.deepcopy(FIRST)
+    watch = page["contents"]["twoColumnWatchNextResults"]
+    watch["sideColumn"] = watch.pop("secondaryResults")
+    _answer(net, page)
+    with pytest.raises(related_scrape.ScrapeError):
+        related_scrape.related("SdTZAMDKrNY")
+
+
+def test_a_related_list_drawn_by_renderers_this_does_not_read_is_an_error(net):
+    page = copy.deepcopy(FIRST)
+    results = _results(page)
+    results[:] = [{"videoTileViewModel": entry} for entry in results]
+    _answer(net, page)
+    with pytest.raises(related_scrape.ScrapeError):
+        related_scrape.related("SdTZAMDKrNY")
+
+
+@pytest.mark.parametrize(
+    "answer",
+    [
+        {"responseContext": {}},  # no watch page frame at all
+        {"onResponseReceivedEndpoints": [{"somethingElse": {}}]},  # a continuation we do not know
+        "<html>consent</html>",  # not JSON
+        [1, 2],  # JSON, not an object
+    ],
+)
+def test_an_answer_of_an_unknown_shape_is_an_error_not_an_empty_list(net, answer):
+    _answer(net, answer)
+    with pytest.raises(related_scrape.ScrapeError):
+        related_scrape.related("SdTZAMDKrNY")
+
+
+def test_a_refused_request_is_an_error_whatever_its_body_says(net):
+    _answer(net, FIRST, status=429)
+    with pytest.raises(related_scrape.ScrapeError):
+        related_scrape.related("SdTZAMDKrNY")

backend/tests/test_route_commits.py

@@ -101,8 +101,10 @@ def test_a_video_state_cleared_through_the_route_is_gone(db, make_user, as_user)
     _video(db)
     db.add(VideoState(user_id=user.id, video_id="v1", status="hidden", position_seconds=90))
     db.commit()
-    assert as_user(user).delete("/api/videos/v1/state").status_code == 200
-    assert _state(db, user) is None
+    assert as_user(user).delete("/api/videos/v1/progress").status_code == 200
+    db.expire_all()
+    row = _state(db, user)
+    assert (row.status, row.position_seconds) == ("hidden", 0)
 
 
 # --- saved views ------------------------------------------------------------------------------
@@ -291,6 +293,31 @@ def test_search_results_cleared_through_the_route_are_gone(db, make_user, as_use
     assert db.execute(select(SearchFind)).first() is None
 
 
+def test_clearing_leaves_a_video_the_caller_never_found(db, make_user, as_user):
+    # A related list ingests its rows with no find: they are in someone's list right now, and an id
+    # any user could name must not delete them from under it.
+    user = make_user()
+    _video(db, "s1", via_search=True)
+    _video(db, "s2", via_search=True)
+    db.add(SearchFind(user_id=user.id, video_id="s1"))
+    db.commit()
+    r = as_user(user).post("/api/search/clear", json={"video_ids": ["s1", "s2"]})
+    assert r.json() == {"ok": True, "removed": 1}
+    db.expire_all()
+    assert db.get(Video, "s1") is None and db.get(Video, "s2") is not None
+    # Naming only ids it never found removes nothing.
+    r = as_user(user).post("/api/search/clear", json={"video_ids": ["s2"]})
+    assert r.json() == {"ok": True, "removed": 0}
+
+
+def test_clearing_refuses_a_body_without_its_list(db, make_user, as_user):
+    # A misnamed key read as an empty list: 200, and nothing cleared.
+    user = make_user()
+    r = as_user(user).post("/api/search/clear", json={"ids": ["s1"]})
+    assert r.status_code == 422
+    assert as_user(user).post("/api/search/clear", json={"video_ids": []}).status_code == 200
+
+
 # --- Plex show and season marks ---------------------------------------------------------------
 
 

backend/tests/test_search_cap.py

@@ -0,0 +1,361 @@
+"""`GET /api/search/youtube` — the per-user daily cap of the live search, both sources.
+
+The scrape and search.list are replaced by pages the test hands out, and YouTube's videos.list by an
+offline enrich. What is held: every request takes a slot, a cursor's too; a search that failed
+outright gives its slot back; a zero limit turns live search off, which says so instead of "try
+again tomorrow"; a lookup that fails says why instead of answering "no results"; only a few
+failures an hour get their slot back; and the API source — 100 units a page — reads one page per
+request, is refused before the call when the shared budget cannot pay for it (checked again under
+one lock with the call, whose wait is bounded), counts one slot per search though search.list logs
+its own event, and keeps the slot of a search search.list was already paid for — but not of one
+that never reached YouTube."""
+
+import threading
+
+import pytest
+
+from app import quota, sysconfig
+from app.routes import search as search_routes
+from app.youtube.client import YouTubeError
+from app.youtube.innertube import ScrapeError
+
+ACTION = quota.QuotaAction.VIDEOS_SEARCH
+
+
+def _item(n: int) -> dict:
+    return {
+        "id": f"srch{n:07d}",
+        "channel_id": "UCsearch001",
+        "channel_title": "Chan",
+        "title": f"Found {n}",
+        "published_at": None,
+        "thumbnail_url": None,
+        "live_broadcast": "none",
+    }
+
+
+class _FakeYT:
+    fail_videos = False
+
+    def __init__(self, *_a, **_kw):
+        self.spent = 0
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def get_channels(self, ids):
+        return []
+
+    # search.list: the pages the test hands out, each logged as the real client does (100 units,
+    # under the action the route attributes it to) — a refusal YouTube answered too, but not a
+    # failure no endpoint answered (no connection, no token).
+    api_pages: list = []
+    api_calls = 0
+
+    def search_videos(self, q, page_token=None, order="relevance"):
+        _FakeYT.api_calls += 1
+        page = _FakeYT.api_pages.pop(0)
+        if not (isinstance(page, YouTubeError) and not page.path):
+            quota.record_usage(100)
+            self.spent += 100
+        if isinstance(page, Exception):
+            raise page
+        return page
+
+    def get_videos(self, ids):
+        if _FakeYT.fail_videos:
+            raise YouTubeError("videos -> 403", reason="quotaExceeded", path="videos")
+        return [
+            {
+                "id": i,
+                "snippet": {"title": f"T {i}", "publishedAt": "2025-01-01T00:00:00Z"},
+                "contentDetails": {"duration": "PT30M"},
+                "statistics": {},
+                "status": {},
+            }
+            for i in ids
+        ]
+
+
+@pytest.fixture
+def pages(monkeypatch, db):
+    """The scrape answers with the pages in `state["pages"]`, one per call."""
+    sysconfig.set_value(db, "shorts_probe_max_seconds", 60)
+    sysconfig.set_value(db, "search_source", "scrape")
+    state: dict = {"pages": [], "calls": 0}
+
+    def search(term, continuation=None):
+        state["calls"] += 1
+        page = state["pages"].pop(0)
+        if isinstance(page, Exception):
+            raise page
+        return page
+
+    monkeypatch.setattr(search_routes.search_scrape, "search", search)
+    monkeypatch.setattr(search_routes, "YouTubeClient", _FakeYT)
+    monkeypatch.setattr(_FakeYT, "fail_videos", False)
+    monkeypatch.setattr(_FakeYT, "api_pages", [])
+    monkeypatch.setattr(_FakeYT, "api_calls", 0)
+    return state
+
+
+def _page(n: int) -> dict:
+    return {"items": [_item(n)], "next_page_token": None}
+
+
+def test_every_request_takes_a_slot_a_cursors_too(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "search_daily_limit_per_user", 1)
+    pages["pages"] = [_page(1), _page(2)]
+    client = as_user(user)
+    assert client.get("/api/search/youtube?q=cats").status_code == 200
+    refused = client.get("/api/search/youtube?q=cats&cursor=more")
+    assert refused.status_code == 429
+    assert refused.json()["detail"]["reason"] == "search_daily_limit"
+    assert pages["calls"] == 1
+
+
+def test_a_search_that_failed_gives_its_slot_back(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "search_daily_limit_per_user", 1)
+    pages["pages"] = [ScrapeError("blocked"), _page(1)]
+    client = as_user(user)
+    assert client.get("/api/search/youtube?q=cats").status_code == 422
+    assert quota.actions_today(db, user.id, ACTION) == 0
+    assert client.get("/api/search/youtube?q=cats").status_code == 200
+    assert quota.actions_today(db, user.id, ACTION) == 1
+
+
+def test_a_zero_limit_turns_live_search_off(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "search_daily_limit_per_user", 0)
+    resp = as_user(user).get("/api/search/youtube?q=cats")
+    assert resp.status_code == 409
+    assert resp.json()["detail"] == {"code": "refused", "reason": "search_disabled"}
+    assert pages["calls"] == 0
+
+
+def test_a_zero_limit_turns_the_api_source_off_too(db, make_user, as_user, pages):
+    user = make_user()
+    sysconfig.set_value(db, "search_source", "api")
+    sysconfig.set_value(db, "search_daily_limit_per_user", 0)
+    resp = as_user(user).get("/api/search/youtube?q=cats")
+    assert resp.status_code == 409
+    assert resp.json()["detail"]["reason"] == "search_disabled"
+
+
+def test_a_lookup_that_fails_says_why_not_no_results(db, make_user, as_user, pages, monkeypatch):
+    user = make_user()
+    monkeypatch.setattr(_FakeYT, "fail_videos", True)
+    pages["pages"] = [_page(1)]
+    resp = as_user(user).get("/api/search/youtube?q=cats")
+    assert resp.status_code == 422
+    assert resp.json()["detail"] == {"code": "youtube", "reason": "quota"}
+    assert quota.actions_today(db, user.id, ACTION) == 0
+
+
+def _api(db) -> None:
+    sysconfig.set_value(db, "search_source", "api")
+    sysconfig.set_value(db, "quota_daily_budget", 10000)
+
+
+def test_the_api_source_reads_one_page_per_request(db, make_user, as_user, pages):
+    # Each page is 100 units: a short page is answered as it is, with its cursor, never paged on.
+    _api(db)
+    _FakeYT.api_pages = [{"items": [_item(1)], "next_page_token": "nextpage"}, _page(2)]
+    resp = as_user(make_user()).get("/api/search/youtube?q=cats&limit=20")
+    assert resp.status_code == 200
+    assert _FakeYT.api_calls == 1
+    assert resp.json()["next_cursor"] == "nextpage"
+
+
+def test_the_api_source_counts_one_slot_per_search(db, make_user, as_user, pages):
+    # search.list logs its own event under the action (record_usage): accounting, not a second slot.
+    user = make_user()
+    _api(db)
+    sysconfig.set_value(db, "search_daily_limit_per_user", 2)
+    _FakeYT.api_pages = [_page(1), _page(2), _page(3)]
+    client = as_user(user)
+    assert client.get("/api/search/youtube?q=cats").status_code == 200
+    assert quota.actions_today(db, user.id, ACTION) == 1
+    assert client.get("/api/search/youtube?q=dogs").status_code == 200
+    refused = client.get("/api/search/youtube?q=birds")
+    assert refused.status_code == 429
+    assert refused.json()["detail"]["reason"] == "search_daily_limit"
+    assert _FakeYT.api_calls == 2
+
+
+def test_the_api_source_takes_its_slot_under_the_lock(db, make_user, as_user, pages, monkeypatch):
+    user = make_user()
+    _api(db)
+    claimed: list = []
+    real = quota.claim_action
+
+    def claim(uid, action, limit):
+        claimed.append(action)
+        return real(uid, action, limit)
+
+    monkeypatch.setattr(search_routes.quota, "claim_action", claim)
+    _FakeYT.api_pages = [_page(1)]
+    assert as_user(user).get("/api/search/youtube?q=cats").status_code == 200
+    assert claimed == [ACTION]
+
+
+def test_the_api_source_is_refused_before_the_call_when_the_budget_cannot_pay(
+    db, make_user, as_user, pages
+):
+    user = make_user()
+    _api(db)
+    sysconfig.set_value(db, "quota_daily_budget", 50)
+    _FakeYT.api_pages = [_page(1)]
+    resp = as_user(user).get("/api/search/youtube?q=cats")
+    assert resp.status_code == 429
+    assert resp.json()["detail"]["reason"] == "quota_spent"
+    assert _FakeYT.api_calls == 0
+    assert quota.actions_today(db, user.id, ACTION) == 0
+
+
+def test_an_api_search_that_search_list_refused_keeps_its_slot(db, make_user, as_user, pages):
+    # YouTube charges a refused call too (the client records the units first), so a search that
+    # reached search.list has spent the shared budget: refunding it let a bogus cursor spend it all.
+    user = make_user()
+    _api(db)
+    sysconfig.set_value(db, "search_daily_limit_per_user", 1)
+    _FakeYT.api_pages = [
+        YouTubeError("search -> 400", reason="invalidPageToken", path="search"),
+        _page(1),
+    ]
+    client = as_user(user)
+    assert client.get("/api/search/youtube?q=cats&cursor=bogus").status_code == 422
+    assert quota.actions_today(db, user.id, ACTION) == 1
+    refused = client.get("/api/search/youtube?q=cats")
+    assert refused.status_code == 429
+    assert refused.json()["detail"]["reason"] == "search_daily_limit"
+    assert _FakeYT.api_calls == 1
+
+
+def test_an_api_search_the_budget_refused_at_the_call_gives_its_slot_back(
+    db, make_user, as_user, pages, monkeypatch
+):
+    user = make_user()
+    _api(db)
+    answers = iter([True, False])  # the pre-check passes; the budget is gone by the call
+    monkeypatch.setattr(search_routes.quota, "can_spend", lambda _db, _u: next(answers))
+    _FakeYT.api_pages = [_page(1)]
+    resp = as_user(user).get("/api/search/youtube?q=cats")
+    assert resp.status_code == 429
+    assert resp.json()["detail"]["reason"] == "quota_spent"
+    assert _FakeYT.api_calls == 0
+    assert quota.actions_today(db, user.id, ACTION) == 0
+
+
+def test_the_budget_check_and_the_call_it_pays_for_hold_one_lock(
+    db, make_user, as_user, pages, monkeypatch
+):
+    # Checked apart, searches sent together at the last 100 units all passed, and all spent: the
+    # check and the call sit inside ONE hold of the lock, not two.
+    user = make_user()
+    _api(db)
+    events: list[str] = []
+    real_check = quota.can_spend
+    real_call = _FakeYT.search_videos
+
+    class _Recorded:
+        def __init__(self):
+            self._lock = threading.Lock()
+
+        def acquire(self, timeout=-1):
+            events.append("acquire")
+            return self._lock.acquire(timeout=timeout)
+
+        def release(self):
+            events.append("release")
+            self._lock.release()
+
+    def can_spend(db_, units):
+        events.append("check")
+        return real_check(db_, units)
+
+    def search_videos(self, q, page_token=None, order="relevance"):
+        events.append("call")
+        return real_call(self, q, page_token=page_token, order=order)
+
+    monkeypatch.setattr(search_routes, "_api_search", _Recorded())
+    monkeypatch.setattr(search_routes.quota, "can_spend", can_spend)
+    monkeypatch.setattr(_FakeYT, "search_videos", search_videos)
+    _FakeYT.api_pages = [_page(1)]
+    assert as_user(user).get("/api/search/youtube?q=cats").status_code == 200
+    assert events == ["check", "acquire", "check", "call", "release"]
+
+
+def test_a_search_kept_waiting_for_the_lock_is_refused_as_busy_and_keeps_nothing(
+    db, make_user, as_user, pages, monkeypatch
+):
+    # Each waiter holds a request worker: a slow YouTube must not park them all behind one another.
+    user = make_user()
+    _api(db)
+    monkeypatch.setattr(search_routes, "API_SEARCH_WAIT_SECONDS", 0.05)
+    _FakeYT.api_pages = [_page(1)]
+    # Held by another search for a while: a wait without its bound would get it, and be answered.
+    assert search_routes._api_search.acquire(timeout=1)
+    later = threading.Timer(2.0, search_routes._api_search.release)
+    later.start()
+    try:
+        resp = as_user(user).get("/api/search/youtube?q=cats")
+    finally:
+        later.join()
+    assert resp.status_code == 429
+    assert resp.json()["detail"]["reason"] == "search_busy"
+    assert _FakeYT.api_calls == 0
+    assert quota.actions_today(db, user.id, ACTION) == 0
+
+
+@pytest.mark.parametrize(
+    "failure",
+    [
+        YouTubeError("YouTube API unreachable (ConnectError)", reason="transport"),
+        YouTubeError("User has no stored OAuth token"),
+    ],
+    ids=["no-connection", "no-token"],
+)
+def test_an_api_search_that_never_reached_youtube_gives_its_slot_back(
+    db, make_user, as_user, pages, failure
+):
+    user = make_user()
+    _api(db)
+    sysconfig.set_value(db, "search_daily_limit_per_user", 1)
+    _FakeYT.api_pages = [failure, _page(1)]
+    client = as_user(user)
+    assert client.get("/api/search/youtube?q=cats").status_code == 422
+    assert quota.actions_today(db, user.id, ACTION) == 0
+    assert client.get("/api/search/youtube?q=cats").status_code == 200
+
+
+def test_an_api_search_whose_answer_never_came_keeps_its_slot(db, make_user, as_user, pages):
+    # The request went out (a read timeout): YouTube may have counted it.
+    user = make_user()
+    _api(db)
+    sysconfig.set_value(db, "search_daily_limit_per_user", 1)
+    _FakeYT.api_pages = [
+        YouTubeError("YouTube API unreachable (ReadTimeout)", reason="transport", sent=True),
+        _page(1),
+    ]
+    client = as_user(user)
+    assert client.get("/api/search/youtube?q=cats").status_code == 422
+    assert quota.actions_today(db, user.id, ACTION) == 1
+    assert client.get("/api/search/youtube?q=cats").status_code == 429
+
+
+def test_failures_past_the_hours_refunds_keep_their_slot(db, make_user, as_user, pages):
+    # A cursor is a free string: a request built to fail would otherwise read YouTube without end.
+    user = make_user()
+    sysconfig.set_value(db, "search_daily_limit_per_user", 50)
+    n = search_routes.REFUNDS_PER_HOUR
+    pages["pages"] = [ScrapeError("bad cursor") for _ in range(n + 1)]
+    client = as_user(user)
+    for _ in range(n + 1):
+        assert client.get("/api/search/youtube?q=cats&cursor=bogus").status_code == 422
+    assert quota.actions_today(db, user.id, ACTION) == 1

backend/tests/test_search_scrape.py

@@ -9,7 +9,7 @@ import json
 import httpx
 import pytest
 
-from app.youtube import search_scrape
+from app.youtube import innertube, search_scrape
 
 RESULTS_HTML = (
     '<script>{"INNERTUBE_API_KEY":"live-key","INNERTUBE_CLIENT_VERSION":"2.20261001"}</script>'
@@ -79,11 +79,11 @@ def net(monkeypatch):
 
     real = httpx.Client
     monkeypatch.setattr(
-        search_scrape.httpx,
+        innertube.httpx,
         "Client",
         lambda **kw: real(transport=httpx.MockTransport(transport), **kw),
     )
-    monkeypatch.setattr(search_scrape, "_config", None)
+    monkeypatch.setattr(innertube, "_config", None)
     state["calls"] = calls
     return state
 
@@ -171,7 +171,7 @@ def test_a_failed_key_fetch_falls_back_for_now_and_tries_again_next_time(net, re
     with no error anywhere."""
     net["handler"] = _serve(results_html=results_html)
     search_scrape.search("a")
-    assert net["calls"][-1].url.params["key"] == search_scrape._FALLBACK_KEY
+    assert net["calls"][-1].url.params["key"] == innertube._FALLBACK_KEY
 
     net["handler"] = _serve()
     search_scrape.search("b")

backend/tests/test_search_scrape_ingest.py

@@ -13,10 +13,13 @@ a placeholder never becomes the video's permanent date.
 
 from datetime import datetime, timezone
 
+import pytest
+
 from app import sysconfig
 from app.models import User
 from app.catalog.models import Video
 from app.catalog.search import ingest_candidates
+from app.youtube.client import YouTubeError
 
 
 class _FakeYT:
@@ -97,6 +100,25 @@ def test_scrape_ingest_enrich_miss_keeps_nonnull_placeholder(db):
     assert c.enriched_at is None
 
 
+class _FailingYT(_FakeYT):
+    def get_videos(self, ids):
+        raise YouTubeError("videos -> 403", reason="quotaExceeded", path="videos")
+
+
+def test_a_videos_list_failure_raises_and_keeps_the_stubs(db):
+    # Swallowed, it answered as a page with nothing on it — "no results" for a search whose lookup
+    # never ran. The stubs stay: the FK targets, backfilled later.
+    user = User(email="searcher3@example.com")
+    db.add(user)
+    db.commit()
+
+    with pytest.raises(YouTubeError):
+        ingest_candidates(db, _FailingYT({}), user, [_candidate("vid_ddddddd", "UC_chan_d")])
+
+    db.rollback()  # what the caller does: the stubs were committed before the lookup
+    assert db.get(Video, "vid_ddddddd") is not None
+
+
 def test_search_youtube_route_returns_422_when_ingest_fails(db, monkeypatch, override_dep):
     # Route-level guard (B-core-1): an ingest failure with nothing yet collected must surface as a 422
     # + message on this JSON endpoint (the FE hides 5xx behind a generic "connection lost" + auto-retry,

backend/tests/test_share_paths.py

@@ -0,0 +1,148 @@
+"""A share link's address says what it opens: /watch/ a video, /file/ anything else, /folder/ a folder.
+
+Only a word for the reader: the token is the key, so every path opens every link, and the links
+already sent out on /watch/ keep working for good. DB-lane.
+"""
+
+import pytest
+from cryptography.fernet import Fernet
+
+from app import main, security
+from app.config import settings
+from app.downloads import og
+from app.downloads import probe as probemod
+
+_PAGE = """<!doctype html><html><head>
+<!--OG:START--><meta property="og:title" content="Siftlode" /><!--OG:END-->
+</head><body><script src="/assets/{entry}.js"></script></body></html>"""
+
+_VIDEO = {
+    "streams": [
+        {"codec_type": "video", "codec_name": "h264", "pix_fmt": "yuv420p"},
+        {"codec_type": "audio", "codec_name": "aac"},
+    ],
+    "format": {"format_name": "mov,mp4", "duration": "5"},
+}
+_AUDIO = {
+    "streams": [{"codec_type": "audio", "codec_name": "aac"}],
+    "format": {"format_name": "mov,mp4", "duration": "5"},
+}
+
+
+@pytest.fixture
+def pages(tmp_path, monkeypatch):
+    index, watch = tmp_path / "index.html", tmp_path / "watch.html"
+    index.write_text(_PAGE.format(entry="app"), encoding="utf-8")
+    watch.write_text(_PAGE.format(entry="watch"), encoding="utf-8")
+    monkeypatch.setattr(main, "INDEX_HTML", index)
+    monkeypatch.setattr(main, "WATCH_HTML", watch)
+
+
+@pytest.fixture
+def key(monkeypatch):
+    """A link's address is read back from its encrypted token."""
+    monkeypatch.setattr(security, "_fernet", Fernet(Fernet.generate_key()))
+
+
+@pytest.fixture
+def shared(as_user, make_user, tmp_path, monkeypatch, upload_headers):
+    """Uploads a file ffprobe reads as `data` (None: it cannot read it) and shares it."""
+    monkeypatch.setattr(settings, "files_root", str(tmp_path / "media"))
+    owner = as_user(make_user())
+
+    def share(name: str, data: dict | None, **link: object) -> dict:
+        monkeypatch.setattr(probemod, "probe_json", lambda _p: data)
+        job = owner.post(
+            "/api/files/upload",
+            content=b"some bytes",
+            headers=upload_headers(name, display_name=name),
+        )
+        assert job.status_code == 200, job.text
+        made = owner.post(f"/api/downloads/{job.json()['id']}/links", json=link)
+        assert made.status_code == 200, made.text
+        return made.json()
+
+    share.owner = owner  # type: ignore[attr-defined]
+    return share
+
+
+@pytest.mark.parametrize(
+    ("name", "data", "prefix"),
+    [
+        ("clip.mp4", _VIDEO, "/watch/"),
+        ("song.m4a", _AUDIO, "/file/"),
+        ("backup.tar.gz", None, "/file/"),
+    ],
+)
+def test_a_link_is_given_out_on_the_path_of_what_it_opens(shared, name, data, prefix):
+    made = shared(name, data)
+    assert made["url"] == f"{prefix}{made['token']}"
+
+
+def test_a_folder_link_is_given_out_on_folder(shared, key):
+    owner = shared.owner
+    folder = owner.post("/api/files/folders", json={"name": "Friends"}).json()
+    made = owner.post(f"/api/downloads/folders/{folder['id']}/links", json={}).json()
+    assert made["url"] == f"/folder/{made['token']}"
+    listed = owner.get(f"/api/downloads/folders/{folder['id']}/links").json()
+    assert [entry["url"] for entry in listed] == [made["url"]]
+
+
+def test_the_list_gives_the_same_address_as_the_making(shared, key):
+    made = shared("backup.tar.gz", None)
+    owner = shared.owner
+    files = owner.get("/api/files").json()
+    job_id = next(f["id"] for f in files if f["display_name"] == "backup.tar.gz")
+    listed = owner.get(f"/api/downloads/{job_id}/links").json()
+    assert [entry["url"] for entry in listed] == [made["url"]]
+
+
+@pytest.mark.parametrize("path", ["watch", "file", "folder"])
+@pytest.mark.parametrize(
+    ("name", "data"), [("clip.mp4", _VIDEO), ("backup.tar.gz", None)], ids=["video", "file"]
+)
+def test_every_path_opens_every_link(pages, shared, client, path, name, data):
+    """The links already sent on /watch/ open whatever they open, for good."""
+    token = shared(name, data)["token"]
+    r = client.get(f"/{path}/{token}")
+    assert r.status_code == 200
+    assert "/assets/watch.js" in r.text and "/assets/app.js" not in r.text
+    assert f'content="{name}"' in r.text
+
+
+@pytest.mark.parametrize("path", ["/file/no-such-token", "/folder/no-such-token", "/file/a/b"])
+def test_a_new_path_without_a_live_link_still_gets_the_player(pages, client, path):
+    r = client.get(path)
+    assert r.status_code == 200
+    assert "/assets/watch.js" in r.text and "/assets/app.js" not in r.text
+
+
+def test_a_card_names_a_file_as_a_file(shared, db):
+    made = shared("backup.tar.gz", None)
+    tags = og._watch_tags(made["token"], db)
+    assert f'{made["url"]}"' in tags
+    assert "video.other" not in tags
+
+    locked = shared("notes.tar.gz", None, password="pw")
+    hidden = og._watch_tags(locked["token"], db)
+    assert "Password-protected file" in hidden and "notes" not in hidden
+    assert "video.other" not in hidden
+
+
+def test_a_card_of_a_video_stays_a_video(shared, db):
+    made = shared("clip.mp4", _VIDEO)
+    tags = og._watch_tags(made["token"], db)
+    assert f"/watch/{made['token']}" in tags and "video.other" in tags
+    locked = shared("other.mp4", _VIDEO, password="pw")
+    assert "Password-protected video" in og._watch_tags(locked["token"], db)
+
+
+@pytest.mark.parametrize(
+    ("name", "data", "video"),
+    [("clip.mp4", _VIDEO, True), ("song.m4a", _AUDIO, False), ("backup.tar.gz", None, False)],
+)
+def test_a_password_link_says_whether_it_opens_a_video(shared, client, name, data, video):
+    """The lock screen asks to watch a video and to open anything else, whichever path it is on."""
+    token = shared(name, data, password="pw")["token"]
+    meta = client.get(f"/api/public/watch/{token}").json()
+    assert meta == {"needs_password": True, "kind": "file", "video": video}

backend/tests/test_takeout.py

@@ -292,17 +292,16 @@ def test_a_known_video_is_marked_watched_at_its_takeout_time_and_the_rest_wait_o
     assert (states["older000000"].status, states["older000000"].position_seconds) == ("watched", 40)
 
 
-@pytest.mark.parametrize("undo", ["unmark", "clear_state"])
-def test_a_video_the_user_un_marked_here_is_not_marked_again_by_an_older_view(db, make_user, undo):
-    """Un-marking (or resetting) a video leaves no state row, and the import inserted a watched one
-    over the user's own choice. A view on YouTube after the un-mark is a new view, and counts."""
-    user = make_user(f"{undo}@example.com")
+def test_a_video_the_user_un_marked_here_is_not_marked_again_by_an_older_view(db, make_user):
+    """Un-marking a video leaves no state row, and the import inserted a watched one over the user's
+    own choice. A view on YouTube after the un-mark is a new view, and counts."""
+    user = make_user("unmark@example.com")
     for vid in ("undone00000", "again000000"):
         _video(db, vid)
     db.commit()
     for vid in ("undone00000", "again000000"):
         service.mark(db, user, vid, "watched")
-        getattr(service, undo)(db, user, vid)
+        service.unmark(db, user, vid)
     db.commit()
     assert _states(db, user) == {}
     later = datetime.now(timezone.utc) + timedelta(minutes=5)
@@ -603,7 +602,6 @@ def test_staging_and_settling_take_the_users_one_lock(db, make_user):
         ),
         # Between the import's read of the un-marks and its marking, one would be overwritten.
         "unmark": lambda s, u: service.unmark(s, u, "aaaaaaaaaaa"),
-        "reset": lambda s, u: service.clear_state(s, u, "aaaaaaaaaaa"),
     }
     with SessionLocal() as holder:
         service.lock_takeout(holder, holder.get(User, user.id))

backend/tests/test_upload.py

@@ -579,7 +579,7 @@ def _display_write_sites() -> dict[tuple[str, str], set[str]]:
 #   enqueue_clip                      slices the source's title to the same width.
 #   files.ingest_spooled              passes through `spool_upload`'s value, bounded there.
 #   routes enqueue_clip               the `display_name=` keyword passes on the name bound above it.
-#   pipeline._download / _process_clip / worker._finish_from_cache
+#   pipeline._download / _process_clip / worker._finish_from_cache / backfill._retitle
 #                                     slice a fetched or stored title to the column's width.
 #
 # Held as EXACT EQUALITY rather than as a list of offenders. The offender form could only fail
@@ -596,6 +596,7 @@ DISPLAY_WRITE_SITES = {
     ("downloads/service.py", "enqueue_clip"): {"display_name or asset.title[:DISPLAY_TEXT_MAX]"},
     ("downloads/pipeline.py", "_download"): {"meta.title[:DISPLAY_TEXT_MAX]"},
     ("downloads/pipeline.py", "_process_clip"): {"named[:DISPLAY_TEXT_MAX]"},
+    ("downloads/backfill.py", "_retitle"): {"named[:DISPLAY_TEXT_MAX]"},
     ("worker.py", "_finish_from_cache"): {"asset.title[:DISPLAY_TEXT_MAX]"},
     ("downloads/upload.py", "ingest_upload"): {"display_text(display_name)"},
     ("routes/auth.py", "callback"): {"display_text(userinfo.get('name'))"},

backend/tests/test_video_row.py

@@ -0,0 +1,47 @@
+"""A catalog video as the feed lists it, the row a player opened from an address starts from. DB lane."""
+
+from datetime import datetime, timezone
+
+from app.catalog.models import Channel, Video
+from app.reader.models import VideoState
+
+
+def _video(db, vid="v1"):
+    db.add(Channel(id="UCo", title="Owner", handle="@owner"))
+    db.flush()
+    db.add(
+        Video(
+            id=vid,
+            title="A talk",
+            channel_id="UCo",
+            published_at=datetime.now(timezone.utc),
+            duration_seconds=3600,
+        )
+    )
+    db.commit()
+
+
+def test_a_video_comes_as_the_feed_row_with_my_own_state(db, make_user, as_user):
+    me, other = make_user(), make_user()
+    _video(db)
+    db.add(VideoState(user_id=me.id, video_id="v1", status="new", position_seconds=600))
+    db.add(VideoState(user_id=other.id, video_id="v1", status="watched", position_seconds=90))
+    db.commit()
+    r = as_user(me).get("/api/videos/v1/row")
+    assert r.status_code == 200, r.text
+    row = r.json()
+    assert (row["id"], row["title"], row["channel_title"]) == ("v1", "A talk", "Owner")
+    assert (row["status"], row["position_seconds"]) == ("new", 600)
+    assert row["watch_url"] == "https://www.youtube.com/watch?v=v1"
+
+
+def test_a_video_never_opened_has_no_state(db, make_user, as_user):
+    _video(db)
+    row = as_user(make_user()).get("/api/videos/v1/row").json()
+    assert (row["status"], row["position_seconds"], row["saved"]) == ("new", 0, False)
+
+
+def test_a_video_outside_the_catalog_is_not_found(db, make_user, as_user):
+    r = as_user(make_user()).get("/api/videos/nope/row")
+    assert r.status_code == 404
+    assert r.json()["detail"]["code"] == "not_found"

backend/tests/test_youtube_refusals.py

@@ -193,3 +193,45 @@ def test_any_other_token_refusal_keeps_the_grant(monkeypatch):
         c._access_token()
     assert tok.scopes == "s"
     assert refusal_reason(caught.value) == "unavailable"
+
+
+@pytest.mark.parametrize(
+    ("failure", "sent"),
+    [
+        (httpx.ConnectError("refused"), False),
+        (httpx.ConnectTimeout("slow connect"), False),
+        (httpx.ProxyError("proxy down"), False),
+        (httpx.ReadTimeout("no answer"), True),
+        (httpx.RemoteProtocolError("dropped"), True),
+    ],
+)
+def test_a_transport_failure_says_whether_the_request_went_out(failure, sent):
+    """A search that never reached YouTube spent nothing and gets its slot back; one whose answer
+    never came may have been counted, and keeps it (`routes/search`)."""
+
+    def request(*_a, **_k):
+        raise failure
+
+    c = yt.YouTubeClient.__new__(yt.YouTubeClient)
+    c._http = SimpleNamespace(request=request)
+    with pytest.raises(YouTubeError) as caught:
+        c._send("GET", "https://example.invalid")
+    assert caught.value.reason == "transport"
+    assert caught.value.sent is sent
+
+
+def test_a_call_youtube_answered_is_spent_a_refused_one_too(monkeypatch):
+    resp = httpx.Response(
+        400,
+        json={"error": {"errors": [{"reason": "invalidPageToken"}]}},
+        request=httpx.Request("GET", f"{yt.API_BASE}/search"),
+    )
+    recorded: list[int] = []
+    c = yt.YouTubeClient.__new__(yt.YouTubeClient)
+    c.db, c.spent = None, 0
+    monkeypatch.setattr(yt.sysconfig, "get_str", lambda d, key: "a-key")
+    monkeypatch.setattr(yt.quota, "record_usage", recorded.append)
+    monkeypatch.setattr(c, "_send", lambda *a, **k: resp)
+    with pytest.raises(YouTubeError):
+        c._get("search", {}, cost=100)
+    assert (recorded, c.spent) == ([100], 100)

docs/DESIGN.md

@@ -225,7 +225,10 @@ Also in force:
   tag chip is `Chip`; a sortable row's grip is `DragHandle`. On the always-dark player chrome both
   `Button` and `IconButton` use the `overlay` variant (white, a white layer), whatever the theme; the Plex
   control row is IconButton's `player` rung (36, a 20px glyph, round, 44 on touch). A pressed toggle is
-  `pressed`: the solid accent on a `Button`, the accent glyph on an `IconButton`. A raw `<button>` (or a bare
+  `pressed`: the solid accent on a `Button`, the accent glyph on an `IconButton`, kept under the pointer
+  (no hover layer or hover colour over it). A mode cycle (the player's auto-advance and loop) is no
+  two-state switch: `lit` gives it the same look when it is not off, without `aria-pressed`, and its name
+  says the mode. A raw `<button>` (or a bare
   `FocusSafeButton`) outside the control primitives (eslint `BUTTON_PRIMITIVES`) is a lint error. A text-less button must have an accessible name, and the type enforces
   it. [WCAG 4.1.2]
 - **The chip family** (`Chip`, E28 S3b): rounded-full, never under 24 (A3 grows it to 44 on touch).
@@ -251,8 +254,13 @@ Also in force:
 - A button that starts slow work shows `loading` (a spinner, `aria-busy`) and can't be pressed twice.
   [Nielsen #1]
 - **A glyph means one thing.** Play (▷) starts playback, or resumes a paused transfer; a retry is the
-  refresh arrow (`RefreshCw`); a reset or revert is the counter-clockwise arrow (`RotateCcw`). A failed
-  download's Retry had worn the Play glyph, which promised a video. [Nielsen #4]
+  refresh arrow (`RefreshCw`), and so is doing a download again; a reset or revert is the
+  counter-clockwise arrow (`RotateCcw`), and so is playing from the beginning, on the card and in its
+  menu alike; clearing a video's watch progress is the eraser (`Eraser`). A failed download's Retry
+  had worn the Play glyph, which promised a video. The skip arrows (⏮ ⏭) are Previous /
+  Next; the auto-advance mode beside them wears list glyphs (`ListEnd` next, `ListStart` previous,
+  `Shuffle` random; off is `ListEnd`, not lit) — a mode in the skip arrows put two identical ⏭ on the
+  panel's glyph-only row. [Nielsen #4]
 
 ## Surfaces and page chrome — _Decided_ (batch B)
 
@@ -293,7 +301,8 @@ Also in force:
   `fade-below` utility (`fade-below-panel` / `fade-above-panel` on a panel); the page band and a
   scrolling panel under its header fade by the scroller's own edge mask (`useScrollFade`), because what
   they sit on is the backdrop, not a colour. The chip rows fold their overflow into "+N" rather than
-  scroll, so no row has clipped ends; the carousels fade theirs. The dialog edges come with C4's pinned
+  scroll, so no row has clipped ends, and a filter row puts its picked chips first so the fold never
+  holds the only sign that a filter is on; the carousels fade theirs. The dialog edges come with C4's pinned
   footer (S3f).
 - **Viewport height:** `dvh`, never `vh` / `h-screen`: `100vh` is the viewport with a mobile browser's
   toolbar retracted, so an `h-screen` shell runs its last rows under the toolbar (contract-tested).
@@ -370,7 +379,11 @@ Which actions are visible and which live in a menu.
   managing the shares, re-download, the copies, cancel / delete / remove
   behind their confirms); a link inside a row keeps the browser's own right-click menu. A notification
   row keeps its link and its unread mark, shows its dismiss on hover (in the "…" on touch), and its
-  "…" holds find / undo for an activity notice. The notification center's band keeps Mark all read
+  "…" holds find / undo for an activity notice. The notification center lists what asks for the
+  reader first ("Needs you · n": an unread row, a notice waiting on an action — one read during the
+  visit keeps its place there until Mark all read), then one stream of both sources, newest first,
+  and folds read rows older than a week under "Earlier (n)", a heading-style disclosure, closed — Back to a row
+  that folded away since opens it on that row. Its band keeps Mark all read
   and puts Clear everything, now behind a confirm, in its "…"; the Scheduler's strip keeps Run all
   and Pause and puts Purge discovery in its "…". A list whose row objects are rebuilt each render or replaced by a
   poll passes `useContextMenu({ keyOf })` (its id), so the "…" still closes its own menu. A menu's
@@ -498,7 +511,10 @@ of a full-width panel and nothing on the right.
 ## Interaction rules — _Decided_
 
 - **Keyboard:** everything works by keyboard, in visual order, with no traps. A shortcut is a row in
-  `lib/keymap.ts`; list and grid navigation is `NavGrid`/`keyboardNav`. [WCAG 2.1.1, 2.4.3, 2.1.2]
+  `lib/keymap.ts`; list and grid navigation is `NavGrid`/`keyboardNav`. An open dialog or player
+  silences the page's list keys, but a list inside the topmost one walks while the focus is in it
+  (the player's related videos); the walk stays inside that layer, and its arrows there move the list,
+  not the video. [WCAG 2.1.1, 2.4.3, 2.1.2]
 - **Focus:** every control has a visible focus ring (the base ring in `index.css`; don't add a second). A
   sticky or fixed layer never covers the focused element. A list item the keyboard lands on rings 2 px
   outside itself where it has a gap round it (a card); a table row, a log line or a row flush in a
@@ -521,6 +537,26 @@ of a full-width panel and nothing on the right.
   shows them as four buttons with the item's place beside the selected view; a side panel in edit mode
   gives each group an Up / Down pair (`ui/OrderButtons`, `compact`). A move that would go nowhere is
   shown off, not hidden. A grip also picks up from the keyboard (space, the arrows, space).
+- **Selecting rows:** a list whose rows take bulk actions shows a box first in every row, always, and one
+  over the column for the rows shown. Shift+click selects a range, `x` toggles the row under the keyboard,
+  Esc clears. A selected row wears the accent tint as well as its tick. An action covers the selected rows
+  shown; a row a filter hides stays selected and comes back ticked; another list starts over. The row's own
+  menu still acts on that row alone. While anything is selected the toolbar's second row is the action band:
+  the count (and how many a filter hides), the last move's target as one click, Move to, Remove, Clear
+  selection. An action clears the selection, undoes by its toast and, when it fails, ticks its rows again.
+  An Undo brings back what is still there to bring: a video the move put in the target and the target no
+  longer holds stays where it went, and a warning says how many came back. One the target held already only
+  left the source, so it returns there.
+  Delete takes the selection when there is one, else the row under the keyboard, with no confirm. With every
+  tick hidden by a filter it removes nothing and says so. An Esc during a drag puts the drag down, and only that.
+  Below `xl` the band's buttons are glyphs named in their tooltips, and a filter's hidden count is "+N" with
+  its sentence in the tooltip. The row the band replaces keeps its height, invisible, so a tick moves no row.
+  On a phone the count is its number (the words read out, and in the tooltip) and the undo pair stays out.
+  A row's grip also carries it onto a list in the rail, under a sort or a filter too (the grip then says
+  so, and no key lifts it); a selected row carries every selected one, named on the drag image below the
+  pointer. The target row lights up (`ring-accent`); the open list is none; an unpinned rail peeks by the
+  drag's own hover and scrolls at its edges. Dropped inside the list, one row takes its new place and many
+  stay. A key never leaves the list and moves its own row: the band and the row's menu are the other way.
 - **Motion:** 150–300ms micro-interactions, transform/opacity only; `prefers-reduced-motion` is respected.
   [WCAG 2.3.3]
 
@@ -556,7 +592,8 @@ of a full-width panel and nothing on the right.
   row is not a card and keeps its one play button: started, that button continues, its "…" has Continue +
   "Play from the beginning", and its picture carries the cards' progress bar.
 - **The YouTube modal:** its chrome uses the `Button` rungs (44 on touch); Previous / Next live in the panel
-  (its transport row, or the shut panel's strip) and on Shift+← / →, with no strips beside the card. Close is
+  (its transport row: glyphs only — Previous, the count, Next, auto-advance, loop on one line, each named in
+  its tooltip, the modes with their current one — or the shut panel's strip) and on Shift+← / →, with no strips beside the card. Close is
   an icon at the top right of the panel (wide: its head, or its strip) and at the end of the title row
   under the video (stacked). Wide, the panel shows the description outright, clamped to three
   lines with a More (`ClampedText`; a Tab onto a link below the cut opens it), and collapses to a 2.75rem
@@ -564,6 +601,18 @@ of a full-width panel and nothing on the right.
   open. Stacked, the description opens from an ⓘ, because a hover popover never opens on a tap (measured
   live). The wheel: over the video it sets the volume; over a panel with something to scroll it scrolls
   only, never the volume, even at its end; over one with nothing to scroll it sets the volume. [WCAG 1.4.13]
+- **Related videos (owner's picks A, A, a, a):** on demand, never open by itself — the modal has no room to
+  spare. Wide, a "Related" tab beside the description in the side panel; stacked, a button beside the ⓘ
+  opens them in a drawer over the player. A row is the thumbnailed video row in its narrow form (a 6rem
+  picture, the relative time only, the "…" its one control — every toggle is a row of that menu), with
+  a check before the channel the user follows (named on hover). A click plays it in the same player
+  (Back returns to the opened video), and the list stays the opened video's. Played, it is the item it
+  now is (owner's pick D1 a): its title, its own watched / playlist / download controls, its progress
+  kept, marked watched at its end — and its end does not step the queue. What the user watched or hid
+  is never in it; a list read so far with nothing unseen says so above Show more. Over it, a two-way
+  switch: on topic or trending (the Hungarian chart, labelled just "Trending"), kept on the account. Turned off on the instance (a daily
+  limit of 0, owner's pick D2 a), there is no tab and no button; a refusal a retry cannot answer (the
+  day's cap, turned off, the shared budget) offers no Retry.
 - **Clip mode (both players, owner's picks A + P1 + a):** a scissors in the control row (Plex: the C5 row,
   before the ⋯; YouTube: the actions beside Download, and the docked bar) or `C` opens a clip panel IN the
   player; `[` / `]` mark the start / end at the playhead and open it when shut. The video being watched is the
@@ -669,129 +718,155 @@ of a full-width panel and nothing on the right.
 
 ## Decision log
 
-| Date       | Decision                                         | Chosen                                                                                                                                                                                                                                                                                                                                                                                              | Over                                                                                                                                                                                                   | Why                                                                                                                                                                                                                          |
-| ---------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 2026-09-24 | Floating button                                  | Back to top: a round 48 glass FAB; "round" = floats over something (media or the page)                                                                                                                                                                                                                                                                                                              | A Material 3 rounded square; a labelled pill; the old 64 circle                                                                                                                                        | The common web convention for back to top; round tells it apart from every toolbar button; 64 was oversized                                                                                                                  |
-| 2026-09-24 | Device contract                                  | Tablet portrait + landscape and up; phones out                                                                                                                                                                                                                                                                                                                                                      | A 1024px floor with a "too small" message                                                                                                                                                              | Portrait tablet use is real, and the app already renders at 820 portrait                                                                                                                                                     |
-| 2026-09-24 | Card actions on touch                            | Fewer visible, the rest in a "…" menu                                                                                                                                                                                                                                                                                                                                                               | 44px buttons that no longer fit the card                                                                                                                                                               | Six 44px targets need more width than a card has                                                                                                                                                                             |
-| 2026-09-24 | Action placement                                 | One menu with several triggers, never gesture-only, a desktop background menu that mirrors the toolbar                                                                                                                                                                                                                                                                                              | Visible buttons for everything                                                                                                                                                                         | Fewer non-critical buttons on screen, without hiding any function                                                                                                                                                            |
-| 2026-09-24 | Text selection                                   | Text stays selectable; a click that ends a selection does nothing                                                                                                                                                                                                                                                                                                                                   | Click-to-play on titles                                                                                                                                                                                | The user must be able to copy any text the app shows                                                                                                                                                                         |
-| 2026-09-24 | A1 Button shape                                  | r8 + a rung per context; glass is a Button variant                                                                                                                                                                                                                                                                                                                                                  | r12; a pill                                                                                                                                                                                            | Nested corners (r8 in r12 in r16); the pill already means "a filter or a choice"                                                                                                                                             |
-| 2026-09-24 | A2 Icon buttons                                  | Two sizes, r8; a round button only on media                                                                                                                                                                                                                                                                                                                                                         | One size; all round                                                                                                                                                                                    | A lone toolbar icon at the row size looks lost; round rows read as tags                                                                                                                                                      |
-| 2026-09-24 | A3 Touch size                                    | 44 for every control primitive                                                                                                                                                                                                                                                                                                                                                                      | 36 + gaps; Button only                                                                                                                                                                                 | One rule (HIG 44) instead of two sizes nobody remembers                                                                                                                                                                      |
-| 2026-09-24 | A4 Input                                         | Bordered, a 55% fg-into-bg edge (≥ 3:1)                                                                                                                                                                                                                                                                                                                                                             | Filled; today's look as a primitive                                                                                                                                                                    | The only option that clears WCAG 1.4.11 without a heavy fill on glass                                                                                                                                                        |
-| 2026-09-24 | A5 Dropdown trigger                              | Pill in a toolbar, r8 in a form                                                                                                                                                                                                                                                                                                                                                                     | Pill everywhere; r8 everywhere                                                                                                                                                                         | Matches the neighbours in each context                                                                                                                                                                                       |
-| 2026-09-24 | A6 Checkbox, switch, slider                      | Native, accent-tinted, the row is the target                                                                                                                                                                                                                                                                                                                                                        | Drawn primitives                                                                                                                                                                                       | Free keyboard / screen-reader / forced-colours support; only 3 sites                                                                                                                                                         |
-| 2026-09-24 | B1 Density                                       | Compact 32 / 28 / 24 by explicit height                                                                                                                                                                                                                                                                                                                                                             | Standard 38 / 32 / 26                                                                                                                                                                                  | The owner's read of the lab; touch is covered separately (A3), and one toolbar row lines up at 28                                                                                                                            |
-| 2026-09-24 | B2 Scheme set                                    | Midnight, Forest→cyan, Slate→fuchsia, Matrix→lime                                                                                                                                                                                                                                                                                                                                                   | Today's six                                                                                                                                                                                            | The accent collided with danger (YouTube), warn (Slate) and success (Forest, Matrix); Midnight and Starship were one scheme twice; 4 of 6 light accents failed 4.5:1                                                         |
-| 2026-09-24 | B3 State layers                                  | Text colour at 10% / 16% over anything                                                                                                                                                                                                                                                                                                                                                              | Material's 8 / 12%; today's opacity + bg-card                                                                                                                                                          | Visible in every scheme and mode (≥ 1.2:1); today's row hover was 1.00:1 on a card                                                                                                                                           |
-| 2026-09-24 | B4 Page chrome                                   | One sticky band + fade; filters fold when short                                                                                                                                                                                                                                                                                                                                                     | A floating glass bar; everything scrolls                                                                                                                                                               | Tabs and filters always in reach, in one place; a keyboard-up tablet keeps its content                                                                                                                                       |
-| 2026-09-24 | B5 Surfaces                                      | One class + radius per role                                                                                                                                                                                                                                                                                                                                                                         | Today's per-site mix                                                                                                                                                                                   | Nested corners and no per-site alpha drift                                                                                                                                                                                   |
-| 2026-09-24 | B6 /watch                                        | The app's surfaces, native video controls                                                                                                                                                                                                                                                                                                                                                           | Flat and minimal                                                                                                                                                                                       | The page strangers see should look like the product; native controls work on any device                                                                                                                                      |
-| 2026-09-24 | B7 Nav rail                                      | Soft tint + edge bar, optional labels (a user setting), slim                                                                                                                                                                                                                                                                                                                                        | Solid accent (recommended); a Material rail                                                                                                                                                            | The owner's combination: calmer than a solid fill, labels for who wants them, no width cost                                                                                                                                  |
-| 2026-09-24 | B8 Loading                                       | Skeleton by shape, spinner in a control                                                                                                                                                                                                                                                                                                                                                             | A spinner everywhere                                                                                                                                                                                   | Nothing jumps when data lands; a long wait doesn't look stuck                                                                                                                                                                |
-| 2026-09-24 | B9 Fade                                          | Toolbars / headers, panel tabs, dialog edges, chip rows                                                                                                                                                                                                                                                                                                                                             | Thumbnails; buttons                                                                                                                                                                                    | The north-star depth where content scrolls under chrome; not on content or small controls                                                                                                                                    |
-| 2026-09-24 | C1 Action classification                         | The table (lab C1): state + primary at rest, everyday toggles on hover, "…" on touch, destructive into the menu                                                                                                                                                                                                                                                                                     | Visible buttons per site, as today                                                                                                                                                                     | One action list per object, nothing gesture-only, fewer buttons without losing a function                                                                                                                                    |
-| 2026-09-24 | C2 Side panels                                   | A tap opens an overlay drawer; pin is a separate button ≥ 1024                                                                                                                                                                                                                                                                                                                                      | A tap pins and the content reflows                                                                                                                                                                     | Below 768 the filters were unreachable; on touch a tap pinned and pushed the grid                                                                                                                                            |
-| 2026-09-24 | C3 Players on touch                              | Tap = show the controls; 44px seek hit area; 44 buttons; the YT description behind ⓘ                                                                                                                                                                                                                                                                                                                | Today (tap also pauses; 7.5px seek bar)                                                                                                                                                                | Measured live: you couldn't reach the seek bar without pausing, and the hover-only description never opened on a tap                                                                                                         |
-| 2026-09-24 | C4 Dialogs                                       | Focus by purpose; a pinned footer                                                                                                                                                                                                                                                                                                                                                                   | Focus on Close; the footer scrolls                                                                                                                                                                     | A form starts in its first field, and Save stays on screen with the keyboard up                                                                                                                                              |
-| 2026-09-24 | C5 Plex player controls                          | The owner's lean set: no Stop / Restart / ±10 s buttons, Back by position, Next only with a next item, Resume + From the start on the card, touch double-tap ±10 s                                                                                                                                                                                                                                  | Every control in one row (it ran off-screen below 1024); Back by a press counter; ±10 s keyboard-only                                                                                                  | The row fits a portrait tablet; the decision to restart is made on the card; a tablet keeps the 10 s skip                                                                                                                    |
-| 2026-09-24 | Glass tuner                                      | Retired; the schemes are the only colour choice                                                                                                                                                                                                                                                                                                                                                     | Keep it with ranges clamped to the rules                                                                                                                                                               | Free tuning is the drift the constitution exists to stop (owner)                                                                                                                                                             |
-| 2026-09-24 | Matrix toned down                                | Moss #86a05a at Midnight's lightness, near-neutral greys; every white-on-accent part → `--accent-fg`                                                                                                                                                                                                                                                                                                | The B2 lime #a3e635                                                                                                                                                                                    | The owner found the lime neon and tiring; it was the loudest accent (L 0.85, C 0.21), and fixed white parts sat on it at 1.5:1                                                                                               |
-| 2026-09-24 | Field primitives                                 | `Input` / `Textarea` / `InnerInput` + `fieldClass`, `SelectTrigger`, the native controls; the lint rule "no raw `<input>`"                                                                                                                                                                                                                                                                          | `inputCls` and ~40 hand-styled boxes                                                                                                                                                                   | Six edges, four radii and two focus looks for one control; the ≥ 3:1 edge held nowhere                                                                                                                                       |
-| 2026-09-25 | Surface roles                                    | `SURFACE` roles in `ui/surfaces.ts`; the lint rule "no bare glass class"; menus p-1 with r8 rows                                                                                                                                                                                                                                                                                                    | Three tiers paired ad hoc with five radii and three menu paddings                                                                                                                                      | ~140 sites drifted; nested corners only hold if the radius comes with the role                                                                                                                                               |
-| 2026-09-25 | Static labels                                    | Flat tonal `Badge`, no edge; a filtering tag is an edged chip                                                                                                                                                                                                                                                                                                                                       | A glass pill with an edge, like the chips                                                                                                                                                              | Edged = pressable at a glance; a static tag that looks like a chip gets clicked and does nothing                                                                                                                             |
-| 2026-09-25 | Header search                                    | A 40 glass pill with the field edge (`lg`); what sits inside it is round                                                                                                                                                                                                                                                                                                                            | 44, r16, a glass box with a faint edge                                                                                                                                                                 | The one rounded box among pills, and its edge under 3:1; the hero search is the YouTube/Gmail pill                                                                                                                           |
-| 2026-09-25 | Switch row (F12)                                 | The whole settings row toggles (`SwitchRow`; a hand-laid row points a label at the switch)                                                                                                                                                                                                                                                                                                          | Only the 36×24 switch toggles                                                                                                                                                                          | The iOS / Material settings row; the text was a dead click beside the control it names                                                                                                                                       |
-| 2026-09-25 | Edges and hovers (F14)                           | The ≥ 3:1 edge on the field family (fields, the form trigger); labelled pills keep the faint edge and the accent-edge hover                                                                                                                                                                                                                                                                         | The ≥ 3:1 edge and a state-layer hover on every control                                                                                                                                                | 1.4.11 asks an edge only where nothing else identifies the control; a heavy edge on every chip and tab weighs the whole UI down                                                                                              |
-| 2026-09-25 | Rating and live (F16)                            | Own tokens: `--rating` (theme-scoped gold), `--live`/`--live-fg`, `--rating-media`, `--media-chrome`; palette classes lint-refused                                                                                                                                                                                                                                                                  | Map them to `--warn` / `--danger`                                                                                                                                                                      | A gold star and a red LIVE are what the eye expects; as warn/danger they would read as a status. The old amber score was 2:1 on light                                                                                        |
-| 2026-09-25 | Fjord trial (B2 exception)                       | A fifth scheme, temporary: Midnight's neutrals, Playnite's steel accent (#337599 lifted to #5aa1cb) and steel rules; exit = fold into Midnight or remove                                                                                                                                                                                                                                            | Retune Midnight straight away; borrow only the qualities                                                                                                                                               | The owner wants to live with the calmer palette app-wide before it replaces the default; it breaks "own hue family" on purpose, and only until that call                                                                     |
-| 2026-09-25 | Whole-card row (owner)                           | A card row's B3 layer is the card's `::before` under its content; the open button's hit layer spans the card, the actions sit above it                                                                                                                                                                                                                                                              | The name button's own hover, ending at the first badge or button                                                                                                                                       | A row that half-answers the pointer reads as broken; a badge click did nothing                                                                                                                                               |
-| 2026-09-25 | Badge tones (F29)                                | `Badge tone` neutral / accent / warn at 6%; light `--warn` #b45309 → #a14a07; edged label spans lint-refused                                                                                                                                                                                                                                                                                        | Keep edged status pills (a private Badge in Users, Settings "Granted", the suggestions count)                                                                                                          | Edged = pressable at a glance; amber-700 was 4.58:1 as text and fell under 4.5 on its own tint                                                                                                                               |
-| 2026-09-26 | Page band built (B4)                             | Controls only in the band (intros scroll); the fold shows the same row in place; one `h1` per page (`PageHeading` steps the hidden one aside); `SectionLabel` headings; Skip to content                                                                                                                                                                                                             | A popover of the folded filters; the page title kept visible                                                                                                                                           | A folded row is still the same controls, nothing duplicated; the rail and the tab title already name the page                                                                                                                |
-| 2026-09-26 | Fade built (B9)                                  | `fade-below` on sticky toolbars and table headers; the scroller mask where the band sits on the backdrop                                                                                                                                                                                                                                                                                            | A painted band over the backdrop                                                                                                                                                                       | The backdrop is the colour under the band, so fading the content into it is the same edge                                                                                                                                    |
-| 2026-09-26 | Viewport units                                   | `dvh` everywhere (the Plex player stage with S3f)                                                                                                                                                                                                                                                                                                                                                   | `vh` / `h-screen`                                                                                                                                                                                      | `100vh` hides the last rows under a tablet browser's toolbar                                                                                                                                                                 |
-| 2026-09-26 | Video actions built (C1)                         | One list per video (menu, right-click, long-press, "…"); the card keeps watched / save / add to playlist on its picture on hover; download, details, copy, hide, reset in the menu                                                                                                                                                                                                                  | The six-button row under the card and the hover ⓘ                                                                                                                                                      | The menu is the one door every device has; the card loses a line of height and the touch card its row of 28px buttons                                                                                                        |
-| 2026-09-26 | Plex actions built (C1)                          | One list per Plex title (play/open, watched, add to playlist, media info, copy title, pin); the poster keeps watched / add / "…" on its picture on hover; seasons get open / watched / add / copy                                                                                                                                                                                                   | The hover ⓘ, the pin-only menu, an episode's add button at rest, a collection's "Remove" X on the card                                                                                                 | The same door as a video's; the collection grid goes to two columns on a phone so the touch "…" leaves the title its line                                                                                                    |
-| 2026-09-26 | Playlist actions built (C1)                      | A playlist row's "…" (play, pin, copy title / link, move, order, remove), Delete + an undo toast; one list per playlist (rename, pin, YouTube open / push / revert, delete) from its rail row and its header's "…"                                                                                                                                                                                  | The row's X column and its confirm; the header's pencil, YouTube link, push, revert and trash buttons                                                                                                  | Remove is reversible, so it needs no confirm; the header keeps Play all; a narrow table drops "#" and Channel so the title keeps a width                                                                                     |
-| 2026-09-26 | Channel + Plex list actions (C1)                 | A channel row's "…" (open, pin, YouTube, copy, full history, hide + undo, unsubscribe); a Plex playlist's title / show / season "…", Delete + undo; its header's "…" (rename, delete); an action toast lasts ≥ 8 s                                                                                                                                                                                  | The channel row's full-history, hide and unsubscribe buttons; the Plex list's red X on every row, show and season; the header's pencil and trash                                                       | Hiding and removing are reversible, so they need no confirm and the undo needs time; unsubscribe and deleting a playlist keep theirs                                                                                         |
-| 2026-09-26 | Download / notification / Scheduler actions (C1) | A download row's "…" (play, share, save, edit, details, re-download, manage sharing, copies, cancel / delete / remove); a library row's Share stays in sight, ahead of save; a notification row's "…" and hover dismiss; the inbox band's and the Scheduler strip's "…"                                                                                                                             | The download row's five rare buttons and its cancel / delete / remove; the source link's copy button; an activity notice's Find / Undo links; the band's Clear everything; the strip's Purge discovery | The destructive rows keep their confirm, and Clear everything gains one; a row link keeps the browser's own menu; Find in feed drops the tag / search / age filters that could hide its video                                |
-| 2026-09-26 | Channel menu: Tags + Priority (C1)               | Tags A–Z as in-place checks; Priority as fixed steps 10 · 5 · 3 · 2 · 1 · 0, the current one ticked; a pick re-sorts at once and the page + focus follow the row; one drawn `MenuCheck` for every checkable row that cannot be an `<input>`                                                                                                                                                         | Relative steps (+1 / +5); straight to the top; the stepper only; seven hand-drawn check marks (three box sizes, a tinted box, a × for "on", a trailing tick)                                           | Bubbling a channel up is one pick; fixed levels keep the scale the reader already uses; the list moving where the reader can see it is the feedback                                                                          |
-| 2026-09-26 | Reorder without a drag (WCAG 2.5.7)              | Row menus: Top / Up / Down / Bottom (YouTube + Plex playlists); saved views: four buttons with the place beside the selected view (owner: A); side panels in edit mode: an Up / Down pair per group (owner: A), the name wrapping there                                                                                                                                                             | A "…" on every saved-view row; a "…" on every panel group; drag only                                                                                                                                   | A visible, one-click path where the list is edited; the edge moves shown off so the buttons never shift                                                                                                                      |
-| 2026-09-26 | Titles in click surfaces                         | The surface stays a button, flagged `selectable`: its text selects, and the click that ends a selection does nothing; every plain `Pressable` pinned with its reason                                                                                                                                                                                                                                | Rebuilding each card and row so the title sits outside the button; exceptions for master-detail lists                                                                                                  | Chrome selects inside a button once it is `user-select: text` (measured), so one flag on the primitive keeps the keyboard, focus and list walking every surface already has                                                  |
-| 2026-09-26 | Right-click on a selection                       | The browser's own menu opens on selected words; beside them the object's menu                                                                                                                                                                                                                                                                                                                       | A "Copy selection" row in the app menu                                                                                                                                                                 | The reader selected the words to do something with them; the native menu copies, searches and translates, and changes nothing else                                                                                           |
-| 2026-09-26 | Keyboard ring on a flush row                     | Inside the row (a table row by its tag, a log line, a show header in its clipping card, with the card's corners)                                                                                                                                                                                                                                                                                    | The ring outside, as on a card                                                                                                                                                                         | Outside it ran under the table head and past the table, and a clipping card cut it away entirely (invisible focus)                                                                                                           |
-| 2026-09-26 | Fade at rest                                     | The sticky header's fade appears with the first 1rem of scroll (a scroll-driven animation; no fade where unsupported)                                                                                                                                                                                                                                                                               | A fade that is always drawn                                                                                                                                                                            | At rest it dimmed the first row and hid its ring's top edge; nothing is under the header yet                                                                                                                                 |
-| 2026-09-26 | Narrow playlist table                            | "#" and Channel hide by the table's own width (under 42rem), not the window's                                                                                                                                                                                                                                                                                                                       | Hiding below the `sm` window width                                                                                                                                                                     | Beside the playlist rail a desktop window left the table 432 px and the title 0 px                                                                                                                                           |
-| 2026-09-26 | Background menu built                            | Five list pages (feed, Plex grid, channels, playlist, notifications); the toolbar's sort / view / filters and the band's actions; no destructive row                                                                                                                                                                                                                                                | Every page with a toolbar; the "…" menus copied whole, delete included                                                                                                                                 | The tab-only pages have nothing a menu would add; a blank-area right-click must not be one click from delete                                                                                                                 |
-| 2026-09-26 | Media card anatomy (C)                           | One frame; the meta line pinned to its bottom; the length a badge on the picture; the Plex card on the same primitive as the video card                                                                                                                                                                                                                                                             | A: the year as an overline over the title; B: the year inline after it; a fixed two-line title slot                                                                                                    | A one-line title left a hole the eye reads as a missing line; C puts nothing under a variable-height title                                                                                                                   |
-| 2026-09-26 | One Play                                         | `MediaPlayGlyph` (the media button variant) and only where the click plays                                                                                                                                                                                                                                                                                                                          | The Plex card's hand-painted accent circle; a playable dot on every card                                                                                                                               | One Play for every card; a dot that only a colour and a tooltip explain says nothing                                                                                                                                         |
-| 2026-09-26 | Filtering values on the info page                | A value that filters (year, certificate, studio, director) is an edged chip; a fact is flat text                                                                                                                                                                                                                                                                                                    | Everything flat, the clickable ones only hover-tinted                                                                                                                                                  | The S3d rule: edged = pressable, so the reader sees which values do something                                                                                                                                                |
-| 2026-09-26 | Shelf density                                    | On any strip: one title line over one meta line                                                                                                                                                                                                                                                                                                                                                     | The grid's two lines and full meta on a strip                                                                                                                                                          | The tallest card set the strip's height and left holes in the cards with less to say                                                                                                                                         |
-| 2026-09-26 | Compact list row (B)                             | The title leads; a faint "…" at the end; the toggles float over the date on hover                                                                                                                                                                                                                                                                                                                   | A leading 128px action column                                                                                                                                                                          | That column sat empty at rest, a hole at the start of every row                                                                                                                                                              |
-| 2026-09-26 | Media-info layout (B)                            | A main column (collections first, crew, cast) beside a facts sidebar; an empty column is not drawn                                                                                                                                                                                                                                                                                                  | Every section full width, stacked                                                                                                                                                                      | The collection is the most used; the keywords' column left a void beside a short details box                                                                                                                                 |
-| 2026-09-26 | Mixed Home shelf (A)                             | Plex titles as wide art beside videos                                                                                                                                                                                                                                                                                                                                                               | Posters, with the videos not stretched                                                                                                                                                                 | Stretching a video card to a poster's height left an ~80px gap                                                                                                                                                               |
-| 2026-09-27 | Home hero                                        | A card (hover row + Play on the picture, the whole menu, a touch "…"; owner: A); three quarters wide and centred on a wide window; one fact line; the summary at the measure                                                                                                                                                                                                                        | The hero's pin row alone; full width; an 18rem picture column                                                                                                                                          | The one answer stands in focus, and it offers what the same card offers anywhere                                                                                                                                             |
-| 2026-09-27 | Home shelf tiles                                 | A channel / playlist tile: Play, ↗ open, "…" with Open; a show acts on its next episode, ⓘ opens it; the shelf slot 232px                                                                                                                                                                                                                                                                          | The tile's pin row alone; 200px                                                                                                                                                                        | A tile without its object's actions read as broken; at 200 the Play touched the hover row                                                                                                                                    |
-| 2026-09-27 | Synopsis preview (C)                             | A ~0.9 s mouse rest opens a passive panel beside the card                                                                                                                                                                                                                                                                                                                                           | The synopsis as the picture's `title` tooltip; an ⓘ to hover; none                                                                                                                                     | One long tooltip line fired anywhere on the art and clashed with the cut title's own tooltip                                                                                                                                 |
-| 2026-09-27 | Reading measure                                  | Prose capped at ~65 characters a line (`measure`)                                                                                                                                                                                                                                                                                                                                                   | The container's full width                                                                                                                                                                             | At 110–130 characters a line the eye loses the next line's start                                                                                                                                                             |
-| 2026-09-24 | Chip family                                      | One `Chip` (filter / token / tag / suggest / ghost) + `DismissibleChip`; nothing under 24; the lint rule "no raw `<button>` outside ui/"                                                                                                                                                                                                                                                            | Five chip geometries in five files                                                                                                                                                                     | The applied-filter row, the tag cells, the year picker and the saved-view editor each drew their own chip; a one-letter tag was 21px wide                                                                                    |
-| 2026-09-24 | Button families                                  | `Button` / `IconButton` / `Pressable` / chips / `DragHandle`; `lg` 40 for a hero CTA; pills and a 48 Play on media (from C5)                                                                                                                                                                                                                                                                        | Every button hand-painted                                                                                                                                                                              | 268 hand-rolled buttons in 79 files drifted into as many looks; the ladder only holds if every button stands on it                                                                                                           |
-| 2026-09-27 | C4 as built                                      | `initialFocus` required on every `Modal`; the commit row in `ModalFooter`, portalled under the body from any depth; the fades driven by the body's scroll timeline; `interactive-widget=resizes-content`                                                                                                                                                                                            | An optional prop defaulting to the ✕; a `footer` prop (the issue composer's buttons live three components down); always-on fades                                                                       | A default is how 21 dialogs came to open on the ✕; lifting the composer's state to reach a prop is the larger change; a resting fade dimmed the first line                                                                   |
-| 2026-09-27 | C3 + C5 as built                                 | A tap toggles the bar through `pointerType` from `pointerdown`; a double-tap takes back its first tap's toggle; the card's pair is the video card's `MediaResumeButtons` (Continue / Restart), a sibling over the picture; the YT description is an ⓘ click popover                                                                                                                                 | A delayed single tap (wait out the double-tap window); new "Resume / From the start" words for Plex; the pair inside the picture's button                                                              | A delayed tap feels dead; one media card says one pair of words; a button inside a button is invalid and the hover row already sits beside the picture                                                                       |
-| 2026-09-27 | C2 as built                                      | The side panel's drawer is `ui/Modal` `drawer-start`; drawer = a coarse pointer or below 768; the pin offered in its header ≥ 1024                                                                                                                                                                                                                                                                  | A drawer of its own inside `SidePanel`                                                                                                                                                                 | Esc, Back, the scrim, the trap and the scroll lock are the dialog's; a second implementation is how two shells drift                                                                                                         |
-| 2026-09-30 | Composition and the reader (E30 S6)              | A chapter and a Conformance step: the space is used, one focal point, worst real data, where am I, a click answers at once, zoom and text size first-class; the person page as two columns (facts and bio left, "Known for" right)                                                                                                                                                                  | Rules for pieces only; the bio in a full-width panel; a narrower panel                                                                                                                                 | The person page passed every piece rule with half its panel empty; the owner reads zoomed in, so zoom is a requirement, not a nicety                                                                                         |
-| 2026-09-30 | Hungarian words (E30 S5)                         | The D3 list: Feed, Shorts, Admin, Token, Port stay; stream, Prio, Job, Audit, Demo, Auto, Info, Frontend/Backend, Backfill, transcode get the Hungarian word; one name per thing (kérelem, behúzás, one "Test connection")                                                                                                                                                                          | Keep every loanword; translate Feed/Shorts too                                                                                                                                                         | The owner chose the list (D3); the final sweep found the same feature under two names in three places                                                                                                                        |
-| 2026-09-29 | Numbers and order in the UI language (E30 S3)    | Every number through `lib/format.ts` in the UI language (decimal mark, grouping, compact, units); A→Z by the shown name in the UI language's alphabet, client and server alike; the language comes off `useTranslation`, never the singleton                                                                                                                                                        | `toFixed`, hand-built "1.2K", `localeCompare` in the browser's locale, byte-order server sorts                                                                                                         | A Hungarian reader saw "8.3", "1.2K", "Életrajzi" after "Z"; the singleton read also left values in the old language after a switch (React Compiler)                                                                         |
-| 2026-09-27 | Narrow rows by container                         | The download row, the playlist table and the Channels tag row stack by a container query; a fact line never wraps                                                                                                                                                                                                                                                                                   | Breakpoints on the window                                                                                                                                                                              | The iPad zoomed in, split screen and a column beside a rail are narrow while the window is not; the zoomed download row broke "18.9 / MB" apart                                                                              |
-| 2026-09-27 | Phones deferred                                  | A phone-only layout (the hamburger nav, a folded feed band) waits for its own epic; E28 stays desktop + tablet                                                                                                                                                                                                                                                                                      | Fix the phone views inside E28                                                                                                                                                                         | Principle 2; the first phone attempts made the feed worse, and the epic's review grows with every sprint                                                                                                                     |
-| 2026-09-27 | Conformance check (S3g)                          | A four-step check before a UI change is done: primitive at a named rung, the chapter re-read, the rendered page measured by kind and look, every state seen                                                                                                                                                                                                                                         | A reviewer's eye per sprint                                                                                                                                                                            | The S1 probe found 69 button looks; after S3 every control kind is drawn by its primitive, and the check keeps a new look from arriving unnoticed                                                                            |
-| 2026-09-27 | Segmented rung                                   | `SegmentedToggle` defaults to the toolbar rung (28, `text-xs`); 24 only for a panel's captioned match toggle                                                                                                                                                                                                                                                                                        | The small default                                                                                                                                                                                      | Two toolbars had inherited 10px type from the default beside 28px buttons                                                                                                                                                    |
-| 2026-09-27 | Copy rule (S3g)                                  | One name per feature (the rail may shorten it); four verbs for four meanings; sentence case with the app's places capitalised; "…" when a command asks first; one-sentence messages without a stop; curly quotes; dates relative in lists with the exact minute on hover, three absolute forms; units from Intl, short                                                                              | Word-for-word names everywhere; the verbs as they were; all lower case; no "…"; always a stop; always absolute dates; long or compact units                                                            | The copy survey found 7 EN and 6 HU double names, 22 Delete against 27 Remove, five date shapes and three spellings of a minute; the owner picked every recommended option                                                   |
-| 2026-09-27 | One glyph, one meaning (S4)                      | Play only for playback or resuming a paused transfer; Retry = `RefreshCw`; reset / revert = `RotateCcw`                                                                                                                                                                                                                                                                                             | Retry drawn with Play                                                                                                                                                                                  | The first UI-review run (Downloads) found a failed row whose Retry showed ▷ in the row and its menu                                                                                                                          |
-| 2026-09-27 | Fjord kept                                       | Fjord stays a fifth scheme beside Midnight; the trial wording goes                                                                                                                                                                                                                                                                                                                                  | Fold it into Midnight; remove it                                                                                                                                                                       | The owner lived with it and likes it; the vivid Midnight stays for those who want it. B2's own-hue rule still binds any new scheme                                                                                           |
-| 2026-09-27 | Tablet columns                                   | A table hides `tabletHidden` columns below 64rem of its own width; Channels drops Prio, About, Length                                                                                                                                                                                                                                                                                               | Hide About only; give the name a bigger share                                                                                                                                                          | At 1024 the channel name had 60 px; the owner chose to drop all three there                                                                                                                                                  |
-| 2026-09-27 | Glyph pager                                      | First / previous / next / last as glyph buttons round the page box, names as tooltips                                                                                                                                                                                                                                                                                                               | Words beside the arrows (hidden only on a phone)                                                                                                                                                       | The owner's call: the words widened the row; four arrows are the shared convention                                                                                                                                           |
-| 2026-09-27 | Match switch on the panel                        | `ui/MatchToggle` above the picker from two picks, everywhere; one wording (Any / All)                                                                                                                                                                                                                                                                                                               | The picker's popover footer (Feed, Plex collection)                                                                                                                                                    | A closed picker hid an active "all"; six pickers had drawn it two ways                                                                                                                                                       |
-| 2026-09-27 | Missing picture, bare link                       | A glyph of the kind for no picture; a download with no name is titled by its short link, once                                                                                                                                                                                                                                                                                                       | An empty box; the URL as title, channel and link                                                                                                                                                       | The owner's picks 4A and 3A: an empty box read as loading, the URL showed three times                                                                                                                                        |
-| 2026-09-27 | Copy on a selection                              | Right-click on selected words keeps the browser's menu; no app Copy row                                                                                                                                                                                                                                                                                                                             | An app menu with Copy first                                                                                                                                                                            | A real browser's menu has copy, search and translate; only the desktop pane's is thin                                                                                                                                        |
-| 2026-10-01 | Zoom target 125–133%                             | Screens are held at 125% and 133% browser zoom (1536 × 729, 1444 × 685 on a 1080p window) and the largest text size                                                                                                                                                                                                                                                                                 | 200% browser zoom                                                                                                                                                                                      | The owner: 200% was a guess; 125–133% is what they read Siftlode and most sites at, so 200% would be an upper bound nobody uses                                                                                              |
-| 2026-10-01 | E31 Nav rail at short heights                    | One "Admin" rail item opening a panel of the admin pages                                                                                                                                                                                                                                                                                                                                            | A denser rail when short; a visible "+4" hint                                                                                                                                                          | The rail fits at 133–150% without a hidden scroll; the admin pages are rare and admin-only                                                                                                                                   |
-| 2026-10-01 | E31 Configuration sections                       | A vertical, grouped section list, as Settings has                                                                                                                                                                                                                                                                                                                                                   | Group tabs + sub-tabs; one long page with a contents list                                                                                                                                              | Sixteen tabs wrapped to three rows at 133%; one pattern for both settings pages                                                                                                                                              |
-| 2026-10-01 | E31 Statistics overview                          | Number tiles, and the per-operation counts as horizontal bars                                                                                                                                                                                                                                                                                                                                       | Three narrow cards; a 30-day chart                                                                                                                                                                     | The label sits by its value; what spends the quota is seen at a glance                                                                                                                                                       |
-| 2026-10-01 | E31 Channel page header                          | The full banner, folding to one row once the grid scrolls                                                                                                                                                                                                                                                                                                                                           | Always compact; no banner                                                                                                                                                                              | The header is fixed and took 40% of a 685px window; the channel keeps its face at first sight                                                                                                                                |
-| 2026-10-01 | E31 Channel page watch state                     | A fresh channel page shows the unwatched videos; a picked state is remembered                                                                                                                                                                                                                                                                                                                       | Show all, forgotten on reload                                                                                                                                                                          | The owner: open a channel to see what is new; a choice made there should stick                                                                                                                                               |
-| 2026-10-01 | E31 Audit log runs                               | A job's successful runs fold into one row that opens, whatever ran between; only that job's failure (never folded, danger colour) breaks it                                                                                                                                                                                                                                                         | A filter defaulting to admin actions; both                                                                                                                                                             | Nothing hidden, the noise collapsed, the failure seen                                                                                                                                                                        |
-| 2026-10-01 | E31 Users row                                    | Role and state as badges, the actions in the row's one menu                                                                                                                                                                                                                                                                                                                                         | An inline role toggle; icon-only buttons                                                                                                                                                               | Action placement: the row shows state, rare and destructive actions live in the menu                                                                                                                                         |
-| 2026-10-01 | E31 YouTube player                               | Video beside an info panel at 1280px and wider (the video as large as the height allows); stacked below                                                                                                                                                                                                                                                                                             | Today's stack with a one-line bar; full-window like Plex                                                                                                                                               | The owner's eyesight: about 1460px of video on 1080p instead of 1008, the actions still visible                                                                                                                              |
-| 2026-10-01 | E31 Plex info and show pages                     | A second column for the facts, keywords and crew, as the person page; a collection's hero sized to its content                                                                                                                                                                                                                                                                                      | Full-width text; a larger poster and fanart                                                                                                                                                            | The right ~40% was empty; one composition for every media page                                                                                                                                                               |
-| 2026-10-01 | E31 Nav rail rows are links                      | Each page row is a real link: a middle-click or Ctrl-click opens the page in a new tab                                                                                                                                                                                                                                                                                                              | A button                                                                                                                                                                                               | The owner: open a page in a tab of its own, as on any site                                                                                                                                                                   |
-| 2026-10-02 | E31 Plex detail second column (refined)          | The facts over the key crew beside the text; the keywords, chips that filter like the genres, under the text; the show page gets all three too                                                                                                                                                                                                                                                      | All three in the column, as the mockup drew it                                                                                                                                                         | At 20 keywords and 12 crew the column ran to twice the text's height (849 vs ~400 px at 133%): a hole under the text instead of beside it                                                                                    |
-| 2026-10-02 | E31 Plex detail poster and crew                  | The movie and show poster keeps its 2:3 and grows a rung in a wide hero (w-56 at a 64rem panel); the crew shows its first 6 names and "Show N more" (a list of 8 or fewer shows whole)                                                                                                                                                                                                              | Poster stretched to the row; a "More" on the keywords                                                                                                                                                  | The row is as tall as the crew column, so the poster drew ~175×590 and cropped; the crew, not the keywords, set the hero's height                                                                                            |
-| 2026-10-04 | E32 `field` focus skips a mode switch            | A form opens on its first field; a control above it that is not a field (the composer's Edit / Preview) is passed over by marking the field `data-initial-focus`                                                                                                                                                                                                                                    | The first text field everywhere                                                                                                                                                                        | That moved the focus in the download dialog off its profile choice and in the upload dialog off its drop zone; the mark changes only the form that needs it                                                                  |
-| 2026-10-04 | E35 Lint for z-levels and edged labels           | Both rules stay; the two eslint selectors (`Z_RAW`, `EDGED_LABEL`) that refused them go                                                                                                                                                                                                                                                                                                             | Keep the selectors                                                                                                                                                                                     | 0 hits since the E28 sweep that fixed the sites: a check that never fires costs a probe test and a snapshot each, and the UI review holds both rules                                                                         |
-| 2026-10-06 | `player` focus                                   | A dialog that is a player opens focused on its panel (the YouTube player's rule, now `Modal`'s too); on the media element itself, Space and the arrows stay the element's own                                                                                                                                                                                                                       | `close`, or the media element                                                                                                                                                                          | On the ✕ Space closed the player; on the element the browser's own controls acted on the same key as the player's (one Space played and paused, measured in Chrome)                                                          |
-| 2026-10-08 | Captions on touch                                | A `Tooltip` opens for a mouse and a key's focus only, never for a finger                                                                                                                                                                                                                                                                                                                            | A caption on tap; a long-press caption                                                                                                                                                                 | On an iPad the tap that showed the caption was taken as a hover and lost its click (every rail button took two taps), and no finger sends the mouseleave that hides it; the rail's labels setting names the buttons on touch |
-| 2026-10-08 | Header search on touch                           | No key cap on a touch screen; the pill grows to 52 px so a ring shows round the 44 px Go; Go drops to its icon by the column's width                                                                                                                                                                                                                                                                | Keep the key cap; a 44 px Go overhanging a 40 px pill                                                                                                                                                  | On a tablet the 44 px key cap and Go sat on the pill's edge and cut the placeholder; an overhanging Go breaks the nested radii                                                                                               |
-| 2026-10-08 | Plex subtitles and the control bar               | The player draws the cues itself; while the bar shows they rise above it (200 ms), then settle back                                                                                                                                                                                                                                                                                                 | The browser's own cues, moved by `line`                                                                                                                                                                | On an iPad the bar covered the text; a native cue cannot be animated or measured, and our layer behaves the same on every engine                                                                                             |
-| 2026-10-08 | Hover on a button over a picture                 | The `media` variant's hover is a 2px accent ring over a darker body (Plex + YT cards, rail arrows; option B)                                                                                                                                                                                                                                                                                        | An accent fill (reads as "selected"); a white wash (weak on a bright poster)                                                                                                                           | The 60 → 75% black step was invisible, and over a card a rail arrow could not be told from the card's own Play under it                                                                                                      |
-| 2026-10-08 | Plex "Add to collection"                         | A movie or show card's menu row opens a panel beside the card: its library's manual collections tick in place, a name + Enter creates one with the title in it (admin; option A)                                                                                                                                                                                                                    | An Add submenu with a "New…" dialog; the per-title editor modal from the menu                                                                                                                          | A collection took a trip to the Collections page, a name, a title search, then a second search per title; the panel is the video card's "Add to playlist"                                                                    |
-| 2026-10-08 | YouTube modal chrome                             | No prev/next strips beside the card; Close an icon (the panel's top right; stacked, the title row's end); the description clamped to three lines + More; the panel shuts to a 2.75rem strip of close, expand, prev/next (option D1)                                                                                                                                                                 | Keep the strips; a "Close" text button; the full description in a scroller; a panel that hides outright                                                                                                | The strips cost the video 7rem of width for a second copy of the panel's buttons; a long description pushed the channel and the actions out of sight; a hidden panel left no way to step the queue without the keyboard      |
-| 2026-10-08 | The wheel over the YouTube modal                 | Over the video: volume. Over a panel with something to scroll: scroll only, never volume, not even at its end. Over a panel with nothing to scroll: volume (owner)                                                                                                                                                                                                                                  | Volume everywhere; a scroll that hands over to the volume at its end                                                                                                                                   | Reading a long description turned the volume down once it hit the end                                                                                                                                                        |
-| 2026-10-09 | A Plex show card plays                           | Its picture plays the show's next episode everywhere (an episode with a resume point → Continue + Restart, else the first unwatched, else S1·E1), resolved on the click; the preview names it once up; title and ⓘ open the show (option A + hover ask)                                                                                                                                             | The picture opens the show page (as before); every card carrying `next`                                                                                                                                | A show card on Discover had no Play while Home's had one; carrying `next` costs a grid page up to 180 queries for the few cards anyone plays                                                                                 |
-| 2026-10-10 | Clip mode in the players (E38)                   | Scissors in the control row + `C`, `[` `]`; the panel in the player with the watched video as preview; overview + zoomed strip on `ui/RangeTrack` (ends are sliders); a toast + the Ready notification after Cut                                                                                                                                                                                    | A ⋯ menu entry; permanent In / Out buttons; a big dialog with its own preview (a second Plex transcode / YouTube iframe)                                                                               | Owner's picks A, P1, a; a film is hours and a clip seconds, so only a zoomed strip gives a hand the precision. The Downloads editor's cuts moved onto the same track (keyboard-steppable now)                                |
-| 2026-10-10 | Crop in clip mode (E38)                          | A Crop toggle in the clip panel: a frame over the playing picture (`ui/CropFrame`, the editor's crop too), Free / 16:9 / 9:16 / 1:1, Whole picture; maximised YouTube keeps the panel in the bar's place; the wide side panel shuts while clipping                                                                                                                                                  | A frame always on the picture in clip mode (K2); a free shape only                                                                                                                                     | Owner's K1 + a: a crop is rare, so it never covers the picture unasked; a phone or square clip needs a held shape. The iframe hides its picture's size: drawn on the 16:9 box, the cut fits it to the real picture           |
-| 2026-10-10 | Marks on the player chrome                       | `--media-mark` (amber) and `--media-danger` (light red), the same in both themes; `media-marks` points the focus ring (`--focus`) and the chosen mark (`--chosen`: a track's tick, a tab's underline; the label stays white) at the amber on the player and every chrome surface; `media-scope` (a form) also the errors at the red                                                                 | The theme's accent ring, chosen text, warn and danger                                                                                                                                                  | On the chrome (#171717) a light theme's accent ring (Slate 2.84:1), warn (2.99:1) and danger (2.77:1) all fall under 3:1; the accent as chosen text under 4.5:1                                                              |
-| 2026-10-11 | Files page (one library)                         | List rows by default, the media grid a toggle remembered per folder; a sidebar of automatic source folders, own folders, Shared with me and the storage meter; the paste-a-link box in the toolbar                                                                                                                                                                                                  | A media grid by default                                                                                                                                                                                | The library holds videos AND plain files: rows read both, show more per screen and scan by size and date                                                                                                                     |
-| 2026-10-11 | Library list columns                             | Every kind of value in its own column (name, source, phone-safe, retention, size, added, actions), one grid with a subgrid per row so they line up; an action that does not apply keeps its slot empty; a right-click menu on every row (the ⋯ opens the same menu)                                                                                                                                 | Badges flowing after the title; icons that shift when one is missing                                                                                                                                   | Owner: values of one kind must fall in one vertical line; a row's every action reachable by right click                                                                                                                      |
-| 2026-10-11 | Running downloads                                | An app-wide tray, bottom right, shown only while something runs or failed (reason + retry), foldable to a pill                                                                                                                                                                                                                                                                                      | A rail icon with a count and a popover                                                                                                                                                                 | Downloading became an action you start anywhere; a running one must be visible without going to look                                                                                                                         |
-| 2026-10-11 | Download done                                    | The notification says whether it plays on a phone and carries Link másolása + Megnyitás (the folder, the item focused); never an automatic jump                                                                                                                                                                                                                                                     | A plain "ready" notice; auto-navigation to the item                                                                                                                                                    | The daily path is paste → done → copy the link; a jump would pull the user out of what they were doing                                                                                                                       |
-| 2026-10-11 | Library row quick icons (owner A)                | On a wide list only the ⋯ holds a place; Copy link, Share and Save come up over the date while the row is hovered or holds the keyboard; a card (phone) keeps them in its own line; Keeps narrower                                                                                                                                                                                                  | Three icons always in sight (the name kept ~150px at 1200); dropping Added below 64rem                                                                                                                 | Owner: the name is what a row is read by; every action stays in the ⋯ and the right-click menu                                                                                                                               |
-| 2026-10-12 | Files preview (owner ★)                          | A file that is not media opens from its name in the dialog shell, wide: an image, a PDF in the browser's own viewer, text as numbered plain text (HTML and SVG too) with a wrap toggle, else a no-preview card with Save; ← / → page the list's such files in its order; an image under 8 MB is its own thumbnail                                                                                   | A side panel beside the list; a new browser tab; pdf.js; syntax highlighting; a click that saves a file without a preview                                                                              | Owner: one way to open anything, paged like the list; the browser's PDF viewer is free and isolated; a page is never rendered on our origin                                                                                  |
-| 2026-10-12 | A running download's step (owner ★)              | The tray row names the step beside its bar ("Downloading audio · 12%", "Merging" with a pulse); a paused-only tray shows a pause mark, never the done check                                                                                                                                                                                                                                         | A bare bar and %                                                                                                                                                                                       | A download fetches video and audio as two streams: unnamed, the second fill reads as a restart; the tray is the only place a download is followed                                                                            |
-| 2026-10-14 | API tokens (owner A/A/A)                         | Settings → API tokens: a row per token in three lines (name + prefix, its folders and rights, last use and expiry), revoked from its ⋯; a new token asks the kind first (Hub exchange or Custom: rights as chips per folder), expiry 1 year by default; the token shows once in the same dialog, with Copy and a curl line                                                                          | A table; one form with a preset link; the token in a banner above the list                                                                                                                             | A table truncates the rights at this width; the common token never shows a matrix to get wrong; closing the dialog is plainly when the token is gone                                                                         |
-| 2026-10-15 | Folder links (owner A/A/A)                       | An own folder's menu has Copy link and Share with link… as a file row does (the dialog is the link half of the file's); the link opens a list of the folder's files as it is now, Play opening the watch player above it with the playing row lit, a document only downloading; the rail marks a folder with a live link beside its count                                                           | Share with link… alone; cards; a download-only list; no mark                                                                                                                                           | Mostly videos from a phone, read on a phone: a list gives a long name its line and the next one is a tap away; the folder link is the one place where moving a file in publishes it, so where it is must show                |
-| 2026-10-17 | Copy-only changes (owner ★)                      | Step 4 of the Conformance check alone (not 1–3 or 5): every state the changed text renders in, seen in both languages                                                                                                                                                                                                                                                                               | The whole five-step check; no screenshot at all (DOM test + key parity)                                                                                                                                | Steps 1–3 and 5 judge controls, patterns and composition, which a text change does not touch; the one risk left is a longer Hungarian string wrapping or clipping, and only a screenshot shows that                          |
-| 2026-10-17 | Text on glass (owner ★)                          | Light `--muted` 15% toward `--fg` in every scheme (≥ 6:1 on the bare page); the item count, the badges and the current Files row on opaque tints mixed into the surface                                                                                                                                                                                                                             | Only the two failing components; the item count's number in `--fg`                                                                                                                                     | Pixel-measured over every scheme × mode × backdrop, the count fell to 3.8:1 (dark too: thumbnails scroll under the toolbar's glass) and Channels' tabs to 4.1:1; an `--fg` count outshouts the filters beside it             |
-| 2026-10-18 | Scheduler run history (owner D4, E1, E2 ★)       | A row's last three runs as dots, newest first (interrupted: a hollow warn ring, set apart from skipped and failed), and a history button that opens the job's runs on the Activity page; a user's ad-hoc runs in their own block under the jobs, with no interval and no run button                                                                                                                 | An inline expandable history per row; a dark-grey interrupted dot; ad-hoc runs only on the Activity page                                                                                               | Three dots answer "did it run, did it work" at a glance; the whole history needs filters, which the Activity page has                                                                                                        |
-| 2026-10-18 | Activity page (owner D1, D2, G1–G3 ★)            | One page, "Napló" / "Activity": four tabs (Runs, Admin actions, Server log, Quota) under one filter bar (text, a period of 1 h · 24 h · 7 d · 30 d · 90 d defaulting to 7 days, an account), the view in the URL; runs and admin actions as dense rows that open in place as a log line does, filtered and paged on the server; a run's or a request's log lines one pivot away, as a history entry | One merged timeline; a page per source; a default period per tab; card rows; the audit log's client-side table                                                                                         | Each source keeps its own table and retention, read in one place; one bar keeps what you narrowed across tabs; about 1.8k runs a day need a log's density and a server-side filter                                           |
+| Date       | Decision                                                         | Chosen                                                                                                                                                                                                                                                                                                                                                                                              | Over                                                                                                                                                                                                   | Why                                                                                                                                                                                                                          |
+| ---------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 2026-09-24 | Floating button                                                  | Back to top: a round 48 glass FAB; "round" = floats over something (media or the page)                                                                                                                                                                                                                                                                                                              | A Material 3 rounded square; a labelled pill; the old 64 circle                                                                                                                                        | The common web convention for back to top; round tells it apart from every toolbar button; 64 was oversized                                                                                                                  |
+| 2026-09-24 | Device contract                                                  | Tablet portrait + landscape and up; phones out                                                                                                                                                                                                                                                                                                                                                      | A 1024px floor with a "too small" message                                                                                                                                                              | Portrait tablet use is real, and the app already renders at 820 portrait                                                                                                                                                     |
+| 2026-09-24 | Card actions on touch                                            | Fewer visible, the rest in a "…" menu                                                                                                                                                                                                                                                                                                                                                               | 44px buttons that no longer fit the card                                                                                                                                                               | Six 44px targets need more width than a card has                                                                                                                                                                             |
+| 2026-09-24 | Action placement                                                 | One menu with several triggers, never gesture-only, a desktop background menu that mirrors the toolbar                                                                                                                                                                                                                                                                                              | Visible buttons for everything                                                                                                                                                                         | Fewer non-critical buttons on screen, without hiding any function                                                                                                                                                            |
+| 2026-09-24 | Text selection                                                   | Text stays selectable; a click that ends a selection does nothing                                                                                                                                                                                                                                                                                                                                   | Click-to-play on titles                                                                                                                                                                                | The user must be able to copy any text the app shows                                                                                                                                                                         |
+| 2026-09-24 | A1 Button shape                                                  | r8 + a rung per context; glass is a Button variant                                                                                                                                                                                                                                                                                                                                                  | r12; a pill                                                                                                                                                                                            | Nested corners (r8 in r12 in r16); the pill already means "a filter or a choice"                                                                                                                                             |
+| 2026-09-24 | A2 Icon buttons                                                  | Two sizes, r8; a round button only on media                                                                                                                                                                                                                                                                                                                                                         | One size; all round                                                                                                                                                                                    | A lone toolbar icon at the row size looks lost; round rows read as tags                                                                                                                                                      |
+| 2026-09-24 | A3 Touch size                                                    | 44 for every control primitive                                                                                                                                                                                                                                                                                                                                                                      | 36 + gaps; Button only                                                                                                                                                                                 | One rule (HIG 44) instead of two sizes nobody remembers                                                                                                                                                                      |
+| 2026-09-24 | A4 Input                                                         | Bordered, a 55% fg-into-bg edge (≥ 3:1)                                                                                                                                                                                                                                                                                                                                                             | Filled; today's look as a primitive                                                                                                                                                                    | The only option that clears WCAG 1.4.11 without a heavy fill on glass                                                                                                                                                        |
+| 2026-09-24 | A5 Dropdown trigger                                              | Pill in a toolbar, r8 in a form                                                                                                                                                                                                                                                                                                                                                                     | Pill everywhere; r8 everywhere                                                                                                                                                                         | Matches the neighbours in each context                                                                                                                                                                                       |
+| 2026-09-24 | A6 Checkbox, switch, slider                                      | Native, accent-tinted, the row is the target                                                                                                                                                                                                                                                                                                                                                        | Drawn primitives                                                                                                                                                                                       | Free keyboard / screen-reader / forced-colours support; only 3 sites                                                                                                                                                         |
+| 2026-09-24 | B1 Density                                                       | Compact 32 / 28 / 24 by explicit height                                                                                                                                                                                                                                                                                                                                                             | Standard 38 / 32 / 26                                                                                                                                                                                  | The owner's read of the lab; touch is covered separately (A3), and one toolbar row lines up at 28                                                                                                                            |
+| 2026-09-24 | B2 Scheme set                                                    | Midnight, Forest→cyan, Slate→fuchsia, Matrix→lime                                                                                                                                                                                                                                                                                                                                                   | Today's six                                                                                                                                                                                            | The accent collided with danger (YouTube), warn (Slate) and success (Forest, Matrix); Midnight and Starship were one scheme twice; 4 of 6 light accents failed 4.5:1                                                         |
+| 2026-09-24 | B3 State layers                                                  | Text colour at 10% / 16% over anything                                                                                                                                                                                                                                                                                                                                                              | Material's 8 / 12%; today's opacity + bg-card                                                                                                                                                          | Visible in every scheme and mode (≥ 1.2:1); today's row hover was 1.00:1 on a card                                                                                                                                           |
+| 2026-09-24 | B4 Page chrome                                                   | One sticky band + fade; filters fold when short                                                                                                                                                                                                                                                                                                                                                     | A floating glass bar; everything scrolls                                                                                                                                                               | Tabs and filters always in reach, in one place; a keyboard-up tablet keeps its content                                                                                                                                       |
+| 2026-09-24 | B5 Surfaces                                                      | One class + radius per role                                                                                                                                                                                                                                                                                                                                                                         | Today's per-site mix                                                                                                                                                                                   | Nested corners and no per-site alpha drift                                                                                                                                                                                   |
+| 2026-09-24 | B6 /watch                                                        | The app's surfaces, native video controls                                                                                                                                                                                                                                                                                                                                                           | Flat and minimal                                                                                                                                                                                       | The page strangers see should look like the product; native controls work on any device                                                                                                                                      |
+| 2026-09-24 | B7 Nav rail                                                      | Soft tint + edge bar, optional labels (a user setting), slim                                                                                                                                                                                                                                                                                                                                        | Solid accent (recommended); a Material rail                                                                                                                                                            | The owner's combination: calmer than a solid fill, labels for who wants them, no width cost                                                                                                                                  |
+| 2026-09-24 | B8 Loading                                                       | Skeleton by shape, spinner in a control                                                                                                                                                                                                                                                                                                                                                             | A spinner everywhere                                                                                                                                                                                   | Nothing jumps when data lands; a long wait doesn't look stuck                                                                                                                                                                |
+| 2026-09-24 | B9 Fade                                                          | Toolbars / headers, panel tabs, dialog edges, chip rows                                                                                                                                                                                                                                                                                                                                             | Thumbnails; buttons                                                                                                                                                                                    | The north-star depth where content scrolls under chrome; not on content or small controls                                                                                                                                    |
+| 2026-09-24 | C1 Action classification                                         | The table (lab C1): state + primary at rest, everyday toggles on hover, "…" on touch, destructive into the menu                                                                                                                                                                                                                                                                                     | Visible buttons per site, as today                                                                                                                                                                     | One action list per object, nothing gesture-only, fewer buttons without losing a function                                                                                                                                    |
+| 2026-09-24 | C2 Side panels                                                   | A tap opens an overlay drawer; pin is a separate button ≥ 1024                                                                                                                                                                                                                                                                                                                                      | A tap pins and the content reflows                                                                                                                                                                     | Below 768 the filters were unreachable; on touch a tap pinned and pushed the grid                                                                                                                                            |
+| 2026-09-24 | C3 Players on touch                                              | Tap = show the controls; 44px seek hit area; 44 buttons; the YT description behind ⓘ                                                                                                                                                                                                                                                                                                                | Today (tap also pauses; 7.5px seek bar)                                                                                                                                                                | Measured live: you couldn't reach the seek bar without pausing, and the hover-only description never opened on a tap                                                                                                         |
+| 2026-09-24 | C4 Dialogs                                                       | Focus by purpose; a pinned footer                                                                                                                                                                                                                                                                                                                                                                   | Focus on Close; the footer scrolls                                                                                                                                                                     | A form starts in its first field, and Save stays on screen with the keyboard up                                                                                                                                              |
+| 2026-09-24 | C5 Plex player controls                                          | The owner's lean set: no Stop / Restart / ±10 s buttons, Back by position, Next only with a next item, Resume + From the start on the card, touch double-tap ±10 s                                                                                                                                                                                                                                  | Every control in one row (it ran off-screen below 1024); Back by a press counter; ±10 s keyboard-only                                                                                                  | The row fits a portrait tablet; the decision to restart is made on the card; a tablet keeps the 10 s skip                                                                                                                    |
+| 2026-09-24 | Glass tuner                                                      | Retired; the schemes are the only colour choice                                                                                                                                                                                                                                                                                                                                                     | Keep it with ranges clamped to the rules                                                                                                                                                               | Free tuning is the drift the constitution exists to stop (owner)                                                                                                                                                             |
+| 2026-09-24 | Matrix toned down                                                | Moss #86a05a at Midnight's lightness, near-neutral greys; every white-on-accent part → `--accent-fg`                                                                                                                                                                                                                                                                                                | The B2 lime #a3e635                                                                                                                                                                                    | The owner found the lime neon and tiring; it was the loudest accent (L 0.85, C 0.21), and fixed white parts sat on it at 1.5:1                                                                                               |
+| 2026-09-24 | Field primitives                                                 | `Input` / `Textarea` / `InnerInput` + `fieldClass`, `SelectTrigger`, the native controls; the lint rule "no raw `<input>`"                                                                                                                                                                                                                                                                          | `inputCls` and ~40 hand-styled boxes                                                                                                                                                                   | Six edges, four radii and two focus looks for one control; the ≥ 3:1 edge held nowhere                                                                                                                                       |
+| 2026-09-25 | Surface roles                                                    | `SURFACE` roles in `ui/surfaces.ts`; the lint rule "no bare glass class"; menus p-1 with r8 rows                                                                                                                                                                                                                                                                                                    | Three tiers paired ad hoc with five radii and three menu paddings                                                                                                                                      | ~140 sites drifted; nested corners only hold if the radius comes with the role                                                                                                                                               |
+| 2026-09-25 | Static labels                                                    | Flat tonal `Badge`, no edge; a filtering tag is an edged chip                                                                                                                                                                                                                                                                                                                                       | A glass pill with an edge, like the chips                                                                                                                                                              | Edged = pressable at a glance; a static tag that looks like a chip gets clicked and does nothing                                                                                                                             |
+| 2026-09-25 | Header search                                                    | A 40 glass pill with the field edge (`lg`); what sits inside it is round                                                                                                                                                                                                                                                                                                                            | 44, r16, a glass box with a faint edge                                                                                                                                                                 | The one rounded box among pills, and its edge under 3:1; the hero search is the YouTube/Gmail pill                                                                                                                           |
+| 2026-09-25 | Switch row (F12)                                                 | The whole settings row toggles (`SwitchRow`; a hand-laid row points a label at the switch)                                                                                                                                                                                                                                                                                                          | Only the 36×24 switch toggles                                                                                                                                                                          | The iOS / Material settings row; the text was a dead click beside the control it names                                                                                                                                       |
+| 2026-09-25 | Edges and hovers (F14)                                           | The ≥ 3:1 edge on the field family (fields, the form trigger); labelled pills keep the faint edge and the accent-edge hover                                                                                                                                                                                                                                                                         | The ≥ 3:1 edge and a state-layer hover on every control                                                                                                                                                | 1.4.11 asks an edge only where nothing else identifies the control; a heavy edge on every chip and tab weighs the whole UI down                                                                                              |
+| 2026-09-25 | Rating and live (F16)                                            | Own tokens: `--rating` (theme-scoped gold), `--live`/`--live-fg`, `--rating-media`, `--media-chrome`; palette classes lint-refused                                                                                                                                                                                                                                                                  | Map them to `--warn` / `--danger`                                                                                                                                                                      | A gold star and a red LIVE are what the eye expects; as warn/danger they would read as a status. The old amber score was 2:1 on light                                                                                        |
+| 2026-09-25 | Fjord trial (B2 exception)                                       | A fifth scheme, temporary: Midnight's neutrals, Playnite's steel accent (#337599 lifted to #5aa1cb) and steel rules; exit = fold into Midnight or remove                                                                                                                                                                                                                                            | Retune Midnight straight away; borrow only the qualities                                                                                                                                               | The owner wants to live with the calmer palette app-wide before it replaces the default; it breaks "own hue family" on purpose, and only until that call                                                                     |
+| 2026-09-25 | Whole-card row (owner)                                           | A card row's B3 layer is the card's `::before` under its content; the open button's hit layer spans the card, the actions sit above it                                                                                                                                                                                                                                                              | The name button's own hover, ending at the first badge or button                                                                                                                                       | A row that half-answers the pointer reads as broken; a badge click did nothing                                                                                                                                               |
+| 2026-09-25 | Badge tones (F29)                                                | `Badge tone` neutral / accent / warn at 6%; light `--warn` #b45309 → #a14a07; edged label spans lint-refused                                                                                                                                                                                                                                                                                        | Keep edged status pills (a private Badge in Users, Settings "Granted", the suggestions count)                                                                                                          | Edged = pressable at a glance; amber-700 was 4.58:1 as text and fell under 4.5 on its own tint                                                                                                                               |
+| 2026-09-26 | Page band built (B4)                                             | Controls only in the band (intros scroll); the fold shows the same row in place; one `h1` per page (`PageHeading` steps the hidden one aside); `SectionLabel` headings; Skip to content                                                                                                                                                                                                             | A popover of the folded filters; the page title kept visible                                                                                                                                           | A folded row is still the same controls, nothing duplicated; the rail and the tab title already name the page                                                                                                                |
+| 2026-09-26 | Fade built (B9)                                                  | `fade-below` on sticky toolbars and table headers; the scroller mask where the band sits on the backdrop                                                                                                                                                                                                                                                                                            | A painted band over the backdrop                                                                                                                                                                       | The backdrop is the colour under the band, so fading the content into it is the same edge                                                                                                                                    |
+| 2026-09-26 | Viewport units                                                   | `dvh` everywhere (the Plex player stage with S3f)                                                                                                                                                                                                                                                                                                                                                   | `vh` / `h-screen`                                                                                                                                                                                      | `100vh` hides the last rows under a tablet browser's toolbar                                                                                                                                                                 |
+| 2026-09-26 | Video actions built (C1)                                         | One list per video (menu, right-click, long-press, "…"); the card keeps watched / save / add to playlist on its picture on hover; download, details, copy, hide, reset in the menu                                                                                                                                                                                                                  | The six-button row under the card and the hover ⓘ                                                                                                                                                      | The menu is the one door every device has; the card loses a line of height and the touch card its row of 28px buttons                                                                                                        |
+| 2026-09-26 | Plex actions built (C1)                                          | One list per Plex title (play/open, watched, add to playlist, media info, copy title, pin); the poster keeps watched / add / "…" on its picture on hover; seasons get open / watched / add / copy                                                                                                                                                                                                   | The hover ⓘ, the pin-only menu, an episode's add button at rest, a collection's "Remove" X on the card                                                                                                 | The same door as a video's; the collection grid goes to two columns on a phone so the touch "…" leaves the title its line                                                                                                    |
+| 2026-09-26 | Playlist actions built (C1)                                      | A playlist row's "…" (play, pin, copy title / link, move, order, remove), Delete + an undo toast; one list per playlist (rename, pin, YouTube open / push / revert, delete) from its rail row and its header's "…"                                                                                                                                                                                  | The row's X column and its confirm; the header's pencil, YouTube link, push, revert and trash buttons                                                                                                  | Remove is reversible, so it needs no confirm; the header keeps Play all; a narrow table drops "#" and Channel so the title keeps a width                                                                                     |
+| 2026-09-26 | Channel + Plex list actions (C1)                                 | A channel row's "…" (open, pin, YouTube, copy, full history, hide + undo, unsubscribe); a Plex playlist's title / show / season "…", Delete + undo; its header's "…" (rename, delete); an action toast lasts ≥ 8 s                                                                                                                                                                                  | The channel row's full-history, hide and unsubscribe buttons; the Plex list's red X on every row, show and season; the header's pencil and trash                                                       | Hiding and removing are reversible, so they need no confirm and the undo needs time; unsubscribe and deleting a playlist keep theirs                                                                                         |
+| 2026-09-26 | Download / notification / Scheduler actions (C1)                 | A download row's "…" (play, share, save, edit, details, re-download, manage sharing, copies, cancel / delete / remove); a library row's Share stays in sight, ahead of save; a notification row's "…" and hover dismiss; the inbox band's and the Scheduler strip's "…"                                                                                                                             | The download row's five rare buttons and its cancel / delete / remove; the source link's copy button; an activity notice's Find / Undo links; the band's Clear everything; the strip's Purge discovery | The destructive rows keep their confirm, and Clear everything gains one; a row link keeps the browser's own menu; Find in feed drops the tag / search / age filters that could hide its video                                |
+| 2026-09-26 | Channel menu: Tags + Priority (C1)                               | Tags A–Z as in-place checks; Priority as fixed steps 10 · 5 · 3 · 2 · 1 · 0, the current one ticked; a pick re-sorts at once and the page + focus follow the row; one drawn `MenuCheck` for every checkable row that cannot be an `<input>`                                                                                                                                                         | Relative steps (+1 / +5); straight to the top; the stepper only; seven hand-drawn check marks (three box sizes, a tinted box, a × for "on", a trailing tick)                                           | Bubbling a channel up is one pick; fixed levels keep the scale the reader already uses; the list moving where the reader can see it is the feedback                                                                          |
+| 2026-09-26 | Reorder without a drag (WCAG 2.5.7)                              | Row menus: Top / Up / Down / Bottom (YouTube + Plex playlists); saved views: four buttons with the place beside the selected view (owner: A); side panels in edit mode: an Up / Down pair per group (owner: A), the name wrapping there                                                                                                                                                             | A "…" on every saved-view row; a "…" on every panel group; drag only                                                                                                                                   | A visible, one-click path where the list is edited; the edge moves shown off so the buttons never shift                                                                                                                      |
+| 2026-09-26 | Titles in click surfaces                                         | The surface stays a button, flagged `selectable`: its text selects, and the click that ends a selection does nothing; every plain `Pressable` pinned with its reason                                                                                                                                                                                                                                | Rebuilding each card and row so the title sits outside the button; exceptions for master-detail lists                                                                                                  | Chrome selects inside a button once it is `user-select: text` (measured), so one flag on the primitive keeps the keyboard, focus and list walking every surface already has                                                  |
+| 2026-09-26 | Right-click on a selection                                       | The browser's own menu opens on selected words; beside them the object's menu                                                                                                                                                                                                                                                                                                                       | A "Copy selection" row in the app menu                                                                                                                                                                 | The reader selected the words to do something with them; the native menu copies, searches and translates, and changes nothing else                                                                                           |
+| 2026-09-26 | Keyboard ring on a flush row                                     | Inside the row (a table row by its tag, a log line, a show header in its clipping card, with the card's corners)                                                                                                                                                                                                                                                                                    | The ring outside, as on a card                                                                                                                                                                         | Outside it ran under the table head and past the table, and a clipping card cut it away entirely (invisible focus)                                                                                                           |
+| 2026-09-26 | Fade at rest                                                     | The sticky header's fade appears with the first 1rem of scroll (a scroll-driven animation; no fade where unsupported)                                                                                                                                                                                                                                                                               | A fade that is always drawn                                                                                                                                                                            | At rest it dimmed the first row and hid its ring's top edge; nothing is under the header yet                                                                                                                                 |
+| 2026-09-26 | Narrow playlist table                                            | "#" and Channel hide by the table's own width (under 42rem), not the window's                                                                                                                                                                                                                                                                                                                       | Hiding below the `sm` window width                                                                                                                                                                     | Beside the playlist rail a desktop window left the table 432 px and the title 0 px                                                                                                                                           |
+| 2026-09-26 | Background menu built                                            | Five list pages (feed, Plex grid, channels, playlist, notifications); the toolbar's sort / view / filters and the band's actions; no destructive row                                                                                                                                                                                                                                                | Every page with a toolbar; the "…" menus copied whole, delete included                                                                                                                                 | The tab-only pages have nothing a menu would add; a blank-area right-click must not be one click from delete                                                                                                                 |
+| 2026-09-26 | Media card anatomy (C)                                           | One frame; the meta line pinned to its bottom; the length a badge on the picture; the Plex card on the same primitive as the video card                                                                                                                                                                                                                                                             | A: the year as an overline over the title; B: the year inline after it; a fixed two-line title slot                                                                                                    | A one-line title left a hole the eye reads as a missing line; C puts nothing under a variable-height title                                                                                                                   |
+| 2026-09-26 | One Play                                                         | `MediaPlayGlyph` (the media button variant) and only where the click plays                                                                                                                                                                                                                                                                                                                          | The Plex card's hand-painted accent circle; a playable dot on every card                                                                                                                               | One Play for every card; a dot that only a colour and a tooltip explain says nothing                                                                                                                                         |
+| 2026-09-26 | Filtering values on the info page                                | A value that filters (year, certificate, studio, director) is an edged chip; a fact is flat text                                                                                                                                                                                                                                                                                                    | Everything flat, the clickable ones only hover-tinted                                                                                                                                                  | The S3d rule: edged = pressable, so the reader sees which values do something                                                                                                                                                |
+| 2026-09-26 | Shelf density                                                    | On any strip: one title line over one meta line                                                                                                                                                                                                                                                                                                                                                     | The grid's two lines and full meta on a strip                                                                                                                                                          | The tallest card set the strip's height and left holes in the cards with less to say                                                                                                                                         |
+| 2026-09-26 | Compact list row (B)                                             | The title leads; a faint "…" at the end; the toggles float over the date on hover                                                                                                                                                                                                                                                                                                                   | A leading 128px action column                                                                                                                                                                          | That column sat empty at rest, a hole at the start of every row                                                                                                                                                              |
+| 2026-09-26 | Media-info layout (B)                                            | A main column (collections first, crew, cast) beside a facts sidebar; an empty column is not drawn                                                                                                                                                                                                                                                                                                  | Every section full width, stacked                                                                                                                                                                      | The collection is the most used; the keywords' column left a void beside a short details box                                                                                                                                 |
+| 2026-09-26 | Mixed Home shelf (A)                                             | Plex titles as wide art beside videos                                                                                                                                                                                                                                                                                                                                                               | Posters, with the videos not stretched                                                                                                                                                                 | Stretching a video card to a poster's height left an ~80px gap                                                                                                                                                               |
+| 2026-09-27 | Home hero                                                        | A card (hover row + Play on the picture, the whole menu, a touch "…"; owner: A); three quarters wide and centred on a wide window; one fact line; the summary at the measure                                                                                                                                                                                                                        | The hero's pin row alone; full width; an 18rem picture column                                                                                                                                          | The one answer stands in focus, and it offers what the same card offers anywhere                                                                                                                                             |
+| 2026-09-27 | Home shelf tiles                                                 | A channel / playlist tile: Play, ↗ open, "…" with Open; a show acts on its next episode, ⓘ opens it; the shelf slot 232px                                                                                                                                                                                                                                                                          | The tile's pin row alone; 200px                                                                                                                                                                        | A tile without its object's actions read as broken; at 200 the Play touched the hover row                                                                                                                                    |
+| 2026-09-27 | Synopsis preview (C)                                             | A ~0.9 s mouse rest opens a passive panel beside the card                                                                                                                                                                                                                                                                                                                                           | The synopsis as the picture's `title` tooltip; an ⓘ to hover; none                                                                                                                                     | One long tooltip line fired anywhere on the art and clashed with the cut title's own tooltip                                                                                                                                 |
+| 2026-09-27 | Reading measure                                                  | Prose capped at ~65 characters a line (`measure`)                                                                                                                                                                                                                                                                                                                                                   | The container's full width                                                                                                                                                                             | At 110–130 characters a line the eye loses the next line's start                                                                                                                                                             |
+| 2026-09-24 | Chip family                                                      | One `Chip` (filter / token / tag / suggest / ghost) + `DismissibleChip`; nothing under 24; the lint rule "no raw `<button>` outside ui/"                                                                                                                                                                                                                                                            | Five chip geometries in five files                                                                                                                                                                     | The applied-filter row, the tag cells, the year picker and the saved-view editor each drew their own chip; a one-letter tag was 21px wide                                                                                    |
+| 2026-09-24 | Button families                                                  | `Button` / `IconButton` / `Pressable` / chips / `DragHandle`; `lg` 40 for a hero CTA; pills and a 48 Play on media (from C5)                                                                                                                                                                                                                                                                        | Every button hand-painted                                                                                                                                                                              | 268 hand-rolled buttons in 79 files drifted into as many looks; the ladder only holds if every button stands on it                                                                                                           |
+| 2026-09-27 | C4 as built                                                      | `initialFocus` required on every `Modal`; the commit row in `ModalFooter`, portalled under the body from any depth; the fades driven by the body's scroll timeline; `interactive-widget=resizes-content`                                                                                                                                                                                            | An optional prop defaulting to the ✕; a `footer` prop (the issue composer's buttons live three components down); always-on fades                                                                       | A default is how 21 dialogs came to open on the ✕; lifting the composer's state to reach a prop is the larger change; a resting fade dimmed the first line                                                                   |
+| 2026-09-27 | C3 + C5 as built                                                 | A tap toggles the bar through `pointerType` from `pointerdown`; a double-tap takes back its first tap's toggle; the card's pair is the video card's `MediaResumeButtons` (Continue / Restart), a sibling over the picture; the YT description is an ⓘ click popover                                                                                                                                 | A delayed single tap (wait out the double-tap window); new "Resume / From the start" words for Plex; the pair inside the picture's button                                                              | A delayed tap feels dead; one media card says one pair of words; a button inside a button is invalid and the hover row already sits beside the picture                                                                       |
+| 2026-09-27 | C2 as built                                                      | The side panel's drawer is `ui/Modal` `drawer-start`; drawer = a coarse pointer or below 768; the pin offered in its header ≥ 1024                                                                                                                                                                                                                                                                  | A drawer of its own inside `SidePanel`                                                                                                                                                                 | Esc, Back, the scrim, the trap and the scroll lock are the dialog's; a second implementation is how two shells drift                                                                                                         |
+| 2026-09-30 | Composition and the reader (E30 S6)                              | A chapter and a Conformance step: the space is used, one focal point, worst real data, where am I, a click answers at once, zoom and text size first-class; the person page as two columns (facts and bio left, "Known for" right)                                                                                                                                                                  | Rules for pieces only; the bio in a full-width panel; a narrower panel                                                                                                                                 | The person page passed every piece rule with half its panel empty; the owner reads zoomed in, so zoom is a requirement, not a nicety                                                                                         |
+| 2026-09-30 | Hungarian words (E30 S5)                                         | The D3 list: Feed, Shorts, Admin, Token, Port stay; stream, Prio, Job, Audit, Demo, Auto, Info, Frontend/Backend, Backfill, transcode get the Hungarian word; one name per thing (kérelem, behúzás, one "Test connection")                                                                                                                                                                          | Keep every loanword; translate Feed/Shorts too                                                                                                                                                         | The owner chose the list (D3); the final sweep found the same feature under two names in three places                                                                                                                        |
+| 2026-09-29 | Numbers and order in the UI language (E30 S3)                    | Every number through `lib/format.ts` in the UI language (decimal mark, grouping, compact, units); A→Z by the shown name in the UI language's alphabet, client and server alike; the language comes off `useTranslation`, never the singleton                                                                                                                                                        | `toFixed`, hand-built "1.2K", `localeCompare` in the browser's locale, byte-order server sorts                                                                                                         | A Hungarian reader saw "8.3", "1.2K", "Életrajzi" after "Z"; the singleton read also left values in the old language after a switch (React Compiler)                                                                         |
+| 2026-09-27 | Narrow rows by container                                         | The download row, the playlist table and the Channels tag row stack by a container query; a fact line never wraps                                                                                                                                                                                                                                                                                   | Breakpoints on the window                                                                                                                                                                              | The iPad zoomed in, split screen and a column beside a rail are narrow while the window is not; the zoomed download row broke "18.9 / MB" apart                                                                              |
+| 2026-09-27 | Phones deferred                                                  | A phone-only layout (the hamburger nav, a folded feed band) waits for its own epic; E28 stays desktop + tablet                                                                                                                                                                                                                                                                                      | Fix the phone views inside E28                                                                                                                                                                         | Principle 2; the first phone attempts made the feed worse, and the epic's review grows with every sprint                                                                                                                     |
+| 2026-09-27 | Conformance check (S3g)                                          | A four-step check before a UI change is done: primitive at a named rung, the chapter re-read, the rendered page measured by kind and look, every state seen                                                                                                                                                                                                                                         | A reviewer's eye per sprint                                                                                                                                                                            | The S1 probe found 69 button looks; after S3 every control kind is drawn by its primitive, and the check keeps a new look from arriving unnoticed                                                                            |
+| 2026-09-27 | Segmented rung                                                   | `SegmentedToggle` defaults to the toolbar rung (28, `text-xs`); 24 only for a panel's captioned match toggle                                                                                                                                                                                                                                                                                        | The small default                                                                                                                                                                                      | Two toolbars had inherited 10px type from the default beside 28px buttons                                                                                                                                                    |
+| 2026-09-27 | Copy rule (S3g)                                                  | One name per feature (the rail may shorten it); four verbs for four meanings; sentence case with the app's places capitalised; "…" when a command asks first; one-sentence messages without a stop; curly quotes; dates relative in lists with the exact minute on hover, three absolute forms; units from Intl, short                                                                              | Word-for-word names everywhere; the verbs as they were; all lower case; no "…"; always a stop; always absolute dates; long or compact units                                                            | The copy survey found 7 EN and 6 HU double names, 22 Delete against 27 Remove, five date shapes and three spellings of a minute; the owner picked every recommended option                                                   |
+| 2026-09-27 | One glyph, one meaning (S4)                                      | Play only for playback or resuming a paused transfer; Retry = `RefreshCw`; reset / revert = `RotateCcw`                                                                                                                                                                                                                                                                                             | Retry drawn with Play                                                                                                                                                                                  | The first UI-review run (Downloads) found a failed row whose Retry showed ▷ in the row and its menu                                                                                                                          |
+| 2026-09-27 | Fjord kept                                                       | Fjord stays a fifth scheme beside Midnight; the trial wording goes                                                                                                                                                                                                                                                                                                                                  | Fold it into Midnight; remove it                                                                                                                                                                       | The owner lived with it and likes it; the vivid Midnight stays for those who want it. B2's own-hue rule still binds any new scheme                                                                                           |
+| 2026-09-27 | Tablet columns                                                   | A table hides `tabletHidden` columns below 64rem of its own width; Channels drops Prio, About, Length                                                                                                                                                                                                                                                                                               | Hide About only; give the name a bigger share                                                                                                                                                          | At 1024 the channel name had 60 px; the owner chose to drop all three there                                                                                                                                                  |
+| 2026-09-27 | Glyph pager                                                      | First / previous / next / last as glyph buttons round the page box, names as tooltips                                                                                                                                                                                                                                                                                                               | Words beside the arrows (hidden only on a phone)                                                                                                                                                       | The owner's call: the words widened the row; four arrows are the shared convention                                                                                                                                           |
+| 2026-09-27 | Match switch on the panel                                        | `ui/MatchToggle` above the picker from two picks, everywhere; one wording (Any / All)                                                                                                                                                                                                                                                                                                               | The picker's popover footer (Feed, Plex collection)                                                                                                                                                    | A closed picker hid an active "all"; six pickers had drawn it two ways                                                                                                                                                       |
+| 2026-09-27 | Missing picture, bare link                                       | A glyph of the kind for no picture; a download with no name is titled by its short link, once                                                                                                                                                                                                                                                                                                       | An empty box; the URL as title, channel and link                                                                                                                                                       | The owner's picks 4A and 3A: an empty box read as loading, the URL showed three times                                                                                                                                        |
+| 2026-09-27 | Copy on a selection                                              | Right-click on selected words keeps the browser's menu; no app Copy row                                                                                                                                                                                                                                                                                                                             | An app menu with Copy first                                                                                                                                                                            | A real browser's menu has copy, search and translate; only the desktop pane's is thin                                                                                                                                        |
+| 2026-10-01 | Zoom target 125–133%                                             | Screens are held at 125% and 133% browser zoom (1536 × 729, 1444 × 685 on a 1080p window) and the largest text size                                                                                                                                                                                                                                                                                 | 200% browser zoom                                                                                                                                                                                      | The owner: 200% was a guess; 125–133% is what they read Siftlode and most sites at, so 200% would be an upper bound nobody uses                                                                                              |
+| 2026-10-01 | E31 Nav rail at short heights                                    | One "Admin" rail item opening a panel of the admin pages                                                                                                                                                                                                                                                                                                                                            | A denser rail when short; a visible "+4" hint                                                                                                                                                          | The rail fits at 133–150% without a hidden scroll; the admin pages are rare and admin-only                                                                                                                                   |
+| 2026-10-01 | E31 Configuration sections                                       | A vertical, grouped section list, as Settings has                                                                                                                                                                                                                                                                                                                                                   | Group tabs + sub-tabs; one long page with a contents list                                                                                                                                              | Sixteen tabs wrapped to three rows at 133%; one pattern for both settings pages                                                                                                                                              |
+| 2026-10-01 | E31 Statistics overview                                          | Number tiles, and the per-operation counts as horizontal bars                                                                                                                                                                                                                                                                                                                                       | Three narrow cards; a 30-day chart                                                                                                                                                                     | The label sits by its value; what spends the quota is seen at a glance                                                                                                                                                       |
+| 2026-10-01 | E31 Channel page header                                          | The full banner, folding to one row once the grid scrolls                                                                                                                                                                                                                                                                                                                                           | Always compact; no banner                                                                                                                                                                              | The header is fixed and took 40% of a 685px window; the channel keeps its face at first sight                                                                                                                                |
+| 2026-10-01 | E31 Channel page watch state                                     | A fresh channel page shows the unwatched videos; a picked state is remembered                                                                                                                                                                                                                                                                                                                       | Show all, forgotten on reload                                                                                                                                                                          | The owner: open a channel to see what is new; a choice made there should stick                                                                                                                                               |
+| 2026-10-01 | E31 Audit log runs                                               | A job's successful runs fold into one row that opens, whatever ran between; only that job's failure (never folded, danger colour) breaks it                                                                                                                                                                                                                                                         | A filter defaulting to admin actions; both                                                                                                                                                             | Nothing hidden, the noise collapsed, the failure seen                                                                                                                                                                        |
+| 2026-10-01 | E31 Users row                                                    | Role and state as badges, the actions in the row's one menu                                                                                                                                                                                                                                                                                                                                         | An inline role toggle; icon-only buttons                                                                                                                                                               | Action placement: the row shows state, rare and destructive actions live in the menu                                                                                                                                         |
+| 2026-10-01 | E31 YouTube player                                               | Video beside an info panel at 1280px and wider (the video as large as the height allows); stacked below                                                                                                                                                                                                                                                                                             | Today's stack with a one-line bar; full-window like Plex                                                                                                                                               | The owner's eyesight: about 1460px of video on 1080p instead of 1008, the actions still visible                                                                                                                              |
+| 2026-10-01 | E31 Plex info and show pages                                     | A second column for the facts, keywords and crew, as the person page; a collection's hero sized to its content                                                                                                                                                                                                                                                                                      | Full-width text; a larger poster and fanart                                                                                                                                                            | The right ~40% was empty; one composition for every media page                                                                                                                                                               |
+| 2026-10-01 | E31 Nav rail rows are links                                      | Each page row is a real link: a middle-click or Ctrl-click opens the page in a new tab                                                                                                                                                                                                                                                                                                              | A button                                                                                                                                                                                               | The owner: open a page in a tab of its own, as on any site                                                                                                                                                                   |
+| 2026-10-02 | E31 Plex detail second column (refined)                          | The facts over the key crew beside the text; the keywords, chips that filter like the genres, under the text; the show page gets all three too                                                                                                                                                                                                                                                      | All three in the column, as the mockup drew it                                                                                                                                                         | At 20 keywords and 12 crew the column ran to twice the text's height (849 vs ~400 px at 133%): a hole under the text instead of beside it                                                                                    |
+| 2026-10-02 | E31 Plex detail poster and crew                                  | The movie and show poster keeps its 2:3 and grows a rung in a wide hero (w-56 at a 64rem panel); the crew shows its first 6 names and "Show N more" (a list of 8 or fewer shows whole)                                                                                                                                                                                                              | Poster stretched to the row; a "More" on the keywords                                                                                                                                                  | The row is as tall as the crew column, so the poster drew ~175×590 and cropped; the crew, not the keywords, set the hero's height                                                                                            |
+| 2026-10-04 | E32 `field` focus skips a mode switch                            | A form opens on its first field; a control above it that is not a field (the composer's Edit / Preview) is passed over by marking the field `data-initial-focus`                                                                                                                                                                                                                                    | The first text field everywhere                                                                                                                                                                        | That moved the focus in the download dialog off its profile choice and in the upload dialog off its drop zone; the mark changes only the form that needs it                                                                  |
+| 2026-10-04 | E35 Lint for z-levels and edged labels                           | Both rules stay; the two eslint selectors (`Z_RAW`, `EDGED_LABEL`) that refused them go                                                                                                                                                                                                                                                                                                             | Keep the selectors                                                                                                                                                                                     | 0 hits since the E28 sweep that fixed the sites: a check that never fires costs a probe test and a snapshot each, and the UI review holds both rules                                                                         |
+| 2026-10-06 | `player` focus                                                   | A dialog that is a player opens focused on its panel (the YouTube player's rule, now `Modal`'s too); on the media element itself, Space and the arrows stay the element's own                                                                                                                                                                                                                       | `close`, or the media element                                                                                                                                                                          | On the ✕ Space closed the player; on the element the browser's own controls acted on the same key as the player's (one Space played and paused, measured in Chrome)                                                          |
+| 2026-10-08 | Captions on touch                                                | A `Tooltip` opens for a mouse and a key's focus only, never for a finger                                                                                                                                                                                                                                                                                                                            | A caption on tap; a long-press caption                                                                                                                                                                 | On an iPad the tap that showed the caption was taken as a hover and lost its click (every rail button took two taps), and no finger sends the mouseleave that hides it; the rail's labels setting names the buttons on touch |
+| 2026-10-08 | Header search on touch                                           | No key cap on a touch screen; the pill grows to 52 px so a ring shows round the 44 px Go; Go drops to its icon by the column's width                                                                                                                                                                                                                                                                | Keep the key cap; a 44 px Go overhanging a 40 px pill                                                                                                                                                  | On a tablet the 44 px key cap and Go sat on the pill's edge and cut the placeholder; an overhanging Go breaks the nested radii                                                                                               |
+| 2026-10-08 | Plex subtitles and the control bar                               | The player draws the cues itself; while the bar shows they rise above it (200 ms), then settle back                                                                                                                                                                                                                                                                                                 | The browser's own cues, moved by `line`                                                                                                                                                                | On an iPad the bar covered the text; a native cue cannot be animated or measured, and our layer behaves the same on every engine                                                                                             |
+| 2026-10-08 | Hover on a button over a picture                                 | The `media` variant's hover is a 2px accent ring over a darker body (Plex + YT cards, rail arrows; option B)                                                                                                                                                                                                                                                                                        | An accent fill (reads as "selected"); a white wash (weak on a bright poster)                                                                                                                           | The 60 → 75% black step was invisible, and over a card a rail arrow could not be told from the card's own Play under it                                                                                                      |
+| 2026-10-08 | Plex "Add to collection"                                         | A movie or show card's menu row opens a panel beside the card: its library's manual collections tick in place, a name + Enter creates one with the title in it (admin; option A)                                                                                                                                                                                                                    | An Add submenu with a "New…" dialog; the per-title editor modal from the menu                                                                                                                          | A collection took a trip to the Collections page, a name, a title search, then a second search per title; the panel is the video card's "Add to playlist"                                                                    |
+| 2026-10-08 | YouTube modal chrome                                             | No prev/next strips beside the card; Close an icon (the panel's top right; stacked, the title row's end); the description clamped to three lines + More; the panel shuts to a 2.75rem strip of close, expand, prev/next (option D1)                                                                                                                                                                 | Keep the strips; a "Close" text button; the full description in a scroller; a panel that hides outright                                                                                                | The strips cost the video 7rem of width for a second copy of the panel's buttons; a long description pushed the channel and the actions out of sight; a hidden panel left no way to step the queue without the keyboard      |
+| 2026-10-08 | The wheel over the YouTube modal                                 | Over the video: volume. Over a panel with something to scroll: scroll only, never volume, not even at its end. Over a panel with nothing to scroll: volume (owner)                                                                                                                                                                                                                                  | Volume everywhere; a scroll that hands over to the volume at its end                                                                                                                                   | Reading a long description turned the volume down once it hit the end                                                                                                                                                        |
+| 2026-10-09 | A Plex show card plays                                           | Its picture plays the show's next episode everywhere (an episode with a resume point → Continue + Restart, else the first unwatched, else S1·E1), resolved on the click; the preview names it once up; title and ⓘ open the show (option A + hover ask)                                                                                                                                             | The picture opens the show page (as before); every card carrying `next`                                                                                                                                | A show card on Discover had no Play while Home's had one; carrying `next` costs a grid page up to 180 queries for the few cards anyone plays                                                                                 |
+| 2026-10-10 | Clip mode in the players (E38)                                   | Scissors in the control row + `C`, `[` `]`; the panel in the player with the watched video as preview; overview + zoomed strip on `ui/RangeTrack` (ends are sliders); a toast + the Ready notification after Cut                                                                                                                                                                                    | A ⋯ menu entry; permanent In / Out buttons; a big dialog with its own preview (a second Plex transcode / YouTube iframe)                                                                               | Owner's picks A, P1, a; a film is hours and a clip seconds, so only a zoomed strip gives a hand the precision. The Downloads editor's cuts moved onto the same track (keyboard-steppable now)                                |
+| 2026-10-10 | Crop in clip mode (E38)                                          | A Crop toggle in the clip panel: a frame over the playing picture (`ui/CropFrame`, the editor's crop too), Free / 16:9 / 9:16 / 1:1, Whole picture; maximised YouTube keeps the panel in the bar's place; the wide side panel shuts while clipping                                                                                                                                                  | A frame always on the picture in clip mode (K2); a free shape only                                                                                                                                     | Owner's K1 + a: a crop is rare, so it never covers the picture unasked; a phone or square clip needs a held shape. The iframe hides its picture's size: drawn on the 16:9 box, the cut fits it to the real picture           |
+| 2026-10-10 | Marks on the player chrome                                       | `--media-mark` (amber) and `--media-danger` (light red), the same in both themes; `media-marks` points the focus ring (`--focus`) and the chosen mark (`--chosen`: a track's tick, a tab's underline; the label stays white) at the amber on the player and every chrome surface; `media-scope` (a form) also the errors at the red                                                                 | The theme's accent ring, chosen text, warn and danger                                                                                                                                                  | On the chrome (#171717) a light theme's accent ring (Slate 2.84:1), warn (2.99:1) and danger (2.77:1) all fall under 3:1; the accent as chosen text under 4.5:1                                                              |
+| 2026-10-11 | Files page (one library)                                         | List rows by default, the media grid a toggle remembered per folder; a sidebar of automatic source folders, own folders, Shared with me and the storage meter; the paste-a-link box in the toolbar                                                                                                                                                                                                  | A media grid by default                                                                                                                                                                                | The library holds videos AND plain files: rows read both, show more per screen and scan by size and date                                                                                                                     |
+| 2026-10-11 | Library list columns                                             | Every kind of value in its own column (name, source, phone-safe, retention, size, added, actions), one grid with a subgrid per row so they line up; an action that does not apply keeps its slot empty; a right-click menu on every row (the ⋯ opens the same menu)                                                                                                                                 | Badges flowing after the title; icons that shift when one is missing                                                                                                                                   | Owner: values of one kind must fall in one vertical line; a row's every action reachable by right click                                                                                                                      |
+| 2026-10-11 | Running downloads                                                | An app-wide tray, bottom right, shown only while something runs or failed (reason + retry), foldable to a pill                                                                                                                                                                                                                                                                                      | A rail icon with a count and a popover                                                                                                                                                                 | Downloading became an action you start anywhere; a running one must be visible without going to look                                                                                                                         |
+| 2026-10-11 | Download done                                                    | The notification says whether it plays on a phone and carries Link másolása + Megnyitás (the folder, the item focused); never an automatic jump                                                                                                                                                                                                                                                     | A plain "ready" notice; auto-navigation to the item                                                                                                                                                    | The daily path is paste → done → copy the link; a jump would pull the user out of what they were doing                                                                                                                       |
+| 2026-10-11 | Library row quick icons (owner A)                                | On a wide list only the ⋯ holds a place; Copy link, Share and Save come up over the date while the row is hovered or holds the keyboard; a card (phone) keeps them in its own line; Keeps narrower                                                                                                                                                                                                  | Three icons always in sight (the name kept ~150px at 1200); dropping Added below 64rem                                                                                                                 | Owner: the name is what a row is read by; every action stays in the ⋯ and the right-click menu                                                                                                                               |
+| 2026-10-12 | Files preview (owner ★)                                          | A file that is not media opens from its name in the dialog shell, wide: an image, a PDF in the browser's own viewer, text as numbered plain text (HTML and SVG too) with a wrap toggle, else a no-preview card with Save; ← / → page the list's such files in its order; an image under 8 MB is its own thumbnail                                                                                   | A side panel beside the list; a new browser tab; pdf.js; syntax highlighting; a click that saves a file without a preview                                                                              | Owner: one way to open anything, paged like the list; the browser's PDF viewer is free and isolated; a page is never rendered on our origin                                                                                  |
+| 2026-10-12 | A running download's step (owner ★)                              | The tray row names the step beside its bar ("Downloading audio · 12%", "Merging" with a pulse); a paused-only tray shows a pause mark, never the done check                                                                                                                                                                                                                                         | A bare bar and %                                                                                                                                                                                       | A download fetches video and audio as two streams: unnamed, the second fill reads as a restart; the tray is the only place a download is followed                                                                            |
+| 2026-10-14 | API tokens (owner A/A/A)                                         | Settings → API tokens: a row per token in three lines (name + prefix, its folders and rights, last use and expiry), revoked from its ⋯; a new token asks the kind first (Hub exchange or Custom: rights as chips per folder), expiry 1 year by default; the token shows once in the same dialog, with Copy and a curl line                                                                          | A table; one form with a preset link; the token in a banner above the list                                                                                                                             | A table truncates the rights at this width; the common token never shows a matrix to get wrong; closing the dialog is plainly when the token is gone                                                                         |
+| 2026-10-15 | Folder links (owner A/A/A)                                       | An own folder's menu has Copy link and Share with link… as a file row does (the dialog is the link half of the file's); the link opens a list of the folder's files as it is now, Play opening the watch player above it with the playing row lit, a document only downloading; the rail marks a folder with a live link beside its count                                                           | Share with link… alone; cards; a download-only list; no mark                                                                                                                                           | Mostly videos from a phone, read on a phone: a list gives a long name its line and the next one is a tap away; the folder link is the one place where moving a file in publishes it, so where it is must show                |
+| 2026-10-17 | Copy-only changes (owner ★)                                      | Step 4 of the Conformance check alone (not 1–3 or 5): every state the changed text renders in, seen in both languages                                                                                                                                                                                                                                                                               | The whole five-step check; no screenshot at all (DOM test + key parity)                                                                                                                                | Steps 1–3 and 5 judge controls, patterns and composition, which a text change does not touch; the one risk left is a longer Hungarian string wrapping or clipping, and only a screenshot shows that                          |
+| 2026-10-17 | Text on glass (owner ★)                                          | Light `--muted` 15% toward `--fg` in every scheme (≥ 6:1 on the bare page); the item count, the badges and the current Files row on opaque tints mixed into the surface                                                                                                                                                                                                                             | Only the two failing components; the item count's number in `--fg`                                                                                                                                     | Pixel-measured over every scheme × mode × backdrop, the count fell to 3.8:1 (dark too: thumbnails scroll under the toolbar's glass) and Channels' tabs to 4.1:1; an `--fg` count outshouts the filters beside it             |
+| 2026-10-18 | Scheduler run history (owner D4, E1, E2 ★)                       | A row's last three runs as dots, newest first (interrupted: a hollow warn ring, set apart from skipped and failed), and a history button that opens the job's runs on the Activity page; a user's ad-hoc runs in their own block under the jobs, with no interval and no run button                                                                                                                 | An inline expandable history per row; a dark-grey interrupted dot; ad-hoc runs only on the Activity page                                                                                               | Three dots answer "did it run, did it work" at a glance; the whole history needs filters, which the Activity page has                                                                                                        |
+| 2026-10-18 | Activity page (owner D1, D2, G1–G3 ★)                            | One page, "Napló" / "Activity": four tabs (Runs, Admin actions, Server log, Quota) under one filter bar (text, a period of 1 h · 24 h · 7 d · 30 d · 90 d defaulting to 7 days, an account), the view in the URL; runs and admin actions as dense rows that open in place as a log line does, filtered and paged on the server; a run's or a request's log lines one pivot away, as a history entry | One merged timeline; a page per source; a default period per tab; card rows; the audit log's client-side table                                                                                         | Each source keeps its own table and retention, read in one place; one bar keeps what you narrowed across tabs; about 1.8k runs a day need a log's density and a server-side filter                                           |
+| 2026-10-24 | Related videos (owner U1–U3 ★, D1 A, D3)                         | On demand: a tab beside the description (wide), a drawer (stacked); the narrow thumbnailed row, its menu alone, a followed check; plays in place and the list stays the opened video's; an on-topic / Hungarian-trending switch kept on the account                                                                                                                                                 | Always shown; the end-of-video grid alone; a dialog; a big card or a text row; a list that follows the playing video                                                                                   | The modal is full on a small screen; a picture is what a choice among strangers rests on; a list that stays put is tried one by one, and spends no more of the day's cap                                                     |
+| 2026-10-25 | Related: one played; off (owner D1 a, D2 a)                      | Played from the list, it is the player's item: its title, controls and progress, marked watched at its end, the queue left where it was; a daily limit of 0 takes the tab and the button away                                                                                                                                                                                                       | A linked video's in-place play (no controls, nothing kept); a tab that only shows a refusal                                                                                                            | What is watched should count as watched, wherever it was started from; a control that can only be refused is not offered                                                                                                     |
+| 2026-10-25 | Player panel glyphs (owner 1A, 2A, 3)                            | In the side panel the queue row is glyph-only on one line, and Mark watched is a glyph toggle among the actions (✓ / ✓✓); the docked bar keeps its labels; the related switch at the default size, "Trending"                                                                                                                                                                                       | Labelled buttons wrapping onto three lines; glyphs on the docked bar too; Mark watched on its own line                                                                                                 | The panel is narrow and the list controls are the same few every time; each glyph keeps its full name and shortcut in its tooltip; the docked bar has the width for words                                                    |
+| 2026-10-25 | Auto-advance glyphs (owner E A, H a)                             | Auto-advance wears list glyphs (`ListEnd` next and off, `ListStart` previous, `Shuffle` random), in the panel and the docked bar; the auto-advance and loop cycles are `lit`, not `pressed`                                                                                                                                                                                                         | The skip arrows for the mode; an X'd list for off; `aria-pressed` on a cycle                                                                                                                           | Beside Previous / Next the skip arrows read as a second Next; a cycle of three or four modes is no two-state switch, and its name already says which                                                                         |
+| 2026-10-25 | Restart and Reset glyphs (owner L A)                             | A menu's Play from the beginning wears `RotateCcw`, as the card's own Restart does; Reset (clear progress and status) wears `Eraser`; Redownload wears `RefreshCw`, the retry arrow                                                                                                                                                                                                                 | The skip arrow ⏮ on the menu's Restart; `RotateCcw` on both Restart and Reset; `TimerReset` for Restart                                                                                               | ⏮ is Previous beside the player; one action wore two glyphs, and two actions in one menu would have worn one                                                                                                                |
+| 2026-10-28 | Notification order (owner A-D1 a, A-D2 a, ★ a)                   | What asks for the reader first, from either source ("Needs you · n"), then one stream newest first; read rows older than a week fold under "Earlier (n)", closed, its label in the section-heading style with a chevron                                                                                                                                                                             | One stream with no band; this browser's activity above the server's (the two fixed sections); a server-side retention that deletes old rows                                                            | An admin's access requests sat under up to a hundred server rows; week-old read notices crowded what is new; folding keeps the rows (nothing is deleted) and an unread row never folds, whatever its age                     |
+| 2026-11-01 | Docked bar glyphs (owner D8 a)                                   | The maximised view's docked bar is glyph-only too (tooltips carry the names and keys): transport, auto-advance, loop, Mark watched (✓ / ✓✓); its controls scroll on a narrow window while Fullscreen and Exit stay pinned at its right end                                                                                                                                                          | Labels from `xl` up                                                                                                                                                                                    | On a tablet the labelled bar ran past the right edge and took Exit with it; the side panel had already lost its labels                                                                                                       |
+| 2026-11-01 | Toolbar group glyphs (owner D9 a, D10 a, D11 a)                  | The feed's, channel page's and Plex Browse's filter pills name their group by a glyph (`Eye` watch state, `Shapes` content types, `ArrowDownUp` sort), the word in the tooltip and the accessible name; Sort + View end the toolbar's row, the chip row shows only with a chip; a channel page has no count pill                                                                                    | The value alone; Sort + View on a row of their own                                                                                                                                                     | "Watch state:" and "Sort:" cost a tablet row its room; the value says enough once the glyph names the group; the channel header already counts the videos                                                                    |
+| 2026-11-01 | Channel header on a tablet (owner E2)                            | Below `xl` the action row drops its two words: "Prio" (the stepper's tooltip names it) and "Subscribed" (a ✓ glyph; its name in the aria-label, Unsubscribe in the tooltip); the tags keep the row's rest, folding into "+N"                                                                                                                                                                        | The tag lane on a full line of its own below ~12rem; the tags under the channel name                                                                                                                   | On an iPad (820 px, 44 px targets) the lane got 29 px, a sliver; now 130 px, and every tag shows at 1180                                                                                                                     |
+| 2026-11-01 | Clear watch progress (owner E a)                                 | A video menu's Reset reads "Clear watch progress" in English (HU "Megtekintés visszaállítása" stays); "Reset view" is only a page's view reset (sort, filters, grouping)                                                                                                                                                                                                                            | "Reset view" for both; the playlist page's view reset renamed instead                                                                                                                                  | On a playlist page the two stood one right-click apart under one name, and one of them erases the video's progress with no undo                                                                                              |
+| 2026-11-01 | Clear watch progress clears only that (owner A)                  | The row shows only on a video with a resume point and clears that alone: a hidden video stays hidden, a watched one watched. Un-hiding and un-watching have rows of their own                                                                                                                                                                                                                       | The old Reset, which also un-hid and un-watched                                                                                                                                                        | A hidden video stays hidden: what the row's name says is all it does                                                                                                                                                         |
+| 2026-11-01 | Selecting a list's rows (owner D2 a)                             | An always visible box first in the row and one over the column for the rows shown; Shift+click a range, `x` the row under the keyboard, Esc clears; the selected row wears `accent/12` with its tick. Rows a filter hides stay selected, an action covers those shown; Watch later offers no selecting.                                                                                             | A "Select" button that shows the boxes on demand                                                                                                                                                       | Found at once and works on touch, with no mode to leave; costs about 2 rem a row                                                                                                                                             |
+| 2026-11-01 | Selection band (owner D1 a, D3 a, D4 a)                          | The toolbar's second row while rows are selected, no floating bar: move (the last target as one click) and remove, no copy; both undo back to the places, a video the target held before stays there; a single row's move undoes too.                                                                                                                                                               | A floating bar at the bottom; copying to a list too; no undo on a move                                                                                                                                 | It covers no row, and the player and the notices live at the bottom; twenty videos sent to the wrong list need a way back to their places                                                                                    |
+| 2026-11-01 | Grip on a phone (owner A)                                        | Below a 24rem table a playlist row has no grip: the title keeps its width, and the row menu keeps the moves.                                                                                                                                                                                                                                                                                        | The grip and its drag kept, the title at 44 px                                                                                                                                                         | The title gets its width back, and the rail is shut on a phone, so a drag had nowhere to go                                                                                                                                  |
+| 2026-11-01 | Selection band on a tablet (owner A)                             | Below `xl` the band is glyphs on one row, the names in tooltip and aria-label, as on the channel header; the replaced row stays in the same grid cell, invisible, so the first tick moves no row under the second tap.                                                                                                                                                                              | The buttons in words, wrapping to a second row                                                                                                                                                         | The first tick pushed the list from under the second tap                                                                                                                                                                     |
+| 2026-11-01 | Playlist heading on a narrow window (owner A)                    | The list's name had no width left: below `xl` Unsynced is its dot (the word read out, the hint in the tooltip); on a phone the cover is gone and Play all is its glyph, named in the tooltip.                                                                                                                                                                                                       | Every word kept, the list's name at no width                                                                                                                                                           | A heading without its name says nothing                                                                                                                                                                                      |
+| 2026-11-02 | Dragging onto a list (owner D5 a, D6 a)                          | The grip carries a row, or every selected row with a selected one, onto a list in the rail; the toast undoes. Many dropped inside the list stay; a coarse pointer's drawer never peeks, so its rail is a target only when pinned.                                                                                                                                                                   | Only the grabbed row going along; the grip off under a view                                                                                                                                            | One row moving out of three lit ones misleads, and a filter is how the rows to move are found                                                                                                                                |
+| 2026-11-02 | Delete with every tick hidden (owner a)                          | It removes nothing and a warning says the filter hides them                                                                                                                                                                                                                                                                                                                                         | Taking the row under the keyboard                                                                                                                                                                      | While the band shows a selection, Delete means that selection: a row no one ticked must not go                                                                                                                               |
+| 2026-11-02 | Undo of a video gone further (owner a)                           | A video the move put in the target comes back only if the target still holds it, and a warning says how many                                                                                                                                                                                                                                                                                        | Everything back, whatever it did since                                                                                                                                                                 | A move skips a video that left the source; the same rule back keeps a video out of lists the reader never put it in                                                                                                          |
+| 2026-11-04 | Tag chip counts (owner D5a)                                      | A Channels tag chip shows how many followed channels it holds: a muted number after the name, no badge                                                                                                                                                                                                                                                                                              | The number in brackets after the name                                                                                                                                                                  | The owner's pick; the number is a detail of the name, so it takes the name's own text, muted, rather than a `CountBadge`                                                                                                     |
+| 2026-11-05 | Picked tag chips lead the row (owner c)                          | On the Channels tag row the picked chips come first, in the tags' order, then the rest                                                                                                                                                                                                                                                                                                              | Keep the order and fold the unpicked first; mark the "+N" when it holds a pick                                                                                                                         | The row folds from its end, so a picked tag late in the list sat only inside "+N" with nothing on the row saying a filter was on                                                                                             |
+| 2026-11-05 | A toggled tag chip keeps the focus (owner a)                     | A chip that moves when toggled takes the keyboard focus with it: to its new place, or to "+N" when it went into the closed fold                                                                                                                                                                                                                                                                     | Keep a picked chip in the "+N" popover until it closes                                                                                                                                                 | The row always shows the filters as they are; the focus, not the order, was what got lost                                                                                                                                    |
+| 2026-11-06 | Tag chip count after a dot (owner a)                             | The count keeps the chip's own colour, set off from the name by a "·"                                                                                                                                                                                                                                                                                                                               | The number dimmed (it fell under the 4.5:1 text floor, resting and pressed); the number in a tinted inner badge                                                                                        | Contrast holds in every scheme without a new token, and the dot still reads the number as a detail of the name                                                                                                               |
+| 2026-11-06 | A pick in the open fold closes it (owner a)                      | Toggling a chip inside the "+N" popover closes the popover; the focus goes with the chip                                                                                                                                                                                                                                                                                                            | Keep the popover open and focus the chip now in the picked one's place                                                                                                                                 | The focus never sits outside a popover left open, and a picked chip leads the row anyway                                                                                                                                     |
+| 2026-11-06 | An expired share link offers no Copy (owner a)                   | An expired row in the share dialog has a warn badge "expired <date>" and its address struck through; Open and Revoke stay, Copy goes                                                                                                                                                                                                                                                                | The warn badge alone, Copy kept                                                                                                                                                                        | An expired link opens nothing, so it is no link to hand out; Open still lets the owner check it                                                                                                                              |
+| 2026-11-06 | The shared page's unlock button is a noun in Hungarian (owner a) | "Megtekintés" for a video, "Megnyitás" for a file or folder                                                                                                                                                                                                                                                                                                                                         | Both verbs, "Megnézem" / "Megnyitom"                                                                                                                                                                   | The app's Hungarian buttons are nouns; one button should not change grammatical form by link kind                                                                                                                            |

docs/development.md

@@ -45,7 +45,18 @@ A frontend page is one folder, `frontend/src/modules/<id>/` (the layering is in
    page renders into the floating header itself through `PageHeader`; the shell knows no page.
 2. `module.ts`: its `ModuleDef` (`lib/moduleDef.ts`): id, label keys, icon, an optional `gate`, the page as a
    `lazyWithPreload(() => import(…))`, and optionally a rail and a `Store`. Of its own folder it imports statically
-   only its store (a `…Provider` / `…Store` file); the page and the rail load lazily.
+   only its store (a `…Provider` / `…Store` file); the page and the rail load lazily. `urlKeys` names every
+   address-bar key its view writes (the URL is the view: a bookmark reopens it), its list kept in `lib/` beside
+   its codec; the shell clears them on a page switch and opens a page without another page's keys.
+   Every setting the page shows — a tab, a sort, a filter, a search, the item open in it — goes there: a codec
+   in `lib/<id>UrlState.ts` (read the params into the view, write the view as updates, a default left out —
+   or always written, when an address naming none falls back to a view remembered elsewhere), written with
+   `useUrlMirror` (a sub-view through `useHistorySubview`'s `url`, an overlay through `useBackToClose`'s),
+   always as the codec's result: a writer outside `lib/` computes no key of its own. Read back first on mount
+   (a link wins over anything remembered). A key that carries typed text — a search box's, a column filter
+   map with a text filter — is also in `typedUrlKeys` (the client log keeps what was typed out). Add its round
+   trip to `e2e/bookmark.spec.ts`, tagged with the page (`{ tag: "@<id>" }`). Only what an address cannot promise to
+   reopen stays out, said in its codec (Home's draw, `lib/homeUrlState`).
 3. `index.ts`, the module's public face: the definition, and only what other folders must read (its store's
    hooks). Another folder reaches the module through this file or not at all.
 4. The id in `lib/urlState`'s `PAGES`, and the definition in `features/navigation/moduleRegistry.ts`, in
@@ -58,7 +69,10 @@ A frontend page is one folder, `frontend/src/modules/<id>/` (the layering is in
    returns to `ui/FilterRail`; tsc names each table still missing the new id.
 
 What holds it: `moduleRegistry.contract.test.ts` (every id defined once, from its own folder, lazily),
-`moduleStores.contract.test.tsx` (no store reads another module), the `local/layers` lint rule (imports only go
+`moduleStores.contract.test.tsx` (no store reads another module), `moduleUrl.contract.test.ts` (each URL key
+belongs to one module and matches what its codec writes; a writer outside `lib/` is handed a literal or a `lib/`
+function's result, never a key of its own; no key literal written or read from the live query undeclared; every key
+sorted as typed or not; every page with keys in a tagged bookmark round trip), the `local/layers` lint rule (imports only go
 down, a module only through its face) and `chunkGuard` in the build (no lazy page on the boot path), plus the
 i18n parity test.
 
@@ -130,7 +144,8 @@ npm run typecheck     # tsc x3 (app / node / e2e)
 npm run lint          # eslint (typed rules included; warnings fail)
 npm run format:check  # prettier
 npm run knip          # unused files/exports/deps
-npm run test          # vitest (incl. the compiler and gate-register contracts)
+npm run test          # vitest (incl. the compiler and gate-register contracts; the refusal contract runs
+                      # the host's `python` on backend/tests/refusal_sites.py, stdlib only)
 npx vite build        # the production bundle (devOnlyGuard fails it on dev-only code, chunkGuard on a lazy page loaded at boot)
 npm audit --omit=dev --audit-level=high   # what ships to the browser, at high or above
 ```

docs/gates.md

@@ -108,8 +108,8 @@ project checks needs a row.
 
 | Scope | Narrowed | Why | Measured |
 | --- | --- | --- | --- |
-| check | e2e (Playwright) not in `check` | It needs the :8080 stack built from the tree (minutes). It runs in `check-full`, and `release` rebuilds the stack and requires it (E32 D2) — nothing ships without it. | 9 specs: 6 × 3 engines, 3 on chromium only (the row below) |
-| e2e | `a11y.spec.ts` `member.spec.ts` `devices.spec.ts` run on chromium only (`CHROMIUM_ONLY`, the webkit and ipad projects' `testIgnore`) | What they hold does not change with the engine: the axe scan reads the DOM and the accessibility tree, which the engines build alike; the member spec checks which pages and requests a role gets; the devices spec opens its own desktop and iPad contexts. Run three times they would triple their time and catch nothing more. What an engine does change (layout, events) the other specs hold on all three. | 3 of 9 specs |
+| check | e2e (Playwright) not in `check` | It needs the :8080 stack built from the tree (minutes). It runs in `check-full`, and `release` rebuilds the stack and requires it (E32 D2) — nothing ships without it. | 12 specs: 9 × 3 engines, 3 on chromium only (the row below) |
+| e2e | `a11y.spec.ts` `member.spec.ts` `devices.spec.ts` run on chromium only (`CHROMIUM_ONLY`, the webkit and ipad projects' `testIgnore`) | What they hold does not change with the engine: the axe scan reads the DOM and the accessibility tree, which the engines build alike; the member spec checks which pages and requests a role gets; the devices spec opens its own desktop and iPad contexts. Run three times they would triple their time and catch nothing more. What an engine does change (layout, events) the other specs hold on all three. | 3 of 12 specs |
 | pushes | no server-side gate (no CI) | Owner decision 2026-10-04. The gate (`scripts/check.sh`) runs on the dev machine before work is handed over, and `release` runs it, then e2e, before anything is merged and Trivy before the image is pushed — the CI only repeated that, after the merge. Its runner shared the git host's container, and one run there starved Gitea of memory until it stopped answering. What it added — a fresh `npm ci` on Linux — the image build does at publish. | — |
 | coverage | not in the gate; no threshold | Owner decision E32 D4: never enforced; "every regression test seen red" is the bar, and a percentage invites tests written to move it. Out of the lanes since E35: read once, by hand, it found 5 bugs; as a lane it was a number nobody acted on, and the slowest vitest run (the one that flaked). On demand: docs/development.md. | frontend 80% / backend 78% of lines (E32 S1) |
 | CVE gate | HIGH/CRITICAL with a fix available only | `--ignore-unfixed` + `--severity HIGH,CRITICAL`: a finding with no fix cannot be acted on by an upgrade; it shows in the scan output. A fixable one fails the publish, and the only way past it is `.trivyignore.yaml`. | 0 open (E32 S1) |

frontend/e2e/README.md

@@ -24,6 +24,10 @@ outlives an `expect` timeout); Node does not, so a request from the test side fa
 that one error again and passes every other failure straight on. Don't run two e2e suites on the
 same machine at once.
 
+**A page load the machine had no buffer for** — on the same host a page load can fail at once with
+`net::ERR_NO_BUFFER_SPACE`. Every page load goes through `gotoRetrying` (same file), which tries that
+one error again; a test that calls `page.goto` itself fails `src/lib/e2eRetryConnect.test.ts`.
+
 **Browsers** — every flow runs in three projects: `chromium` (Desktop Chrome), `webkit` (Desktop
 Safari) and `ipad` (iPad gen 7 landscape: 1080×810, touch, mobile) — except `a11y`, `member` and
 `devices`, which run on chromium only (`CHROMIUM_ONLY`; why is in the `docs/gates.md` row). Install the engines once per

frontend/e2e/bookmark.spec.ts

@@ -0,0 +1,259 @@
+import { test, expect, type Browser, type Page } from "@playwright/test";
+import {
+  clickVisibleChannelLink,
+  expectContentType,
+  gotoPage,
+  openApp,
+  openFirstVideo,
+  toggleContentType,
+} from "./helpers";
+
+// The address is the view: a view set through the UI, its address opened as a bookmark — in a NEW
+// browser context, so nothing this tab remembered (its history entries, sessionStorage, the view
+// storage it wrote) can stand in for what the address says. One round trip per page that names its
+// view, tagged with the page (moduleUrl.contract.test holds the tags to the module definitions),
+// plus the overlays the shell opens over any page (the channel page, the player) and the live
+// search. Not Plex: what it shows is the instance's own library, which a test stack may not have.
+
+const STORAGE_STATE = "e2e/.auth/state.json";
+
+/** The page's address, opened as a bookmark in a fresh context of the same account. */
+async function bookmarked(browser: Browser, page: Page, prepare?: (p: Page) => Promise<void>) {
+  const url = page.url();
+  const ctx = await browser.newContext({ storageState: STORAGE_STATE, locale: "en-US" });
+  const fresh = await ctx.newPage();
+  await prepare?.(fresh);
+  await openApp(fresh, url);
+  return fresh;
+}
+
+const tab = (p: Page, name: string) => p.getByRole("tab", { name, exact: true });
+const column = (p: Page, name: string) =>
+  p.getByRole("columnheader", { name: new RegExp(`^${name}`) });
+
+async function gotoAdminPage(page: Page, id: string): Promise<void> {
+  await page.getByTestId("nav-admin").click();
+  await page.getByTestId(`nav-admin-${id}`).click();
+}
+
+test.describe("a bookmark reopens the view it was taken of", () => {
+  test("the feed's filters", { tag: "@feed" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await toggleContentType(page, "includeLive");
+    await expect(page).toHaveURL(/[?&]live=/);
+    const fresh = await bookmarked(browser, page);
+    await expectContentType(fresh, "includeLive", true);
+    await fresh.context().close();
+  });
+
+  test("Home's time budget", { tag: "@home" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=home");
+    await page.getByRole("button", { name: "An evening", exact: true }).click();
+    await expect(page).toHaveURL(/[?&]hb=long/);
+    const fresh = await bookmarked(browser, page);
+    await expect(fresh.getByRole("button", { name: "An evening", exact: true })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    await fresh.context().close();
+  });
+
+  test("a Settings tab", { tag: "@settings" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await gotoPage(page, "settings");
+    await tab(page, "Notifications").click();
+    const fresh = await bookmarked(browser, page);
+    await expect(tab(fresh, "Notifications")).toHaveAttribute("aria-selected", "true");
+    await fresh.context().close();
+  });
+
+  test("an admin page's tab", { tag: "@users" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await gotoAdminPage(page, "users");
+    await tab(page, "Access requests").click();
+    const fresh = await bookmarked(browser, page);
+    await expect(tab(fresh, "Access requests")).toHaveAttribute("aria-selected", "true");
+    await fresh.context().close();
+  });
+
+  test("a Configuration group", { tag: "@config" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await gotoAdminPage(page, "config");
+    const second = page.getByRole("tab").nth(1);
+    const name = (await second.textContent()) ?? "";
+    await second.click();
+    await expect(page).toHaveURL(/[?&]cfgtab=/);
+    const fresh = await bookmarked(browser, page);
+    await expect(fresh.getByRole("tab", { name, exact: true })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    await fresh.context().close();
+  });
+
+  test("the Activity tab and its time window", { tag: "@activity" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await gotoAdminPage(page, "activity");
+    await tab(page, "Server log").click();
+    await page.getByRole("button", { name: "30 days", exact: true }).click();
+    await expect(page).toHaveURL(/[?&]aw=30d/);
+    const fresh = await bookmarked(browser, page);
+    await expect(tab(fresh, "Server log")).toHaveAttribute("aria-selected", "true");
+    await expect(fresh.getByRole("button", { name: "30 days", exact: true })).toHaveAttribute(
+      "aria-pressed",
+      "true",
+    );
+    await fresh.context().close();
+  });
+
+  test("a playlist and its sort", { tag: "@playlists" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await gotoPage(page, "playlists");
+    await expect(column(page, "Title")).toBeVisible();
+    await column(page, "Title").getByRole("button").first().click();
+    await expect(page).toHaveURL(/[?&]plsort=/);
+    const sorted = await column(page, "Title").getAttribute("aria-sort");
+    const fresh = await bookmarked(browser, page);
+    await expect(column(fresh, "Title")).toHaveAttribute("aria-sort", sorted ?? "");
+    expect(new URL(fresh.url()).searchParams.get("pl")).toBe(
+      new URL(page.url()).searchParams.get("pl"),
+    );
+    await fresh.context().close();
+  });
+
+  test(
+    "the Channels manager's tab and name search",
+    { tag: "@channels" },
+    async ({ page, browser }) => {
+      await openApp(page, "/?page=feed");
+      await gotoPage(page, "channels");
+      await tab(page, "Hidden").click();
+      await page.getByPlaceholder("Search channels…").fill("zz");
+      await expect(page).toHaveURL(/zz/); // written once the typing settles
+      const fresh = await bookmarked(browser, page);
+      await expect(tab(fresh, "Hidden")).toHaveAttribute("aria-selected", "true");
+      await expect(fresh.getByPlaceholder("Search channels…")).toHaveValue("zz");
+      await fresh.context().close();
+    },
+  );
+
+  test("the Files search", { tag: "@files" }, async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await gotoPage(page, "files");
+    await page.getByPlaceholder("Search files…").fill("zz");
+    await expect(page).toHaveURL(/zz/);
+    const fresh = await bookmarked(browser, page);
+    await expect(fresh.getByPlaceholder("Search files…")).toHaveValue("zz");
+    await fresh.context().close();
+  });
+
+  // A file of the test's own, uploaded for it and deleted after, and the account's sort put back:
+  // the account is left as it was found.
+  test(
+    "the Files sort, and the file open in the viewer",
+    { tag: "@files" },
+    async ({ page, browser }) => {
+      await openApp(page, "/?page=feed");
+      const NAME = "bookmark-note";
+      // One a run cut short left behind goes first.
+      const left = (await (await page.request.get("/api/files")).json()) as Record<
+        string,
+        unknown
+      >[];
+      for (const f of left.filter((f) => JSON.stringify(f).includes(`"${NAME}`)))
+        await page.request.delete(`/api/files/${String(f.id)}`);
+      const up = await page.request.post("/api/files/upload", {
+        headers: { "X-Upload-Filename": `${NAME}.txt` },
+        data: Buffer.from("a note the bookmark reopens\n"),
+      });
+      expect(up.ok(), await up.text()).toBeTruthy();
+      const { id } = (await up.json()) as { id: number };
+      // The account's own sort, put back after: a header press cycles it (asc, desc, none), so the
+      // case starts from none, as the address names it, whatever an earlier run left.
+      const me = (await (await page.request.get("/api/me")).json()) as {
+        preferences?: Record<string, unknown>;
+      };
+      const ownSort = me.preferences?.filesSort ?? null;
+      try {
+        await openApp(page, "/?page=files&fsort=none");
+        await column(page, "Name").getByRole("button").first().click();
+        await expect(page).toHaveURL(/[?&]fsort=name/);
+        const sorted = await column(page, "Name").getAttribute("aria-sort");
+        await page.getByText(NAME, { exact: true }).first().click();
+        await expect(page).toHaveURL(new RegExp(`[?&]fview=${id}`));
+        const fresh = await bookmarked(browser, page);
+        await expect(fresh.getByRole("dialog", { name: NAME })).toBeVisible();
+        await fresh.keyboard.press("Escape");
+        await expect(column(fresh, "Name")).toHaveAttribute("aria-sort", sorted ?? "");
+        await fresh.context().close();
+      } finally {
+        await page.request.delete(`/api/files/${id}`);
+        await page.request.put("/api/me/preferences", { data: { filesSort: ownSort } });
+      }
+    },
+  );
+
+  test("a channel page's own tab, over the page it was opened from", async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await expect(page.getByTestId("video-card").first()).toBeVisible();
+    await clickVisibleChannelLink(page);
+    const title = await page.getByTestId("channel-title").textContent();
+    await tab(page, "About").click();
+    const fresh = await bookmarked(browser, page);
+    await expect(fresh.getByTestId("channel-title")).toHaveText(title ?? "");
+    await expect(tab(fresh, "About")).toHaveAttribute("aria-selected", "true");
+    await fresh.context().close();
+  });
+
+  test("the player and the video it plays", async ({ page, browser }) => {
+    await openApp(page, "/?page=feed");
+    await openFirstVideo(page);
+    await expect(page).toHaveURL(/[?&]watch=/);
+    const watch = new URL(page.url()).searchParams.get("watch");
+    const fresh = await bookmarked(browser, page);
+    await expect(fresh.getByTestId("player-modal")).toBeVisible();
+    expect(new URL(fresh.url()).searchParams.get("watch")).toBe(watch);
+    await fresh.context().close();
+  });
+
+  // The search itself never reaches YouTube here: the answer is the server's shape, served by the
+  // test, and the request it answers is what the address named. The instance's search settings are
+  // pinned too (the free source, switched on): a stack left on the API source reopens the search
+  // waiting for its press, by design, and one with search off offers none.
+  test(
+    "a live YouTube search, its term and its count",
+    { tag: "@feed" },
+    async ({ page, browser }) => {
+      const answer = async (p: Page, seen: string[]) => {
+        await p.route("**/api/me", async (route) => {
+          const me = (await (await route.fetch()).json()) as Record<string, unknown>;
+          return route.fulfill({ json: { ...me, search_source: "scrape", search_enabled: true } });
+        });
+        await p.route("**/api/search/youtube?**", (route) => {
+          seen.push(route.request().url());
+          return route.fulfill({ json: { items: [], next_cursor: null, source: "scrape" } });
+        });
+      };
+      await answer(page, []);
+      await openApp(page, "/?page=feed");
+      await page.getByPlaceholder("Search your subscriptions…").fill("lofi");
+      await page.getByRole("button", { name: "Search YouTube", exact: true }).click();
+      await expect(page.getByText("YouTube results for “lofi”")).toBeVisible();
+      await expect(page).toHaveURL(/[?&]yt=lofi/); // named as it opens, not only once the count is set
+      await page.getByRole("button", { name: "40", exact: true }).click();
+      await expect(page).toHaveURL(/[?&]ytn=40/);
+
+      const seen: string[] = [];
+      const fresh = await bookmarked(browser, page, (p) => answer(p, seen));
+      await expect(fresh.getByText("YouTube results for “lofi”")).toBeVisible();
+      await expect(fresh.getByRole("button", { name: "40", exact: true })).toHaveAttribute(
+        "aria-pressed",
+        "true",
+      );
+      await expect.poll(() => seen.length).toBeGreaterThan(0);
+      const asked = new URL(seen[0]!).searchParams;
+      expect([asked.get("q"), asked.get("limit")]).toEqual(["lofi", "40"]);
+      await fresh.context().close();
+    },
+  );
+});

frontend/e2e/channel.spec.ts

@@ -48,7 +48,7 @@ test.describe("channel view", () => {
     // `.first()` here would grab an overscan card ABOVE the viewport, and Playwright's scroll-into-
     // view would move the feed before navigating, so Back would restore that moved position, not
     // the one under test. (This is what made the test fail while the app was in fact correct.)
-    expect(await clickVisibleChannelLink(page)).toBe(true);
+    await clickVisibleChannelLink(page);
     await expect(page.getByTestId("channel-title")).toBeVisible();
     await page.getByTestId("channel-back").click();
     await expect(page.getByTestId("video-card").first()).toBeVisible();
@@ -114,7 +114,9 @@ test.describe("channel view", () => {
   }) => {
     await openApp(page);
     await page.getByTestId("video-card-channel").first().click();
-    const count = page.getByTestId("item-count");
+    // A pill of the feed's toolbar, which rides in the fixed chrome (the page has no count pill: its
+    // header counts the videos).
+    const count = page.getByTestId("feed-show");
     await expect(count).toBeVisible();
     await expect(page.getByTestId("video-card").first()).toBeVisible();
     await expect(page.getByTestId("channel-folded")).toHaveCount(0);

frontend/e2e/global.setup.ts

@@ -4,7 +4,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { MEMBER_STORAGE, SEED_FILE } from "./helpers";
-import { retryConnect } from "./retryConnect";
+import { gotoRetrying, retryConnect } from "./retryConnect";
 
 /**
  * One-time setup for the characterization net (the `setup` project the tests depend on):
@@ -52,7 +52,7 @@ async function signIn(page: Page, email: string, path: string): Promise<void> {
   // and player flows this net locks all open "/" expecting the feed; the opt-out is the one
   // Settings → Appearance → Startup writes. Both flags are the account's local state, held for the
   // account the browser records as their owner (`siftlode.owner`, see storage.ts claimLocalData).
-  await page.goto("/");
+  await gotoRetrying(page, "/");
   await page.evaluate((id: number) => {
     localStorage.setItem("siftlode.owner", String(id));
     localStorage.setItem("siftlode.lang", "en");

frontend/e2e/helpers.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { expect, type Page } from "@playwright/test";
+import { gotoRetrying } from "./retryConnect";
 
 /** The plain member's saved session (global.setup.ts signs it in); `member.spec.ts` and
  *  `devices.spec.ts` run from it. */
@@ -16,7 +17,7 @@ export function seeded(key: string): string[] {
 
 /** Open the app and wait for the authenticated shell (the nav rail) to be ready. */
 export async function openApp(page: Page, path = "/"): Promise<void> {
-  await page.goto(path);
+  await gotoRetrying(page, path);
   await expect(page.getByTestId("nav-feed")).toBeVisible();
 }
 
@@ -33,23 +34,41 @@ export async function gotoPage(page: Page, id: string): Promise<void> {
  * that then asserts on where the feed was. Being inside the viewport is not enough either: a card
  * can sit under the page chrome above the scroller (the update banner, the toolbar band), and the
  * covered click makes Playwright scroll and retry — the same move (webkit failed 3 in 24).
- * So the link must be the element hit at its own centre. Returns false if none found.
+ * So the link must be the element hit at its own centre; none within the wait fails the test, with
+ * the poll's own message. Looked for again until one is, not once: a fresh load is still settling
+ * when the first card shows (the links move down ~55px), and webkit can answer the hit test at a
+ * link's new centre with the card under it — every link missed in 1 of 30 runs. A link that goes
+ * away mid-look (its evaluate waits for it, or throws) counts as not hit, so the next look runs.
  */
-export async function clickVisibleChannelLink(page: Page): Promise<boolean> {
+export async function clickVisibleChannelLink(page: Page): Promise<void> {
   const links = page.getByTestId("video-card-channel").filter({ visible: true });
-  const count = await links.count();
-  for (let i = 0; i < count; i++) {
-    const hittable = await links.nth(i).evaluate((el) => {
-      const r = el.getBoundingClientRect();
-      const hit = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
-      return hit !== null && el.contains(hit);
-    });
-    if (hittable) {
-      await links.nth(i).click();
-      return true;
+  let index = -1;
+  const findHittable = async () => {
+    const count = await links.count();
+    for (let i = 0; i < count; i++) {
+      const hittable = await links
+        .nth(i)
+        .evaluate(
+          (el) => {
+            const r = el.getBoundingClientRect();
+            const hit = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+            return hit !== null && el.contains(hit);
+          },
+          undefined,
+          { timeout: 1000 },
+        )
+        .catch(() => false);
+      if (hittable) return i;
     }
-  }
-  return false;
+    return -1;
+  };
+  await expect
+    .poll(async () => (index = await findHittable()), {
+      message: "a channel link hit at its own centre",
+      timeout: 5000,
+    })
+    .toBeGreaterThan(-1);
+  await links.nth(index).click();
 }
 
 /**

frontend/e2e/playlists.spec.ts

@@ -0,0 +1,315 @@
+import { test, expect, type Locator, type Page } from "@playwright/test";
+import { openApp } from "./helpers";
+
+// A video dragged onto a list in the rail, with a real pointer: the rail and the page are separate
+// React trees, and jsdom lays out nothing to drag across. The browser projects share one account, so
+// each test holds lists of its own, named for it, and takes them away after.
+
+interface Listed {
+  id: number;
+  items: { id: string; title: string }[];
+}
+
+const made: number[] = [];
+
+async function newList(page: Page, name: string, videos: string[] = []): Promise<number> {
+  const res = await page.request.post("/api/playlists", { data: { name } });
+  const { id } = (await res.json()) as { id: number };
+  made.push(id);
+  for (const video_id of videos) {
+    const added = await page.request.post(`/api/playlists/${String(id)}/items`, {
+      data: { video_id },
+    });
+    expect(added.ok()).toBe(true);
+  }
+  return id;
+}
+
+const contents = async (page: Page, id: number) =>
+  ((await (await page.request.get(`/api/playlists/${String(id)}`)).json()) as Listed).items.map(
+    (v) => v.id,
+  );
+
+async function setUp(page: Page, name: string, project: string) {
+  await pinOnTouch(page, project);
+  const feed = (await (await page.request.get("/api/feed?limit=3")).json()) as {
+    items: { id: string; title: string }[];
+  };
+  expect(feed.items.length).toBe(3);
+  const videos = feed.items;
+  const from = await newList(
+    page,
+    `${name} from`,
+    videos.map((v) => v.id),
+  );
+  const to = await newList(page, `${name} to`);
+  await openApp(page, `/?page=playlists&pl=${String(from)}`);
+  await expect(page.getByRole("heading", { name: `${name} from` })).toBeVisible();
+  await expect(page.locator("tbody tr")).toHaveCount(3);
+  return { videos, from, to, target: page.locator(`[data-playlist-drop="${String(to)}"]`) };
+}
+
+const centre = async (el: Locator) => {
+  const box = await el.boundingBox();
+  if (!box) throw new Error("nothing to point at");
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+};
+
+/** Pick the row up by its grip and carry it to a point, the button still held. */
+async function carry(page: Page, grip: Locator, to: { x: number; y: number }) {
+  const from = await centre(grip);
+  await page.mouse.move(from.x, from.y);
+  await page.mouse.down();
+  await page.mouse.move(from.x + 8, from.y + 8, { steps: 3 });
+  await page.mouse.move(to.x, to.y, { steps: 12 });
+}
+
+/** The same onto the rail. An unpinned one is a tab until the drag's own hover peeks it open. */
+async function carryToRail(page: Page, grip: Locator, target: Locator) {
+  const tab = page.getByRole("button", { name: "Pin Playlists open" });
+  // The rail's lists answer after the rows: until then a pinned rail shows neither the list nor a tab.
+  await target.or(tab).first().waitFor();
+  if (await target.isVisible()) {
+    await carry(page, grip, await centre(target));
+    return;
+  }
+  await carry(page, grip, await centre(tab));
+  await expect(target).toBeVisible();
+  await page.mouse.move(...(Object.values(await centre(target)) as [number, number]), { steps: 6 });
+}
+
+/** What dnd-kit tells a screen reader: said once the drag has taken the step in, so a drop after it
+ *  is the one a person makes, not one that beats the row to its new place. */
+const said = (page: Page, text: RegExp) =>
+  expect(page.locator('[id^="DndLiveRegion"]').filter({ hasText: text })).toBeAttached();
+
+/** A coarse pointer's rail never peeks, a drawer instead: on the tablet it is pinned, for these. */
+async function pinOnTouch(page: Page, project: string) {
+  if (project !== "ipad") return;
+  await page.route("**/api/me", async (route) => {
+    const res = await route.fetch();
+    const me = (await res.json()) as { preferences?: Record<string, unknown> };
+    await route.fulfill({
+      response: res,
+      json: { ...me, preferences: { ...me.preferences, playlistsCollapsed: false } },
+    });
+  });
+}
+
+test.describe("acting on the selected rows", { tag: "@playlists" }, () => {
+  test.afterEach(async ({ page }) => {
+    for (const id of made.splice(0)) await page.request.delete(`/api/playlists/${String(id)}`);
+  });
+
+  const box = (page: Page, title: string) =>
+    page.getByRole("checkbox", { name: `Select “${title}”` });
+
+  test("a Shift range, the band's Remove, and its Undo back to the places", async ({
+    page,
+  }, info) => {
+    const { videos, from } = await setUp(page, `band ${info.project.name}`, info.project.name);
+    await box(page, videos[0]!.title).click();
+    await box(page, videos[1]!.title).click({ modifiers: ["Shift"] });
+    await expect(box(page, videos[1]!.title)).toBeChecked();
+    await expect(box(page, videos[2]!.title)).not.toBeChecked();
+    await page.getByRole("button", { name: "Remove", exact: true }).click();
+    await expect(page.locator("tbody tr")).toHaveCount(1);
+    await expect.poll(() => contents(page, from)).toEqual([videos[2]!.id]);
+    await page.getByRole("button", { name: "Undo", exact: true }).last().click();
+    await expect.poll(() => contents(page, from)).toEqual(videos.map((v) => v.id));
+    await expect(page.locator("tbody tr")).toHaveCount(3);
+  });
+
+  test("x ticks the walked row, Esc clears, and Delete takes the selection and goes on", async ({
+    page,
+  }, info) => {
+    const { videos, from } = await setUp(page, `keys ${info.project.name}`, info.project.name);
+    const firstRow = page.locator("tbody tr").first();
+    await page.keyboard.press("j");
+    await expect(firstRow).toBeFocused();
+    await page.keyboard.press("x");
+    await expect(box(page, videos[0]!.title)).toBeChecked();
+    await page.keyboard.press("Escape");
+    await expect(box(page, videos[0]!.title)).not.toBeChecked();
+    await page.keyboard.press("x");
+    await page.keyboard.press("j");
+    await page.keyboard.press("x");
+    await page.keyboard.press("Delete");
+    await expect.poll(() => contents(page, from)).toEqual([videos[2]!.id]);
+    await expect(page.locator("tbody tr")).toHaveCount(1);
+    await expect(firstRow).toBeFocused();
+  });
+});
+
+test.describe("dragging onto a list", { tag: "@playlists" }, () => {
+  test.afterEach(async ({ page }) => {
+    await page.mouse.up();
+    for (const id of made.splice(0)) await page.request.delete(`/api/playlists/${String(id)}`);
+  });
+
+  test("a row leaves for the list it is dropped on, lit up on the way, and Undo brings it back", async ({
+    page,
+  }, info) => {
+    const { videos, from, to, target } = await setUp(
+      page,
+      `drag one ${info.project.name}`,
+      info.project.name,
+    );
+    const grip = page.getByRole("button", { name: `Reorder “${videos[1]!.title}”`, exact: false });
+    await carryToRail(page, grip, target);
+    await expect(target).toHaveClass(/ring-2/);
+    await page.mouse.up();
+    await expect(target).not.toHaveClass(/ring-2/);
+    await expect(page.locator("tbody tr")).toHaveCount(2);
+    // The grip that held the focus has left: the keyboard keeps its place in the list.
+    await expect
+      .poll(() => page.evaluate(() => document.activeElement?.closest("tbody") != null))
+      .toBe(true);
+    await expect.poll(() => contents(page, to)).toEqual([videos[1]!.id]);
+    expect(await contents(page, from)).toEqual([videos[0]!.id, videos[2]!.id]);
+    await page.getByRole("button", { name: "Undo", exact: true }).last().click();
+    await expect.poll(() => contents(page, from)).toEqual(videos.map((v) => v.id));
+    expect(await contents(page, to)).toEqual([]);
+  });
+
+  test("a selected row carries the selected ones, named on the drag image", async ({
+    page,
+  }, info) => {
+    const { videos, from, to, target } = await setUp(
+      page,
+      `drag many ${info.project.name}`,
+      info.project.name,
+    );
+    await page.getByRole("checkbox", { name: videos[0]!.title, exact: false }).click();
+    await page.getByRole("checkbox", { name: videos[2]!.title, exact: false }).click();
+    const grip = page.getByRole("button", { name: `Reorder “${videos[2]!.title}”`, exact: false });
+    await carryToRail(page, grip, target);
+    const image = page.getByText("2 videos", { exact: true });
+    await expect(image).toBeVisible();
+    // Above every layer, by the tooltip's token: the overlay wrapping it takes the level.
+    expect(await image.evaluate((el) => getComputedStyle(el.parentElement!).zIndex)).toBe("100");
+    // Below the pointer, so it leaves the list's name to read.
+    const { y } = await centre(target);
+    expect((await image.boundingBox())!.y).toBeGreaterThan(y);
+    await page.mouse.up();
+    await expect.poll(() => contents(page, to)).toEqual([videos[0]!.id, videos[2]!.id]);
+    expect(await contents(page, from)).toEqual([videos[1]!.id]);
+    await expect(page.getByRole("checkbox", { name: "Select all" })).not.toBeChecked();
+  });
+
+  test("many rows dropped inside the list stay as they were", async ({ page }, info) => {
+    const { videos, from } = await setUp(
+      page,
+      `drag inside ${info.project.name}`,
+      info.project.name,
+    );
+    await page.getByRole("checkbox", { name: videos[0]!.title, exact: false }).click();
+    await page.getByRole("checkbox", { name: videos[1]!.title, exact: false }).click();
+    const grip = page.getByRole("button", { name: `Reorder “${videos[0]!.title}”`, exact: false });
+    await carry(page, grip, await centre(page.locator("tbody tr").nth(2)));
+    await page.mouse.up();
+    await expect(page.locator("tbody tr")).toHaveCount(3);
+    expect(await contents(page, from)).toEqual(videos.map((v) => v.id));
+  });
+
+  test("one row dropped inside the list takes the new place", async ({ page }, info) => {
+    const { videos, from } = await setUp(
+      page,
+      `drag order ${info.project.name}`,
+      info.project.name,
+    );
+    const grip = page.getByRole("button", { name: `Reorder “${videos[0]!.title}”`, exact: false });
+    await carry(page, grip, await centre(page.locator("tbody tr").nth(2)));
+    await said(page, /position 3/);
+    await page.mouse.up();
+    await expect
+      .poll(() => contents(page, from))
+      .toEqual([videos[1]!.id, videos[2]!.id, videos[0]!.id]);
+  });
+
+  test("Escape puts the drag down, with nothing moved and nothing lit", async ({ page }, info) => {
+    const { videos, from, to, target } = await setUp(
+      page,
+      `drag cancel ${info.project.name}`,
+      info.project.name,
+    );
+    // A tick on another row: the Esc is the drag's, and leaves the selection alone.
+    const ticked = page.getByRole("checkbox", { name: `Select “${videos[2]!.title}”` });
+    await ticked.click();
+    const grip = page.getByRole("button", { name: `Reorder “${videos[0]!.title}”`, exact: false });
+    await carryToRail(page, grip, target);
+    await expect(target).toHaveClass(/ring-2/);
+    await page.keyboard.press("Escape");
+    await expect(target).not.toHaveClass(/ring-2/);
+    await page.mouse.up();
+    expect(await contents(page, from)).toEqual(videos.map((v) => v.id));
+    expect(await contents(page, to)).toEqual([]);
+    await expect(ticked).toBeChecked();
+  });
+
+  test("a key still reorders a row, alone", async ({ page }, info) => {
+    const { videos, from } = await setUp(page, `drag key ${info.project.name}`, info.project.name);
+    await page.getByRole("checkbox", { name: videos[0]!.title, exact: false }).click();
+    await page.getByRole("checkbox", { name: videos[2]!.title, exact: false }).click();
+    await page.getByRole("button", { name: `Reorder “${videos[0]!.title}”`, exact: false }).focus();
+    await page.keyboard.press("Space");
+    await said(page, /picked up/i);
+    // A person's pause: dnd-kit drops an arrow pressed before it has measured the lifted row, which
+    // nothing on the page announces (11 of 31 runs without it, none of 31 with it).
+    await page.waitForTimeout(300);
+    await page.keyboard.press("ArrowDown");
+    await said(page, /position 2/);
+    await page.keyboard.press("Space");
+    await expect
+      .poll(() => contents(page, from))
+      .toEqual([videos[1]!.id, videos[0]!.id, videos[2]!.id]);
+  });
+
+  test("under a filter a row still goes to another list, and none is reordered", async ({
+    page,
+  }, info) => {
+    const { videos, from, to, target } = await setUp(
+      page,
+      `drag filter ${info.project.name}`,
+      info.project.name,
+    );
+    await page.getByRole("columnheader", { name: "Title" }).getByRole("button").last().click();
+    await page.getByPlaceholder("Title").fill(videos[1]!.title);
+    await page.keyboard.press("Escape");
+    await expect(page.locator("tbody tr")).toHaveCount(1);
+    const grip = page.getByRole("button", {
+      name: `Drag “${videos[1]!.title}” onto a list`,
+      exact: false,
+    });
+    await carryToRail(page, grip, target);
+    await page.mouse.up();
+    await expect.poll(() => contents(page, to)).toEqual([videos[1]!.id]);
+    expect(await contents(page, from)).toEqual([videos[0]!.id, videos[2]!.id]);
+  });
+
+  test("the rail scrolls while the drag holds at its edge", async ({ page }, info) => {
+    const name = `drag scroll ${info.project.name}`;
+    for (let i = 0; i < 12; i++) await newList(page, `${name} ${String(i)}`);
+    await page.setViewportSize({ width: 1280, height: 520 });
+    const { videos } = await setUp(page, name, info.project.name);
+    const grip = page.getByRole("button", { name: `Reorder “${videos[0]!.title}”`, exact: false });
+    const area = page.locator("[data-playlist-drop-area]");
+    await carryToRail(page, grip, area.locator("[data-playlist-drop]").first());
+    const scroller = () =>
+      area.evaluate((el) => {
+        for (let p = el.parentElement; p; p = p.parentElement) {
+          const { overflowY } = getComputedStyle(p);
+          if ((overflowY === "auto" || overflowY === "scroll") && p.scrollHeight > p.clientHeight) {
+            const { left, right, bottom } = p.getBoundingClientRect();
+            return { top: p.scrollTop, x: (left + right) / 2, bottom };
+          }
+        }
+        return { top: -1, x: 0, bottom: 0 };
+      });
+    const before = await scroller();
+    expect(before.top).toBeGreaterThanOrEqual(0);
+    await page.mouse.move(before.x, before.bottom - 8, { steps: 4 });
+    await expect.poll(async () => (await scroller()).top).toBeGreaterThan(before.top);
+    await page.keyboard.press("Escape");
+  });
+});

frontend/e2e/retryConnect.ts

@@ -11,6 +11,19 @@ const METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "fetch
 const NO_CONNECTION = /\bconnect ETIMEDOUT\b/;
 const WAITS_MS = [500, 1000, 2000, 4000, 8000];
 
+/** `attempt` again after each wait while it fails with `transient`; any other failure goes on. */
+async function tryAgain<R>(attempt: () => Promise<R>, transient: RegExp): Promise<R> {
+  for (let i = 0; ; i++) {
+    try {
+      return await attempt();
+    } catch (e) {
+      const wait = WAITS_MS[i];
+      if (wait === undefined || !transient.test(String((e as Error)?.message))) throw e;
+      await new Promise((r) => setTimeout(r, wait));
+    }
+  }
+}
+
 /** `ctx` with its request methods trying a connect that timed out again (see above). */
 export function retryConnect<T extends object>(ctx: T): T {
   return new Proxy(ctx, {
@@ -18,17 +31,19 @@ export function retryConnect<T extends object>(ctx: T): T {
       const v: unknown = Reflect.get(target, key, target);
       if (typeof v !== "function") return v;
       if (typeof key !== "string" || !METHODS.has(key)) return v.bind(target);
-      return async (...args: unknown[]) => {
-        for (let i = 0; ; i++) {
-          try {
-            return await v.apply(target, args);
-          } catch (e) {
-            const wait = WAITS_MS[i];
-            if (wait === undefined || !NO_CONNECTION.test(String((e as Error)?.message))) throw e;
-            await new Promise((r) => setTimeout(r, wait));
-          }
-        }
-      };
+      return (...args: unknown[]) =>
+        tryAgain(() => Promise.resolve(v.apply(target, args)), NO_CONNECTION);
     },
   });
 }
+
+// A page load has a failure of its own on the same machine: `net::ERR_NO_BUFFER_SPACE`, the socket
+// call refused for the moment. It stopped a release's e2e at its first page (0.116.3, with nothing
+// else running; 0.107.3 aborted on it too), and the unchanged rerun passed. A browser does not try
+// a main document again by itself, and the request never left, so this does. The suite's every page
+// load goes through here (`e2eRetryConnect.test.ts`).
+const NO_BUFFER = /\bERR_NO_BUFFER_SPACE\b/;
+
+export function gotoRetrying<R>(page: { goto(url: string): Promise<R> }, url: string): Promise<R> {
+  return tryAgain(() => page.goto(url), NO_BUFFER);
+}

frontend/e2e/speed.measure.ts

@@ -1,7 +1,7 @@
 import { test, type Page } from "@playwright/test";
 import { execFileSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
-import { retryConnect } from "./retryConnect";
+import { gotoRetrying, retryConnect } from "./retryConnect";
 
 /**
  * The speed baseline: numbers, not assertions — read by `scripts/audit_metrics.py --speed`, which
@@ -78,7 +78,7 @@ test("speed baseline", async ({ browser, page: page0 }) => {
   for (let i = 0; i < RUNS; i++) {
     const ctx = await browser.newContext();
     const page = await ctx.newPage();
-    await page.goto("/");
+    await gotoRetrying(page, "/");
     // Timed inside the page, every frame: an `expect` would read the clock on its own retry
     // schedule (100 ms … 1 s steps), not when the card appeared.
     const at = await page.waitForFunction(
@@ -108,7 +108,7 @@ test("speed baseline", async ({ browser, page: page0 }) => {
     for (let i = 0; i < RUNS; i++) {
       const ctx = await browser.newContext({ storageState: { cookies: [], origins: [] } });
       const page = await ctx.newPage();
-      await page.goto(`/watch/${token}`);
+      await gotoRetrying(page, `/watch/${token}`);
       await page.waitForFunction(() => document.querySelector("video, audio"), null, {
         polling: "raf",
         timeout: 30_000,

frontend/e2e/stylesheet.spec.ts

@@ -0,0 +1,61 @@
+import { test, expect, type Page } from "@playwright/test";
+import { openApp } from "./helpers";
+import { gotoRetrying } from "./retryConnect";
+
+// A request can be lost on the way on a loaded machine or a poor line. A lost stylesheet leaves the
+// whole page unstyled, and every test that finds its elements by testid still passes on it: only an
+// axe run ever noticed (8 controls under the target size). So this looks at the styles themselves.
+
+/** Lose the first request for every stylesheet of the page; the ones after it go through. */
+async function loseEachStylesheetOnce(page: Page): Promise<string[]> {
+  const lost: string[] = [];
+  await page.route(/\/assets\/[^/]+\.css/, async (route) => {
+    const url = route.request().url();
+    if (lost.includes(url)) return route.continue();
+    lost.push(url);
+    return route.abort("failed");
+  });
+  return lost;
+}
+
+/** Every stylesheet link of the page holds rules (a lost one still has a `sheet`, whose rules throw
+ *  on reading), and the page's own tokens are in force: `--bg` comes from the stylesheet alone, while
+ *  `--font-scale` would prove nothing, the app also sets it from script. */
+async function expectStyled(page: Page): Promise<void> {
+  await expect
+    .poll(() =>
+      page.evaluate(() => {
+        const hasRules = (l: HTMLLinkElement) => {
+          try {
+            return (l.sheet?.cssRules.length ?? 0) > 0;
+          } catch {
+            return false;
+          }
+        };
+        const links = [...document.querySelectorAll<HTMLLinkElement>('link[rel="stylesheet"]')];
+        const root = getComputedStyle(document.documentElement);
+        return {
+          links: links.length > 0,
+          rules: links.every(hasRules),
+          tokens: root.getPropertyValue("--bg").trim() !== "",
+        };
+      }),
+    )
+    .toEqual({ links: true, rules: true, tokens: true });
+}
+
+test("the app gets back a stylesheet lost on the way", async ({ page }) => {
+  const lost = await loseEachStylesheetOnce(page);
+  await openApp(page);
+  expect(lost.length).toBeGreaterThan(0);
+  await expectStyled(page);
+});
+
+test("a public /watch link gets back a stylesheet lost on the way", async ({ page }) => {
+  const lost = await loseEachStylesheetOnce(page);
+  // No such link: the page says so, and it is the same entry with the same stylesheet.
+  await gotoRetrying(page, "/watch/no-such-token");
+  await expect(page.locator("#root")).not.toBeEmpty();
+  expect(lost.length).toBeGreaterThan(0);
+  await expectStyled(page);
+});